comboot.doc

   1          $Id$
   2
   3                        COMBOOT and COM32 files
   4
   5
   6 SYSLINUX supports simple standalone programs, using a file format
   7 similar to DOS ".com" files.  A 32-bit version, called COM32, is also
   8 provided.  A simple API provides access to a limited set of filesystem
   9 and console functions.
  10
  11
  12         ++++ COMBOOT file format ++++
  13
  14 A COMBOOT file is a raw binary file containing 16-bit code.  It should
  15 be linked to run at offset 0x100, and contain no absolute segment
  16 references.  It is run in 16-bit real mode.
  17
  18 A COMBOOT image can be written to be compatible with MS-DOS.  Such a
  19 file will usually have extension ".com".  A COMBOOT file which is not
  20 compatible with MS-DOS will usually have extension ".cbt".
  21
  22 Before running the program, SYSLINUX sets up the following fields in
  23 the Program Segment Prefix (PSP), a structure at offset 0 in the
  24 program segment:
  25
  26  Offset Size    Meaning
  27  0      word    Contains an INT 20h instruction
  28  2      word    Contains the paragraph (16-byte "segment" address) at
  29                 the end of memory available to the program.
  30  128    byte    Length of the command line arguments, including the leading
  31                 space but not including the final CR character.
  32  129    127b    Command line arguments, starting with a space and ending
  33                 with a CR character (ASCII 13).
  34
  35 The program is allowed to use memory between the PSP paragraph (which
  36 all the CS, DS, ES and SS registers point to at program start) and the
  37 paragraph value given at offset 2.
  38
  39 On startup, SP is set up to point to the end of the 64K segment, at
  40 0xfffe.  Under DOS it is possible for SP to contain a smaller
  41 value if memory is very tight; this is never the case under SYSLINUX.
  42
  43 The program should make no assumptions about what segment address it
  44 will be loaded at; instead it should look at the segment registers on
  45 program startup.  Both DOS and SYSLINUX will guarantee CS == DS == ES
  46 == SS on program start; the program should not assume anything about
  47 the values of FS or GS.
  48
  49 To exit, a program can either execute a near RET (which will jump to
  50 offset 0 which contains an INT 20h instruction, terminating the
  51 program), or execute INT 20h or INT 21h AH=00h or INT 21h AH=4Ch.
  52 If compatiblity with SYSLINUX 1.xx is desired, use INT 20h.
  53
  54
  55         ++++ COM32 file format ++++
  56
  57 A COM32 file is a raw binary file containing 32-bit code.  It should
  58 be linked to run at address 0x101000, and should not contain any
  59 segment references.  It will be run in flat-memory 32-bit protected
  60 mode.  Under SYSLINUX, it will be run in CPL 0, however, since it may
  61 be possible to create a COM32 execution engine that would run under
  62 something like Linux DOSEMU, it is recommended that the code does not
  63 assume CPL 0 unless absolutely necessary.
  64
  65 It is highly recommended that every COM32 program begins with the byte
  66 sequence B8 FF 4C CD 21 (mov eax,21cd4cffh) as a magic number.
  67
  68 A COM32 file should have extension ".c32".
  69
  70 On startup, CS will be set up as a flat 32-bit code segment, and DS ==
  71 ES == SS will be set up as the equivalent flat 32-bit data segment.
  72 FS and GS are reserved for future use and are currently initialized to
  73 zero.  A COM32 image should not assume any particular values of
  74 segment selectors.
  75
  76 ESP is set up at the end of available memory and also serves as
  77 notification to the program how much memory is available.
  78
  79 The following arguments are passed to the program on the stack:
  80
  81  Address  Size  Meaning
  82  [ESP]    dword Return (termination) address
  83  [ESP+4]  dword Number of additional arguments (currently 5)
  84  [ESP+8]  dword Pointer to the command line arguments (null-terminated string)
  85  [ESP+12] dword Pointer to INT call helper function
  86  [ESP+16] dword Pointer to low memory bounce buffer
  87  [ESP+20] dword Size of low memory bounce buffer
  88  [ESP+24] dword Pointer to FAR call helper function (new in 2.05)
  89
  90 This corresponds to the following C prototype, available in the file
  91 com32/include/com32.h:
  92
  93 /* The standard prototype for _start() */
  94 int _start(unsigned int __nargs,
  95            char *__cmdline,
  96            void (*__intcall)(uint8_t, com32sys_t *, com32sys_t *),
  97            void *__bounce_ptr,
  98            unsigned int __bounce_len,
  99            void (*__farcall)(uint32_t, uint16_t, com32sys_t *, com32sys_t *));
 100
 101 The intcall helper function can be used to issue BIOS or SYSLINUX API
 102 calls, and takes the interrupt number as first argument.  The second
 103 argument is a pointer to the input register definition, an instance of
 104 the following structure (also available in com32.h):
 105
 106 typedef union {
 107   uint32_t l;
 108   uint16_t w[2];
 109   uint8_t  b[4];
 110 } reg32_t;
 111
 112 typedef struct {
 113   uint16_t gs;                  /* Offset  0 */
 114   uint16_t fs;                  /* Offset  2 */
 115   uint16_t es;                  /* Offset  4 */
 116   uint16_t ds;                  /* Offset  6 */
 117
 118   reg32_t edi;                  /* Offset  8 */
 119   reg32_t esi;                  /* Offset 12 */
 120   reg32_t ebp;                  /* Offset 16 */
 121   reg32_t _unused;              /* Offset 20 */
 122   reg32_t ebx;                  /* Offset 24 */
 123   reg32_t edx;                  /* Offset 28 */
 124   reg32_t ecx;                  /* Offset 32 */
 125   reg32_t eax;                  /* Offset 36 */
 126
 127   reg32_t eflags;               /* Offset 40 */
 128 } com32sys_t;
 129
 130 The third argument is a pointer to the output register definition, an
 131 instance of the same structure.  The third argument can also be zero
 132 (NULL).
 133
 134 Since BIOS or SYSLINUX API calls can generally only manipulate data
 135 below address 0x100000, a "bounce buffer" in low memory, at least 64K
 136 in size, is available, to copy data in and out.
 137
 138 The farcall helper function behaves similarly, but takes as its first
 139 argument the CS:IP (in the form (CS << 16) + IP) of procedure to be
 140 invoked via a FAR CALL.
 141
 142
 143         ++++ SYSLINUX API CALLS +++
 144
 145 SYSLINUX provides the following API calls.  SYSLINUX 1.xx only
 146 supported INT 20h - terminate program. [] indicates the first version
 147 of SYSLINUX which supported this feature (correctly.)
 148
 149 NOTE: Most of the API functionality is still experimental.  Expect to
 150 find bugs.
 151
 152
 153         ++++ DOS-COMPATIBLE API CALLS ++++
 154
 155 INT 20h         [1.48] Terminate program
 156 INT 21h AH=00h  [2.00] Terminate program
 157 INT 21h AH=4Ch  [2.00] Terminate program
 158
 159         All of these terminate the program.
 160
 161 INT 21h AH=01h  [2.01] Get Key with Echo
 162
 163         Reads a key from the console input, with echo to the console
 164         output.  The read character is returned in AL.  Extended
 165         characters received from the keyboard are returned as NUL (00h)
 166         + the extended character code.
 167
 168 INT 21h AH=02h  [2.01] Write Character
 169
 170         Writes a character in DL to the console (video and serial)
 171         output.
 172
 173 INT 21h AH=04h  [2.01] Write Character to Serial Port
 174
 175         Writes a character in DL to the serial console output
 176         (if enabled.)  If no serial port is configured, this routine
 177         does nothing.
 178
 179 INT 21h AH=08h  [2.09] Get Key without Echo
 180
 181         Reads a key fron the console input, without echoing it to the
 182         console output.  The read character is returned in AL.
 183
 184 INT 21h AH=09h  [2.01] Write DOS String to Console
 185
 186         Writes a DOS $-terminated string in DS:DX to the console.
 187
 188 INT 21h AH=0Bh  [2.00] Check Keyboard
 189
 190         Returns AL=FFh if there is a keystroke waiting (which can then
 191         be read with INT 21h, AH=01h or AH=08h), otherwise AL=00h.
 192
 193 INT 21h AH=30h  [2.00] Check DOS Version
 194
 195         This function returns AX=BX=CX=DX=0, corresponding to a
 196         hypothetical "DOS 0.0", but the high parts of EAX-EBX-ECX-EDX
 197         spell "SYSLINUX":
 198
 199         EAX=59530000h EBX=4C530000h ECX=4E490000h EDX=58550000h
 200
 201         This function can thus be used to distinguish running on
 202         SYSLINUX from running on DOS.
 203
 204
 205         ++++ SYSLINUX-SPECIFIC API CALLS ++++
 206
 207 SYSLINUX-specific API calls are executed using INT 22h, with a
 208 function number in AX.  INT 22h is used by DOS for internal purposes;
 209 do not execute INT 22h under DOS.
 210
 211 DOS-compatible function INT 21h, AH=30h can be used to detect if the
 212 SYSLINUX API calls are available.
 213
 214 Any register not specifically listed as modified is preserved;
 215 however, future versions of SYSLINUX may add additional output
 216 registers to existing calls.
 217
 218 All calls return CF=0 on success, CF=1 on failure.  The noted outputs
 219 apply if CF=0 only unless otherwise noted.  All calls clobber the
 220 arithmetric flags (CF, PF, AF, ZF, SF and OF) but leave all other
 221 flags unchanged unless otherwise noted.
 222
 223
 224 AX=0001h [2.00] Get Version
 225
 226         Input:  AX      0001h
 227         Output: AX      number of INT 22h API functions available
 228                 CH      SYSLINUX major version number
 229                 CL      SYSLINUX minor version number
 230                 DL      SYSLINUX derivative ID (e.g. 32h = PXELINUX)
 231                 ES:SI   SYSLINUX version string
 232                 ES:DI   SYSLINUX copyright string
 233
 234         This API call returns the SYSLINUX version and API
 235         information.
 236
 237
 238 AX=0002h [2.01] Write String
 239
 240         Input:  AX      0002h
 241                 ES:BX   null-terminated string
 242         Output: None
 243
 244         Writes a null-terminated string on the console.
 245
 246
 247 AX=0003h [2.01] Run command
 248
 249         Input:  AX      0003h
 250                 ES:BX   null-terminated command string
 251         Output: Does not return
 252
 253         This API call terminates the program and executes the command
 254         string as if the user had entered it at the SYSLINUX command
 255         line.  This API call does not return.
 256
 257
 258 AX=0004h [2.01] Run default command
 259
 260         Input:  AX      0004h
 261         Output: Does not return
 262
 263         This API call terminates the program and executes the default
 264         command string as if the user had pressed Enter alone on the
 265         SYSLINUX command line.  This API call does not return.
 266
 267
 268 AX=0005h [2.00] Force text mode
 269
 270         Input:  AX      0005h
 271         Output: None
 272
 273         If the screen was in graphics mode (due to displaying a splash
 274         screen using the <Ctrl-X> command in a message file, or
 275         similar), return to text mode.
 276
 277
 278 AX=0006h [2.08] Open file
 279
 280         Input:  AX      0006h
 281                 ES:SI   null-terminated filename
 282         Output: SI      file handle
 283                 EAX     length of file in bytes
 284                 CX      file block size
 285
 286         Open a file for reading.  The exact syntax of the filenames
 287         allowed depends on the particular SYSLINUX derivative.
 288
 289         The SYSLINUX file system is block-oriented.  The size of a
 290         block will always be a power of two and no greater than 16K.
 291
 292         Note: SYSLINUX considers a zero-length file to be nonexistent.
 293
 294
 295 AX=0007h [2.08] Read file
 296
 297         Input:  AX      0007h
 298                 SI      file handle
 299                 ES:BX   buffer
 300                 CX      number of blocks to read
 301         Output: SI      file handle, or 0 if EOF was reached
 302
 303         Read blocks from a file.  Note that the file handle that is
 304         returned in SI may not be the same value that was passed in.
 305
 306         If end of file was reached (SI=0), the file was automatically
 307         closed.
 308
 309         The address of the buffer (ES:BX) should be at least 512-byte
 310         aligned.  SYSLINUX guarantees at least this alignment for the
 311         COMBOOT load segment or the COM32 bounce buffer.
 312
 313         Keep in mind that a "file" may be a TFTP connection, and that
 314         leaving a file open for an extended period of time may result
 315         in a timeout.
 316
 317         WARNING: Calling this function with an invalid file handle
 318         will probably crash the system.
 319
 320
 321 AX=0008h [2.08] Close file
 322
 323         Input:  AX      0008h
 324                 SI      file handle
 325         Output: None
 326
 327         Close a file before reaching the end of file.
 328
 329         WARNING: Calling this function with an invalid file handle
 330         will probably crash the system.
 331
 332
 333 AX=0009h [2.00] Call PXE Stack [PXELINUX ONLY]
 334
 335         Input:  AX      0009h
 336                 BX      PXE function number
 337                 ES:DI   PXE data buffer
 338         Output: AX      PXE return status code
 339
 340         Invoke an arbitrary PXE stack function.  On SYSLINUX/ISOLINUX,
 341         this function returns with an error (CF=1) and no action is
 342         taken.  On PXELINUX, this function always returns with CF=0
 343         indicating that the PXE stack was successfully invoked; check
 344         the status code in AX and in the first word of the data buffer
 345         to determine if the PXE call succeeded or not.
 346
 347
 348 AX=000Ah [2.00] Get Derivative-Specific Information
 349
 350         [SYSLINUX]
 351         Input:  AX      000Ah
 352         Output: AL      31h (SYSLINUX)
 353                 DL      drive number
 354                 ES:BX   pointer to partition table entry (if DL >= 80h)
 355
 356
 357         [PXELINUX]
 358         Input:  AX      000Ah
 359         Output: AL      32h (PXELINUX)
 360                 DX      PXE API version detected (DH=major, DL=minor)
 361                 ES:BX   pointer to PXENV+ or !PXE structure
 362                 FS:SI   pointer to original stack with invocation record
 363
 364                 Note: DX notes the API version detected by PXELINUX,
 365                 which may be more conservative than the actual version
 366                 available.  For exact information examine the API
 367                 version entry in the PXENV+ structure, or the API
 368                 version entries in the ROMID structures pointed from
 369                 the !PXE structure.
 370
 371                 PXELINUX will use, and provide, the !PXE structure
 372                 over the PXENV+ structure.  Examine the structure
 373                 signature to determine which particular structure was
 374                 provided.
 375
 376                 The FS:SI pointer points to the top of the original stack
 377                 provided by the PXE stack, with the following values
 378                 pushed at the time PXELINUX is started:
 379
 380                 [fs:si+0]       GS              <- top of stack
 381                 [fs:si+2]       FS
 382                 [fs:si+4]       ES
 383                 [fs:si+6]       DS
 384                 [fs:si+8]       EDI
 385                 [fs:si+12]      ESI
 386                 [fs:si+16]      EBP
 387                 [fs:si+20]      -
 388                 [fs:si+24]      EBX
 389                 [fs:si+28]      EDX
 390                 [fs:si+32]      ECX
 391                 [fs:si+36]      EAX
 392                 [fs:si+40]      EFLAGS
 393                 [fs:si+44]      PXE return IP   <- t.o.s. when PXELINUX invoked
 394                 [fs:si+46]      PXE return CS
 395
 396
 397         [ISOLINUX]
 398         Input:  AX      000Ah
 399         Output: AL      33h (ISOLINUX)
 400                 DL      drive number
 401                 ES:BX   pointer to El Torito spec packet
 402
 403                 Note: Some very broken El Torito implementations do
 404                 not provide the spec packet information.  If so, ES:BX
 405                 may point to all zeroes or to garbage.  Call INT 13h,
 406                 AX=4B01h to obtain the spec packet directly from the
 407                 BIOS if necessary.
 408
 409         This call gives information specific to a particular SYSLINUX
 410         derivative.  The value returned in AL is the same as is
 411         returned in DL by INT 22h AX=0001h.
 412
 413
 414 AX=000Bh [2.00] Get Serial Console Configuration
 415
 416         Input:  AX      000Bh
 417         Output: DX      Serial port I/O base (e.g. 3F8h = COM1...)
 418                 CX      Baud rate divisor (1 = 115200 bps, 2 = 57600 bps...)
 419                 BX      Flow control configuration bits (see syslinux.doc)
 420
 421         If no serial port is configured, DX will be set to 0 and the
 422         other registers are undefined.
 423
 424
 425 AX=000Ch [2.00] Perform final cleanup
 426         Input:  AX      000Ch
 427                 DX      derivative-specific flags (0000h = clean up all)
 428         Output: Does not return
 429
 430         This routine performs any "final cleanup" the boot loader
 431         would normally perform before loading a kernel, such as
 432         unloading the PXE stack in the case of PXELINUX.  AFTER
 433         INVOKING THIS CALL, NO OTHER API CALLS MAY BE INVOKED, NOR MAY
 434         THE PROGRAM TERMINATE AND RETURN TO THE BOOT LOADER.  This
 435         call basically tells the boot loader "get out of the way, I'll
 436         handle it from here."
 437
 438         For COM32 images, the boot loader will continue to provide
 439         interrupt and BIOS call thunking services as long its memory
 440         areas (0x1000-0xffff, 0x100000-0x100fff) are not overwritten.
 441         MAKE SURE TO DISABLE INTERRUPTS, AND INSTALL NEW GDT AND IDTS
 442         BEFORE OVERWRITING THESE MEMORY AREAS.
 443
 444         The permissible values for DX is an OR of these values:
 445
 446         SYSLINUX:       0000h   Normal cleanup
 447
 448         PXELINUX:       0000h   Normal cleanup
 449                         0003h   Keep UNDI and PXE stacks loaded
 450
 451         ISOLINUX:       0000h   Normal cleanup
 452
 453         All other values are undefined, and may have different
 454         meanings in future versions of SYSLINUX.
 455
 456
 457 AX=000Dh [2.08] Cleanup and replace bootstrap code
 458         Input:  AX      000Dh
 459                 DX      derivative-specific flags (see previous function)
 460                 EDI     bootstrap code (linear address, can be in high memory)
 461                 ECX     bootstrap code length in bytes (must fit in low mem)
 462                 EBX(!)  initial value of EDX after bootstrap
 463                 ESI     initial value of ESI after bootstrap
 464                 DS      initial value of DS after bootstrap
 465         Output: Does not return
 466
 467         This routine performs final cleanup, then takes a piece of
 468         code, copies it over the primary bootstrap at address 7C00h,
 469         and jumps to it.  This can be used to chainload boot sectors,
 470         MBRs, bootstraps, etc.
 471
 472         Normal boot sectors expect DL to contain the drive number,
 473         and, for hard drives (DL >= 80h) DS:SI to contain a pointer to
 474         the 16-byte partition table entry.  The memory between
 475         600h-7FFh is available to put the partition table entry in.
 476
 477         For PXELINUX, if the PXE stack is not unloaded, all registers
 478         (except DS, ESI and EDX) and the stack will be set up as they
 479         were set up by the PXE ROM.
 480
 481
 482 AX=000Eh [2.11] Get configuration file name
 483         Input:  AX      0000Eh
 484         Output: ES:BX   null-terminated file name string
 485
 486         Returns the name of the configuration file.  Note that it is
 487         possible that the configuration file doesn't actually exist.
 488