9. DOS Memory Management Services

• 9.1 Allocate DOS Memory Block
• 9.2 Free DOS Memory Block
• 9.3 Resize DOS Memory Block

Some applications require the ability to allocate memory in the real mode addressable 1 megabyte region. These services allow protected mode applications to allocate and free memory that is directly addressable by real mode software such as networks and DOS device drivers. Often, this memory is used in conjunction with the API translation services to call real mode software that is not directly supported by DPMI.

9.1 Allocate DOS Memory Block

This function will allocate a block of memory from the DOS free memory pool. It returns both the real mode segment and one or more descriptors that can be used by protected mode applications to access the block.

To Call

     AX = 0100h
     BX = Number of paragraphs (16 byte blocks) desired

Returns

     If function was successful:
     Carry flag is clear.
     AX = Initial real mode segment of allocated block
     DX = Selector for allocated block

     If function was not successful:
     Carry flag is set.
     AX = DOS error code:
          07h  memory control blocks damaged
          08h  insufficient memory available to allocate as
               requested
          1Fh  no more selectors available (DOS/4G(W) specific)
     BX = Size of largest available block in paragraphs

Programmer's Notes

• When running in a Windows NT DOS box, there appears to be a limit of about 1470 allocations of DOS memory. This limit may be due to the limit of descriptors in NT, since each DOS allocation consumes at least one descriptor.

• When running in a Windows NT DOS box, there appears to be a bug in NT that returns a failure code when the limit on the number of allocations is reached. In this case, memory is allocated, but the carry flag is set, indicating that no memory was allocated. In this case, the return values seem to indicate a valid segment, but reuse a previous selector value.

• When running under DOS/4G or DOS/4GW under plain DOS, there is a limit of about 1900 DOS allocations, due to the default limitation on selector entries.

• Because of the above limitations, and because of DOS's one paragraph per allocation overhead, if you want to allocate a lot of separate pieces of DOS memory, you may need to allocate bigger chunks from DOS, and subdivide them yourself.

• If the size of the block requested is greater than 64K bytes (BX > 1000h) then contiguous descriptors will be allocated. To access the next descriptor for the memory block add the value return by function 0003h (Get Next Selector Increment Value) to the base selector. If more than one descriptor is allocated under 32- bit DPMI implementations, the limit of the first descriptor will be set to the size of the entire block. All subsequent descriptors will have a limit of 64K except for the final descriptor which will have a limit of Block size MOD 64K. 16-bit DPMI implementations will always set the limit of the first descriptor to 64K even when running on an 80386.

• Your program should never modify or deallocate any descriptors allocated by this function. The Free DOS Memory Block function will deallocate the descriptors automatically

Code Sample:

The following function allocates some DOS memory and returns a C pointer to the memory.
It compiles with Watcom C/C++ version 11.0 or later, and Microsoft Visual C/C++ version 4.0 or later, and should compile with 16-bit C/C++ compilers:

// allocate DOS space from DPMI
// return error code, 0 if successful

void *dpmiAllocateDOSMemoryBlock(
	long nbytes,			// number of bytes requested
	unsigned short *pPMsel)		// (returned) protected-mode selector
	{
	short failed = 0;		// non-zero if int 31h fails
	unsigned short numpara;		// number of paragraphs
	unsigned short rmseg = 0;	// real mode segment
	unsigned short pmsel = 0;	// protected-mode selector

	// can't allocate 0 or negative bytes
	if (nbytes <= 0)
		return 0;

	// fail if we ask for 1MB (or more)
	if (nbytes >= (1024L * 1024)
		return 0;

	// convert bytes to paragraphs
	numpara = (unsigned short) ((nbytes | 15) >> 4);

	// switch to assembly to call DPMI host
	__asm {
		mov	bx, numpara	// put number of paragraphs into bx

		mov	ax, 0x100	// call dpmi host
		int	0x31

		mov	rmseg, ax	// collect results to C variables
		mov	pmsel, dx

		sbb	ax, ax		// carry code to ax
		mov	failed, ax	// and then to result
		}

	// if we didn't succeed, return null
	if (failed)
		return 0;

	// set output results
	*pPMsel = pmsel;

	// return real-mode segment converted to linear address
	return (void *) (((unsigned long) rmseg) << 4);
	}

The following function returns the size in bytes of the largest available DOS memory block.
It compiles with Watcom C/C++ version 11.0 or later, and Microsoft Visual C/C++ version 4.0 or later, and should compile with 16-bit C/C++ compilers:

// return size of largest available DOS block in bytes

unsigned long dpmiGetMaxDOSMemory(void)
	{
	unsigned short largest=0;	// size of largest available block in paragraphs

	// switch to assembly to call DPMI host
	__asm {
		mov	bx, 0xffff	// maximum request can never be satisfied
		mov	ax, 0x100	// DOS memory allocate/report
		int	0x31

		mov	largest, bx	// get largest available block
		}

	return ((unsigned long) largest) << 4;
	}

9.2 Free DOS Memory Block

This function frees memory that was allocated through the Allocate DOS Memory Block function.

To Call

     AX = 0101h
     DX = Selector of block to free

Returns

     If function was successful:
     Carry flag is clear.

     If function was not successful:
     Carry flag is set.
     AX = DOS error code:
          07h  memory control blocks damaged
          09h  incorrect memory segment specified

Programmer's Notes

• All descriptors allocated for the memory block are automatically freed and therefore should not be accessed once the block is freed by this function.

9.3 Resize DOS Memory Block

This function is used to grow or shrink a memory block that was allocated through the Allocate DOS Memory Block function.

To Call

     AX = 0102h
     BX = New block size in paragraphs
     DX = Selector of block to modify

Returns

     If function was successful:
     Carry flag is clear.

     If function was not successful:
     Carry flag is set.
     AX = DOS error code:
          07h  memory control blocks damaged
          08h  insufficient memory  available to allocate as
          requested
          09h  incorrect memory segment specified
     BX = Maximum block size possible in paragraphs

Programmer's Notes

• Growing a memory block is often likely to fail since other DOS block allocations will prevent increasing the size of the block. Also, if the size of a block grows past a 64K boundary then the allocation will fail if the next descriptor in the LDT is not free. Therefore, this function is usually only used to shrink a block.

• Shrinking a block may cause some descriptors that were previously allocated to the block to be freed. For example shrinking a block from 140K to 120K would cause the third allocated descriptor to be freed since it is no longer valid. The initial selector will remain unchanged, however, the limits of the remaining two descriptors will change: the first to 120K and the second to 56k.