path: root/comboot.doc

$Id$

		       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.

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+4]  dword	Number of additional arguments (currently 4)
 [ESP+8]  dword	Pointer to the command line arguments (null-terminated string)
 [ESP+12] dword Pointer to system call helper function
 [ESP+16] dword Pointer to low memory bounce buffer
 [ESP+20] dword Size of low memory bounce buffer

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

/* The standard prototype for _start() */
int _start(unsigned int __nargs,
	   char *__cmdline,
	   void (*__syscall)(unsigned char, com32sys_t *, com32sys_t *),
	   void *__bounce_ptr,
	   unsigned int __bounce_len);

The system call 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 (also available in com32.h):

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

  unsigned int edi;		/* Offset  8 */
  unsigned int esi;		/* Offset 12 */
  unsigned int ebp;		/* Offset 16 */
  unsigned int _unused;		/* Offset 20 */
  unsigned int ebx;		/* Offset 24 */
  unsigned int edx;		/* Offset 28 */
  unsigned int ecx;		/* Offset 32 */
  unsigned int eax;		/* Offset 36 */

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


	++++ SYSLINUX API CALLS +++

SYSLINUX provides the following API calls.  SYSLINUX 1.xx only
supported INT 20h - terminate program.


	++++ DOS-COMPATIBLE API CALLS ++++

INT 20h		Terminate program
INT 21h AH=00h	Terminate program
INT 21h AH=4Ch	Terminate program

	All of these terminate the program.

INT 21h AH=01h	Get Key with Echo

	Reads a key from the console input, with echo to the console
	output.  The read character is returned in AL.

INT 21h AH=02h	Write Character

	Writes a character in DL to the console output.

INT 21h AH=08h	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=0Bh	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	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=53590000h EBX=534C0000h ECX=494E0000h EDX=55580000h

	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.

All INT 22h API calls may clobber the general-purpose registers (EAX,
EBX, ECX, EDX, EBP, ESI and EDI).  Segment registers are left
unchanged unless otherwise noted.

All calls return CF=0 on success, CF=1 on failure.  The noted outputs
apply if CF=0 only unless otherwise noted.


AX=0000h	No Operation

	Input:	AX	0000h
	Output:	None

	This API call does nothing.


AX=0001h	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	Write String

	Input:	AX	0002h
		ES:BX	null-terminated string
	Output:	None

	Writes a null-terminated string on the console.


AX=0003h	Run command

	Input:	AX	0003h
		ES:BX	null-terminated command string
	Output:	None

	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	Run default command

	Input:	AX	0004h
	Output:	None

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

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


AX=0008h	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	Call PXE Stack [PXELINUX ONLY]

	Input:	AX	0009h
		BX	PXE function number
		ES:DI	PXE data 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.