From 7cfa9099ea0aa53c6e3a24c9902b141d0aca6369 Mon Sep 17 00:00:00 2001 From: "H. Peter Anvin" Date: Thu, 28 Feb 2008 16:04:08 -0800 Subject: Rename text documentation from *.doc to *.txt Rename plaintext documentation from doc/*.doc to doc/*.txt, to avoid the chronic problem of web sites thinking they're in MS-Word format. Sigh. As if Microsoft somehow had a monopoly on the word "document". --- doc/comboot.txt | 895 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 895 insertions(+) create mode 100644 doc/comboot.txt (limited to 'doc/comboot.txt') diff --git a/doc/comboot.txt b/doc/comboot.txt new file mode 100644 index 00000000..46afc64c --- /dev/null +++ b/doc/comboot.txt @@ -0,0 +1,895 @@ + + 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 ): + +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 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 + 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. + + +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 + + 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. + + 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.doc) + -> 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.doc 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 ): + + 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 ; + 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. -- cgit v1.2.1 From be4cdf334ddc9bdf71e92b8a0f16a910ded7ae28 Mon Sep 17 00:00:00 2001 From: "H. Peter Anvin" Date: Fri, 29 Feb 2008 12:02:36 -0800 Subject: Document the file renaming from .doc -> .txt --- doc/comboot.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'doc/comboot.txt') diff --git a/doc/comboot.txt b/doc/comboot.txt index 46afc64c..c4b0f076 100644 --- a/doc/comboot.txt +++ b/doc/comboot.txt @@ -452,7 +452,7 @@ 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.doc) + 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 @@ -647,7 +647,7 @@ AX=0014h [3.10] Local boot [PXELINUX, ISOLINUX] 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.doc for the definition. + see syslinux.txt for the definition. AX=0015h [3.10] Get feature flags -- cgit v1.2.1