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