summaryrefslogtreecommitdiffstats
path: root/contrib/syslinux-4.02/doc/comboot.txt
diff options
context:
space:
mode:
Diffstat (limited to 'contrib/syslinux-4.02/doc/comboot.txt')
-rw-r--r--contrib/syslinux-4.02/doc/comboot.txt1012
1 files changed, 1012 insertions, 0 deletions
diff --git a/contrib/syslinux-4.02/doc/comboot.txt b/contrib/syslinux-4.02/doc/comboot.txt
new file mode 100644
index 0000000..4b4b880
--- /dev/null
+++ b/contrib/syslinux-4.02/doc/comboot.txt
@@ -0,0 +1,1012 @@
+
+ COMBOOT and COM32 files
+
+
+Syslinux supports simple standalone programs, using a file format
+similar to DOS ".com" files. A 32-bit version, called COM32, is also
+provided. A simple API provides access to a limited set of filesystem
+and console functions.
+
+
+ ++++ COMBOOT file format ++++
+
+A COMBOOT file is a raw binary file containing 16-bit code. It should
+be linked to run at offset 0x100, and contain no absolute segment
+references. It is run in 16-bit real mode.
+
+A COMBOOT image can be written to be compatible with MS-DOS. Such a
+file will usually have extension ".com". A COMBOOT file which is not
+compatible with MS-DOS will usually have extension ".cbt".
+
+Before running the program, Syslinux sets up the following fields in
+the Program Segment Prefix (PSP), a structure at offset 0 in the
+program segment:
+
+ Offset Size Meaning
+ 0 word Contains an INT 20h instruction
+ 2 word Contains the paragraph (16-byte "segment" address) at
+ the end of memory available to the program.
+ 128 byte Length of the command line arguments, including the leading
+ space but not including the final CR character.
+ 129 127b Command line arguments, starting with a space and ending
+ with a CR character (ASCII 13).
+
+The program is allowed to use memory between the PSP paragraph (which
+all the CS, DS, ES and SS registers point to at program start) and the
+paragraph value given at offset 2.
+
+On startup, SP is set up to point to the end of the 64K segment, at
+0xfffe. Under DOS it is possible for SP to contain a smaller
+value if memory is very tight; this is never the case under Syslinux.
+
+The program should make no assumptions about what segment address it
+will be loaded at; instead it should look at the segment registers on
+program startup. Both DOS and Syslinux will guarantee CS == DS == ES
+== SS on program start; the program should not assume anything about
+the values of FS or GS.
+
+To exit, a program can either execute a near RET (which will jump to
+offset 0 which contains an INT 20h instruction, terminating the
+program), or execute INT 20h or INT 21h AH=00h or INT 21h AH=4Ch.
+If compatiblity with Syslinux 1.xx is desired, use INT 20h.
+
+
+ ++++ COM32R file format ++++
+
+A COM32R file is a raw binary file containing 32-bit code. It should
+be self-relocating, as it will be loaded by the Syslinux core at any
+4K aligned address. It will be run in flat-memory 32-bit protected
+mode. Under Syslinux, it will be run in CPL 0, however, since it may
+be possible to create a COM32 execution engine that would run under
+something like Linux DOSEMU, it is recommended that the code does not
+assume CPL 0 unless absolutely necessary.
+
+A COM32R program must start with the byte sequence B8 FE 4C CD 21 (mov
+eax,21cd4cfeh) as a magic number.
+
+The COM32R format replaces the earlier COM32 format, which was linked
+to a fixed address (0x101000).
+
+A COM32R file should have extension ".c32".
+
+On startup, CS will be set up as a flat 32-bit code segment, and DS ==
+ES == SS will be set up as the equivalent flat 32-bit data segment.
+FS and GS are reserved for future use and are currently initialized to
+zero. A COM32R image should not assume any particular values of
+segment selectors.
+
+ESP is set up at the end of available memory and also serves as
+notification to the program how much memory is available.
+
+The following arguments are passed to the program on the stack:
+
+ Address Size Meaning
+ [ESP] dword Return (termination) address
+ [ESP+4] dword Number of additional arguments (currently 8)
+ [ESP+8] dword Pointer to the command line arguments (null-terminated string)
+ [ESP+12] dword Pointer to INT call helper function
+ [ESP+16] dword Pointer to low memory bounce buffer
+ [ESP+20] dword Size of low memory bounce buffer
+ [ESP+24] dword Pointer to FAR call helper function (new in 2.05)
+ [ESP+28] dword Pointer to CDECL helper function (new in 3.54)
+ [ESP+32] dword Amount of memory controlled by the Syslinux core (new in 3.74)
+ [ESP+36] dword Pointer to the filename of the com32 module (new in 3.86)
+ [ESP+40] dword Pointer to protected-mode functions (new in 4.00)
+
+The libcom32 startup code loads this into a structure named __com32,
+defined in <com32.h>:
+
+extern struct com32_sys_args {
+ uint32_t cs_sysargs;
+ char *cs_cmdline;
+ void __cdecl(*cs_intcall)(uint8_t, const com32sys_t *, com32sys_t *);
+ void *cs_bounce;
+ uint32_t cs_bounce_size;
+ void __cdecl(*cs_farcall)(uint32_t, const com32sys_t *, com32sys_t *);
+ int __cdecl(*cs_cfarcall)(uint32_t, const void *, uint32_t);
+ uint32_t cs_memsize;
+ const char *cs_name;
+ const struct com32_pmapi *cs_pm;
+} __com32;
+
+The intcall helper function can be used to issue BIOS or Syslinux API
+calls, and takes the interrupt number as first argument. The second
+argument is a pointer to the input register definition, an instance of
+the following structure (available in <com32.h>):
+
+typedef union {
+ uint32_t l;
+ uint16_t w[2];
+ uint8_t b[4];
+} reg32_t;
+
+typedef struct {
+ uint16_t gs; /* Offset 0 */
+ uint16_t fs; /* Offset 2 */
+ uint16_t es; /* Offset 4 */
+ uint16_t ds; /* Offset 6 */
+
+ reg32_t edi; /* Offset 8 */
+ reg32_t esi; /* Offset 12 */
+ reg32_t ebp; /* Offset 16 */
+ reg32_t _unused_esp; /* Offset 20 */
+ reg32_t ebx; /* Offset 24 */
+ reg32_t edx; /* Offset 28 */
+ reg32_t ecx; /* Offset 32 */
+ reg32_t eax; /* Offset 36 */
+
+ reg32_t eflags; /* Offset 40 */
+} com32sys_t;
+
+The third argument is a pointer to the output register definition, an
+instance of the same structure. The third argument can also be zero
+(NULL).
+
+Since BIOS or Syslinux API calls can generally only manipulate data
+below address 0x100000, a "bounce buffer" in low memory, at least 64K
+in size, is available, to copy data in and out.
+
+The farcall helper function behaves similarly, but takes as its first
+argument the CS:IP (in the form (CS << 16) + IP) of procedure to be
+invoked via a FAR CALL.
+
+The cfarcall helper function takes (CS << 16)+IP, a pointer to a stack
+frame, a size of that stack frame, and returns the return value of EAX
+(which may need to be appropriate truncated by the user.)
+
+Starting in version 4.00, some of these API calls are available as
+protected-mode function calls, using the regparm(3) calling convention
+(the first three argumetns in EAX, EDX, ECX; the rest on the stack.)
+Those functions are defined in struct com32_pmapi, defined in
+<syslinux/pmapi.h>.
+
+
+ ++++ SYSLINUX API CALLS +++
+
+Syslinux provides the following API calls. Syslinux 1.xx only
+supported INT 20h - terminate program. [] indicates the first version
+of Syslinux which supported this feature (correctly.)
+
+NOTE: Most of the API functionality is still experimental. Expect to
+find bugs.
+
+
+ ++++ DOS-COMPATIBLE API CALLS ++++
+
+INT 20h [1.48] Terminate program
+INT 21h AH=00h [2.00] Terminate program
+INT 21h AH=4Ch [2.00] Terminate program
+
+ All of these terminate the program.
+
+
+INT 21h AH=01h [2.01] Get Key with Echo
+
+ Reads a key from the console input, with echo to the console
+ output. The read character is returned in AL. Extended
+ characters received from the keyboard are returned as NUL (00h)
+ + the extended character code.
+
+
+INT 21h AH=02h [2.01] Write Character
+
+ Writes a character in DL to the console (video and serial)
+ output.
+
+
+INT 21h AH=04h [2.01] Write Character to Serial Port
+
+ Writes a character in DL to the serial console output
+ (if enabled.) If no serial port is configured, this routine
+ does nothing.
+
+
+INT 21h AH=08h [2.09] Get Key without Echo
+
+ Reads a key fron the console input, without echoing it to the
+ console output. The read character is returned in AL.
+
+
+INT 21h AH=09h [2.01] Write DOS String to Console
+
+ Writes a DOS $-terminated string in DS:DX to the console.
+
+
+INT 21h AH=0Bh [2.00] Check Keyboard
+
+ Returns AL=FFh if there is a keystroke waiting (which can then
+ be read with INT 21h, AH=01h or AH=08h), otherwise AL=00h.
+
+
+INT 21h AH=30h [2.00] Check DOS Version
+
+ This function returns AX=BX=CX=DX=0, corresponding to a
+ hypothetical "DOS 0.0", but the high parts of EAX-EBX-ECX-EDX
+ spell "SYSLINUX":
+
+ EAX=59530000h EBX=4C530000h ECX=4E490000h EDX=58550000h
+
+ This function can thus be used to distinguish running on
+ Syslinux from running on DOS.
+
+
+ ++++ SYSLINUX-SPECIFIC API CALLS ++++
+
+Syslinux-specific API calls are executed using INT 22h, with a
+function number in AX. INT 22h is used by DOS for internal purposes;
+do not execute INT 22h under DOS.
+
+DOS-compatible function INT 21h, AH=30h can be used to detect if the
+Syslinux API calls are available.
+
+Any register not specifically listed as modified is preserved;
+however, future versions of Syslinux may add additional output
+registers to existing calls.
+
+All calls return CF=0 on success, CF=1 on failure. The noted outputs
+apply if CF=0 only unless otherwise noted. All calls clobber the
+arithmetric flags (CF, PF, AF, ZF, SF and OF) but leave all other
+flags unchanged unless otherwise noted.
+
+
+AX=0001h [2.00] Get Version
+
+ Input: AX 0001h
+ Output: AX number of INT 22h API functions available
+ CH Syslinux major version number
+ CL Syslinux minor version number
+ DL Syslinux derivative ID (e.g. 32h = PXELINUX)
+ ES:SI Syslinux version string
+ ES:DI Syslinux copyright string
+
+ This API call returns the Syslinux version and API
+ information.
+
+ Note: before version 3.86, the version string had a leading CR LF
+ and the copyright string had a leading space. The strings might
+ still contain trailing CR and/or LF.
+
+
+AX=0002h [2.01] Write String
+
+ Input: AX 0002h
+ ES:BX null-terminated string
+ Output: None
+
+ Writes a null-terminated string on the console.
+
+
+AX=0003h [2.01] Run command
+
+ Input: AX 0003h
+ ES:BX null-terminated command string
+ Output: Does not return
+
+ This API call terminates the program and executes the command
+ string as if the user had entered it at the Syslinux command
+ line. This API call does not return.
+
+
+AX=0004h [2.01] Run default command
+
+ Input: AX 0004h
+ Output: Does not return
+
+ This API call terminates the program and executes the default
+ command string as if the user had pressed Enter alone on the
+ Syslinux command line. This API call does not return.
+
+
+AX=0005h [2.00] Force text mode
+
+ Input: AX 0005h
+ Output: None
+
+ If the screen was in graphics mode (due to displaying a splash
+ screen using the <Ctrl-X> command in a message file, or
+ similar), return to text mode.
+
+
+AX=0006h [2.08] Open file
+
+ Input: AX 0006h
+ ES:SI null-terminated filename
+ Output: SI file handle
+ EAX length of file in bytes, or -1
+ CX file block size
+
+ Open a file for reading. The exact syntax of the filenames
+ allowed depends on the particular Syslinux derivative.
+
+ The Syslinux file system is block-oriented. The size of a
+ block will always be a power of two and no greater than 16K.
+
+ Note: Syslinux considers a zero-length file to be nonexistent.
+
+ In 3.70 or later, EAX can contain -1 indicating that the file
+ length is unknown.
+
+ 32-BIT VERSION:
+
+ int cs_pm->open_file(const char *filename, struct com32_filedata *data)
+
+ filename - null-terminated filename
+ data - pointer to a file data buffer
+
+ Returns the file handle, or -1 on failure.
+ The file data buffer contains block size and file size.
+
+
+AX=0007h [2.08] Read file
+
+ Input: AX 0007h
+ SI file handle
+ ES:BX buffer
+ CX number of blocks to read
+ Output: SI file handle, or 0 if EOF was reached
+ ECX number of bytes read [3.70]
+
+ Read blocks from a file. Note that the file handle that is
+ returned in SI may not be the same value that was passed in.
+
+ If end of file was reached (SI=0), the file was automatically
+ closed.
+
+ In 3.70 or later, ECX returns the number of bytes read. This
+ will always be a multiple of the block size unless EOF is
+ reached.
+
+ The address of the buffer (ES:BX) should be at least 512-byte
+ aligned. Syslinux guarantees at least this alignment for the
+ COMBOOT load segment or the COM32 bounce buffer.
+
+ Keep in mind that a "file" may be a TFTP connection, and that
+ leaving a file open for an extended period of time may result
+ in a timeout.
+
+ WARNING: Calling this function with an invalid file handle
+ will probably crash the system.
+
+ 32-BIT VERSION:
+
+ size_t cs_pm->read_file(uint16_t *handle, void *buf, size_t blocks)
+
+ handle - file handle (input and output, set to zero on end of file)
+ buf - buffer to write to
+ blocks - number of blocks to read
+
+ Returns number of bytes read, or 0 on failure.
+
+
+AX=0008h [2.08] Close file
+
+ Input: AX 0008h
+ SI file handle
+ Output: None
+
+ Close a file before reaching the end of file.
+
+ WARNING: Calling this function with an invalid file handle
+ will probably crash the system.
+
+ 32-BIT VERSION:
+
+ void cs_pm->close_file(uint16_t handle)
+
+ handle - file handle to close
+
+
+AX=0009h [2.00] Call PXE Stack [PXELINUX ONLY]
+
+ Input: AX 0009h
+ BX PXE function number
+ ES:DI PXE parameter structure buffer
+ Output: AX PXE return status code
+
+ Invoke an arbitrary PXE stack function. On SYSLINUX/ISOLINUX,
+ this function returns with an error (CF=1) and no action is
+ taken. On PXELINUX, this function always returns with CF=0
+ indicating that the PXE stack was successfully invoked; check
+ the status code in AX and in the first word of the data buffer
+ to determine if the PXE call succeeded or not.
+
+ The PXE stack will have the UDP stack OPEN; if you change that
+ you cannot call any of the file-related API functions, and
+ must restore UDP OPEN before returning to PXELINUX.
+
+ PXELINUX reserves UDP port numbers from 49152 to 65535 for its
+ own use; port numbers below that range is available.
+
+
+AX=000Ah [2.00] Get Derivative-Specific Information
+
+ [SYSLINUX, EXTLINUX]
+ Input: AX 000Ah
+ CL 9 (to get a valid return in CL for all versions)
+ Output: AL 31h (SYSLINUX), 34h (EXTLINUX)
+ DL drive number
+ CL sector size as a power of 2 (9 = 512 bytes) [3.35]
+ CH mode [3.73]
+ 1 = CBIOS mode
+ 2 = EBIOS mode
+ ES:BX pointer to partition table entry (if DL >= 80h)
+ FS:SI pointer to initial ES:DI value [3.53]
+ GS:DI pointer to partition offset (QWORD) [4.00]
+
+ Note: This function was broken in EXTLINUX 3.00-3.02.
+
+ On boot, ES:DI is supposed to point to the BIOS $PnP
+ structure, although in practice most operating systems
+ will search for it in memory. However, preserving
+ this while chainloading is probably a good idea.
+
+ Note that FS:SI is a pointer to a memory location
+ containing the original ES:DI value, not the value
+ itself.
+
+
+ [PXELINUX]
+ Input: AX 000Ah
+ Output: AL 32h (PXELINUX)
+ DX PXE API version detected (DH=major, DL=minor)
+ ECX Local IP number (network byte order) [3.85]
+ ES:BX pointer to PXENV+ or !PXE structure
+ FS:SI pointer to original stack with invocation record
+ GS:DI pointer to network information [4.00]
+
+ Note: DX notes the API version detected by PXELINUX,
+ which may be more conservative than the actual version
+ available. For exact information examine the API
+ version entry in the PXENV+ structure, or the API
+ version entries in the ROMID structures pointed from
+ the !PXE structure.
+
+ PXELINUX will use, and provide, the !PXE structure
+ over the PXENV+ structure. Examine the structure
+ signature to determine which particular structure was
+ provided.
+
+ The FS:SI pointer points to the top of the original stack
+ provided by the PXE stack, with the following values
+ pushed at the time PXELINUX is started:
+
+ [fs:si+0] GS <- top of stack
+ [fs:si+2] FS
+ [fs:si+4] ES
+ [fs:si+6] DS
+ [fs:si+8] EDI
+ [fs:si+12] ESI
+ [fs:si+16] EBP
+ [fs:si+20] -
+ [fs:si+24] EBX
+ [fs:si+28] EDX
+ [fs:si+32] ECX
+ [fs:si+36] EAX
+ [fs:si+40] EFLAGS
+ [fs:si+44] PXE return IP <- t.o.s. when PXELINUX invoked
+ [fs:si+46] PXE return CS
+
+ GS:DI points to a structure of the following form:
+
+ [gs:di+0] 4 - IPv4
+ [gs:di+4] My IP
+ [gs:di+8] Boot server IP
+ [gs:di+12] Gateway IP
+ [gs:di+16] Netmask
+
+ [ISOLINUX]
+ Input: AX 000Ah
+ Output: AL 33h (ISOLINUX)
+ DL drive number
+ CL 11 (sector size as a power of 2) [3.35]
+ CH mode [3.73]
+ 0 = El Torito
+ 1 = Hybrid (hard disk), CBIOS mode
+ 2 = Hybrid (hard disk), EBIOS mode
+ ES:BX pointer to El Torito spec packet
+ FS:SI pointer to initial ES:DI value [3.53]
+ GS:DI pointer to partition offset (QWORD) [4.00]
+
+ Note: Some very broken El Torito implementations do
+ not provide the spec packet information. If so, ES:BX
+ may point to all zeroes or to garbage. Call INT 13h,
+ AX=4B01h to obtain the spec packet directly from the
+ BIOS if necessary.
+
+
+AX=000Bh [2.00] Get Serial Console Configuration
+
+ Input: AX 000Bh
+ Output: DX serial port I/O base (e.g. 3F8h = COM1...)
+ CX baud rate divisor (1 = 115200 bps, 2 = 57600 bps...)
+ BX flow control configuration bits (see syslinux.txt)
+ -> bit 15 is set if the video console is disabled
+
+ If no serial port is configured, DX will be set to 0 and the
+ other registers are undefined.
+
+
+AX=000Ch [2.00] Perform final cleanup
+ Input: AX 000Ch
+ DX derivative-specific flags (0000h = clean up all)
+ Output: None
+
+ This routine performs any "final cleanup" the boot loader
+ would normally perform before loading a kernel, such as
+ unloading the PXE stack in the case of PXELINUX. AFTER
+ INVOKING THIS CALL, NO OTHER API CALLS MAY BE INVOKED, NOR MAY
+ THE PROGRAM TERMINATE AND RETURN TO THE BOOT LOADER. This
+ call basically tells the boot loader "get out of the way, I'll
+ handle it from here."
+
+ For COM32 images, the boot loader will continue to provide
+ interrupt and BIOS call thunking services as long its memory
+ areas (0x0800-0xffff, 0x100000-0x100fff) are not overwritten.
+ MAKE SURE TO DISABLE INTERRUPTS, AND INSTALL NEW GDT AND IDTS
+ BEFORE OVERWRITING THESE MEMORY AREAS.
+
+ The permissible values for DX is an OR of these values:
+
+ SYSLINUX: 0000h Normal cleanup
+
+ PXELINUX: 0000h Normal cleanup
+ 0003h Keep UNDI and PXE stacks loaded
+
+ ISOLINUX: 0000h Normal cleanup
+
+ EXTLINUX: 0000h Normal cleanup
+
+ All other values are undefined, and may have different
+ meanings in future versions of Syslinux.
+
+
+AX=000Dh [2.08] Cleanup and replace bootstrap code
+ Input: AX 000Dh
+ DX derivative-specific flags (see previous function)
+ EDI bootstrap code (linear address, can be in high memory)
+ ECX bootstrap code length in bytes (must fit in low mem)
+ EBX(!) initial value of EDX after bootstrap
+ ESI initial value of ESI after bootstrap
+ DS initial value of DS after bootstrap
+ Output: Does not return
+
+ This routine performs final cleanup, then takes a piece of
+ code, copies it over the primary bootstrap at address 7C00h,
+ and jumps to it. This can be used to chainload boot sectors,
+ MBRs, bootstraps, etc.
+
+ Normal boot sectors expect DL to contain the drive number,
+ and, for hard drives (DL >= 80h) DS:SI to contain a pointer to
+ the 16-byte partition table entry. The memory between
+ 600h-7FFh is available to put the partition table entry in.
+
+ For PXELINUX, if the PXE stack is not unloaded, all registers
+ (except DS, ESI and EDX) and the stack will be set up as they
+ were set up by the PXE ROM.
+
+
+AX=000Eh [2.11] Get configuration file name
+ Input: AX 0000Eh
+ Output: ES:BX null-terminated file name string
+
+ Returns the name of the configuration file. Note that it is
+ possible that the configuration file doesn't actually exist.
+
+
+AX=000Fh [3.00] Get IPAPPEND strings [PXELINUX]
+ Input: AX 000Fh
+ Output: CX number of strings (currently 2)
+ ES:BX pointer to an array of NEAR pointers in
+ the same segment, one for each of the above
+ strings
+
+ Returns the same strings that the "ipappend" option would have
+ added to the command line, one for each bit of the "ipappend"
+ flag value, so entry 0 is the "ip=" string and entry 1 is the
+ "BOOTIF=" string.
+
+
+AX=0010h [3.00] Resolve hostname [PXELINUX]
+ Input: AX 0010h
+ ES:BX pointer to null-terminated hostname
+ Output: EAX IP address of hostname (zero if not found)
+
+ Queries the DNS server(s) for a specific hostname. If the
+ hostname does not contain a dot (.), the local domain name
+ is automatically appended.
+
+ This function only return CF=1 if the function is not
+ supported. If the function is supported, but the hostname did
+ not resolve, it returns with CF=0, EAX=0.
+
+ The IP address is returned in network byte order, i.e. if the
+ IP address is 1.2.3.4, EAX will contain 0x04030201. Note that
+ all uses of IP addresses in PXE are also in network byte order.
+
+
+AX=0011h [3.05] Obsoleted in 3.80
+
+
+AX=0012h [3.50] Cleanup, shuffle and boot
+ Input: AX 0012h
+ DX derivative-specific flags (see function 000Ch)
+ ES:DI shuffle descriptor list (must be in low memory)
+ CX number of shuffle descriptors
+ EBX(!) initial value of EDX after bootstrap
+ ESI initial value of ESI after bootstrap
+ DS initial value of DS after bootstrap
+ EBP CS:IP of routine to jump to
+ Output: Does not return
+ (if CX is too large the routine returns with CF=1)
+
+ This routine performs final cleanup, then performs a sequence
+ of copies, and jumps to a specified real mode entry point.
+ This is a more general version of function 000Dh, which can
+ also be used to load other types of programs.
+
+ The copies must not touch memory below address 7C00h.
+
+ ES:DI points to a list of CX descriptors each of the form:
+
+ Offset Size Meaning
+ 0 dword destination address
+ 4 dword source address
+ 8 dword length in bytes
+
+ The copies are overlap-safe, like memmove().
+
+ Starting in version 3.50, if the source address is -1
+ (FFFFFFFFh) then the block specified by the destination
+ address and the length is set to all zero.
+
+ Starting in version 3.50, if the destination address is -1
+ (FFFFFFFFh) then the data block is loaded as a new set of
+ descriptors, and processing is continued (and unprocessed
+ descriptors are lost, this is thus typically only used as the
+ last descriptor in a block.) The block must still fit in the
+ internal descriptor buffer (see function 0011h), but can, of
+ course, itself chain another block.
+
+
+ Normal boot sectors expect DL to contain the drive number,
+ and, for hard drives (DL >= 80h) DS:SI to contain a pointer to
+ the 16-byte partition table entry. The memory between
+ 600h-7FFh is available to put the partition table entry in.
+
+ For PXELINUX, if the PXE stack is not unloaded, all registers
+ (except DS, ESI and EDX) and the stack will be set up as they
+ were set up by the PXE ROM.
+
+ This interface was probably broken before version 3.50.
+
+
+AX=0013h [3.08] Idle loop call
+ Input: AX 0013h
+ Output: None
+
+ Call this routine while sitting in an idle loop. It performs
+ any periodic activities required by the filesystem code. At
+ the moment, this is a no-op on all derivatives except
+ PXELINUX, where it executes PXE calls to answer ARP queries.
+
+ Starting with version 3.10, this API call harmlessly returns
+ failure (CF=1) if invoked on a platform which does not need
+ idle calls. Additionally, it's safe to call this API call on
+ previous Syslinux versions (2.00 or later); it will just
+ harmlessly fail. Thus, if this call returns failure (CF=1),
+ it means that there is no technical reason to call this
+ function again, although doing so is of course safe.
+
+
+AX=0014h [3.10] Local boot [PXELINUX, ISOLINUX]
+ Input: AX 0014h
+ DX Local boot parameter
+ Output: Does not return
+
+ This function invokes the equivalent of the "localboot"
+ configuration file option. The parameter in DX is the same
+ parameter as would be entered after "localboot" in the
+ configuration file; this parameter is derivative-specific --
+ see syslinux.txt for the definition.
+
+
+AX=0015h [3.10] Get feature flags
+ Input: AX 0015h
+ Output: ES:BX pointer to flags in memory
+ CX number of flag bytes
+
+ This function reports whether or not this Syslinux version and
+ derivative supports specific features. Keep in mind that
+ future versions might have more bits; remember to treat any
+ bits beyond the end of the array (as defined by the value in
+ CX) as zero.
+
+ Currently the following feature flag is defined:
+
+ Byte Bit Definition
+ ----------------------------------------------------
+ 0 0 Local boot (AX=0014h) supported
+ 1 Idle loop call (AX=0013h) is a no-op
+
+ All other flags are reserved.
+
+
+AX=0016h [3.10] Run kernel image
+ Input: AX 0016h
+ DS:SI Filename of kernel image (zero-terminated string)
+ ES:BX Command line (zero-terminated string)
+ ECX IPAPPEND flags [PXELINUX]
+ EDX Type of file (since 3.50)
+ Output: Does not return if successful; returns with CF=1 if
+ the kernel image is not found.
+
+ This function is similiar to AX=0003h Run command, except that
+ the filename and command line are treated as if specified in a
+ KERNEL and APPEND statement of a LABEL statement, which means:
+
+ - The filename has to be exact; no variants are tried;
+ - No global APPEND statement is applied;
+ - ALLOWOPTIONS and IMPLICIT statements in the configuration
+ file do not apply. It is therefore important that the
+ COMBOOT module doesn't allow the end user to violate the
+ intent of the administrator.
+
+ Additionally, this function returns with a failure if the file
+ doesn't exist, instead of returning to the command line. (It
+ may still return to the command line if the image is somehow
+ corrupt, however.)
+
+ The file types are defined as follows:
+
+ Equivalent
+ EDX Config Extensions Type of file
+ 0 KERNEL Determined by filename extension
+ 1 LINUX none Linux kernel image
+ 2 BOOT .bs .bin Bootstrap program
+ 3 BSS .bss Boot sector with patch [SYSLINUX]
+ 4 PXE .0 PXE Network Bootstrap Prog [PXELINUX]
+ 5 FDIMAGE .img Floppy disk image [ISOLINUX]
+ 6 COMBOOT .com .cbt 16-bit COMBOOT program
+ 7 COM32 .c32 COM32 program
+ 8 CONFIG Configuration file
+
+
+AX=0017h [3.30] Report video mode change
+ Input: AX 0017h
+ BX Video mode flags
+ Bit 0: graphics mode
+ Bit 1: non-default mode
+ Bit 2: VESA mode
+ Bit 3: text functions not supported
+ CX For graphics modes, pixel columns
+ DX For graphics modes, pixel rows
+ Output: None
+
+ This function is used to report video mode changes to
+ Syslinux. It does NOT actually change the video mode, but
+ rather, allows Syslinux to take appropriate action in response
+ to a video mode change. Modes that cannot be exited either
+ with the conventional BIOS mode set command (INT 10h, AH=00h)
+ or the VESA VBE mode set command (INT 10h, AX=4F02h) should
+ not be used.
+
+ This function returns with a failure if BX contains any bits
+ which are undefined in the current version of Syslinux.
+
+ The following bits in BX are currently defined:
+
+ Bit 0: graphics mode
+
+ Indicates that the mode is a graphics mode, as opposed
+ to a text mode.
+
+ Bit 1: non-standard mode
+
+ A non-standard mode is any mode except text mode and
+ graphics mode 0012h (VGA 640x480, 16 color.)
+
+ Bit 2: VESA mode
+
+ This mode is a VESA mode, and has to be exited with
+ the VESA VBE API (INT 10h, AX=4F02h) as opposed to the
+ conventional BIOS API (INT 10h, AH=00h).
+
+ Bit 3: Text functions not supported
+
+ This indicates that the BIOS text output functions
+ (INT 10h, AH=02h, 03h, 06h, 09h, 0Eh, 11h) don't work.
+ If this bit is set, Syslinux will reset the mode
+ before printing any characters on the screen.
+
+ This is common for VESA modes.
+
+
+AX=0018h [3.30] Query custom font
+ Input: AX 0018h
+ Output: AL Height of custom font in scan lines, or zero
+ ES:BX Pointer to custom font in memory
+
+ This call queries if a custom display font has been loaded via
+ the "font" configuration file command. If no custom font has
+ been loaded, AL contains zero.
+
+
+AX=0019h [3.50] Read disk [SYSLINUX, ISOLINUX, EXTLINUX]
+ Input: AX 0019h
+ EDX Sector number (LSW)
+ ESI Sector number (MSW) [4.00]
+ EDI Reserved - MUST BE ZERO
+ CX Sector count
+ ES:BX Buffer address
+ Output: None
+
+ Read disk blocks from the active filesystem (partition); for
+ disks, sector number zero is the boot sector. For ISOLINUX,
+ this call reads the CD-ROM.
+
+ For compatiblity with all systems, the buffer should
+ *neither* cross 64K boundaries, *nor* wrap around the segment.
+
+ This routine reports "boot failed" (and does not return) on
+ disk error.
+
+ Note: for ISOLINUX in hybrid mode, this call uses simulated
+ 2048-byte CD-ROM sector numbers.
+
+
+AX=001Ah [3.50] Obsoleted in 3.80
+
+
+AX=001Bh [3.50] Obsoleted in 3.80
+
+
+AX=001Ch [3.60] Get pointer to auxilliary data vector
+ Input: AX 001Ch
+ Output: ES:BX Auxilliary data vector
+ CX Size of the ADV (currently 500 bytes)
+
+ The auxillary data vector is a tagged data structure used
+ to carry a small amount of information (up to 500 bytes) from
+ one boot to another.
+
+
+AX=001Dh [3.60] Write auxilliary data vector
+ Input: AX 001Dh
+ Output: None
+
+ Write the auxilliary data vector back to disk. Returns
+ failure for non-disk-based derivatives unless the "auxdata"
+ configuration command is used to specify a disk location
+ (not yet implemented.)
+
+ In a future version, PXELINUX may end up attempting to save
+ the ADV on the server via TFTP write.
+
+
+AX=001Eh [3.74] Keyboard remapping table
+ Input: AX 001Eh
+ DX 0000h - all other values reserved
+ Output: AX format version (1)
+ CX length in bytes (256)
+ ES:BX pointer to keyboard table
+
+ This call queries the keyboard remapping table. For the current
+ version, the format code is always 1 and the length is always
+ 256. This version can be updated simply by overwriting the version
+ in memory; this may not be true in the future.
+
+
+AX=001Fh [3.74] Get current working directory
+ Input: AX 0001Fh
+ Output: ES:BX null-terminated directory name string
+
+ Returns the current working directory.
+
+
+AX=0020h [3.74] Obsoleted in 4.00
+AX=0021h [3.74] Obsoleted in 4.00
+AX=0022h [3.74] Obsoleted in 4.00
+
+ These three functions provided opendir/readdir/closedir
+ functionality in the late 3.xx series. They have been
+ replaced by the protected-mode interface.
+
+
+AX=0023h [3.80] Get shuffler parameters
+ Input: AX 0023h
+ Output: CX size of shuffler "safe area" in bytes
+ Other registers reserved for future use
+
+ This call gives the size of the required shuffler "safe area",
+ in bytes; for call 0024h. In the future, it may provide
+ additional parameters.
+
+
+AX=0024h [3.80] Cleanup, shuffle and boot, raw version
+ Input: AX 0024h
+ DX derivative-specific flags (see function 000Ch)
+ EDI shuffle descriptor list safe area
+ ESI shuffle descriptor list source
+ ECX byte count of shuffle descriptor list
+ Output: Does not return
+
+ This routine performs final cleanup, then performs a sequence
+ of copies, and jumps to a specified real mode entry point.
+ This is a more general version of function 000Dh, which can
+ also be used to load other types of programs.
+
+ Unlike previous obsolete versions of this function, there are
+ no restrictions that copies must not touch memory below
+ address 7C00h. Either the shuffle descriptor list or the safe
+ area (or both) may be located in high memory.
+
+ ESI points to a list of descriptors each of the form:
+
+ Offset Size Meaning
+ 0 dword destination address
+ 4 dword source address (-1 = zero)
+ 8 dword length in bytes (0 = end of list)
+
+ The copies are overlap-safe, like memmove().
+
+ Before actually executing the move list, the list is moved to
+ the address specified in EDI. The caller is responsibe to
+ ensure that the moved descriptor list plus a "safe area"
+ immediately afterwards (the size of which is specified by
+ function 0023h) is not disturbed by the copy sequence. It is,
+ however, safe to overwrite descriptors already consumed.
+
+ If the source address is -1 (FFFFFFFFh) then the block
+ specified by the destination address and the length is set to
+ all zero.
+
+ The list is terminated by an entry with length 0. For that
+ entry, the destination is used as an entry point, and the
+ source represents the type of entry point:
+
+ 0 16-bit protected mode (dst is CS.base)
+ 1 Flat 32-bit protected mode (dst is EIP)
+
+ This routine does not set up any GPR register state
+ whatsoever, including stack. It is the responsibility of the
+ caller to make sure the entry point provided sets up any
+ registers needed.
+
+ For mode 0 (16-bit real mode), EAX will contain CR0 with bit 0
+ masked out, suitable for loading into CR0 to immediately enter
+ real mode. Note: if real-mode entry is planned,
+ (CS.base & 0xfff0000f) should == 0 for compatibility with KVM,
+ and possibly other virtualization solutions.
+
+ In both mode 0 and mode 1, the data segments will be loaded
+ with read/write data segments, matching the respective code
+ segment. For mode 0, B=0 and the limits will be 64K, for mode
+ 1, B=1 and the limits will be 4 GB.
+
+
+ ++++ 32-BIT ONLY API CALLS ++++
+
+void *pm_cs->lmalloc(size_t bytes)
+
+ Allocate a buffer in low memory (below 1 MB).
+
+
+void pm_cs->lfree(void *ptr)
+
+ Free a buffer allocated with pm_cs->lmalloc().
+
+
+DIR *pm_cs->opendir(const char *pathname)
+
+ Open a directory.
+
+
+struct dirent *pm_cs->readdir(DIR *dir)
+
+ Read an entry from a directory. The entry is returned in a
+ static buffer.
+
+
+int pm_cs->closedir(DIR *dir)
+
+ Close a directory.