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