pmapi.h

BIOS emulator and interface to Realmode X86 Emulator Library Can emulate a PCI Graphic Controller V

extern "C" {            /* Use "C" linkage when in C++ mode */
#endif

#ifdef	__WIN32_VXD__
#define	VESA_BUF_SIZE 1024
extern uchar *_PM_rmBufAddr;
#endif

/* {secret} Pointer to global exports structure.
 * Should not be used by application programs.
 */
extern PM_imports _VARAPI _PM_imports;

/*--------------------------- Function Prototypes -------------------------*/

/* Routine to initialise the host side PM library. Note used from DLL's */

void	PMAPI PM_init(void);

/* Routine to return either PM_realMode, PM_286 or PM_386 */

int 	PMAPI PM_getModeType(void);

/* Routine to return a selector to the BIOS data area at segment 0x40 */

void *	PMAPI PM_getBIOSPointer(void);

/* Routine to return a linear pointer to the VGA frame buffer memory */

void * 	PMAPI PM_getA0000Pointer(void);

/* Routines to map/free physical memory into the current DS segment. In
 * some environments (32-bit DOS is one), after the mapping has been
 * allocated, it cannot be freed. Hence you should only allocate the
 * mapping once and cache the value for use by other parts of your
 * application. If the mapping cannot be createed, this function will
 * return a NULL pointer.
 *
 * This routine will also work for memory addresses below 1Mb, but the
 * mapped address cannot cross the 1Mb boundary.
 */

void * 	PMAPI PM_mapPhysicalAddr(ulong base,ulong limit,ibool isCached);
void  	PMAPI PM_freePhysicalAddr(void *ptr,ulong limit);

/* Routine to determine the physical address of a linear address. It is
 * up to the caller to ensure the entire address range for a linear
 * block of memory is page aligned if that is required.
 */

ulong 	PMAPI PM_getPhysicalAddr(void *p);

/* Routine to allocate a memory block in the global shared region that
 * is common to all tasks and accessible from ring 0 code.
 */

void *	PMAPI PM_mallocShared(long size);

/* Routine to map a shared memory block into the current process */

int		PMAPI PM_mapShared(void *ptr);

/* Routine to free the allocated shared memory block */

void	PMAPI PM_freeShared(void *ptr);

/* Attach a previously allocated linear mapping to a new process */

void *	PMAPI PM_mapToProcess(void *linear,ulong limit);

/* Macros to extract byte, word and long values from a char pointer */

#define	PM_getByte(p)		*((volatile uchar*)(p))
#define	PM_getWord(p)		*((volatile ushort*)(p))
#define	PM_getLong(p)		*((volatile ulong*)(p))
#define	PM_setByte(p,v)		PM_getByte(p) = (v)
#define	PM_setWord(p,v)		PM_getWord(p) = (v)
#define	PM_setLong(p,v)		PM_getLong(p) = (v)

/* Routine for accessing a low 1Mb memory block. You dont need to free this
 * pointer, but in 16 bit protected mode the selector allocated will be
 * re-used the next time this routine is called.
 */

void *	PMAPI PM_mapRealPointer(uint r_seg,uint r_off);

/* Routine to allocate a block of conventional memory below the 1Mb
 * limit so that it can be accessed from real mode. Ensure that you free
 * the segment when you are done with it.
 *
 * This routine returns a selector and offset to the segment that has been
 * allocated, and also returns the real mode segment and offset which can
 * be passed to real mode routines. Will return 0 if memory could not be
 * allocated.
 *
 * Please note that with some DOS extenders, memory allocated with the
 * following function cannot be freed, hence it will be allocated for the
 * life of your program. Thus if you need to call a bunch of different
 * real-mode routines in your program, allocate a single large buffer at
 * program startup that can be re-used throughout the program execution.
 */

void *	PMAPI PM_allocRealSeg(uint size,uint *r_seg,uint *r_off);
void	PMAPI PM_freeRealSeg(void *mem);

/* Routine to allocate a block of locked memory, and return both the
 * linear and physical addresses of the memory.
 */

void *	PMAPI PM_allocLockedMem(uint size,ulong *physAddr);
void	PMAPI PM_freeLockedMem(void *p,uint size);

/* Routine to return true if we have access to the BIOS on the host OS */

ibool	PMAPI PM_haveBIOSAccess(void);

/* Routine to call a real mode assembly language procedure. Register
 * values are passed in and out in the 'regs' and 'sregs' structures. We
 * do not provide any method of copying data from the protected mode stack
 * to the real mode stack, so if you need to pass data to real mode, you will
 * need to write a real mode assembly language hook to recieve the values
 * in registers, and to pass the data through a real mode block allocated
 * with the PM_allocRealSeg() routine.
 */

void 	PMAPI PM_callRealMode(uint seg,uint off, RMREGS *regs,RMSREGS *sregs);

/* Routines to generate real mode interrupts using the same interface that
 * is used by int86() and int86x() in realmode. This routine is need to
 * call certain BIOS and DOS functions that are not supported by some
 * DOS extenders. No translation is done on any of the register values,
 * so they must be correctly set up and translated by the calling program.
 *
 * Normally the DOS extenders will allow you to use the normal int86()
 * function directly and will pass on unhandled calls to real mode to be
 * handled by the real mode handler. However calls to int86x() with real
 * mode segment values to be loaded will cause a GPF if used with the
 * standard int86x(), so you should use these routines if you know you
 * want to call a real mode handler.
 */

int 	PMAPI PM_int86(int intno, RMREGS *in, RMREGS *out);
int 	PMAPI PM_int86x(int intno, RMREGS *in, RMREGS *out,RMSREGS *sregs);

/* Routine to generate a real mode interrupt. This is identical to the
 * above function, but takes a DPMI_regs structure for the registers
 * which has a lot more information. It is only available from 32-bit
 * protected mode.
 */

void	PMAPI DPMI_int86(int intno, DPMI_regs *regs);

/* Function to return the amount of available physical and total memory.
 * The results of this function are *only* valid before you have made any
 * calls to malloc() and free(). If you need to keep track of exactly how
 * much memory is currently allocated, you need to call this function to
 * get the total amount of memory available and then keep track of
 * the available memory every time you call malloc() and free().
 */

void	PMAPI PM_availableMemory(ulong *physical,ulong *total);

/* Return the address of a global VESA real mode transfer buffer for use
 * by applications.
 */

void *	PMAPI PM_getVESABuf(uint *len,uint *rseg,uint *roff);

/* Handle fatal error conditions */

void 	PMAPI PM_fatalError(const char *msg);

/* Function to set a cleanup error handler called when PM_fatalError
 * is called. This allows us to the console back into a normal state
 * if we get a failure from deep inside a BPD file. This function is
 * not exported to BPD files, and is only used by code compiled for the
 * OS.
 */

void 	PMAPI PM_setFatalErrorCleanup(PM_fatalCleanupHandler cleanup);

/* Return the OS type flag as defined in <drvlib/os/os.h> */

long	PMAPI PM_getOSType(void);

/* Functions to set a VBE bank via an Int 10h */

void 	PMAPI PM_setBankA(int bank);
void	PMAPI PM_setBankAB(int bank);
void 	PMAPI PM_setCRTStart(int x,int y,int waitVRT);

/* Return the current working directory */

const char * PMAPI PM_getCurrentPath(void);

/* Return paths to the VBE/AF and Nucleus directories */

const char * PMAPI PM_getVBEAFPath(void);
const char * PMAPI PM_getNucleusPath(void);
const char * PMAPI PM_getNucleusConfigPath(void);

/* Find the path to a binary portable DLL */

ibool 	PMAPI PM_findBPD(const char *dllname,char *bpdpath);

/* Returns the drive letter of the boot drive for DOS, OS/2 and Windows */

char 	PMAPI PM_getBootDrive(void);

/* Return a network unique machine identifier as a string */

const char * PMAPI PM_getUniqueID(void);

/* Return the network machine name as a string */

const char * PMAPI PM_getMachineName(void);

/* Functions to install and remove the virtual linear framebuffer
 * emulation code. For unsupported DOS extenders and when running under
 * a DPMI host like Windows or OS/2, this function will return a NULL.
 */

ibool 	PMAPI VF_available(void);
void * 	PMAPI VF_init(ulong baseAddr,int bankSize,int codeLen,void *bankFunc);
void 	PMAPI VF_exit(void);

/* Functions to wait for a keypress and read a key for command line
 * environments such as DOS, Win32 console and Unix.
 */

int		PMAPI PM_kbhit(void);
int		PMAPI PM_getch(void);

/* Functions to create either a fullscreen or windowed console on the
 * desktop, and to allow the resolution of fullscreen consoles to be
 * changed on the fly without closing the console. For non-windowed
 * environments (such as a Linux or OS/2 fullscreen console), these
 * functions enable console graphics mode and restore console text mode.
 *
 * The suspend application callback is used to allow the application to
 * save the state of the fullscreen console mode to allow temporary
 * switching to another console or back to the regular GUI desktop. It
 * is also called to restore the fullscreen graphics state after the
 * fullscreen console regains the focus.
 *
 * The device parameter allows for the console to be opened on a different
 * display controllers (0 is always the primary controller).
 */

typedef int (_ASMAPIP PM_saveState_cb)(int flags);

PM_HWND	PMAPI PM_openConsole(PM_HWND hwndUser,int device,int xRes,int yRes,int bpp,ibool fullScreen);
int		PMAPI PM_getConsoleStateSize(void);
void	PMAPI PM_saveConsoleState(void *stateBuf,PM_HWND hwndConsole);
void	PMAPI PM_changeResolution(PM_HWND hwndConsole,int xRes,int yRes,int bpp);
void	PMAPI PM_setSuspendAppCallback(PM_saveState_cb saveState);
void	PMAPI PM_restoreConsoleState(const void *stateBuf,PM_HWND hwndConsole);
void	PMAPI PM_closeConsole(PM_HWND hwndConsole);

/* Functions to modify OS console information */

void 	PMAPI PM_setOSCursorLocation(int x,int y);
void 	PMAPI PM_setOSScreenWidth(int width,int height);

/* Function to emable Intel PPro/PII write combining */

int		PMAPI PM_enableWriteCombine(ulong base,ulong length,uint type);

/* Function to add a path separator to the end of a filename (if not present) */

void	PMAPI PM_backslash(char *filename);

/* Routines to lock and unlock regions of memory under a virtual memory
 * environment. These routines _must_ be used to lock all hardware
 * and mouse interrupt handlers installed, _AND_ any global data that
 * these handler manipulate, so that they will always be present in memory
 * to handle the incoming interrupts.
 *
 * Note that it is important to call the correct routine depending on
 * whether the area being locked is code or data, so that under 32 bit
 * PM we will get the selector value correct.
 */

int 	PMAPI PM_lockDataPages(void *p,uint len);
int 	PMAPI PM_unlockDataPages(void *p,uint len);
int 	PMAPI PM_lockCodePages(__codePtr p,uint len);
int 	PMAPI PM_unlockCodePages(__codePtr p,uint len);

/* Routines to install and remove Real Time Clock interrupt handlers. The
 * frequency of the real time clock can be changed by calling
 * PM_setRealTimeClockFrequeny, and the value can be any power of 2 value
 * from 2Hz to 8192Hz.
 *
 * Note that you _must_ lock the memory containing the interrupt
 * handlers with the PM_lockPages() function otherwise you may encounter
 * problems in virtual memory environments.
 *
 * NOTE: User space versions of the PM library should fail these functions.
 */

ibool	PMAPI PM_setRealTimeClockHandler(PM_intHandler ih,int frequency);
void	PMAPI PM_setRealTimeClockFrequency(int frequency);
void 	PMAPI PM_restoreRealTimeClockHandler(void);

/* Function to post secondary graphics controllers using the BIOS */

ibool 	PMAPI PM_doBIOSPOST(ushort axVal,ulong BIOSPhysAddr,void *mappedBIOS,ulong BIOSLen);

/* Functions to do I/O port manipulation directly from C code. These
 * functions are portable and will work on any processor architecture
 * to access I/O space registers on PCI devices.
 */

uchar	PMAPI PM_inpb(int port);
ushort	PMAPI PM_inpw(int port);
ulong	PMAPI PM_inpd(int port);
void	PMAPI PM_outpb(int port,uchar val);
void	PMAPI PM_outpw(int port,ushort val);
void	PMAPI PM_outpd(int port,ulong val);

/* Functions to determine the I/O port locations for COM and LPT ports.
 * The functions are zero based, so for COM1 or LPT1 pass in a value of 0,
 * for COM2 or LPT2 pass in a value of 1 etc.
 */

int		PMAPI PM_getCOMPort(int port);
int		PMAPI PM_getLPTPort(int port);

/* Internal functions that need prototypes */

void 	PMAPI _PM_getRMvect(int intno, long *realisr);
void 	PMAPI _PM_setRMvect(int intno, long realisr);
void 	PMAPI _PM_freeMemoryMappings(void);

/* Function to override the default debug log file location */

void 	PMAPI PM_setDebugLog(const char *logFilePath);

/* Function to put the process to sleep for the specified milliseconds */

void	PMAPI PM_sleep(ulong milliseconds);

/* Functions to handle loading OS specific shared libraries */

PM_MODULE PMAPI PM_loadLibrary(const char *szDLLName);
void * 	PMAPI PM_getProcAddress(PM_MODULE hModule,const char *szProcName);
void	PMAPI PM_freeLibrary(PM_MODULE hModule);

/* Function to enable IOPL access if required */

int 	PMAPI PM_setIOPL(int iopl);

/* Linux specific functions to save the VGA hardware state */

#ifdef	__LINUX__
void 	PMAPI PM_saveVGAState(void *stateBuf);
void 	PMAPI PM_restoreVGAState(const void *stateBuf);
void 	PMAPI PM_vgaBlankDisplay(void);
void 	PMAPI PM_vgaUnblankDisplay(void);
#endif

/* Call the X86 emulator or the real BIOS in our test harness */

#ifdef	TEST_HARNESS
#define	PM_mapRealPointer(r_seg,r_off)		_PM_imports.PM_mapRealPointer(r_seg,r_off)
#define	PM_getVESABuf(len,rseg,roff)		_PM_imports.PM_getVESABuf(len,rseg,roff)
#define	PM_callRealMode(seg,off,regs,sregs)	_PM_imports.PM_callRealMode(seg,off,regs,sregs)
#define	PM_int86(intno,in,out)				_PM_imports.PM_int86(intno,in,out)
#define	PM_int86x(intno,in,out,sregs)		_PM_imports.PM_int86x(intno,in,out,sregs)
#endif

#ifdef	__cplusplus
}						/* End of "C" linkage for C++	*/
#endif

/* Include OS extensions for interrupt handling */

#if defined(__REALDOS__) || defined(__SMX32__)
#include "pmint.h"
#endif

#endif /* __PMAPI_H */