aboutsummaryrefslogtreecommitdiffstats
path: root/doc/comboot.txt
diff options
context:
space:
mode:
authorH. Peter Anvin <hpa@zytor.com>2008-03-02 12:01:11 -0800
committerH. Peter Anvin <hpa@zytor.com>2008-03-02 12:01:11 -0800
commitdbfc8677d54259b66dbfa52dfdcb861abb301569 (patch)
treeb38a7140d559659284c5cd9e36211728ac2fda40 /doc/comboot.txt
parent815e226e01e6272afb4d2356cdc55b34294bb218 (diff)
parente8004fc8eec23ad151fda3664f7abac1a7391373 (diff)
downloadsyslinux-elf-dbfc8677d54259b66dbfa52dfdcb861abb301569.tar.gz
syslinux-elf-dbfc8677d54259b66dbfa52dfdcb861abb301569.tar.xz
syslinux-elf-dbfc8677d54259b66dbfa52dfdcb861abb301569.zip
Merge commit 'origin/master' into nolen
Diffstat (limited to 'doc/comboot.txt')
-rw-r--r--doc/comboot.txt903
1 files changed, 903 insertions, 0 deletions
diff --git a/doc/comboot.txt b/doc/comboot.txt
new file mode 100644
index 00000000..42078ed5
--- /dev/null
+++ b/doc/comboot.txt
@@ -0,0 +1,903 @@
+
+ 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.
+
+
+ ++++ COM32 file format ++++
+
+A COM32 file is a raw binary file containing 32-bit code. It should
+be linked to run at address 0x101000, and should not contain any
+segment references. 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.
+
+It is highly recommended that every COM32 program begins with the byte
+sequence B8 FF 4C CD 21 (mov eax,21cd4cffh) as a magic number.
+
+A COM32 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 COM32 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 5)
+ [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)
+
+This corresponds to the following C prototype, available in the file
+com32/include/com32.h:
+
+/* The standard prototype for _start() */
+int _start(unsigned int __nargs,
+ char *__cmdline,
+ void (*__intcall)(uint8_t, com32sys_t *, com32sys_t *),
+ void *__bounce_ptr,
+ unsigned int __bounce_len,
+ void (*__farcall)(uint32_t, com32sys_t *, com32sys_t *),
+ int (*__cfarcall)(uint32_t, void *, size_t)
+ );
+
+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.)
+
+
+ ++++ 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.
+
+
+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.
+
+
+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.
+
+
+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.
+
+
+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]
+ ES:BX pointer to partition table entry (if DL >= 80h)
+ FS:SI pointer to initial ES:DI value [3.53]
+
+ 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)
+ ES:BX pointer to PXENV+ or !PXE structure
+ FS:SI pointer to original stack with invocation record
+
+ 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
+
+
+ [ISOLINUX]
+ Input: AX 000Ah
+ Output: AL 33h (ISOLINUX)
+ DL drive number
+ CL 11 (sector size as a power of 2) [3.35]
+ ES:BX pointer to El Torito spec packet
+ FS:SI pointer to initial ES:DI value [3.53]
+
+ 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.
+
+ This call gives information specific to a particular SYSLINUX
+ derivative. The value returned in AL is the same as is
+ returned in DL by INT 22h AX=0001h.
+
+
+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: 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] Maximum number of shuffle descriptors
+ Input: AX 0011h
+ Output: CX maximum number of descriptors
+
+ This routine reports the maximum number of shuffle descriptors
+ permitted in a call to functions 0012h, 001Ah and 001Bh.
+
+ This is guaranteed to be at least 64. For the current
+ version, this is 682 for all derivatives.
+
+
+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
+ ESI Reserved - MUST BE ZERO
+ 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.
+
+
+AX=001Ah [3.50] Cleanup, shuffle and boot to flat protected mode
+ Input: AX 001Ah
+ DX derivative-specific flags (see function 000Ch)
+ ES:DI shuffle descriptor list (must be in low memory)
+ CX number of shuffle descriptors
+ DS:SI pointer to register values (must be in low memory)
+ 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 protected mode entry point.
+ This is otherwise similar to function 0012h; see that function
+ for the meaning of ES:DI and CX.
+
+ DS:SI points to the initial register file, which is a structure
+ of 9 dwords (available in <syslinux/bootpm.h>):
+
+ struct syslinux_pm_regs {
+ uint32_t eax; /* Offset 0 */
+ uint32_t ecx; /* Offset 4 */
+ uint32_t edx; /* Offset 8 */
+ uint32_t ebx; /* Offset 12 */
+ uint32_t esp; /* Offset 16 */
+ uint32_t ebp; /* Offset 20 */
+ uint32_t esi; /* Offset 24 */
+ uint32_t edi; /* Offset 28 */
+
+ uint32_t eip; /* Offset 32 */
+ };
+
+ Protected mode is entered with all data segments set up as a
+ flat 32-bit read/write segment and the code segment a flat 32-bit
+ read/execute segment. Interrupts and paging is off, CPL=0, DF=0;
+ however, GDT, LDT and IDT are undefined, so it is up to the
+ invoked code to set new descriptor tables to its liking.
+
+
+AX=001Bh [3.50] Cleanup, shuffle and boot to real mode
+ Input: AX 001Bh
+ DX derivative-specific flags (see function 000Ch)
+ ES:DI shuffle descriptor list (must be in low memory)
+ CX number of shuffle descriptors
+ DS:SI pointer to register values (must be in low memory)
+ 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 entry point.
+ This is similar to function 0012h but allow more control over
+ the initial register state; see that function for the meaning of
+ ES:DI and CX.
+
+ DS:SI points to the initial register file, which is a structure
+ in the following format (available in <syslinux/bootrm.h>;
+ note that this is a completely different structure from the
+ com32sys_t structure described at the top of this document!):
+
+ struct syslinux_rm_regs {
+ uint16_t es; /* Offset 0 */
+ uint16_t _unused_cs; /* Offset 2 */
+ uint16_t ds; /* Offset 4 */
+ uint16_t ss; /* Offset 6 */
+ uint16_t fs; /* Offset 8 */
+ uint16_t gs; /* Offset 10 */
+
+ reg32_t eax; /* Offset 12 */
+ reg32_t ecx; /* Offset 16 */
+ reg32_t edx; /* Offset 20 */
+ reg32_t ebx; /* Offset 24 */
+ reg32_t esp; /* Offset 28 */
+ reg32_t ebp; /* Offset 32 */
+ reg32_t esi; /* Offset 36 */
+ reg32_t edi; /* Offset 40 */
+
+ uint16_t ip; /* Offset 44 */
+ uint16_t cs; /* Offset 46 */
+ };
+
+ Interrupts are off and DF=0 on entry.
+
+
+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.