| |
| 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. |