syslinux/comboot.doc

   1          $Id: comboot.doc,v 1.34 2005/01/20 18:43:22 hpa Exp $
   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         The PXE stack will have the UDP stack OPEN; if you change that
 348         you cannot call any of the file-related API functions, and
 349         must restore UDP OPEN before returning to PXELINUX.
 350
 351         PXELINUX reserves UDP port numbers from 49152 to 65535 for its
 352         own use; port numbers below that range is available.
 353
 354
 355 AX=000Ah [2.00] Get Derivative-Specific Information
 356
 357         [SYSLINUX, EXTLINUX]
 358         Input:  AX      000Ah
 359         Output: AL      31h (SYSLINUX), 34h (EXTLINUX)
 360                 DL      drive number
 361                 ES:BX   pointer to partition table entry (if DL >= 80h)
 362
 363                 Note: This function was broken in EXTLINUX 3.00-3.02.
 364
 365
 366         [PXELINUX]
 367         Input:  AX      000Ah
 368         Output: AL      32h (PXELINUX)
 369                 DX      PXE API version detected (DH=major, DL=minor)
 370                 ES:BX   pointer to PXENV+ or !PXE structure
 371                 FS:SI   pointer to original stack with invocation record
 372
 373                 Note: DX notes the API version detected by PXELINUX,
 374                 which may be more conservative than the actual version
 375                 available.  For exact information examine the API
 376                 version entry in the PXENV+ structure, or the API
 377                 version entries in the ROMID structures pointed from
 378                 the !PXE structure.
 379
 380                 PXELINUX will use, and provide, the !PXE structure
 381                 over the PXENV+ structure.  Examine the structure
 382                 signature to determine which particular structure was
 383                 provided.
 384
 385                 The FS:SI pointer points to the top of the original stack
 386                 provided by the PXE stack, with the following values
 387                 pushed at the time PXELINUX is started:
 388
 389                 [fs:si+0]       GS              <- top of stack
 390                 [fs:si+2]       FS
 391                 [fs:si+4]       ES
 392                 [fs:si+6]       DS
 393                 [fs:si+8]       EDI
 394                 [fs:si+12]      ESI
 395                 [fs:si+16]      EBP
 396                 [fs:si+20]      -
 397                 [fs:si+24]      EBX
 398                 [fs:si+28]      EDX
 399                 [fs:si+32]      ECX
 400                 [fs:si+36]      EAX
 401                 [fs:si+40]      EFLAGS
 402                 [fs:si+44]      PXE return IP   <- t.o.s. when PXELINUX invoked
 403                 [fs:si+46]      PXE return CS
 404
 405
 406         [ISOLINUX]
 407         Input:  AX      000Ah
 408         Output: AL      33h (ISOLINUX)
 409                 DL      drive number
 410                 ES:BX   pointer to El Torito spec packet
 411
 412                 Note: Some very broken El Torito implementations do
 413                 not provide the spec packet information.  If so, ES:BX
 414                 may point to all zeroes or to garbage.  Call INT 13h,
 415                 AX=4B01h to obtain the spec packet directly from the
 416                 BIOS if necessary.
 417
 418         This call gives information specific to a particular SYSLINUX
 419         derivative.  The value returned in AL is the same as is
 420         returned in DL by INT 22h AX=0001h.
 421
 422
 423 AX=000Bh [2.00] Get Serial Console Configuration
 424
 425         Input:  AX      000Bh
 426         Output: DX      serial port I/O base (e.g. 3F8h = COM1...)
 427                 CX      baud rate divisor (1 = 115200 bps, 2 = 57600 bps...)
 428                 BX      flow control configuration bits (see syslinux.doc)
 429                         -> bit 15 is set if the video console is disabled
 430
 431         If no serial port is configured, DX will be set to 0 and the
 432         other registers are undefined.
 433
 434
 435 AX=000Ch [2.00] Perform final cleanup
 436         Input:  AX      000Ch
 437                 DX      derivative-specific flags (0000h = clean up all)
 438         Output: Does not return
 439
 440         This routine performs any "final cleanup" the boot loader
 441         would normally perform before loading a kernel, such as
 442         unloading the PXE stack in the case of PXELINUX.  AFTER
 443         INVOKING THIS CALL, NO OTHER API CALLS MAY BE INVOKED, NOR MAY
 444         THE PROGRAM TERMINATE AND RETURN TO THE BOOT LOADER.  This
 445         call basically tells the boot loader "get out of the way, I'll
 446         handle it from here."
 447
 448         For COM32 images, the boot loader will continue to provide
 449         interrupt and BIOS call thunking services as long its memory
 450         areas (0x0800-0xffff, 0x100000-0x100fff) are not overwritten.
 451         MAKE SURE TO DISABLE INTERRUPTS, AND INSTALL NEW GDT AND IDTS
 452         BEFORE OVERWRITING THESE MEMORY AREAS.
 453
 454         The permissible values for DX is an OR of these values:
 455
 456         SYSLINUX:       0000h   Normal cleanup
 457
 458         PXELINUX:       0000h   Normal cleanup
 459                         0003h   Keep UNDI and PXE stacks loaded
 460
 461         ISOLINUX:       0000h   Normal cleanup
 462
 463         All other values are undefined, and may have different
 464         meanings in future versions of SYSLINUX.
 465
 466
 467 AX=000Dh [2.08] Cleanup and replace bootstrap code
 468         Input:  AX      000Dh
 469                 DX      derivative-specific flags (see previous function)
 470                 EDI     bootstrap code (linear address, can be in high memory)
 471                 ECX     bootstrap code length in bytes (must fit in low mem)
 472                 EBX(!)  initial value of EDX after bootstrap
 473                 ESI     initial value of ESI after bootstrap
 474                 DS      initial value of DS after bootstrap
 475         Output: Does not return
 476
 477         This routine performs final cleanup, then takes a piece of
 478         code, copies it over the primary bootstrap at address 7C00h,
 479         and jumps to it.  This can be used to chainload boot sectors,
 480         MBRs, bootstraps, etc.
 481
 482         Normal boot sectors expect DL to contain the drive number,
 483         and, for hard drives (DL >= 80h) DS:SI to contain a pointer to
 484         the 16-byte partition table entry.  The memory between
 485         600h-7FFh is available to put the partition table entry in.
 486
 487         For PXELINUX, if the PXE stack is not unloaded, all registers
 488         (except DS, ESI and EDX) and the stack will be set up as they
 489         were set up by the PXE ROM.
 490
 491
 492 AX=000Eh [2.11] Get configuration file name
 493         Input:  AX      0000Eh
 494         Output: ES:BX   null-terminated file name string
 495
 496         Returns the name of the configuration file.  Note that it is
 497         possible that the configuration file doesn't actually exist.
 498
 499
 500 AX=000Fh [3.00] Get IPAPPEND strings [PXELINUX]
 501         Input:  AX      000Fh
 502         Output: CX      number of strings (currently 2)
 503                 ES:BX   pointer to an array of NEAR pointers in
 504                         the same segment, one for each of the above
 505                         strings
 506
 507         Returns the same strings that the "ipappend" option would have
 508         added to the command line, one for each bit of the "ipappend"
 509         flag value, so entry 0 is the "ip=" string and entry 1 is the
 510         "BOOTIF=" string.
 511
 512
 513 AX=0010h [3.00] Resolve hostname [PXELINUX]
 514         Input:  ES:BX   pointer to null-terminated hostname
 515         Output: EAX     IP address of hostname (zero if not found)
 516
 517         Queries the DNS server(s) for a specific hostname.  If the
 518         hostname does not contain a dot (.), the local domain name
 519         is automatically appended.
 520
 521         This function only return CF=1 if the function is not
 522         supported.  If the function is supported, but the hostname did
 523         not resolve, it returns with CF=0, EAX=0.
 524
 525         The IP address is returned in network byte order, i.e. if the
 526         IP address is 1.2.3.4, EAX will contain 0x04030201.  Note that
 527         all uses of IP addresses in PXE are also in network byte order.
 528
 529
 530 AX=0011h [3.05] Maximum number of shuffle descriptors
 531         Input:  AX      0011h
 532         Output: CX      maximum number of descriptors
 533
 534         This routine reports the maximum number of shuffle descriptors
 535         permitted in a call to function 0012h.
 536
 537         Typical values are 682 and 1365.
 538
 539
 540 AX=0012h [3.05] Cleanup, shuffle and boot
 541         Input:  AX      0012h
 542                 DX      derivative-specific flags (see previous function)
 543                 ES:DI   shuffle descriptor list (must be in low memory)
 544                 CX      number of shuffle descriptors
 545                 EBX(!)  initial value of EDX after bootstrap
 546                 ESI     initial value of ESI after bootstrap
 547                 DS      initial value of DS after bootstrap
 548                 EBP     CS:IP of routine to jump to
 549         Output: Does not return
 550                 (if CX is too large the routine returns with CF=1)
 551
 552         This routine performs final cleanup, then performs a sequence
 553         of copies, and jumps to a specified real mode entry point.
 554         This is a more general version of function 000Dh, which can
 555         also be used to load other types of programs.
 556
 557         The copies must not touch memory below address 7C00h.
 558
 559         ES:DI points to a list of CX descriptors each of the form:
 560
 561                 Offset  Size    Meaning
 562                  0      dword   destination address
 563                  4      dword   source address
 564                  8      dword   length in bytes
 565
 566         The copies are overlap-safe, like memmove().
 567
 568         Normal boot sectors expect DL to contain the drive number,
 569         and, for hard drives (DL >= 80h) DS:SI to contain a pointer to
 570         the 16-byte partition table entry.  The memory between
 571         600h-7FFh is available to put the partition table entry in.
 572
 573         For PXELINUX, if the PXE stack is not unloaded, all registers
 574         (except DS, ESI and EDX) and the stack will be set up as they
 575         were set up by the PXE ROM.
 576
 577
 578 AX=0013h [3.08] Idle loop call
 579         Input:  AX      0013h
 580         Output: None
 581
 582         Call this routine while sitting in an idle loop.  It performs
 583         any periodic activities required by the filesystem code.  At
 584         the moment, this is a no-op on all derivatives except
 585         PXELINUX, where it executes PXE calls to answer ARP queries.