diff options
Diffstat (limited to 'contrib/syslinux-4.02/doc/comboot.txt')
| -rw-r--r-- | contrib/syslinux-4.02/doc/comboot.txt | 1012 |
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. |