INT10 X86 Real Mode executor ============================= PRELIMINARY INT10 is a XFree86 module for soft-booting and executing real mode int10 BIOS calls. The BIOS call code is largely untested, yet. 1. Usage ======== To use the int10 module in a driver the header file xfree86/os-support/int10/xf86int10.h must be included. a. Initialization ----------------- The int10-executer gets initialized by calling: xf86Int10InfoPtr xf86InitInt10(int entityIndex); The function will soft-boot any non-primary device and return a pointer to a xf86Int10InfoRec on success. If anything fails or if int10 execution is disabled by an option in the device section NULL will be returned. The driver should store this pointer for later calls to other int10 module functions. b. Memory allocation -------------------- To allocate memory in the real mode execution environment void * xf86Int10AllocPages(xf86Int10InfoPtr pInt,int num, int *off); can be called. It allocates num consecutive pagesize chunks. It returns the address of the allocated area. off is set to its offset in the real mode memory space. void xf86Int10FreePages(xf86Int10InfoPtr pInt, void *pbase, int num); Is used to free num pages beginning at pbase. c. Doing int10 BIOS calls ------------------------- The BIOS call is executed by calling: void xf86ExecX86int10(xf86Int10InfoPtr pInt); The number of the interrupt (normally 10) and the initial values of the ax, bx, cx, dx, si, di and es x86-CPU registers can be set in the xf86Int10InfoRec passed to the function. On return this structure contains the exit values of the registers listed above and the CPU flag register. d. De-initializing ----------------- If no further int10 calls are required for a certain chipset the driver should call: void xf86FreeInt10(xf86Int10InfoPtr pInt); to free the memory allocated for real mode int10 calls. 2. Porting issues ================= The int10 real mode executor is designed to run on top of various x86 CPU emulators as well as in vm86 mode of a real x86 CPU. If used with a CPU emulator the emulator and CPU specific interfaces can be held separate thus requiring minimal efforts to port the int10 module to new platforms. Currently an interface to the x86emu real mode emulator is provided. Since details of setting up and running the vm86 mode is platform dependent both the platform dependent environment and the emulation layer have to be ported. Several helper functions are provided for that. A CPU emulator should meet certain requirements to be usable for the INT10 executor: 1. It must trap calls to intXX instructions and pass execution to an external function which is allowed to modify CPU registers including the instruction pointer (IP) before returning to the emulator for continuing execution. When the external function is called the IP must point to the instruction past the intXX call. 2. The emulator should use externally provided functions to handle PIO. 3. The emulator should be able to use externally provided functions to access memory from the real mode memory environment. Note, that the vm86 mode usually requires one hunk of consecutive memory starting at address 0 in the process virtual memory space. Thus if this mode is to be used, the OS environment has to be able to provide that, ie. it must be able to remap the processes virtual memory space onto itself. If the emulator is able to handle memory access thru externally provided functions the real mode process memory can be located anywhere in the processes virtual memory. It does not even have to be consecutive. 4. The executor should terminate on encountering a 'hlt' instruction. Functions to implement: To simplify development the code has been split into a general setup part and an emulator specific one. A generic setup code is provided in generic.c. It should be usable with any emulator satisfying the conditions mentioned above. Therefore the following section on int10 setup may be skipped when porting int10 to new emulator. If the vm86() is to be used no memory access functions can be used. Therefore the layout of the real mode memory image has to meet certain requirements. Therefore when porting to other platforms a new setup code may have to be designed, too. The following section will give guidelines how this may be done. A sample implementation using SysV IPC to map the appropriate real mode memory image to address 0 in virtual address space just prior to execution may be found in xfree86/os-support/linux/int10/linux.c. On non-PC like platforms emulation of certain PC features such as initialization of BIOS int vectors, sys_BIOS constants or PCI config method 1 can be turned on by defining _PC. I. Setup Code ------------- This sets up the real mode memory image, calls the emulator to POST the chipset if required and maintains memory allocations in real mode address space. 1. xf86Int10InfoPtr xf86InitInt10(int entityIndex); This function should first find the screen assigned to the entity carrying entitiyIndex and then call Bool int10skip(ScrnInfoPtr pScrn) to find out if the user has requested not to initialize int10. If so xf86InitInt10() should return NULL. Otherwise an xf86Int10InfoRec should be allocated. This structure contains the following fields: a. int entityIndex - index of the entity whose BIOS is to be executed. b. int scrnIndex - index of the screen assigned the entity. c. pointer cpuRegs - pointer to a emulator/vm86-mode private structure. May hold cpu register values for the emulator. d. CARD16 BIOSseg - Video BIOS segment address. e. pointer private - pointer to a os specific data structure. f. struct _int10Mem* - pointer to a structure to hold the memory access functions for use by an emulator. g. int num - number of the int to be called. h. int ax..es,flags - CPU register values to pass to int-call. The Init function should initialize a-f. To initialize the emulator specific execute environment the function Bool xf86Int10ExecSetup(xf86Int10InfoPtr pInt) should be called. If this function returns FALSE any already allocated memory should be freed and xf86Int10Init(0 should exit returning NULL. If the platform has a PC like system BIOS it may be copied to or mapped into memory locations SYS_BIOS to SYS_SIZE-1 of the real mode memory environment of this process. Otherwise the helper function: int setup_system_bios(CARD32 base_addr); may be called to set up a rudimentary system BIOS sufficient to be used to boot video BIOSes. base_addr specifies the virtual address corresponding to SYS_BIOS in the real mode environment. If a PC-like int vector and BIOS data area is available it should be copied to 0 to LOW_PAGE_SIZE of the entities real mode environment. In this case the video interrupt related entries should be reset for all non-primary cards by calling: void reset_int_vect(xf86Int10InfoPtr pInt); To initialize the correct video BIOS entry points the BIOS must be warm-booted. If no PC-like int vector is available one can be set up by calling void setup_int_vect(xf86Int10InfoPtr pInt); In this case the video BIOS has to be warm-booted always. If the video BIOS for this entity has been installed during boot it may be mapped (or copied) directly to the correct address in the real mode memory environment. Otherwise int mapPciRom(xf86Int10InfoPtr pInt, unsigned char * address); should be called to copy the BIOS image from PCI ROM. 'address' specifies the address this image should be copied to. Sufficient space to hold an entire BIOS image should be allocated prior to calling mapPciRom(). This function will return the size of the BIOS image in bytes if it was able to successfully copy the image and 0 otherwise. To create a well defined point to exit the softbooter void set_return_trap(xf86Int10Ptr pInt); may be called. It sets up a 'hlt' instruction in the emulator memory just above the BIOS variable area. Before entering real mode execution this address will be pushed onto the return stack. If the BIOS needs to be warm-booted this should be done before leaving xf86InitInt10() by setting num in the xf86Int10InfoRec to 0xe6 and calling void xf86ExecX86int10(xf86Int10IfoPtr pInt); The implementation of this function will be discussed below. This function should be wrapped by calls to void LockLegacyVGA(screen, legacyVGAPtr vga); and void UnlockLegacyVGA(screen, legacyVGAPtr vga); The struct vga is used to hold the state of the legacy VGA access registers if a legacy VGA device exists. xf86InitInt10() should return a pointer to the xf86Int10InfoRec allocated. 2. Bool MapCurrentInt10(xf86Int10InfoPtr pInt); In case a platform specific mapping has to be performed to map the memory allocated for the real mode memory environment into a specific location prior to executing the x86 real mode code a function Bool MapCurrentInt10(xf86Int10InfoPtr pInt); has to be provided. It will be called by a helper function whenever the active entity changes. If the vm86 mode is used it is most likely that the 1MB real mode memory space located somewhere in the processes virtual memory will have to be remapped to address 0 of the virtual memory space. 3. void xf86FreeInt10(xf86Int10InfoPtr pInt); To free all memory allocated for video BIOS calls of a specific entity the function void xf86FreeInt10(xf86Int10InfoPtr pInt); should be provided. If the entity to be freed was mapped by MapCurrentInt10() this mapping needs to be undone also. 4. void * xf86Int10AllocPages(xf86Int10InfoPtr pInt,int num, int *off) void xf86Int10FreePages(xf86Int10InfoPtr pInt, void *pbase, int num) xf86Int10AllocPages() should allocate 'num' consecutive page-size chunks of memory. In real mode memory space this range needs to occupy consecutive addresses, too. The function must return the address of this memory. The offset in real mode memory needs to be returned in 'off'. If no block of 'num' pages are available the function should return NULL. xf86Int10FreePages() will free the 'num' pages starting at 'pbase'. 'num' is equal to the number of pages allocated by a single xf86Int10AllocatePages() call. 'pbase' is the address of the range previously returned by xf86Int10AllocatePages(). II. Emulator specific functions ------------------------------- 1. Bool xf86Int10ExecSetup(xf86Int10InfoPtr pInt); This function will be called from xf86InitInt10(). It may be used to set up the static emulator specific part of the real mode environment. On success it should return TRUE. 2. xf86ExecX86int10(xf86Int10InfoPtr pInt); This function gets called to execute an int call. It may call the helper function: void setup_int(xf86Int10InfoPrt pInt); to copy the register values to the emulator specific locations and to set up the non-static real mode execution environment. On return from setup_int() 'Int10Current' holds a pointer to the current xf86Int10InfoRec. It should start execution by calling Bool int_handler(xf86Int10InfoPtr pInt); and if this function returns TRUE it should call whatever necessary to continue execution until a 'hlt' instruction is encountered. To copy the resulting register values back to the xf86Int10InfoRec structure void finish_int(xf86Int10InfoPtr pInt); should be called. Helper functions are provided to aid the implementation of a vm86 call: Bool vm86_GP_fault(xf86Int10InfoPtr pInt); This function handles instructions which cause a vm86 call to trap. PIO access is handled by the in/out calls as defined in compiler.h. Optionally the PIO instructions can be logged by defining PRINT_PORT in xf86int10.h. This is meant for debugging purposes. Unknown instructions and 'hlt' cause vm86_GP_fault() to return FALSE. Otherwise TRUE is returned. Note: This function is currently based on the Linux vm86 call. It might have to be modified or even rewritten for other OS. So your milage may vary. Functions to dump memory, code, xf86 CPU register values and stack are also provided. Take a look at helper.c To view a memory range the function void dprint(unsigned long start, unsigned long size) is provided. The use should be self explanatory. Register and memory access functions are provided in helper_mem.c. The PIO register access functions can trap access to PCI config space access register (config method 1) if _PC is not defined. A header file 'defines.h' is required to define OS/emulator specific ways to access memory and xf86 CPU registers: Defines need to be provided for memory byte/work/long read/write access (MEM_RB(name,addr),MEM_RW(name,addr),MEM_RL(name,addr), MEM_WB(name,addr,val),MEM_WL(name,addr,val),MEM_WL(name,addr,val)) of the real mode memory environment. 'name' will contain a pointer to the current xf86Int10InfoRec. Currently defines are available for vm86-mode under Linux and x86emu. They may be activated by defining _X86EMU or _VM86_LINUX respectively. Note: Emulators usually are not able to pass this pointer when calling memory access functions. In this case a global variable should be defined which can hold this pointer. This variable can be set in MapCurrentInt10(). It also must be set in xf86InitInt10() if this function calls the memory access functions either directly or by calling xf86ExecX86int10(pInt). Defines to access the emulator specific xf86 CPU register locations are also required: X86_EAX,...,X86_EFLAGS for access of the full 32 bit registers, X86_AX...X86_FLAGS for access of the 16 bit registers and XF86_AL,XF86_BL,XF86_CL,XF86_DL to access the lower byte of the AX,BX,CX and DX register. $XFree86: xc/programs/Xserver/hw/xfree86/int10/INT10.HOWTO,v 1.3 2001/04/30 14:34:57 tsi Exp $