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.2 2000/02/08 13:13:22 eich Exp $
|
