DM&P DOS XMS Library Reference
2002/04/18 Version 0.10

DOS XMS Library

DOS XMS library is a DOS real mode and large memory model C library. Because DOS is ran under real mode, programmer only can access RAM under 1MB. The memory user can use are 640 KB, Other 384 KB are reserved for ROM BIOS and other cards. XMS library provides M6117D programmer a easy way to access RAM above 1 MB under DOS via XMS driver. For X-DOS, add "DOS=HIGH" to you CONFIG.SYS will force X-DOS to active XMS driver.

Notice: The memory size should be even when you call XMS functions. The string "szStr" in DEMO.C contains 15 characters which length is 16(15+one '\0'). You can modified it that the length of "szStr" to be odd and will get mistake.

If you have any problem, mail to soc@dmp.com.tw please.

Function Reference

int XMS_Init();
Description: Initialize XMS driver and get control function address.
Arguments:
return 0 is error, non-zero is okay.
Example: 

/* Initialize XMS driver */
if(XMS_Init() == 0)
{
  printf("Unable to find XMS driver.\n");
  return;
}

unsigned int XMS_GetVer();
Description: Get XMS driver version.
Arguments:
return XMS driver version.
Example: 

/* Show XMS version */
printf("XMS Version: %x\n", XMS_GetVer());

void XMS_GetFree(unsigned int *pnMax, unsigned int *pnTotal);
Description: Query free memory and maximum available space
Arguments:
pnMax Pointer to save maximum available space in KBytes.
pnTotal Pointer to save total memory free space in KBytes.
Example: 

unsigned int  nMax, nTotal;
XMS_GetFree(&nMax, &nTotal);
printf("Free memory: max=%u KB, total=%u KB.\n", nMax, nTotal);

int XMS_Allocate(unsigned int nSize, unsigned int *pHandle);
Description: Allocate XMS memory.
Arguments:
return 0 is error, non-zero is okay.
nSize Memory size in KBytes you want to allocate.
pHandle Pointer to save handle.
Example: 

unsigned int  Handle;
if(XMS_Allocate(1, &Handle) == 0)
{
  printf("failed!\n");
  return;
}

int XMS_Free(unsigned int Handle);
Description: Free allocated XMS memory.
Arguments:
return 0 is error, non-zero is okay.
Handle Memory handle
Example: 

/* Free XMS we allocated */
XMS_Free(Handle);

int XMS_GetInfo(unsigned int Handle, unsigned char *pcLockCounter,unsigned char *pcAvailHandle, unsigned int *nSize);
Description: Get handle information.
Arguments:
return 0 is error, non-zero is okay.
Handle Memory handle.
pcLockCounter Lock counter of this handle.
pcAvailHandle Available memory of XMS.
nSize The XMS memory size of this handle.
Example: 

/* Show handle information */
XMS_GetInfo(Handle, &cLockCounter, &cAvailHandle, &nSize);
printf("Block info: ");
printf("lock counter=%u, ", cLockCounter);
printf("available handle=%u, ", cAvailHandle);
printf("size=%u KB.\n", nSize);

int XMS_Copy(struct XMMS *pXMMS);
Description: Copy memory.
Arguments:
return 0 is error, non-zero is okay.
pXMMS Pointer of eXtended Memory Move Structure.

The XMMS structure: 

struct XMMS
{
  unsigned long lLen;       /* length */
  unsigned int  SrcHandle;  /* source handle */
  unsigned long lSrcOffset; /* source offset */
  unsigned int  DstHandle;  /* destination handle */
  unsigned long lDstOffset; /* destination offset */
};
Example: 

XMMS XMMS;
XMMS.lLen = lLen;
XMMS.SrcHandle = SrcHandle;
XMMS.lSrcOffset = lSrcOffset;
XMMS.DstHandle = 0;
((unsigned int *)(&XMMS.lDstOffset))[0] = FP_OFF(pDst);
((unsigned int *)(&XMMS.lDstOffset))[1] = FP_SEG(pDst);
XMS_Copy(&XMMS);

int XMS_CopyToXMS(unsigned int DstHandle, unsigned long lDstOffset,const void far *pSrc, unsigned long lLen);
Description: Copy memory buffer to XMS.
Arguments:
return 0 is error, non-zero is okay.
DstHandle Destination handle.
lDstOffset Destination offset.
pSrc Pointer of source memory.
lLen Length to copy.
Example: 

XMS_CopyToXMS(Handle, 0, pcBuf, BUF_SIZE);

int XMS_CopyFromXMS(void far *pDst, unsigned int SrcHandle,unsigned long lSrcOffset, unsigned long lLen);
Description: Copy XMS to memory buffer.
Arguments:
return 0 is error, non-zero is okay.
pDst Pointer of memory buffer.
SrcHandle Handle of XMS.
lSrcOffset Offset of source memory.
lLen Length to copy.
Example: 

XMS_CopyFromXMS(pcBuf, Handle, 0, BUF_SIZE);
DMP Electronics Inc. All rights reserved. Email us: info@dmp.com.tw