doc/comboot.txt

   1
   2                        COMBOOT and COM32 files
   3
   4
   5 Syslinux supports simple standalone programs, using a file format
   6 similar to DOS ".com" files.  A 32-bit version, called COM32, is also
   7 provided.  A simple API provides access to a limited set of filesystem
   8 and console functions.
   9
  10
  11         ++++ COMBOOT file format ++++
  12
  13 A COMBOOT file is a raw binary file containing 16-bit code.  It should
  14 be linked to run at offset 0x100, and contain no absolute segment
  15 references.  It is run in 16-bit real mode.
  16
  17 A COMBOOT image can be written to be compatible with MS-DOS.  Such a
  18 file will usually have extension ".com".  A COMBOOT file which is not
  19 compatible with MS-DOS will usually have extension ".cbt".
  20
  21 Before running the program, Syslinux sets up the following fields in
  22 the Program Segment Prefix (PSP), a structure at offset 0 in the
  23 program segment:
  24
  25  Offset Size    Meaning
  26  0      word    Contains an INT 20h instruction
  27  2      word    Contains the paragraph (16-byte "segment" address) at
  28                 the end of memory available to the program.
  29  128    byte    Length of the command line arguments, including the leading
  30                 space but not including the final CR character.
  31  129    127b    Command line arguments, starting with a space and ending
  32                 with a CR character (ASCII 13).
  33
  34 The program is allowed to use memory between the PSP paragraph (which
  35 all the CS, DS, ES and SS registers point to at program start) and the
  36 paragraph value given at offset 2.
  37
  38 On startup, SP is set up to point to the end of the 64K segment, at
  39 0xfffe.  Under DOS it is possible for SP to contain a smaller
  40 value if memory is very tight; this is never the case under Syslinux.
  41
  42 The program should make no assumptions about what segment address it
  43 will be loaded at; instead it should look at the segment registers on
  44 program startup.  Both DOS and Syslinux will guarantee CS == DS == ES
  45 == SS on program start; the program should not assume anything about
  46 the values of FS or GS.
  47
  48 To exit, a program can either execute a near RET (which will jump to
  49 offset 0 which contains an INT 20h instruction, terminating the
  50 program), or execute INT 20h or INT 21h AH=00h or INT 21h AH=4Ch.
  51 If compatiblity with Syslinux 1.xx is desired, use INT 20h.
  52
  53
  54         ++++ COM32 file format ++++
  55
  56 A COM32 file is a raw binary file containing 32-bit code.  It should
  57 be linked to run at address 0x101000, and should not contain any
  58 segment references.  It will be run in flat-memory 32-bit protected
  59 mode.  Under Syslinux, it will be run in CPL 0, however, since it may
  60 be possible to create a COM32 execution engine that would run under
  61 something like Linux DOSEMU, it is recommended that the code does not
  62 assume CPL 0 unless absolutely necessary.
  63
  64 It is highly recommended that every COM32 program begins with the byte
  65 sequence B8 FF 4C CD 21 (mov eax,21cd4cffh) as a magic number.
  66
  67 A COM32 file should have extension ".c32".
  68
  69 On startup, CS will be set up as a flat 32-bit code segment, and DS ==
  70 ES == SS will be set up as the equivalent flat 32-bit data segment.
  71 FS and GS are reserved for future use and are currently initialized to
  72 zero.  A COM32 image should not assume any particular values of
  73 segment selectors.
  74
  75 ESP is set up at the end of available memory and also serves as
  76 notification to the program how much memory is available.
  77
  78 The following arguments are passed to the program on the stack:
  79
  80  Address  Size  Meaning
  81  [ESP]    dword Return (termination) address
  82  [ESP+4]  dword Number of additional arguments (currently 8)
  83  [ESP+8]  dword Pointer to the command line arguments (null-terminated string)
  84  [ESP+12] dword Pointer to INT call helper function
  85  [ESP+16] dword Pointer to low memory bounce buffer
  86  [ESP+20] dword Size of low memory bounce buffer
  87  [ESP+24] dword Pointer to FAR call helper function (new in 2.05)
  88  [ESP+28] dword Pointer to CDECL helper function (new in 3.54)
  89  [ESP+32] dword Amount of memory controlled by the Syslinux core (new in 3.74)
  90  [ESP+36] dword Pointer to the filename of the com32 module (new in 3.86)
  91
  92 The intcall helper function can be used to issue BIOS or Syslinux API
  93 calls, and takes the interrupt number as first argument.  The second
  94 argument is a pointer to the input register definition, an instance of
  95 the following structure (available in <com32.h>):
  96
  97 typedef union {
  98   uint32_t l;
  99   uint16_t w[2];
 100   uint8_t  b[4];
 101 } reg32_t;
 102
 103 typedef struct {
 104   uint16_t gs;                  /* Offset  0 */
 105   uint16_t fs;                  /* Offset  2 */
 106   uint16_t es;                  /* Offset  4 */
 107   uint16_t ds;                  /* Offset  6 */
 108
 109   reg32_t edi;                  /* Offset  8 */
 110   reg32_t esi;                  /* Offset 12 */
 111   reg32_t ebp;                  /* Offset 16 */
 112   reg32_t _unused_esp;          /* Offset 20 */
 113   reg32_t ebx;                  /* Offset 24 */
 114   reg32_t edx;                  /* Offset 28 */
 115   reg32_t ecx;                  /* Offset 32 */
 116   reg32_t eax;                  /* Offset 36 */
 117
 118   reg32_t eflags;               /* Offset 40 */
 119 } com32sys_t;
 120
 121 The third argument is a pointer to the output register definition, an
 122 instance of the same structure.  The third argument can also be zero
 123 (NULL).
 124
 125 Since BIOS or Syslinux API calls can generally only manipulate data
 126 below address 0x100000, a "bounce buffer" in low memory, at least 64K
 127 in size, is available, to copy data in and out.
 128
 129 The farcall helper function behaves similarly, but takes as its first
 130 argument the CS:IP (in the form (CS << 16) + IP) of procedure to be
 131 invoked via a FAR CALL.
 132
 133 The cfarcall helper function takes (CS << 16)+IP, a pointer to a stack
 134 frame, a size of that stack frame, and returns the return value of EAX
 135 (which may need to be appropriate truncated by the user.)
 136
 137
 138         ++++ SYSLINUX API CALLS +++
 139
 140 Syslinux provides the following API calls.  Syslinux 1.xx only
 141 supported INT 20h - terminate program. [] indicates the first version
 142 of Syslinux which supported this feature (correctly.)
 143
 144 NOTE: Most of the API functionality is still experimental.  Expect to
 145 find bugs.
 146
 147
 148         ++++ DOS-COMPATIBLE API CALLS ++++
 149
 150 INT 20h         [1.48] Terminate program
 151 INT 21h AH=00h  [2.00] Terminate program
 152 INT 21h AH=4Ch  [2.00] Terminate program
 153
 154         All of these terminate the program.
 155
 156
 157 INT 21h AH=01h  [2.01] Get Key with Echo
 158
 159         Reads a key from the console input, with echo to the console
 160         output.  The read character is returned in AL.  Extended
 161         characters received from the keyboard are returned as NUL (00h)
 162         + the extended character code.
 163
 164
 165 INT 21h AH=02h  [2.01] Write Character
 166
 167         Writes a character in DL to the console (video and serial)
 168         output.
 169
 170
 171 INT 21h AH=04h  [2.01] Write Character to Serial Port
 172
 173         Writes a character in DL to the serial console output
 174         (if enabled.)  If no serial port is configured, this routine
 175         does nothing.
 176
 177
 178 INT 21h AH=08h  [2.09] Get Key without Echo
 179
 180         Reads a key fron the console input, without echoing it to the
 181         console output.  The read character is returned in AL.
 182
 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
 189 INT 21h AH=0Bh  [2.00] Check Keyboard
 190
 191         Returns AL=FFh if there is a keystroke waiting (which can then
 192         be read with INT 21h, AH=01h or AH=08h), otherwise AL=00h.
 193
 194
 195 INT 21h AH=30h  [2.00] Check DOS Version
 196
 197         This function returns AX=BX=CX=DX=0, corresponding to a
 198         hypothetical "DOS 0.0", but the high parts of EAX-EBX-ECX-EDX
 199         spell "SYSLINUX":
 200
 201         EAX=59530000h EBX=4C530000h ECX=4E490000h EDX=58550000h
 202
 203         This function can thus be used to distinguish running on
 204         Syslinux from running on DOS.
 205
 206
 207         ++++ SYSLINUX-SPECIFIC API CALLS ++++
 208
 209 Syslinux-specific API calls are executed using INT 22h, with a
 210 function number in AX.  INT 22h is used by DOS for internal purposes;
 211 do not execute INT 22h under DOS.
 212
 213 DOS-compatible function INT 21h, AH=30h can be used to detect if the
 214 Syslinux API calls are available.
 215
 216 Any register not specifically listed as modified is preserved;
 217 however, future versions of Syslinux may add additional output
 218 registers to existing calls.
 219
 220 All calls return CF=0 on success, CF=1 on failure.  The noted outputs
 221 apply if CF=0 only unless otherwise noted.  All calls clobber the
 222 arithmetric flags (CF, PF, AF, ZF, SF and OF) but leave all other
 223 flags unchanged unless otherwise noted.
 224
 225
 226 AX=0001h [2.00] Get Version
 227
 228         Input:  AX      0001h
 229         Output: AX      number of INT 22h API functions available
 230                 CH      Syslinux major version number
 231                 CL      Syslinux minor version number
 232                 DL      Syslinux derivative ID (e.g. 32h = PXELINUX)
 233                 ES:SI   Syslinux version string
 234                 ES:DI   Syslinux copyright string
 235
 236         This API call returns the Syslinux version and API
 237         information.
 238
 239         Note: before version 3.86, the version string had a leading CR LF
 240         and the copyright string had a leading space.  The strings might
 241         still contain trailing CR and/or LF.
 242
 243
 244 AX=0002h [2.01] Write String
 245
 246         Input:  AX      0002h
 247                 ES:BX   null-terminated string
 248         Output: None
 249
 250         Writes a null-terminated string on the console.
 251
 252
 253 AX=0003h [2.01] Run command
 254
 255         Input:  AX      0003h
 256                 ES:BX   null-terminated command string
 257         Output: Does not return
 258
 259         This API call terminates the program and executes the command
 260         string as if the user had entered it at the Syslinux command
 261         line.  This API call does not return.
 262
 263
 264 AX=0004h [2.01] Run default command
 265
 266         Input:  AX      0004h
 267         Output: Does not return
 268
 269         This API call terminates the program and executes the default
 270         command string as if the user had pressed Enter alone on the
 271         Syslinux command line.  This API call does not return.
 272
 273
 274 AX=0005h [2.00] Force text mode
 275
 276         Input:  AX      0005h
 277         Output: None
 278
 279         If the screen was in graphics mode (due to displaying a splash
 280         screen using the <Ctrl-X> command in a message file, or
 281         similar), return to text mode.
 282
 283
 284 AX=0006h [2.08] Open file
 285
 286         Input:  AX      0006h
 287                 ES:SI   null-terminated filename
 288         Output: SI      file handle
 289                 EAX     length of file in bytes, or -1
 290                 CX      file block size
 291
 292         Open a file for reading.  The exact syntax of the filenames
 293         allowed depends on the particular Syslinux derivative.
 294
 295         The Syslinux file system is block-oriented.  The size of a
 296         block will always be a power of two and no greater than 16K.
 297
 298         Note: Syslinux considers a zero-length file to be nonexistent.
 299
 300         In 3.70 or later, EAX can contain -1 indicating that the file
 301         length is unknown.
 302
 303
 304 AX=0007h [2.08] Read file
 305
 306         Input:  AX      0007h
 307                 SI      file handle
 308                 ES:BX   buffer
 309                 CX      number of blocks to read
 310         Output: SI      file handle, or 0 if EOF was reached
 311                 ECX     number of bytes read [3.70]
 312
 313         Read blocks from a file.  Note that the file handle that is
 314         returned in SI may not be the same value that was passed in.
 315
 316         If end of file was reached (SI=0), the file was automatically
 317         closed.
 318
 319         In 3.70 or later, ECX returns the number of bytes read.  This
 320         will always be a multiple of the block size unless EOF is
 321         reached.
 322
 323         The address of the buffer (ES:BX) should be at least 512-byte
 324         aligned.  Syslinux guarantees at least this alignment for the
 325         COMBOOT load segment or the COM32 bounce buffer.
 326
 327         Keep in mind that a "file" may be a TFTP connection, and that
 328         leaving a file open for an extended period of time may result
 329         in a timeout.
 330
 331         WARNING: Calling this function with an invalid file handle
 332         will probably crash the system.
 333
 334
 335 AX=0008h [2.08] Close file
 336
 337         Input:  AX      0008h
 338                 SI      file handle
 339         Output: None
 340
 341         Close a file before reaching the end of file.
 342
 343         WARNING: Calling this function with an invalid file handle
 344         will probably crash the system.
 345
 346
 347 AX=0009h [2.00] Call PXE Stack [PXELINUX ONLY]
 348
 349         Input:  AX      0009h
 350                 BX      PXE function number
 351                 ES:DI   PXE parameter structure buffer
 352         Output: AX      PXE return status code
 353
 354         Invoke an arbitrary PXE stack function.  On SYSLINUX/ISOLINUX,
 355         this function returns with an error (CF=1) and no action is
 356         taken.  On PXELINUX, this function always returns with CF=0
 357         indicating that the PXE stack was successfully invoked; check
 358         the status code in AX and in the first word of the data buffer
 359         to determine if the PXE call succeeded or not.
 360
 361         The PXE stack will have the UDP stack OPEN; if you change that
 362         you cannot call any of the file-related API functions, and
 363         must restore UDP OPEN before returning to PXELINUX.
 364
 365         PXELINUX reserves UDP port numbers from 49152 to 65535 for its
 366         own use; port numbers below that range is available.
 367
 368
 369 AX=000Ah [2.00] Get Derivative-Specific Information
 370
 371         [SYSLINUX, EXTLINUX]
 372         Input:  AX      000Ah
 373                 CL      9 (to get a valid return in CL for all versions)
 374         Output: AL      31h (SYSLINUX), 34h (EXTLINUX)
 375                 DL      drive number
 376                 CL      sector size as a power of 2 (9 = 512 bytes) [3.35]
 377                 ES:BX   pointer to partition table entry (if DL >= 80h)
 378                 FS:SI   pointer to initial ES:DI value [3.53]
 379
 380                 Note: This function was broken in EXTLINUX 3.00-3.02.
 381
 382                 On boot, ES:DI is supposed to point to the BIOS $PnP
 383                 structure, although in practice most operating systems
 384                 will search for it in memory.  However, preserving
 385                 this while chainloading is probably a good idea.
 386
 387                 Note that FS:SI is a pointer to a memory location
 388                 containing the original ES:DI value, not the value
 389                 itself.
 390
 391
 392         [PXELINUX]
 393         Input:  AX      000Ah
 394         Output: AL      32h (PXELINUX)
 395                 DX      PXE API version detected (DH=major, DL=minor)
 396                 ECX     Local IP number (network byte order) [3.85]
 397                 ES:BX   pointer to PXENV+ or !PXE structure
 398                 FS:SI   pointer to original stack with invocation record
 399
 400                 Note: DX notes the API version detected by PXELINUX,
 401                 which may be more conservative than the actual version
 402                 available.  For exact information examine the API
 403                 version entry in the PXENV+ structure, or the API
 404                 version entries in the ROMID structures pointed from
 405                 the !PXE structure.
 406
 407                 PXELINUX will use, and provide, the !PXE structure
 408                 over the PXENV+ structure.  Examine the structure
 409                 signature to determine which particular structure was
 410                 provided.
 411
 412                 The FS:SI pointer points to the top of the original stack
 413                 provided by the PXE stack, with the following values
 414                 pushed at the time PXELINUX is started:
 415
 416                 [fs:si+0]       GS              <- top of stack
 417                 [fs:si+2]       FS
 418                 [fs:si+4]       ES
 419                 [fs:si+6]       DS
 420                 [fs:si+8]       EDI
 421                 [fs:si+12]      ESI
 422                 [fs:si+16]      EBP
 423                 [fs:si+20]      -
 424                 [fs:si+24]      EBX
 425                 [fs:si+28]      EDX
 426                 [fs:si+32]      ECX
 427                 [fs:si+36]      EAX
 428                 [fs:si+40]      EFLAGS
 429                 [fs:si+44]      PXE return IP   <- t.o.s. when PXELINUX invoked
 430                 [fs:si+46]      PXE return CS
 431
 432
 433         [ISOLINUX]
 434         Input:  AX      000Ah
 435         Output: AL      33h (ISOLINUX)
 436                 DL      drive number
 437                 CL      11 (sector size as a power of 2) [3.35]
 438                 CH      mode [3.73]
 439                         0 = El Torito
 440                         1 = Hybrid (hard disk), CBIOS mode
 441                         2 = Hybrid (hard disk), EBIOS mode
 442                 ES:BX   pointer to El Torito spec packet
 443                 FS:SI   pointer to initial ES:DI value [3.53]
 444
 445                 Note: Some very broken El Torito implementations do
 446                 not provide the spec packet information.  If so, ES:BX
 447                 may point to all zeroes or to garbage.  Call INT 13h,
 448                 AX=4B01h to obtain the spec packet directly from the
 449                 BIOS if necessary.
 450
 451         This call gives information specific to a particular Syslinux
 452         derivative.  The value returned in AL is the same as is
 453         returned in DL by INT 22h AX=0001h.
 454
 455
 456 AX=000Bh [2.00] Get Serial Console Configuration
 457
 458         Input:  AX      000Bh
 459         Output: DX      serial port I/O base (e.g. 3F8h = COM1...)
 460                 CX      baud rate divisor (1 = 115200 bps, 2 = 57600 bps...)
 461                 BX      flow control configuration bits (see syslinux.txt)
 462                         -> bit 15 is set if the video console is disabled
 463
 464         If no serial port is configured, DX will be set to 0 and the
 465         other registers are undefined.
 466
 467
 468 AX=000Ch [2.00] Perform final cleanup
 469         Input:  AX      000Ch
 470                 DX      derivative-specific flags (0000h = clean up all)
 471         Output: None
 472
 473         This routine performs any "final cleanup" the boot loader
 474         would normally perform before loading a kernel, such as
 475         unloading the PXE stack in the case of PXELINUX.  AFTER
 476         INVOKING THIS CALL, NO OTHER API CALLS MAY BE INVOKED, NOR MAY
 477         THE PROGRAM TERMINATE AND RETURN TO THE BOOT LOADER.  This
 478         call basically tells the boot loader "get out of the way, I'll
 479         handle it from here."
 480
 481         For COM32 images, the boot loader will continue to provide
 482         interrupt and BIOS call thunking services as long its memory
 483         areas (0x0800-0xffff, 0x100000-0x100fff) are not overwritten.
 484         MAKE SURE TO DISABLE INTERRUPTS, AND INSTALL NEW GDT AND IDTS
 485         BEFORE OVERWRITING THESE MEMORY AREAS.
 486
 487         The permissible values for DX is an OR of these values:
 488
 489         SYSLINUX:       0000h   Normal cleanup
 490
 491         PXELINUX:       0000h   Normal cleanup
 492                         0003h   Keep UNDI and PXE stacks loaded
 493
 494         ISOLINUX:       0000h   Normal cleanup
 495
 496         EXTLINUX:       0000h   Normal cleanup
 497
 498         All other values are undefined, and may have different
 499         meanings in future versions of Syslinux.
 500
 501
 502 AX=000Dh [2.08] Cleanup and replace bootstrap code
 503         Input:  AX      000Dh
 504                 DX      derivative-specific flags (see previous function)
 505                 EDI     bootstrap code (linear address, can be in high memory)
 506                 ECX     bootstrap code length in bytes (must fit in low mem)
 507                 EBX(!)  initial value of EDX after bootstrap
 508                 ESI     initial value of ESI after bootstrap
 509                 DS      initial value of DS after bootstrap
 510         Output: Does not return
 511
 512         This routine performs final cleanup, then takes a piece of
 513         code, copies it over the primary bootstrap at address 7C00h,
 514         and jumps to it.  This can be used to chainload boot sectors,
 515         MBRs, bootstraps, etc.
 516
 517         Normal boot sectors expect DL to contain the drive number,
 518         and, for hard drives (DL >= 80h) DS:SI to contain a pointer to
 519         the 16-byte partition table entry.  The memory between
 520         600h-7FFh is available to put the partition table entry in.
 521
 522         For PXELINUX, if the PXE stack is not unloaded, all registers
 523         (except DS, ESI and EDX) and the stack will be set up as they
 524         were set up by the PXE ROM.
 525
 526
 527 AX=000Eh [2.11] Get configuration file name
 528         Input:  AX      0000Eh
 529         Output: ES:BX   null-terminated file name string
 530
 531         Returns the name of the configuration file.  Note that it is
 532         possible that the configuration file doesn't actually exist.
 533
 534
 535 AX=000Fh [3.00] Get IPAPPEND strings [PXELINUX]
 536         Input:  AX      000Fh
 537         Output: CX      number of strings (currently 2)
 538                 ES:BX   pointer to an array of NEAR pointers in
 539                         the same segment, one for each of the above
 540                         strings
 541
 542         Returns the same strings that the "ipappend" option would have
 543         added to the command line, one for each bit of the "ipappend"
 544         flag value, so entry 0 is the "ip=" string and entry 1 is the
 545         "BOOTIF=" string.
 546
 547
 548 AX=0010h [3.00] Resolve hostname [PXELINUX]
 549         Input:  AX      0010h
 550                 ES:BX   pointer to null-terminated hostname
 551         Output: EAX     IP address of hostname (zero if not found)
 552
 553         Queries the DNS server(s) for a specific hostname.  If the
 554         hostname does not contain a dot (.), the local domain name
 555         is automatically appended.
 556
 557         This function only return CF=1 if the function is not
 558         supported.  If the function is supported, but the hostname did
 559         not resolve, it returns with CF=0, EAX=0.
 560
 561         The IP address is returned in network byte order, i.e. if the
 562         IP address is 1.2.3.4, EAX will contain 0x04030201.  Note that
 563         all uses of IP addresses in PXE are also in network byte order.
 564
 565
 566 AX=0011h [3.05] Obsoleted in 3.80
 567
 568
 569 AX=0012h [3.50] Cleanup, shuffle and boot
 570         Input:  AX      0012h
 571                 DX      derivative-specific flags (see function 000Ch)
 572                 ES:DI   shuffle descriptor list (must be in low memory)
 573                 CX      number of shuffle descriptors
 574                 EBX(!)  initial value of EDX after bootstrap
 575                 ESI     initial value of ESI after bootstrap
 576                 DS      initial value of DS after bootstrap
 577                 EBP     CS:IP of routine to jump to
 578         Output: Does not return
 579                 (if CX is too large the routine returns with CF=1)
 580
 581         This routine performs final cleanup, then performs a sequence
 582         of copies, and jumps to a specified real mode entry point.
 583         This is a more general version of function 000Dh, which can
 584         also be used to load other types of programs.
 585
 586         The copies must not touch memory below address 7C00h.
 587
 588         ES:DI points to a list of CX descriptors each of the form:
 589
 590                 Offset  Size    Meaning
 591                  0      dword   destination address
 592                  4      dword   source address
 593                  8      dword   length in bytes
 594
 595         The copies are overlap-safe, like memmove().
 596
 597         Starting in version 3.50, if the source address is -1
 598         (FFFFFFFFh) then the block specified by the destination
 599         address and the length is set to all zero.
 600
 601         Starting in version 3.50, if the destination address is -1
 602         (FFFFFFFFh) then the data block is loaded as a new set of
 603         descriptors, and processing is continued (and unprocessed
 604         descriptors are lost, this is thus typically only used as the
 605         last descriptor in a block.)  The block must still fit in the
 606         internal descriptor buffer (see function 0011h), but can, of
 607         course, itself chain another block.
 608
 609
 610         Normal boot sectors expect DL to contain the drive number,
 611         and, for hard drives (DL >= 80h) DS:SI to contain a pointer to
 612         the 16-byte partition table entry.  The memory between
 613         600h-7FFh is available to put the partition table entry in.
 614
 615         For PXELINUX, if the PXE stack is not unloaded, all registers
 616         (except DS, ESI and EDX) and the stack will be set up as they
 617         were set up by the PXE ROM.
 618
 619         This interface was probably broken before version 3.50.
 620
 621
 622 AX=0013h [3.08] Idle loop call
 623         Input:  AX      0013h
 624         Output: None
 625
 626         Call this routine while sitting in an idle loop.  It performs
 627         any periodic activities required by the filesystem code.  At
 628         the moment, this is a no-op on all derivatives except
 629         PXELINUX, where it executes PXE calls to answer ARP queries.
 630
 631         Starting with version 3.10, this API call harmlessly returns
 632         failure (CF=1) if invoked on a platform which does not need
 633         idle calls.  Additionally, it's safe to call this API call on
 634         previous Syslinux versions (2.00 or later); it will just
 635         harmlessly fail.  Thus, if this call returns failure (CF=1),
 636         it means that there is no technical reason to call this
 637         function again, although doing so is of course safe.
 638
 639
 640 AX=0014h [3.10] Local boot [PXELINUX, ISOLINUX]
 641         Input:  AX      0014h
 642                 DX      Local boot parameter
 643         Output: Does not return
 644
 645         This function invokes the equivalent of the "localboot"
 646         configuration file option.  The parameter in DX is the same
 647         parameter as would be entered after "localboot" in the
 648         configuration file; this parameter is derivative-specific --
 649         see syslinux.txt for the definition.
 650
 651
 652 AX=0015h [3.10] Get feature flags
 653         Input:  AX      0015h
 654         Output: ES:BX   pointer to flags in memory
 655                 CX      number of flag bytes
 656
 657         This function reports whether or not this Syslinux version and
 658         derivative supports specific features.  Keep in mind that
 659         future versions might have more bits; remember to treat any
 660         bits beyond the end of the array (as defined by the value in
 661         CX) as zero.
 662
 663         Currently the following feature flag is defined:
 664
 665         Byte    Bit     Definition
 666         ----------------------------------------------------
 667         0       0       Local boot (AX=0014h) supported
 668                 1       Idle loop call (AX=0013h) is a no-op
 669
 670         All other flags are reserved.
 671
 672
 673 AX=0016h [3.10] Run kernel image
 674         Input:  AX      0016h
 675                 DS:SI   Filename of kernel image (zero-terminated string)
 676                 ES:BX   Command line (zero-terminated string)
 677                 ECX     IPAPPEND flags [PXELINUX]
 678                 EDX     Type of file (since 3.50)
 679         Output: Does not return if successful; returns with CF=1 if
 680                 the kernel image is not found.
 681
 682         This function is similiar to AX=0003h Run command, except that
 683         the filename and command line are treated as if specified in a
 684         KERNEL and APPEND statement of a LABEL statement, which means:
 685
 686         - The filename has to be exact; no variants are tried;
 687         - No global APPEND statement is applied;
 688         - ALLOWOPTIONS and IMPLICIT statements in the configuration
 689           file do not apply.  It is therefore important that the
 690           COMBOOT module doesn't allow the end user to violate the
 691           intent of the administrator.
 692
 693         Additionally, this function returns with a failure if the file
 694         doesn't exist, instead of returning to the command line.  (It
 695         may still return to the command line if the image is somehow
 696         corrupt, however.)
 697
 698         The file types are defined as follows:
 699
 700                     Equivalent
 701         EDX     Config  Extensions      Type of file
 702         0       KERNEL                  Determined by filename extension
 703         1       LINUX   none            Linux kernel image
 704         2       BOOT    .bs .bin        Bootstrap program
 705         3       BSS     .bss            Boot sector with patch [SYSLINUX]
 706         4       PXE     .0              PXE Network Bootstrap Prog [PXELINUX]
 707         5       FDIMAGE .img            Floppy disk image [ISOLINUX]
 708         6       COMBOOT .com .cbt       16-bit COMBOOT program
 709         7       COM32   .c32            COM32 program
 710         8       CONFIG                  Configuration file
 711
 712
 713 AX=0017h [3.30] Report video mode change
 714         Input:  AX      0017h
 715                 BX      Video mode flags
 716                         Bit 0:  graphics mode
 717                         Bit 1:  non-default mode
 718                         Bit 2:  VESA mode
 719                         Bit 3:  text functions not supported
 720                 CX      For graphics modes, pixel columns
 721                 DX      For graphics modes, pixel rows
 722         Output: None
 723
 724         This function is used to report video mode changes to
 725         Syslinux.  It does NOT actually change the video mode, but
 726         rather, allows Syslinux to take appropriate action in response
 727         to a video mode change.  Modes that cannot be exited either
 728         with the conventional BIOS mode set command (INT 10h, AH=00h)
 729         or the VESA VBE mode set command (INT 10h, AX=4F02h) should
 730         not be used.
 731
 732         This function returns with a failure if BX contains any bits
 733         which are undefined in the current version of Syslinux.
 734
 735         The following bits in BX are currently defined:
 736
 737         Bit 0: graphics mode
 738
 739                 Indicates that the mode is a graphics mode, as opposed
 740                 to a text mode.
 741
 742         Bit 1: non-standard mode
 743
 744                 A non-standard mode is any mode except text mode and
 745                 graphics mode 0012h (VGA 640x480, 16 color.)
 746
 747         Bit 2: VESA mode
 748
 749                 This mode is a VESA mode, and has to be exited with
 750                 the VESA VBE API (INT 10h, AX=4F02h) as opposed to the
 751                 conventional BIOS API (INT 10h, AH=00h).
 752
 753         Bit 3: Text functions not supported
 754
 755                 This indicates that the BIOS text output functions
 756                 (INT 10h, AH=02h, 03h, 06h, 09h, 0Eh, 11h) don't work.
 757                 If this bit is set, Syslinux will reset the mode
 758                 before printing any characters on the screen.
 759
 760                 This is common for VESA modes.
 761
 762
 763 AX=0018h [3.30] Query custom font
 764         Input:  AX      0018h
 765         Output: AL      Height of custom font in scan lines, or zero
 766                 ES:BX   Pointer to custom font in memory
 767
 768         This call queries if a custom display font has been loaded via
 769         the "font" configuration file command.  If no custom font has
 770         been loaded, AL contains zero.
 771
 772
 773 AX=0019h [3.50] Read disk [SYSLINUX, ISOLINUX, EXTLINUX]
 774         Input:  AX      0019h
 775                 EDX     Sector number
 776                 ESI     Reserved - MUST BE ZERO
 777                 EDI     Reserved - MUST BE ZERO
 778                 CX      Sector count
 779                 ES:BX   Buffer address
 780         Output: None
 781
 782         Read disk blocks from the active filesystem (partition); for
 783         disks, sector number zero is the boot sector.  For ISOLINUX,
 784         this call reads the CD-ROM.
 785
 786         For compatiblity with all systems, the buffer should
 787         *neither* cross 64K boundaries, *nor* wrap around the segment.
 788
 789         This routine reports "boot failed" (and does not return) on
 790         disk error.
 791
 792         Note: for ISOLINUX in hybrid mode, this call uses simulated
 793         2048-byte CD-ROM sector numbers.
 794
 795
 796 AX=001Ah [3.50] Obsoleted in 3.80
 797
 798
 799 AX=001Bh [3.50] Obsoleted in 3.80
 800
 801
 802 AX=001Ch [3.60] Get pointer to auxilliary data vector
 803         Input:  AX      001Ch
 804         Output: ES:BX   Auxilliary data vector
 805                 CX      Size of the ADV (currently 500 bytes)
 806
 807         The auxillary data vector is a tagged data structure used
 808         to carry a small amount of information (up to 500 bytes) from
 809         one boot to another.
 810
 811
 812 AX=001Dh [3.60] Write auxilliary data vector
 813         Input:  AX      001Dh
 814         Output: None
 815
 816         Write the auxilliary data vector back to disk.  Returns
 817         failure for non-disk-based derivatives unless the "auxdata"
 818         configuration command is used to specify a disk location
 819         (not yet implemented.)
 820
 821         In a future version, PXELINUX may end up attempting to save
 822         the ADV on the server via TFTP write.
 823
 824
 825 AX=001Eh [3.74] Keyboard remapping table
 826         Input:  AX      001Eh
 827                 DX      0000h - all other values reserved
 828         Output: AX      format version (1)
 829                 CX      length in bytes (256)
 830                 ES:BX   pointer to keyboard table
 831
 832         This call queries the keyboard remapping table.  For the current
 833         version, the format code is always 1 and the length is always
 834         256.  This version can be updated simply by overwriting the version
 835         in memory; this may not be true in the future.
 836
 837
 838 AX=001Fh [3.74] Get current working directory
 839         Input:  AX      0001Fh
 840         Output: ES:BX   null-terminated directory name string
 841
 842         Returns the current working directory.  For SYSLINUX, ISOLINUX,
 843         and PXELINUX, this will be an absolute path.  For EXTLINUX, it
 844         currently returns "./".
 845
 846
 847 AX=0020h [3.74] Open directory
 848         Input:  AX      0020h
 849                 ES:SI   /-null-terminated directory name
 850         Output: SI      directory handle
 851                 EAX     clobbered
 852
 853         Open a directory for reading.  Directory name must have a trailing
 854          "/" before the null (otherwise, you're looking for a file)(This
 855         may change as this is a BETA call).
 856
 857
 858 AX=0021h [3.74] Read directory
 859         Input:  AX      0021h
 860                 SI      directory handle
 861                 ES:DI   buffer for file name
 862         Output: DL      Type of file
 863                 SI      directory handle, or 0 if end of directory was reached
 864                 EAX     Size of file
 865                 EBX     Inode of file
 866
 867         Read one filename from the directory, incrementing the
 868         directory structure at SI as appropriate, storing the filename
 869         into the buffer at ES:DI, and returning the type of the file
 870         in DL, the file length in EAX, the inode/file number in EBX
 871         and the updated directory handle.
 872
 873
 874 AX=0022h [3.74] Close directory
 875         Input:  AX      0022h
 876                 SI      directory handle
 877         Output  SI      0
 878
 879         Closes a directory.
 880
 881
 882 AX=0023h [3.80] Get shuffler parameters
 883         Input:  AX      0023h
 884         Output: CX      size of shuffler "safe area" in bytes
 885                 Other registers reserved for future use
 886
 887         This call gives the size of the required shuffler "safe area",
 888         in bytes; for call 0024h.  In the future, it may provide
 889         additional parameters.
 890
 891
 892 AX=0024h [3.80] Cleanup, shuffle and boot, raw version
 893         Input:  AX      0024h
 894                 DX      derivative-specific flags (see function 000Ch)
 895                 EDI     shuffle descriptor list safe area
 896                 ESI     shuffle descriptor list source
 897                 ECX     byte count of shuffle descriptor list
 898         Output: Does not return
 899
 900         This routine performs final cleanup, then performs a sequence
 901         of copies, and jumps to a specified real mode entry point.
 902         This is a more general version of function 000Dh, which can
 903         also be used to load other types of programs.
 904
 905         Unlike previous obsolete versions of this function, there are
 906         no restrictions that copies must not touch memory below
 907         address 7C00h.  Either the shuffle descriptor list or the safe
 908         area (or both) may be located in high memory.
 909
 910         ESI points to a list of descriptors each of the form:
 911
 912                 Offset  Size    Meaning
 913                  0      dword   destination address
 914                  4      dword   source address (-1 = zero)
 915                  8      dword   length in bytes (0 = end of list)
 916
 917         The copies are overlap-safe, like memmove().
 918
 919         Before actually executing the move list, the list is moved to
 920         the address specified in EDI.  The caller is responsibe to
 921         ensure that the moved descriptor list plus a "safe area"
 922         immediately afterwards (the size of which is specified by
 923         function 0023h) is not disturbed by the copy sequence.  It is,
 924         however, safe to overwrite descriptors already consumed.
 925
 926         If the source address is -1 (FFFFFFFFh) then the block
 927         specified by the destination address and the length is set to
 928         all zero.
 929
 930         The list is terminated by an entry with length 0.  For that
 931         entry, the destination is used as an entry point, and the
 932         source represents the type of entry point:
 933
 934                 0       16-bit protected mode (dst is CS.base)
 935                 1       Flat 32-bit protected mode (dst is EIP)
 936
 937         This routine does not set up any GPR register state
 938         whatsoever, including stack.  It is the responsibility of the
 939         caller to make sure the entry point provided sets up any
 940         registers needed.
 941
 942         For mode 0 (16-bit real mode), EAX will contain CR0 with bit 0
 943         masked out, suitable for loading into CR0 to immediately enter
 944         real mode.  Note: if real-mode entry is planned,
 945         (CS.base & 0xfff0000f) should == 0 for compatibility with KVM,
 946         and possibly other virtualization solutions.
 947
 948         In both mode 0 and mode 1, the data segments will be loaded
 949         with read/write data segments, matching the respective code
 950         segment.  For mode 0, B=0 and the limits will be 64K, for mode
 951         1, B=1 and the limits will be 4 GB.