comboot.doc

   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 5)
  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
  90 This corresponds to the following C prototype, available in the file
  91 com32/include/com32.h:
  92
  93 /* The standard prototype for _start() */
  94 int _start(unsigned int __nargs,
  95            char *__cmdline,
  96            void (*__intcall)(uint8_t, com32sys_t *, com32sys_t *),
  97            void *__bounce_ptr,
  98            unsigned int __bounce_len,
  99            void (*__farcall)(uint32_t, com32sys_t *, com32sys_t *),
 100            int (*__cfarcall)(uint32_t, void *, size_t)
 101            );
 102
 103 The intcall helper function can be used to issue BIOS or SYSLINUX API
 104 calls, and takes the interrupt number as first argument.  The second
 105 argument is a pointer to the input register definition, an instance of
 106 the following structure (available in <com32.h>):
 107
 108 typedef union {
 109   uint32_t l;
 110   uint16_t w[2];
 111   uint8_t  b[4];
 112 } reg32_t;
 113
 114 typedef struct {
 115   uint16_t gs;                  /* Offset  0 */
 116   uint16_t fs;                  /* Offset  2 */
 117   uint16_t es;                  /* Offset  4 */
 118   uint16_t ds;                  /* Offset  6 */
 119
 120   reg32_t edi;                  /* Offset  8 */
 121   reg32_t esi;                  /* Offset 12 */
 122   reg32_t ebp;                  /* Offset 16 */
 123   reg32_t _unused_esp;          /* Offset 20 */
 124   reg32_t ebx;                  /* Offset 24 */
 125   reg32_t edx;                  /* Offset 28 */
 126   reg32_t ecx;                  /* Offset 32 */
 127   reg32_t eax;                  /* Offset 36 */
 128
 129   reg32_t eflags;               /* Offset 40 */
 130 } com32sys_t;
 131
 132 The third argument is a pointer to the output register definition, an
 133 instance of the same structure.  The third argument can also be zero
 134 (NULL).
 135
 136 Since BIOS or SYSLINUX API calls can generally only manipulate data
 137 below address 0x100000, a "bounce buffer" in low memory, at least 64K
 138 in size, is available, to copy data in and out.
 139
 140 The farcall helper function behaves similarly, but takes as its first
 141 argument the CS:IP (in the form (CS << 16) + IP) of procedure to be
 142 invoked via a FAR CALL.
 143
 144 The cfarcall helper function takes (CS << 16)+IP, a pointer to a stack
 145 frame, a size of that stack frame, and returns the return value of EAX
 146 (which may need to be appropriate truncated by the user.)
 147
 148
 149         ++++ SYSLINUX API CALLS +++
 150
 151 SYSLINUX provides the following API calls.  SYSLINUX 1.xx only
 152 supported INT 20h - terminate program. [] indicates the first version
 153 of SYSLINUX which supported this feature (correctly.)
 154
 155 NOTE: Most of the API functionality is still experimental.  Expect to
 156 find bugs.
 157
 158
 159         ++++ DOS-COMPATIBLE API CALLS ++++
 160
 161 INT 20h         [1.48] Terminate program
 162 INT 21h AH=00h  [2.00] Terminate program
 163 INT 21h AH=4Ch  [2.00] Terminate program
 164
 165         All of these terminate the program.
 166
 167
 168 INT 21h AH=01h  [2.01] Get Key with Echo
 169
 170         Reads a key from the console input, with echo to the console
 171         output.  The read character is returned in AL.  Extended
 172         characters received from the keyboard are returned as NUL (00h)
 173         + the extended character code.
 174
 175
 176 INT 21h AH=02h  [2.01] Write Character
 177
 178         Writes a character in DL to the console (video and serial)
 179         output.
 180
 181
 182 INT 21h AH=04h  [2.01] Write Character to Serial Port
 183
 184         Writes a character in DL to the serial console output
 185         (if enabled.)  If no serial port is configured, this routine
 186         does nothing.
 187
 188
 189 INT 21h AH=08h  [2.09] Get Key without Echo
 190
 191         Reads a key fron the console input, without echoing it to the
 192         console output.  The read character is returned in AL.
 193
 194
 195 INT 21h AH=09h  [2.01] Write DOS String to Console
 196
 197         Writes a DOS $-terminated string in DS:DX to the console.
 198
 199
 200 INT 21h AH=0Bh  [2.00] Check Keyboard
 201
 202         Returns AL=FFh if there is a keystroke waiting (which can then
 203         be read with INT 21h, AH=01h or AH=08h), otherwise AL=00h.
 204
 205
 206 INT 21h AH=30h  [2.00] Check DOS Version
 207
 208         This function returns AX=BX=CX=DX=0, corresponding to a
 209         hypothetical "DOS 0.0", but the high parts of EAX-EBX-ECX-EDX
 210         spell "SYSLINUX":
 211
 212         EAX=59530000h EBX=4C530000h ECX=4E490000h EDX=58550000h
 213
 214         This function can thus be used to distinguish running on
 215         SYSLINUX from running on DOS.
 216
 217
 218         ++++ SYSLINUX-SPECIFIC API CALLS ++++
 219
 220 SYSLINUX-specific API calls are executed using INT 22h, with a
 221 function number in AX.  INT 22h is used by DOS for internal purposes;
 222 do not execute INT 22h under DOS.
 223
 224 DOS-compatible function INT 21h, AH=30h can be used to detect if the
 225 SYSLINUX API calls are available.
 226
 227 Any register not specifically listed as modified is preserved;
 228 however, future versions of SYSLINUX may add additional output
 229 registers to existing calls.
 230
 231 All calls return CF=0 on success, CF=1 on failure.  The noted outputs
 232 apply if CF=0 only unless otherwise noted.  All calls clobber the
 233 arithmetric flags (CF, PF, AF, ZF, SF and OF) but leave all other
 234 flags unchanged unless otherwise noted.
 235
 236
 237 AX=0001h [2.00] Get Version
 238
 239         Input:  AX      0001h
 240         Output: AX      number of INT 22h API functions available
 241                 CH      SYSLINUX major version number
 242                 CL      SYSLINUX minor version number
 243                 DL      SYSLINUX derivative ID (e.g. 32h = PXELINUX)
 244                 ES:SI   SYSLINUX version string
 245                 ES:DI   SYSLINUX copyright string
 246
 247         This API call returns the SYSLINUX version and API
 248         information.
 249
 250
 251 AX=0002h [2.01] Write String
 252
 253         Input:  AX      0002h
 254                 ES:BX   null-terminated string
 255         Output: None
 256
 257         Writes a null-terminated string on the console.
 258
 259
 260 AX=0003h [2.01] Run command
 261
 262         Input:  AX      0003h
 263                 ES:BX   null-terminated command string
 264         Output: Does not return
 265
 266         This API call terminates the program and executes the command
 267         string as if the user had entered it at the SYSLINUX command
 268         line.  This API call does not return.
 269
 270
 271 AX=0004h [2.01] Run default command
 272
 273         Input:  AX      0004h
 274         Output: Does not return
 275
 276         This API call terminates the program and executes the default
 277         command string as if the user had pressed Enter alone on the
 278         SYSLINUX command line.  This API call does not return.
 279
 280
 281 AX=0005h [2.00] Force text mode
 282
 283         Input:  AX      0005h
 284         Output: None
 285
 286         If the screen was in graphics mode (due to displaying a splash
 287         screen using the <Ctrl-X> command in a message file, or
 288         similar), return to text mode.
 289
 290
 291 AX=0006h [2.08] Open file
 292
 293         Input:  AX      0006h
 294                 ES:SI   null-terminated filename
 295         Output: SI      file handle
 296                 EAX     length of file in bytes
 297                 CX      file block size
 298
 299         Open a file for reading.  The exact syntax of the filenames
 300         allowed depends on the particular SYSLINUX derivative.
 301
 302         The SYSLINUX file system is block-oriented.  The size of a
 303         block will always be a power of two and no greater than 16K.
 304
 305         Note: SYSLINUX considers a zero-length file to be nonexistent.
 306
 307
 308 AX=0007h [2.08] Read file
 309
 310         Input:  AX      0007h
 311                 SI      file handle
 312                 ES:BX   buffer
 313                 CX      number of blocks to read
 314         Output: SI      file handle, or 0 if EOF was reached
 315
 316         Read blocks from a file.  Note that the file handle that is
 317         returned in SI may not be the same value that was passed in.
 318
 319         If end of file was reached (SI=0), the file was automatically
 320         closed.
 321
 322         The address of the buffer (ES:BX) should be at least 512-byte
 323         aligned.  SYSLINUX guarantees at least this alignment for the
 324         COMBOOT load segment or the COM32 bounce buffer.
 325
 326         Keep in mind that a "file" may be a TFTP connection, and that
 327         leaving a file open for an extended period of time may result
 328         in a timeout.
 329
 330         WARNING: Calling this function with an invalid file handle
 331         will probably crash the system.
 332
 333
 334 AX=0008h [2.08] Close file
 335
 336         Input:  AX      0008h
 337                 SI      file handle
 338         Output: None
 339
 340         Close a file before reaching the end of file.
 341
 342         WARNING: Calling this function with an invalid file handle
 343         will probably crash the system.
 344
 345
 346 AX=0009h [2.00] Call PXE Stack [PXELINUX ONLY]
 347
 348         Input:  AX      0009h
 349                 BX      PXE function number
 350                 ES:DI   PXE parameter structure buffer
 351         Output: AX      PXE return status code
 352
 353         Invoke an arbitrary PXE stack function.  On SYSLINUX/ISOLINUX,
 354         this function returns with an error (CF=1) and no action is
 355         taken.  On PXELINUX, this function always returns with CF=0
 356         indicating that the PXE stack was successfully invoked; check
 357         the status code in AX and in the first word of the data buffer
 358         to determine if the PXE call succeeded or not.
 359
 360         The PXE stack will have the UDP stack OPEN; if you change that
 361         you cannot call any of the file-related API functions, and
 362         must restore UDP OPEN before returning to PXELINUX.
 363
 364         PXELINUX reserves UDP port numbers from 49152 to 65535 for its
 365         own use; port numbers below that range is available.
 366
 367
 368 AX=000Ah [2.00] Get Derivative-Specific Information
 369
 370         [SYSLINUX, EXTLINUX]
 371         Input:  AX      000Ah
 372                 CL      9 (to get a valid return in CL for all versions)
 373         Output: AL      31h (SYSLINUX), 34h (EXTLINUX)
 374                 DL      drive number
 375                 CL      sector size as a power of 2 (9 = 512 bytes) [3.35]
 376                 ES:BX   pointer to partition table entry (if DL >= 80h)
 377                 FS:SI   pointer to initial ES:DI value [3.53]
 378
 379                 Note: This function was broken in EXTLINUX 3.00-3.02.
 380
 381                 On boot, ES:DI is supposed to point to the BIOS $PnP
 382                 structure, although in practice most operating systems
 383                 will search for it in memory.  However, preserving
 384                 this while chainloading is probably a good idea.
 385
 386                 Note that FS:SI is a pointer to a memory location
 387                 containing the original ES:DI value, not the value
 388                 itself.
 389
 390
 391         [PXELINUX]
 392         Input:  AX      000Ah
 393         Output: AL      32h (PXELINUX)
 394                 DX      PXE API version detected (DH=major, DL=minor)
 395                 ES:BX   pointer to PXENV+ or !PXE structure
 396                 FS:SI   pointer to original stack with invocation record
 397
 398                 Note: DX notes the API version detected by PXELINUX,
 399                 which may be more conservative than the actual version
 400                 available.  For exact information examine the API
 401                 version entry in the PXENV+ structure, or the API
 402                 version entries in the ROMID structures pointed from
 403                 the !PXE structure.
 404
 405                 PXELINUX will use, and provide, the !PXE structure
 406                 over the PXENV+ structure.  Examine the structure
 407                 signature to determine which particular structure was
 408                 provided.
 409
 410                 The FS:SI pointer points to the top of the original stack
 411                 provided by the PXE stack, with the following values
 412                 pushed at the time PXELINUX is started:
 413
 414                 [fs:si+0]       GS              <- top of stack
 415                 [fs:si+2]       FS
 416                 [fs:si+4]       ES
 417                 [fs:si+6]       DS
 418                 [fs:si+8]       EDI
 419                 [fs:si+12]      ESI
 420                 [fs:si+16]      EBP
 421                 [fs:si+20]      -
 422                 [fs:si+24]      EBX
 423                 [fs:si+28]      EDX
 424                 [fs:si+32]      ECX
 425                 [fs:si+36]      EAX
 426                 [fs:si+40]      EFLAGS
 427                 [fs:si+44]      PXE return IP   <- t.o.s. when PXELINUX invoked
 428                 [fs:si+46]      PXE return CS
 429
 430
 431         [ISOLINUX]
 432         Input:  AX      000Ah
 433         Output: AL      33h (ISOLINUX)
 434                 DL      drive number
 435                 CL      11 (sector size as a power of 2) [3.35]
 436                 ES:BX   pointer to El Torito spec packet
 437                 FS:SI   pointer to initial ES:DI value [3.53]
 438
 439                 Note: Some very broken El Torito implementations do
 440                 not provide the spec packet information.  If so, ES:BX
 441                 may point to all zeroes or to garbage.  Call INT 13h,
 442                 AX=4B01h to obtain the spec packet directly from the
 443                 BIOS if necessary.
 444
 445         This call gives information specific to a particular SYSLINUX
 446         derivative.  The value returned in AL is the same as is
 447         returned in DL by INT 22h AX=0001h.
 448
 449
 450 AX=000Bh [2.00] Get Serial Console Configuration
 451
 452         Input:  AX      000Bh
 453         Output: DX      serial port I/O base (e.g. 3F8h = COM1...)
 454                 CX      baud rate divisor (1 = 115200 bps, 2 = 57600 bps...)
 455                 BX      flow control configuration bits (see syslinux.doc)
 456                         -> bit 15 is set if the video console is disabled
 457
 458         If no serial port is configured, DX will be set to 0 and the
 459         other registers are undefined.
 460
 461
 462 AX=000Ch [2.00] Perform final cleanup
 463         Input:  AX      000Ch
 464                 DX      derivative-specific flags (0000h = clean up all)
 465         Output: None
 466
 467         This routine performs any "final cleanup" the boot loader
 468         would normally perform before loading a kernel, such as
 469         unloading the PXE stack in the case of PXELINUX.  AFTER
 470         INVOKING THIS CALL, NO OTHER API CALLS MAY BE INVOKED, NOR MAY
 471         THE PROGRAM TERMINATE AND RETURN TO THE BOOT LOADER.  This
 472         call basically tells the boot loader "get out of the way, I'll
 473         handle it from here."
 474
 475         For COM32 images, the boot loader will continue to provide
 476         interrupt and BIOS call thunking services as long its memory
 477         areas (0x0800-0xffff, 0x100000-0x100fff) are not overwritten.
 478         MAKE SURE TO DISABLE INTERRUPTS, AND INSTALL NEW GDT AND IDTS
 479         BEFORE OVERWRITING THESE MEMORY AREAS.
 480
 481         The permissible values for DX is an OR of these values:
 482
 483         SYSLINUX:       0000h   Normal cleanup
 484
 485         PXELINUX:       0000h   Normal cleanup
 486                         0003h   Keep UNDI and PXE stacks loaded
 487
 488         ISOLINUX:       0000h   Normal cleanup
 489
 490         EXTLINUX:       0000h   Normal cleanup
 491
 492         All other values are undefined, and may have different
 493         meanings in future versions of SYSLINUX.
 494
 495
 496 AX=000Dh [2.08] Cleanup and replace bootstrap code
 497         Input:  AX      000Dh
 498                 DX      derivative-specific flags (see previous function)
 499                 EDI     bootstrap code (linear address, can be in high memory)
 500                 ECX     bootstrap code length in bytes (must fit in low mem)
 501                 EBX(!)  initial value of EDX after bootstrap
 502                 ESI     initial value of ESI after bootstrap
 503                 DS      initial value of DS after bootstrap
 504         Output: Does not return
 505
 506         This routine performs final cleanup, then takes a piece of
 507         code, copies it over the primary bootstrap at address 7C00h,
 508         and jumps to it.  This can be used to chainload boot sectors,
 509         MBRs, bootstraps, etc.
 510
 511         Normal boot sectors expect DL to contain the drive number,
 512         and, for hard drives (DL >= 80h) DS:SI to contain a pointer to
 513         the 16-byte partition table entry.  The memory between
 514         600h-7FFh is available to put the partition table entry in.
 515
 516         For PXELINUX, if the PXE stack is not unloaded, all registers
 517         (except DS, ESI and EDX) and the stack will be set up as they
 518         were set up by the PXE ROM.
 519
 520
 521 AX=000Eh [2.11] Get configuration file name
 522         Input:  AX      0000Eh
 523         Output: ES:BX   null-terminated file name string
 524
 525         Returns the name of the configuration file.  Note that it is
 526         possible that the configuration file doesn't actually exist.
 527
 528
 529 AX=000Fh [3.00] Get IPAPPEND strings [PXELINUX]
 530         Input:  AX      000Fh
 531         Output: CX      number of strings (currently 2)
 532                 ES:BX   pointer to an array of NEAR pointers in
 533                         the same segment, one for each of the above
 534                         strings
 535
 536         Returns the same strings that the "ipappend" option would have
 537         added to the command line, one for each bit of the "ipappend"
 538         flag value, so entry 0 is the "ip=" string and entry 1 is the
 539         "BOOTIF=" string.
 540
 541
 542 AX=0010h [3.00] Resolve hostname [PXELINUX]
 543         Input:  ES:BX   pointer to null-terminated hostname
 544         Output: EAX     IP address of hostname (zero if not found)
 545
 546         Queries the DNS server(s) for a specific hostname.  If the
 547         hostname does not contain a dot (.), the local domain name
 548         is automatically appended.
 549
 550         This function only return CF=1 if the function is not
 551         supported.  If the function is supported, but the hostname did
 552         not resolve, it returns with CF=0, EAX=0.
 553
 554         The IP address is returned in network byte order, i.e. if the
 555         IP address is 1.2.3.4, EAX will contain 0x04030201.  Note that
 556         all uses of IP addresses in PXE are also in network byte order.
 557
 558
 559 AX=0011h [3.05] Maximum number of shuffle descriptors
 560         Input:  AX      0011h
 561         Output: CX      maximum number of descriptors
 562
 563         This routine reports the maximum number of shuffle descriptors
 564         permitted in a call to function 0012h.
 565
 566         Typical values are 682 and 1365.
 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.doc 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
 793 AX=001Ah [3.50] Cleanup, shuffle and boot to flat protected mode
 794         Input:  AX      001Ah
 795                 DX      derivative-specific flags (see function 000Ch)
 796                 ES:DI   shuffle descriptor list (must be in low memory)
 797                 CX      number of shuffle descriptors
 798                 DS:SI   pointer to register values (must be in low memory)
 799         Output: Does not return
 800                 (if CX is too large the routine returns with CF=1)
 801
 802         This routine performs final cleanup, then performs a sequence
 803         of copies, and jumps to a specified protected mode entry point.
 804         This is otherwise similar to function 0012h; see that function
 805         for the meaning of ES:DI and CX.
 806
 807         DS:SI points to the initial register file, which is a structure
 808         of 9 dwords (available in <syslinux/bootpm.h>):
 809
 810         struct syslinux_pm_regs {
 811           uint32_t eax;                 /* Offset  0 */
 812           uint32_t ecx;                 /* Offset  4 */
 813           uint32_t edx;                 /* Offset  8 */
 814           uint32_t ebx;                 /* Offset 12 */
 815           uint32_t esp;                 /* Offset 16 */
 816           uint32_t ebp;                 /* Offset 20 */
 817           uint32_t esi;                 /* Offset 24 */
 818           uint32_t edi;                 /* Offset 28 */
 819
 820           uint32_t eip;                 /* Offset 32 */
 821         };
 822
 823         Protected mode is entered with all data segments set up as a
 824         flat 32-bit read/write segment and the code segment a flat 32-bit
 825         read/execute segment.  Interrupts and paging is off, CPL=0, DF=0;
 826         however, GDT, LDT and IDT are undefined, so it is up to the
 827         invoked code to set new descriptor tables to its liking.
 828
 829
 830 AX=001Bh [3.50] Cleanup, shuffle and boot to real mode
 831         Input:  AX      001Ah
 832                 DX      derivative-specific flags (see function 000Ch)
 833                 ES:DI   shuffle descriptor list (must be in low memory)
 834                 CX      number of shuffle descriptors
 835                 DS:SI   pointer to register values (must be in low memory)
 836         Output: Does not return
 837                 (if CX is too large the routine returns with CF=1)
 838
 839         This routine performs final cleanup, then performs a sequence
 840         of copies, and jumps to a specified entry point.
 841         This is similar to function 0012h but allow more control over
 842         the initial register state; see that function for the meaning of
 843         ES:DI and CX.
 844
 845         DS:SI points to the initial register file, which is a structure
 846         in the following format (available in <syslinux/bootrm.h>;
 847         note that this is a completely different structure from the
 848         com32sys_t structure described at the top of this document!):
 849
 850         struct syslinux_rm_regs {
 851           uint16_t es;                  /* Offset  0 */
 852           uint16_t _unused_cs;          /* Offset  2 */
 853           uint16_t ds;                  /* Offset  4 */
 854           uint16_t ss;                  /* Offset  6 */
 855           uint16_t fs;                  /* Offset  8 */
 856           uint16_t gs;                  /* Offset 10 */
 857
 858           reg32_t eax;                  /* Offset 12 */
 859           reg32_t ecx;                  /* Offset 16 */
 860           reg32_t edx;                  /* Offset 20 */
 861           reg32_t ebx;                  /* Offset 24 */
 862           reg32_t esp;                  /* Offset 28 */
 863           reg32_t ebp;                  /* Offset 32 */
 864           reg32_t esi;                  /* Offset 36 */
 865           reg32_t edi;                  /* Offset 40 */
 866
 867           uint16_t ip;                  /* Offset 44 */
 868           uint16_t cs;                  /* Offset 46 */
 869         };
 870
 871         Interrupts are off and DF=0 on entry.