Doc/comboot

From Syslinux Wiki
Revision as of 20:58, 3 November 2008 by Clan (talk | contribs) (The content of doc/comboot.txt (release 3.72))

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

The content of doc/comboot.txt (release 3.72):

Contents

COMBOOT and COM32 files

SYSLINUX supports simple standalone programs, using a file format similar to DOS ".com" files. A 32-bit version, called COM32, is also provided. A simple API provides access to a limited set of filesystem and console functions.


COMBOOT file format

A COMBOOT file is a raw binary file containing 16-bit code. It should be linked to run at offset 0x100, and contain no absolute segment references. It is run in 16-bit real mode.

A COMBOOT image can be written to be compatible with MS-DOS. Such a file will usually have extension ".com". A COMBOOT file which is not compatible with MS-DOS will usually have extension ".cbt".

Before running the program, SYSLINUX sets up the following fields in the Program Segment Prefix (PSP), a structure at offset 0 in the program segment:

Offset  Size    Meaning
 0      word    Contains an INT 20h instruction
 2      word    Contains the paragraph (16-byte "segment" address) at
                the end of memory available to the program.
 128    byte    Length of the command line arguments, including the leading
                space but not including the final CR character.
 129    127b    Command line arguments, starting with a space and ending
                with a CR character (ASCII 13).

The program is allowed to use memory between the PSP paragraph (which all the CS, DS, ES and SS registers point to at program start) and the paragraph value given at offset 2.

On startup, SP is set up to point to the end of the 64K segment, at 0xfffe. Under DOS it is possible for SP to contain a smaller value if memory is very tight; this is never the case under SYSLINUX.

The program should make no assumptions about what segment address it will be loaded at; instead it should look at the segment registers on program startup. Both DOS and SYSLINUX will guarantee CS == DS == ES == SS on program start; the program should not assume anything about the values of FS or GS.

To exit, a program can either execute a near RET (which will jump to offset 0 which contains an INT 20h instruction, terminating the program), or execute INT 20h or INT 21h AH=00h or INT 21h AH=4Ch. If compatiblity with SYSLINUX 1.xx is desired, use INT 20h.


COM32 file format

A COM32 file is a raw binary file containing 32-bit code. It should be linked to run at address 0x101000, and should not contain any segment references. It will be run in flat-memory 32-bit protected mode. Under SYSLINUX, it will be run in CPL 0, however, since it may be possible to create a COM32 execution engine that would run under something like Linux DOSEMU, it is recommended that the code does not assume CPL 0 unless absolutely necessary.

It is highly recommended that every COM32 program begins with the byte sequence B8 FF 4C CD 21 (mov eax,21cd4cffh) as a magic number.

A COM32 file should have extension ".c32".

On startup, CS will be set up as a flat 32-bit code segment, and DS == ES == SS will be set up as the equivalent flat 32-bit data segment. FS and GS are reserved for future use and are currently initialized to zero. A COM32 image should not assume any particular values of segment selectors.

ESP is set up at the end of available memory and also serves as notification to the program how much memory is available.

The following arguments are passed to the program on the stack:

Address   Size   Meaning
[ESP]     dword  Return (termination) address
[ESP+4]   dword  Number of additional arguments (currently 5)
[ESP+8]   dword  Pointer to the command line arguments (null-terminated string)
[ESP+12]  dword  Pointer to INT call helper function
[ESP+16]  dword  Pointer to low memory bounce buffer
[ESP+20]  dword  Size of low memory bounce buffer
[ESP+24]  dword  Pointer to FAR call helper function (new in 2.05)
[ESP+28]  dword  Pointer to CDECL helper function (new in 3.54)

This corresponds to the following C prototype, available in the file com32/include/com32.h:

/* The standard prototype for _start() */
int _start(unsigned int __nargs,
           char *__cmdline,
           void (*__intcall)(uint8_t, com32sys_t *, com32sys_t *),
           void *__bounce_ptr,
           unsigned int __bounce_len,
           void (*__farcall)(uint32_t, com32sys_t *, com32sys_t *),
           int (*__cfarcall)(uint32_t, void *, size_t)
           );

The intcall helper function can be used to issue BIOS or SYSLINUX API calls, and takes the interrupt number as first argument. The second argument is a pointer to the input register definition, an instance of the following structure (available in <com32.h>):

typedef union {
  uint32_t l;
  uint16_t w[2];
  uint8_t  b[4];
} reg32_t;

typedef struct {
  uint16_t gs;                  /* Offset  0 */
  uint16_t fs;                  /* Offset  2 */
  uint16_t es;                  /* Offset  4 */
  uint16_t ds;                  /* Offset  6 */

  reg32_t edi;                  /* Offset  8 */
  reg32_t esi;                  /* Offset 12 */
  reg32_t ebp;                  /* Offset 16 */
  reg32_t _unused_esp;          /* Offset 20 */
  reg32_t ebx;                  /* Offset 24 */
  reg32_t edx;                  /* Offset 28 */
  reg32_t ecx;                  /* Offset 32 */
  reg32_t eax;                  /* Offset 36 */

  reg32_t eflags;               /* Offset 40 */
} com32sys_t;

The third argument is a pointer to the output register definition, an instance of the same structure. The third argument can also be zero (NULL).

Since BIOS or SYSLINUX API calls can generally only manipulate data below address 0x100000, a "bounce buffer" in low memory, at least 64K in size, is available, to copy data in and out.

The farcall helper function behaves similarly, but takes as its first argument the CS:IP (in the form (CS << 16) + IP) of procedure to be invoked via a FAR CALL.

The cfarcall helper function takes (CS << 16)+IP, a pointer to a stack frame, a size of that stack frame, and returns the return value of EAX (which may need to be appropriate truncated by the user.)


SYSLINUX API calls

SYSLINUX provides the following API calls. SYSLINUX 1.xx only supported INT 20h - terminate program. [] indicates the first version of SYSLINUX which supported this feature (correctly.)

NOTE: Most of the API functionality is still experimental. Expect to find bugs.


DOS-compatible API calls

INT 20h [1.48] Terminate program

INT 21h AH=00h [2.00] Terminate program

INT 21h AH=4Ch [2.00] Terminate program

All of these terminate the program.


INT 21h AH=01h [2.01] Get Key with Echo

Reads a key from the console input, with echo to the console output. The read character is returned in AL. Extended characters received from the keyboard are returned as NUL (00h) + the extended character code.


INT 21h AH=02h [2.01] Write Character

Writes a character in DL to the console (video and serial) output.


INT 21h AH=04h [2.01] Write Character to Serial Port

Writes a character in DL to the serial console output (if enabled.) If no serial port is configured, this routine does nothing.


INT 21h AH=08h [2.09] Get Key without Echo

Reads a key fron the console input, without echoing it to the console output. The read character is returned in AL.


INT 21h AH=09h [2.01] Write DOS String to Console

Writes a DOS $-terminated string in DS:DX to the console.


INT 21h AH=0Bh [2.00] Check Keyboard

Returns AL=FFh if there is a keystroke waiting (which can thenbe read with INT 21h, AH=01h or AH=08h), otherwise AL=00h.


INT 21h AH=30h [2.00] Check DOS Version

This function returns AX=BX=CX=DX=0, corresponding to a hypothetical "DOS 0.0", but the high parts of EAX-EBX-ECX-EDX spell "SYSLINUX":

EAX=59530000h EBX=4C530000h ECX=4E490000h EDX=58550000h

This function can thus be used to distinguish running on SYSLINUX from running on DOS.


SYSLINUX-specific API calls

SYSLINUX-specific API calls are executed using INT 22h, with a function number in AX. INT 22h is used by DOS for internal purposes; do not execute INT 22h under DOS.

DOS-compatible function INT 21h, AH=30h can be used to detect if the SYSLINUX API calls are available.

Any register not specifically listed as modified is preserved; however, future versions of SYSLINUX may add additional output registers to existing calls.

All calls return CF=0 on success, CF=1 on failure. The noted outputs apply if CF=0 only unless otherwise noted. All calls clobber the arithmetric flags (CF, PF, AF, ZF, SF and OF) but leave all other flags unchanged unless otherwise noted.


AX=0001h [2.00] Get Version

Input:

AX        0001h

Output:

AX        number of INT 22h API functions available
CH        SYSLINUX major version number
CL        SYSLINUX minor version number
DL        SYSLINUX derivative ID (e.g. 32h = PXELINUX)
ES:SI     SYSLINUX version string
ES:DI     SYSLINUX copyright string

This API call returns the SYSLINUX version and API information.


AX=0002h [2.01] Write String

Input:

AX        0002h
ES:BX     null-terminated string

Output:

None

Writes a null-terminated string on the console.


AX=0003h [2.01] Run command

Input:

AX        0003h
ES:BX     null-terminated command string

Output:

Does not return

This API call terminates the program and executes the command string as if the user had entered it at the SYSLINUX command line. This API call does not return.


AX=0004h [2.01] Run default command

Input:

AX        0004h

Output:

Does not return

This API call terminates the program and executes the default command string as if the user had pressed Enter alone on the SYSLINUX command line. This API call does not return.


AX=0005h [2.00] Force text mode

Input:

AX        0005h

Output:

None

If the screen was in graphics mode (due to displaying a splash screen using the <Ctrl-X> command in a message file, or similar), return to text mode.


AX=0006h [2.08] Open file

Input:

AX        0006h
ES:SI     null-terminated filename

Output:

SI        file handle
EAX       length of file in bytes, or -1
CX        file block size

Open a file for reading. The exact syntax of the filenames allowed depends on the particular SYSLINUX derivative.

The SYSLINUX file system is block-oriented. The size of a block will always be a power of two and no greater than 16K.

Note: SYSLINUX considers a zero-length file to be nonexistent.

In 3.70 or later, EAX can contain -1 indicating that the file length is unknown.


AX=0007h [2.08] Read file

Input:

AX        0007h
SI        file handle
ES:BX     buffer
CX        number of blocks to read

Output:

SI        file handle, or 0 if EOF was reached
ECX       number of bytes read [3.70]

Read blocks from a file. Note that the file handle that is returned in SI may not be the same value that was passed in.

If end of file was reached (SI=0), the file was automatically closed.

In 3.70 or later, ECX returns the number of bytes read. This will always be a multiple of the block size unless EOF is reached.

The address of the buffer (ES:BX) should be at least 512-byte aligned. SYSLINUX guarantees at least this alignment for the COMBOOT load segment or the COM32 bounce buffer.

Keep in mind that a "file" may be a TFTP connection, and that leaving a file open for an extended period of time may result in a timeout.

WARNING: Calling this function with an invalid file handle will probably crash the system.


AX=0008h [2.08] Close file

Input:

AX        0008h
SI        file handle

Output:

None

Close a file before reaching the end of file.

WARNING: Calling this function with an invalid file handle will probably crash the system.


AX=0009h [2.00] Call PXE Stack [PXELINUX ONLY]

Input:

AX        0009h
BX        PXE function number
ES:DI     PXE parameter structure buffer

Output:

AX        PXE return status code

Invoke an arbitrary PXE stack function. On SYSLINUX/ISOLINUX, this function returns with an error (CF=1) and no action is taken. On PXELINUX, this function always returns with CF=0 indicating that the PXE stack was successfully invoked; check the status code in AX and in the first word of the data buffer to determine if the PXE call succeeded or not.

The PXE stack will have the UDP stack OPEN; if you change that you cannot call any of the file-related API functions, and must restore UDP OPEN before returning to PXELINUX.

PXELINUX reserves UDP port numbers from 49152 to 65535 for its own use; port numbers below that range is available.


AX=000Ah [2.00] Get Derivative-Specific Information

[SYSLINUX, EXTLINUX]
Input:

AX        000Ah
CL        9 (to get a valid return in CL for all versions)

Output:

AL        31h (SYSLINUX), 34h (EXTLINUX)
DL        drive number
CL        sector size as a power of 2 (9 = 512 bytes) [3.35]
ES:BX     pointer to partition table entry (if DL >= 80h)
FS:SI     pointer to initial ES:DI value [3.53]

Note: This function was broken in EXTLINUX 3.00-3.02.

On boot, ES:DI is supposed to point to the BIOS $PnP structure, although in practice most operating systems will search for it in memory. However, preserving this while chainloading is probably a good idea.

Note that FS:SI is a pointer to a memory location containing the original ES:DI value, not the value itself.

[PXELINUX]
Input:

AX        000Ah

Output:

AL        32h (PXELINUX)
DX        PXE API version detected (DH=major, DL=minor)
ES:BX     pointer to PXENV+ or !PXE structure
FS:SI     pointer to original stack with invocation record

Note: DX notes the API version detected by PXELINUX, which may be more conservative than the actual version available. For exact information examine the API version entry in the PXENV+ structure, or the API version entries in the ROMID structures pointed from the !PXE structure.

PXELINUX will use, and provide, the !PXE structure over the PXENV+ structure. Examine the structure signature to determine which particular structure was provided.

The FS:SI pointer points to the top of the original stack provided by the PXE stack, with the following values pushed at the time PXELINUX is started:

[fs:si+0]       GS              <- top of stack
[fs:si+2]       FS
[fs:si+4]       ES
[fs:si+6]       DS
[fs:si+8]       EDI
[fs:si+12]      ESI
[fs:si+16]      EBP
[fs:si+20]      -
[fs:si+24]      EBX
[fs:si+28]      EDX
[fs:si+32]      ECX
[fs:si+36]      EAX
[fs:si+40]      EFLAGS
[fs:si+44]      PXE return IP   <- t.o.s. when PXELINUX invoked
[fs:si+46]      PXE return CS

[ISOLINUX]
Input:

AX        000Ah

Output:

AL        33h (ISOLINUX)
DL        drive number
CL        11 (sector size as a power of 2) [3.35]
ES:BX     pointer to El Torito spec packet
FS:SI     pointer to initial ES:DI value [3.53]

Note: Some very broken El Torito implementations do not provide the spec packet information. If so, ES:BX may point to all zeroes or to garbage. Call INT 13h, AX=4B01h to obtain the spec packet directly from the BIOS if necessary.

This call gives information specific to a particular SYSLINUX derivative. The value returned in AL is the same as is returned in DL by INT 22h AX=0001h.


AX=000Bh [2.00] Get Serial Console Configuration

Input:

AX        000Bh

Output:

DX        serial port I/O base (e.g. 3F8h = COM1...)
CX        baud rate divisor (1 = 115200 bps, 2 = 57600 bps...)
BX        flow control configuration bits (see syslinux.txt)
          -> bit 15 is set if the video console is disabled

If no serial port is configured, DX will be set to 0 and the other registers are undefined.


AX=000Ch [2.00] Perform final cleanup

Input:

AX        000Ch
DX        derivative-specific flags (0000h = clean up all)

Output:

None

This routine performs any "final cleanup" the boot loader would normally perform before loading a kernel, such as unloading the PXE stack in the case of PXELINUX. AFTER INVOKING THIS CALL, NO OTHER API CALLS MAY BE INVOKED, NOR MAY THE PROGRAM TERMINATE AND RETURN TO THE BOOT LOADER. This call basically tells the boot loader "get out of the way, I'll handle it from here."

For COM32 images, the boot loader will continue to provide interrupt and BIOS call thunking services as long its memory areas (0x0800-0xffff, 0x100000-0x100fff) are not overwritten. MAKE SURE TO DISABLE INTERRUPTS, AND INSTALL NEW GDT AND IDTS BEFORE OVERWRITING THESE MEMORY AREAS.

The permissible values for DX is an OR of these values:

SYSLINUX: 0000h Normal cleanup
PXELINUX: 0000h Normal cleanup
PXELINUX: 0003h Keep UNDI and PXE stacks loaded
ISOLINUX: 0000h Normal cleanup
EXTLINUX: 0000h Normal cleanup

All other values are undefined, and may have different meanings in future versions of SYSLINUX.


AX=000Dh [2.08] Cleanup and replace bootstrap code

Input:

AX        000Dh
DX        derivative-specific flags (see previous function)
EDI       bootstrap code (linear address, can be in high memory)
ECX       bootstrap code length in bytes (must fit in low mem)
EBX(!)    initial value of EDX after bootstrap
ESI       initial value of ESI after bootstrap
DS        initial value of DS after bootstrap

Output:

Does not return

This routine performs final cleanup, then takes a piece of code, copies it over the primary bootstrap at address 7C00h, and jumps to it. This can be used to chainload boot sectors, MBRs, bootstraps, etc.

Normal boot sectors expect DL to contain the drive number, and, for hard drives (DL >= 80h) DS:SI to contain a pointer to the 16-byte partition table entry. The memory between 600h-7FFh is available to put the partition table entry in.

For PXELINUX, if the PXE stack is not unloaded, all registers (except DS, ESI and EDX) and the stack will be set up as they were set up by the PXE ROM.


AX=000Eh [2.11] Get configuration file name

Input:

AX        0000Eh

Output:

ES:BX     null-terminated file name string

Returns the name of the configuration file. Note that it is possible that the configuration file doesn't actually exist.


AX=000Fh [3.00] Get IPAPPEND strings [PXELINUX]

Input:

AX        000Fh

Output:

CX        number of strings (currently 2)
ES:BX     pointer to an array of NEAR pointers in the same segment, one for each of the above strings

Returns the same strings that the "ipappend" option would have added to the command line, one for each bit of the "ipappend" flag value, so entry 0 is the "ip=" string and entry 1 is the "BOOTIF=" string.


AX=0010h [3.00] Resolve hostname [PXELINUX]

Input:

ES:BX     pointer to null-terminated hostname

Output:

EAX       IP address of hostname (zero if not found)

Queries the DNS server(s) for a specific hostname. If the hostname does not contain a dot (.), the local domain name is automatically appended.

This function only return CF=1 if the function is not supported. If the function is supported, but the hostname did not resolve, it returns with CF=0, EAX=0.

The IP address is returned in network byte order, i.e. if the IP address is 1.2.3.4, EAX will contain 0x04030201. Note that all uses of IP addresses in PXE are also in network byte order.


AX=0011h [3.05] Maximum number of shuffle descriptors

Input:

AX        0011h

Output:

CX        maximum number of descriptors

This routine reports the maximum number of shuffle descriptors permitted in a call to functions 0012h, 001Ah and 001Bh.

This is guaranteed to be at least 64. For the current version, this is 682 for all derivatives.


AX=0012h [3.50] Cleanup, shuffle and boot

Input:

AX        0012h
DX        derivative-specific flags (see function 000Ch)
ES:DI     shuffle descriptor list (must be in low memory)
CX        number of shuffle descriptors
EBX(!)    initial value of EDX after bootstrap
ESI       initial value of ESI after bootstrap
DS        initial value of DS after bootstrap
EBP       CS:IP of routine to jump to

Output:

Does not return
(if CX is too large the routine returns with CF=1)

This routine performs final cleanup, then performs a sequence of copies, and jumps to a specified real mode entry point. This is a more general version of function 000Dh, which can also be used to load other types of programs.

The copies must not touch memory below address 7C00h.

ES:DI points to a list of CX descriptors each of the form:

Offset   Size    Meaning
  0      dword   destination address
  4      dword   source address
  8      dword   length in bytes

The copies are overlap-safe, like memmove().

Starting in version 3.50, if the source address is -1 (FFFFFFFFh) then the block specified by the destination address and the length is set to all zero.

Starting in version 3.50, if the destination address is -1 (FFFFFFFFh) then the data block is loaded as a new set of descriptors, and processing is continued (and unprocessed descriptors are lost, this is thus typically only used as the last descriptor in a block.) The block must still fit in the internal descriptor buffer (see function 0011h), but can, of course, itself chain another block.


Normal boot sectors expect DL to contain the drive number, and, for hard drives (DL >= 80h) DS:SI to contain a pointer to the 16-byte partition table entry. The memory between 600h-7FFh is available to put the partition table entry in.

For PXELINUX, if the PXE stack is not unloaded, all registers (except DS, ESI and EDX) and the stack will be set up as they were set up by the PXE ROM.

This interface was probably broken before version 3.50.


AX=0013h [3.08] Idle loop call

Input:

AX        0013h

Output:

None

Call this routine while sitting in an idle loop. It performs any periodic activities required by the filesystem code. At the moment, this is a no-op on all derivatives except PXELINUX, where it executes PXE calls to answer ARP queries.

Starting with version 3.10, this API call harmlessly returns failure (CF=1) if invoked on a platform which does not need idle calls. Additionally, it's safe to call this API call on previous SYSLINUX versions (2.00 or later); it will just harmlessly fail. Thus, if this call returns failure (CF=1), it means that there is no technical reason to call this function again, although doing so is of course safe.


AX=0014h [3.10] Local boot [PXELINUX, ISOLINUX]

Input:

AX        0014h
DX        Local boot parameter

Output:

Does not return

This function invokes the equivalent of the "localboot" configuration file option. The parameter in DX is the same parameter as would be entered after "localboot" in the configuration file; this parameter is derivative-specific -- see syslinux.txt for the definition.


AX=0015h [3.10] Get feature flags

Input:

AX        0015h

Output:

ES:BX     pointer to flags in memory
CX        number of flag bytes

This function reports whether or not this SYSLINUX version and derivative supports specific features. Keep in mind that future versions might have more bits; remember to treat any bits beyond the end of the array (as defined by the value in CX) as zero.

Currently the following feature flag is defined:

Byte   Bit   Definition
----------------------------------------------------
  0     0    Local boot (AX=0014h) supported
        1    Idle loop call (AX=0013h) is a no-op

All other flags are reserved.


AX=0016h [3.10] Run kernel image

Input:

AX        0016h
DS:SI     Filename of kernel image (zero-terminated string)
ES:BX     Command line (zero-terminated string)
ECX       IPAPPEND flags [PXELINUX]
EDX       Type of file (since 3.50)

Output:

Does not return if successful; returns with CF=1 if the kernel image is not found.

This function is similiar to AX=0003h Run command, except that the filename and command line are treated as if specified in a KERNEL and APPEND statement of a LABEL statement, which means:

  • The filename has to be exact; no variants are tried;
  • No global APPEND statement is applied;
  • ALLOWOPTIONS and IMPLICIT statements in the configuration file do not apply. It is therefore important that the COMBOOT module doesn't allow the end user to violate the intent of the administrator.

Additionally, this function returns with a failure if the file doesn't exist, instead of returning to the command line. (It may still return to the command line if the image is somehow corrupt, however.)

The file types are defined as follows:

            Equivalent
EDX     Config  Extensions      Type of file
0       KERNEL                  Determined by filename extension
1       LINUX   none            Linux kernel image
2       BOOT    .bs .bin        Bootstrap program
3       BSS     .bss            Boot sector with patch [SYSLINUX]
4       PXE     .0              PXE Network Bootstrap Prog [PXELINUX]
5       FDIMAGE .img            Floppy disk image [ISOLINUX]
6       COMBOOT .com .cbt       16-bit COMBOOT program
7       COM32   .c32            COM32 program
8       CONFIG                  Configuration file

AX=0017h [3.30] Report video mode change

Input:

AX        0017h
BX        Video mode flags
          Bit 0: graphics mode
          Bit 1: non-default mode
          Bit 2: VESA mode
          Bit 3: text functions not supported
CX        For graphics modes, pixel columns
DX        For graphics modes, pixel rows

Output:

None

This function is used to report video mode changes to SYSLINUX. It does NOT actually change the video mode, but rather, allows SYSLINUX to take appropriate action in response to a video mode change. Modes that cannot be exited either with the conventional BIOS mode set command (INT 10h, AH=00h) or the VESA VBE mode set command (INT 10h, AX=4F02h) should not be used.

This function returns with a failure if BX contains any bits which are undefined in the current version of SYSLINUX.

The following bits in BX are currently defined:

Bit 0: graphics mode
Indicates that the mode is a graphics mode, as opposed to a text mode.
Bit 1: non-standard mode
A non-standard mode is any mode except text mode and graphics mode 0012h (VGA 640x480, 16 color.)
Bit 2: VESA mode
This mode is a VESA mode, and has to be exited with the VESA VBE API (INT 10h, AX=4F02h) as opposed to the conventional BIOS API (INT 10h, AH=00h).
Bit 3: Text functions not supported
This indicates that the BIOS text output functions (INT 10h, AH=02h, 03h, 06h, 09h, 0Eh, 11h) don't work. If this bit is set, SYSLINUX will reset the mode before printing any characters on the screen.
This is common for VESA modes.


AX=0018h [3.30] Query custom font

Input:

AX        0018h

Output:

AL        Height of custom font in scan lines, or zero
ES:BX     Pointer to custom font in memory

This call queries if a custom display font has been loaded via the "font" configuration file command. If no custom font has been loaded, AL contains zero.


AX=0019h [3.50] Read disk [SYSLINUX, ISOLINUX, EXTLINUX]

Input:

AX        0019h
EDX       Sector number
ESI       Reserved - MUST BE ZERO
EDI       Reserved - MUST BE ZERO
CX        Sector count
ES:BX     Buffer address

Output:

None

Read disk blocks from the active filesystem (partition); for disks, sector number zero is the boot sector. For ISOLINUX, this call reads the CD-ROM.

For compatiblity with all systems, the buffer should neither cross 64K boundaries, nor wrap around the segment.

This routine reports "boot failed" (and does not return) on disk error.


AX=001Ah [3.50] Cleanup, shuffle and boot to flat protected mode

Input:

AX        001Ah
DX        derivative-specific flags (see function 000Ch)
ES:DI     shuffle descriptor list (must be in low memory)
CX        number of shuffle descriptors
DS:SI     pointer to register values (must be in low memory)

Output:

Does not return
(if CX is too large the routine returns with CF=1)

This routine performs final cleanup, then performs a sequence of copies, and jumps to a specified protected mode entry point. This is otherwise similar to function 0012h; see that function for the meaning of ES:DI and CX.

DS:SI points to the initial register file, which is a structure of 9 dwords (available in <syslinux/bootpm.h>):

struct syslinux_pm_regs {
  uint32_t eax;                 /* Offset  0 */
  uint32_t ecx;                 /* Offset  4 */
  uint32_t edx;                 /* Offset  8 */
  uint32_t ebx;                 /* Offset 12 */
  uint32_t esp;                 /* Offset 16 */
  uint32_t ebp;                 /* Offset 20 */
  uint32_t esi;                 /* Offset 24 */
  uint32_t edi;                 /* Offset 28 */

  uint32_t eip;                 /* Offset 32 */
};

Protected mode is entered with all data segments set up as a flat 32-bit read/write segment and the code segment a flat 32-bit read/execute segment. Interrupts and paging is off, CPL=0, DF=0; however, GDT, LDT and IDT are undefined, so it is up to the invoked code to set new descriptor tables to its liking.


AX=001Bh [3.50] Cleanup, shuffle and boot to real mode

Input:

AX        001Bh
DX        derivative-specific flags (see function 000Ch)
ES:DI     shuffle descriptor list (must be in lo memory)
CX        number of shuffle descriptors
DS:SI     pointer to register values (must be in low memory)

Output:

Does not return
(if CX is too large the routine returns with CF=1)

This routine performs final cleanup, then performs a sequence of copies, and jumps to a specified entry point. This is similar to function 0012h but allow more control over the initial register state; see that function for the meaning of ES:DI and CX.

DS:SI points to the initial register file, which is a structure in the following format (available in <syslinux/bootrm.h>; note that this is a completely different structure from the com32sys_t structure described at the top of this document!):

struct syslinux_rm_regs {
  uint16_t es;                  /* Offset  0 */
  uint16_t _unused_cs;          /* Offset  2 */
  uint16_t ds;                  /* Offset  4 */
  uint16_t ss;                  /* Offset  6 */
  uint16_t fs;                  /* Offset  8 */
  uint16_t gs;                  /* Offset 10 */

  reg32_t eax;                  /* Offset 12 */
  reg32_t ecx;                  /* Offset 16 */
  reg32_t edx;                  /* Offset 20 */
  reg32_t ebx;                  /* Offset 24 */
  reg32_t esp;                  /* Offset 28 */
  reg32_t ebp;                  /* Offset 32 */
  reg32_t esi;                  /* Offset 36 */
  reg32_t edi;                  /* Offset 40 */

  uint16_t ip;                  /* Offset 44 */
  uint16_t cs;                  /* Offset 46 */
};

Interrupts are off and DF=0 on entry.


AX=001Ch [3.60] Get pointer to auxilliary data vector

Input:

AX        001Ch

Output:

ES:BX     Auxilliary data vector
CX        Size of the ADV (currently 500 bytes)

The auxillary data vector is a tagged data structure used to carry a small amount of information (up to 500 bytes) from one boot to another.


AX=001Dh [3.60] Write auxilliary data vector

Input:

AX        001Dh

Output:

None

Write the auxilliary data vector back to disk. Returns failure for non-disk-based derivatives unless the "auxdata" configuration command is used to specify a disk location (not yet implemented.)

In a future version, PXELINUX may end up attempting to save the ADV on the server via TFTP write.