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