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 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.txt)
 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 functions 0012h, 001Ah and 001Bh.
 565
 566         This is guaranteed to be at least 64.  For the current
 567         version, this is 682 for all derivatives.
 568
 569
 570 AX=0012h [3.50] Cleanup, shuffle and boot
 571         Input:  AX      0012h
 572                 DX      derivative-specific flags (see function 000Ch)
 573                 ES:DI   shuffle descriptor list (must be in low memory)
 574                 CX      number of shuffle descriptors
 575                 EBX(!)  initial value of EDX after bootstrap
 576                 ESI     initial value of ESI after bootstrap
 577                 DS      initial value of DS after bootstrap
 578                 EBP     CS:IP of routine to jump to
 579         Output: Does not return
 580                 (if CX is too large the routine returns with CF=1)
 581
 582         This routine performs final cleanup, then performs a sequence
 583         of copies, and jumps to a specified real mode entry point.
 584         This is a more general version of function 000Dh, which can
 585         also be used to load other types of programs.
 586
 587         The copies must not touch memory below address 7C00h.
 588
 589         ES:DI points to a list of CX descriptors each of the form:
 590
 591                 Offset  Size    Meaning
 592                  0      dword   destination address
 593                  4      dword   source address
 594                  8      dword   length in bytes
 595
 596         The copies are overlap-safe, like memmove().
 597
 598         Starting in version 3.50, if the source address is -1
 599         (FFFFFFFFh) then the block specified by the destination
 600         address and the length is set to all zero.
 601
 602         Starting in version 3.50, if the destination address is -1
 603         (FFFFFFFFh) then the data block is loaded as a new set of
 604         descriptors, and processing is continued (and unprocessed
 605         descriptors are lost, this is thus typically only used as the
 606         last descriptor in a block.)  The block must still fit in the
 607         internal descriptor buffer (see function 0011h), but can, of
 608         course, itself chain another block.
 609
 610
 611         Normal boot sectors expect DL to contain the drive number,
 612         and, for hard drives (DL >= 80h) DS:SI to contain a pointer to
 613         the 16-byte partition table entry.  The memory between
 614         600h-7FFh is available to put the partition table entry in.
 615
 616         For PXELINUX, if the PXE stack is not unloaded, all registers
 617         (except DS, ESI and EDX) and the stack will be set up as they
 618         were set up by the PXE ROM.
 619
 620         This interface was probably broken before version 3.50.
 621
 622
 623 AX=0013h [3.08] Idle loop call
 624         Input:  AX      0013h
 625         Output: None
 626
 627         Call this routine while sitting in an idle loop.  It performs
 628         any periodic activities required by the filesystem code.  At
 629         the moment, this is a no-op on all derivatives except
 630         PXELINUX, where it executes PXE calls to answer ARP queries.
 631
 632         Starting with version 3.10, this API call harmlessly returns
 633         failure (CF=1) if invoked on a platform which does not need
 634         idle calls.  Additionally, it's safe to call this API call on
 635         previous SYSLINUX versions (2.00 or later); it will just
 636         harmlessly fail.  Thus, if this call returns failure (CF=1),
 637         it means that there is no technical reason to call this
 638         function again, although doing so is of course safe.
 639
 640
 641 AX=0014h [3.10] Local boot [PXELINUX, ISOLINUX]
 642         Input:  AX      0014h
 643                 DX      Local boot parameter
 644         Output: Does not return
 645
 646         This function invokes the equivalent of the "localboot"
 647         configuration file option.  The parameter in DX is the same
 648         parameter as would be entered after "localboot" in the
 649         configuration file; this parameter is derivative-specific --
 650         see syslinux.txt for the definition.
 651
 652
 653 AX=0015h [3.10] Get feature flags
 654         Input:  AX      0015h
 655         Output: ES:BX   pointer to flags in memory
 656                 CX      number of flag bytes
 657
 658         This function reports whether or not this SYSLINUX version and
 659         derivative supports specific features.  Keep in mind that
 660         future versions might have more bits; remember to treat any
 661         bits beyond the end of the array (as defined by the value in
 662         CX) as zero.
 663
 664         Currently the following feature flag is defined:
 665
 666         Byte    Bit     Definition
 667         ----------------------------------------------------
 668         0       0       Local boot (AX=0014h) supported
 669                 1       Idle loop call (AX=0013h) is a no-op
 670
 671         All other flags are reserved.
 672
 673
 674 AX=0016h [3.10] Run kernel image
 675         Input:  AX      0016h
 676                 DS:SI   Filename of kernel image (zero-terminated string)
 677                 ES:BX   Command line (zero-terminated string)
 678                 ECX     IPAPPEND flags [PXELINUX]
 679                 EDX     Type of file (since 3.50)
 680         Output: Does not return if successful; returns with CF=1 if
 681                 the kernel image is not found.
 682
 683         This function is similiar to AX=0003h Run command, except that
 684         the filename and command line are treated as if specified in a
 685         KERNEL and APPEND statement of a LABEL statement, which means:
 686
 687         - The filename has to be exact; no variants are tried;
 688         - No global APPEND statement is applied;
 689         - ALLOWOPTIONS and IMPLICIT statements in the configuration
 690           file do not apply.  It is therefore important that the
 691           COMBOOT module doesn't allow the end user to violate the
 692           intent of the administrator.
 693
 694         Additionally, this function returns with a failure if the file
 695         doesn't exist, instead of returning to the command line.  (It
 696         may still return to the command line if the image is somehow
 697         corrupt, however.)
 698
 699         The file types are defined as follows:
 700
 701                     Equivalent
 702         EDX     Config  Extensions      Type of file
 703         0       KERNEL                  Determined by filename extension
 704         1       LINUX   none            Linux kernel image
 705         2       BOOT    .bs .bin        Bootstrap program
 706         3       BSS     .bss            Boot sector with patch [SYSLINUX]
 707         4       PXE     .0              PXE Network Bootstrap Prog [PXELINUX]
 708         5       FDIMAGE .img            Floppy disk image [ISOLINUX]
 709         6       COMBOOT .com .cbt       16-bit COMBOOT program
 710         7       COM32   .c32            COM32 program
 711         8       CONFIG                  Configuration file
 712
 713
 714 AX=0017h [3.30] Report video mode change
 715         Input:  AX      0017h
 716                 BX      Video mode flags
 717                         Bit 0:  graphics mode
 718                         Bit 1:  non-default mode
 719                         Bit 2:  VESA mode
 720                         Bit 3:  text functions not supported
 721                 CX      For graphics modes, pixel columns
 722                 DX      For graphics modes, pixel rows
 723         Output: None
 724
 725         This function is used to report video mode changes to
 726         SYSLINUX.  It does NOT actually change the video mode, but
 727         rather, allows SYSLINUX to take appropriate action in response
 728         to a video mode change.  Modes that cannot be exited either
 729         with the conventional BIOS mode set command (INT 10h, AH=00h)
 730         or the VESA VBE mode set command (INT 10h, AX=4F02h) should
 731         not be used.
 732
 733         This function returns with a failure if BX contains any bits
 734         which are undefined in the current version of SYSLINUX.
 735
 736         The following bits in BX are currently defined:
 737
 738         Bit 0: graphics mode
 739
 740                 Indicates that the mode is a graphics mode, as opposed
 741                 to a text mode.
 742
 743         Bit 1: non-standard mode
 744
 745                 A non-standard mode is any mode except text mode and
 746                 graphics mode 0012h (VGA 640x480, 16 color.)
 747
 748         Bit 2: VESA mode
 749
 750                 This mode is a VESA mode, and has to be exited with
 751                 the VESA VBE API (INT 10h, AX=4F02h) as opposed to the
 752                 conventional BIOS API (INT 10h, AH=00h).
 753
 754         Bit 3: Text functions not supported
 755
 756                 This indicates that the BIOS text output functions
 757                 (INT 10h, AH=02h, 03h, 06h, 09h, 0Eh, 11h) don't work.
 758                 If this bit is set, SYSLINUX will reset the mode
 759                 before printing any characters on the screen.
 760
 761                 This is common for VESA modes.
 762
 763
 764 AX=0018h [3.30] Query custom font
 765         Input:  AX      0018h
 766         Output: AL      Height of custom font in scan lines, or zero
 767                 ES:BX   Pointer to custom font in memory
 768
 769         This call queries if a custom display font has been loaded via
 770         the "font" configuration file command.  If no custom font has
 771         been loaded, AL contains zero.
 772
 773
 774 AX=0019h [3.50] Read disk [SYSLINUX, ISOLINUX, EXTLINUX]
 775         Input:  AX      0019h
 776                 EDX     Sector number
 777                 ESI     Reserved - MUST BE ZERO
 778                 EDI     Reserved - MUST BE ZERO
 779                 CX      Sector count
 780                 ES:BX   Buffer address
 781         Output: None
 782
 783         Read disk blocks from the active filesystem (partition); for
 784         disks, sector number zero is the boot sector.  For ISOLINUX,
 785         this call reads the CD-ROM.
 786
 787         For compatiblity with all systems, the buffer should
 788         *neither* cross 64K boundaries, *nor* wrap around the segment.
 789
 790         This routine reports "boot failed" (and does not return) on
 791         disk error.
 792
 793
 794 AX=001Ah [3.50] Cleanup, shuffle and boot to flat protected mode
 795         Input:  AX      001Ah
 796                 DX      derivative-specific flags (see function 000Ch)
 797                 ES:DI   shuffle descriptor list (must be in low memory)
 798                 CX      number of shuffle descriptors
 799                 DS:SI   pointer to register values (must be in low memory)
 800         Output: Does not return
 801                 (if CX is too large the routine returns with CF=1)
 802
 803         This routine performs final cleanup, then performs a sequence
 804         of copies, and jumps to a specified protected mode entry point.
 805         This is otherwise similar to function 0012h; see that function
 806         for the meaning of ES:DI and CX.
 807
 808         DS:SI points to the initial register file, which is a structure
 809         of 9 dwords (available in <syslinux/bootpm.h>):
 810
 811         struct syslinux_pm_regs {
 812           uint32_t eax;                 /* Offset  0 */
 813           uint32_t ecx;                 /* Offset  4 */
 814           uint32_t edx;                 /* Offset  8 */
 815           uint32_t ebx;                 /* Offset 12 */
 816           uint32_t esp;                 /* Offset 16 */
 817           uint32_t ebp;                 /* Offset 20 */
 818           uint32_t esi;                 /* Offset 24 */
 819           uint32_t edi;                 /* Offset 28 */
 820
 821           uint32_t eip;                 /* Offset 32 */
 822         };
 823
 824         Protected mode is entered with all data segments set up as a
 825         flat 32-bit read/write segment and the code segment a flat 32-bit
 826         read/execute segment.  Interrupts and paging is off, CPL=0, DF=0;
 827         however, GDT, LDT and IDT are undefined, so it is up to the
 828         invoked code to set new descriptor tables to its liking.
 829
 830
 831 AX=001Bh [3.50] Cleanup, shuffle and boot to real mode
 832         Input:  AX      001Bh
 833                 DX      derivative-specific flags (see function 000Ch)
 834                 ES:DI   shuffle descriptor list (must be in low memory)
 835                 CX      number of shuffle descriptors
 836                 DS:SI   pointer to register values (must be in low memory)
 837         Output: Does not return
 838                 (if CX is too large the routine returns with CF=1)
 839
 840         This routine performs final cleanup, then performs a sequence
 841         of copies, and jumps to a specified entry point.
 842         This is similar to function 0012h but allow more control over
 843         the initial register state; see that function for the meaning of
 844         ES:DI and CX.
 845
 846         DS:SI points to the initial register file, which is a structure
 847         in the following format (available in <syslinux/bootrm.h>;
 848         note that this is a completely different structure from the
 849         com32sys_t structure described at the top of this document!):
 850
 851         struct syslinux_rm_regs {
 852           uint16_t es;                  /* Offset  0 */
 853           uint16_t _unused_cs;          /* Offset  2 */
 854           uint16_t ds;                  /* Offset  4 */
 855           uint16_t ss;                  /* Offset  6 */
 856           uint16_t fs;                  /* Offset  8 */
 857           uint16_t gs;                  /* Offset 10 */
 858
 859           reg32_t eax;                  /* Offset 12 */
 860           reg32_t ecx;                  /* Offset 16 */
 861           reg32_t edx;                  /* Offset 20 */
 862           reg32_t ebx;                  /* Offset 24 */
 863           reg32_t esp;                  /* Offset 28 */
 864           reg32_t ebp;                  /* Offset 32 */
 865           reg32_t esi;                  /* Offset 36 */
 866           reg32_t edi;                  /* Offset 40 */
 867
 868           uint16_t ip;                  /* Offset 44 */
 869           uint16_t cs;                  /* Offset 46 */
 870         };
 871
 872         Interrupts are off and DF=0 on entry.
 873
 874
 875 AX=001Ch [3.60] Get pointer to auxilliary data vector
 876         Input:  AX      001Ch
 877         Output: ES:BX   Auxilliary data vector
 878                 CX      Size of the ADV (currently 500 bytes)
 879
 880         The auxillary data vector is a tagged data structure used
 881         to carry a small amount of information (up to 500 bytes) from
 882         one boot to another.
 883
 884
 885 AX=001Dh [3.60] Write auxilliary data vector
 886         Input:  AX      001Dh
 887         Output: None
 888
 889         Write the auxilliary data vector back to disk.  Returns
 890         failure for non-disk-based derivatives unless the "auxdata"
 891         configuration command is used to specify a disk location
 892         (not yet implemented.)
 893
 894         In a future version, PXELINUX may end up attempting to save
 895         the ADV on the server via TFTP write.