doc/comboot.txt

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