Add an API for COMBOOT images, and add support for "COM32" -- 32-bit

linear .com files.

1 files changed, 266 insertions, 0 deletions

diff --git a/comboot.doc b/comboot.doc
new file mode 100644
index 00000000..db9203ac
--- /dev/null
+++ b/comboot.doc
@@ -0,0 +1,266 @@
+$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
+
+	++++ 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.
+
+