path: root/doc/comboot.txt

		       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]
		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)
		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

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

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

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


AX=000Bh [2.00]	Get Serial Console Configuration

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

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


AX=000Ch [2.00]	Perform final cleanup
	Input:	AX	000Ch
		DX	derivative-specific flags (0000h = clean up all)
	Output:	None

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

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

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

	SYSLINUX:	0000h	Normal cleanup

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

	ISOLINUX:	0000h	Normal cleanup

	EXTLINUX:	0000h	Normal cleanup

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


AX=000Dh [2.08]	Cleanup and replace bootstrap code
	Input:	AX	000Dh
		DX	derivative-specific flags (see previous function)
		EDI	bootstrap code (linear address, can be in high memory)
		ECX	bootstrap code length in bytes (must fit in low mem)
		EBX(!)	initial value of EDX after bootstrap
		ESI	initial value of ESI after bootstrap
		DS	initial value of DS after bootstrap
	Output:	Does not return

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

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

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


AX=000Eh [2.11]	Get configuration file name
	Input:	AX	0000Eh
	Output:	ES:BX	null-terminated file name string

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


AX=000Fh [3.00] Get IPAPPEND strings [PXELINUX]
	Input:  AX	000Fh
	Output:	CX	number of strings (currently 2)
		ES:BX	pointer to an array of NEAR pointers in
			the same segment, one for each of the above
			strings

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


AX=0010h [3.00] Resolve hostname [PXELINUX]
	Input:  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
		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.

	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.