| blob | 387303d3f6fc4c495a8083b859af100eebf721b9 |
2 COMBOOT and COM32 files
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.
11 ++++ COMBOOT file format ++++
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.
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".
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:
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).
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.
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.
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.
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.
54 ++++ COM32 file format ++++
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.
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.
67 A COM32 file should have extension ".c32".
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.
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.
78 The following arguments are passed to the program on the stack:
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)
90 This corresponds to the following C prototype, available in the file
91 com32/include/com32.h:
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 );
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>):
108 typedef union {
109 uint32_t l;
110 uint16_t w[2];
111 uint8_t b[4];
112 } reg32_t;
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 */
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 */
129 reg32_t eflags; /* Offset 40 */
130 } com32sys_t;
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).
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.
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.
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.)
149 ++++ SYSLINUX API CALLS +++
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.)
155 NOTE: Most of the API functionality is still experimental. Expect to
156 find bugs.
159 ++++ DOS-COMPATIBLE API CALLS ++++
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
165 All of these terminate the program.
168 INT 21h AH=01h [2.01] Get Key with Echo
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.
176 INT 21h AH=02h [2.01] Write Character
178 Writes a character in DL to the console (video and serial)
179 output.
182 INT 21h AH=04h [2.01] Write Character to Serial Port
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.
189 INT 21h AH=08h [2.09] Get Key without Echo
191 Reads a key fron the console input, without echoing it to the
192 console output. The read character is returned in AL.
195 INT 21h AH=09h [2.01] Write DOS String to Console
197 Writes a DOS $-terminated string in DS:DX to the console.
200 INT 21h AH=0Bh [2.00] Check Keyboard
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.
206 INT 21h AH=30h [2.00] Check DOS Version
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":
212 EAX=59530000h EBX=4C530000h ECX=4E490000h EDX=58550000h
214 This function can thus be used to distinguish running on
215 Syslinux from running on DOS.
218 ++++ SYSLINUX-SPECIFIC API CALLS ++++
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.
224 DOS-compatible function INT 21h, AH=30h can be used to detect if the
225 Syslinux API calls are available.
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.
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.
237 AX=0001h [2.00] Get Version
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
247 This API call returns the Syslinux version and API
248 information.
251 AX=0002h [2.01] Write String
253 Input: AX 0002h
254 ES:BX null-terminated string
255 Output: None
257 Writes a null-terminated string on the console.
260 AX=0003h [2.01] Run command
262 Input: AX 0003h
263 ES:BX null-terminated command string
264 Output: Does not return
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.
271 AX=0004h [2.01] Run default command
273 Input: AX 0004h
274 Output: Does not return
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.
281 AX=0005h [2.00] Force text mode
283 Input: AX 0005h
284 Output: None
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.
291 AX=0006h [2.08] Open file
293 Input: AX 0006h
294 ES:SI null-terminated filename
295 Output: SI file handle
296 EAX length of file in bytes, or -1
297 CX file block size
299 Open a file for reading. The exact syntax of the filenames
300 allowed depends on the particular Syslinux derivative.
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.
305 Note: Syslinux considers a zero-length file to be nonexistent.
307 In 3.70 or later, EAX can contain -1 indicating that the file
308 length is unknown.
311 AX=0007h [2.08] Read file
313 Input: AX 0007h
314 SI file handle
315 ES:BX buffer
316 CX number of blocks to read
317 Output: SI file handle, or 0 if EOF was reached
318 ECX number of bytes read [3.70]
320 Read blocks from a file. Note that the file handle that is
321 returned in SI may not be the same value that was passed in.
323 If end of file was reached (SI=0), the file was automatically
324 closed.
326 In 3.70 or later, ECX returns the number of bytes read. This
327 will always be a multiple of the block size unless EOF is
328 reached.
330 The address of the buffer (ES:BX) should be at least 512-byte
331 aligned. Syslinux guarantees at least this alignment for the
332 COMBOOT load segment or the COM32 bounce buffer.
334 Keep in mind that a "file" may be a TFTP connection, and that
335 leaving a file open for an extended period of time may result
336 in a timeout.
338 WARNING: Calling this function with an invalid file handle
339 will probably crash the system.
342 AX=0008h [2.08] Close file
344 Input: AX 0008h
345 SI file handle
346 Output: None
348 Close a file before reaching the end of file.
350 WARNING: Calling this function with an invalid file handle
351 will probably crash the system.
354 AX=0009h [2.00] Call PXE Stack [PXELINUX ONLY]
356 Input: AX 0009h
357 BX PXE function number
358 ES:DI PXE parameter structure buffer
359 Output: AX PXE return status code
361 Invoke an arbitrary PXE stack function. On SYSLINUX/ISOLINUX,
362 this function returns with an error (CF=1) and no action is
363 taken. On PXELINUX, this function always returns with CF=0
364 indicating that the PXE stack was successfully invoked; check
365 the status code in AX and in the first word of the data buffer
366 to determine if the PXE call succeeded or not.
368 The PXE stack will have the UDP stack OPEN; if you change that
369 you cannot call any of the file-related API functions, and
370 must restore UDP OPEN before returning to PXELINUX.
372 PXELINUX reserves UDP port numbers from 49152 to 65535 for its
373 own use; port numbers below that range is available.
376 AX=000Ah [2.00] Get Derivative-Specific Information
378 [SYSLINUX, EXTLINUX]
379 Input: AX 000Ah
380 CL 9 (to get a valid return in CL for all versions)
381 Output: AL 31h (SYSLINUX), 34h (EXTLINUX)
382 DL drive number
383 CL sector size as a power of 2 (9 = 512 bytes) [3.35]
384 ES:BX pointer to partition table entry (if DL >= 80h)
385 FS:SI pointer to initial ES:DI value [3.53]
387 Note: This function was broken in EXTLINUX 3.00-3.02.
389 On boot, ES:DI is supposed to point to the BIOS $PnP
390 structure, although in practice most operating systems
391 will search for it in memory. However, preserving
392 this while chainloading is probably a good idea.
394 Note that FS:SI is a pointer to a memory location
395 containing the original ES:DI value, not the value
396 itself.
399 [PXELINUX]
400 Input: AX 000Ah
401 Output: AL 32h (PXELINUX)
402 DX PXE API version detected (DH=major, DL=minor)
403 ES:BX pointer to PXENV+ or !PXE structure
404 FS:SI pointer to original stack with invocation record
406 Note: DX notes the API version detected by PXELINUX,
407 which may be more conservative than the actual version
408 available. For exact information examine the API
409 version entry in the PXENV+ structure, or the API
410 version entries in the ROMID structures pointed from
411 the !PXE structure.
413 PXELINUX will use, and provide, the !PXE structure
414 over the PXENV+ structure. Examine the structure
415 signature to determine which particular structure was
416 provided.
418 The FS:SI pointer points to the top of the original stack
419 provided by the PXE stack, with the following values
420 pushed at the time PXELINUX is started:
422 [fs:si+0] GS <- top of stack
423 [fs:si+2] FS
424 [fs:si+4] ES
425 [fs:si+6] DS
426 [fs:si+8] EDI
427 [fs:si+12] ESI
428 [fs:si+16] EBP
429 [fs:si+20] -
430 [fs:si+24] EBX
431 [fs:si+28] EDX
432 [fs:si+32] ECX
433 [fs:si+36] EAX
434 [fs:si+40] EFLAGS
435 [fs:si+44] PXE return IP <- t.o.s. when PXELINUX invoked
436 [fs:si+46] PXE return CS
439 [ISOLINUX]
440 Input: AX 000Ah
441 Output: AL 33h (ISOLINUX)
442 DL drive number
443 CL 11 (sector size as a power of 2) [3.35]
444 CH mode [3.73]
445 0 = El Torito
446 1 = Hybrid (hard disk), CBIOS mode
447 2 = Hybrid (hard disk), EBIOS mode
448 ES:BX pointer to El Torito spec packet
449 FS:SI pointer to initial ES:DI value [3.53]
451 Note: Some very broken El Torito implementations do
452 not provide the spec packet information. If so, ES:BX
453 may point to all zeroes or to garbage. Call INT 13h,
454 AX=4B01h to obtain the spec packet directly from the
455 BIOS if necessary.
457 This call gives information specific to a particular Syslinux
458 derivative. The value returned in AL is the same as is
459 returned in DL by INT 22h AX=0001h.
462 AX=000Bh [2.00] Get Serial Console Configuration
464 Input: AX 000Bh
465 Output: DX serial port I/O base (e.g. 3F8h = COM1...)
466 CX baud rate divisor (1 = 115200 bps, 2 = 57600 bps...)
467 BX flow control configuration bits (see syslinux.txt)
468 -> bit 15 is set if the video console is disabled
470 If no serial port is configured, DX will be set to 0 and the
471 other registers are undefined.
474 AX=000Ch [2.00] Perform final cleanup
475 Input: AX 000Ch
476 DX derivative-specific flags (0000h = clean up all)
477 Output: None
479 This routine performs any "final cleanup" the boot loader
480 would normally perform before loading a kernel, such as
481 unloading the PXE stack in the case of PXELINUX. AFTER
482 INVOKING THIS CALL, NO OTHER API CALLS MAY BE INVOKED, NOR MAY
483 THE PROGRAM TERMINATE AND RETURN TO THE BOOT LOADER. This
484 call basically tells the boot loader "get out of the way, I'll
485 handle it from here."
487 For COM32 images, the boot loader will continue to provide
488 interrupt and BIOS call thunking services as long its memory
489 areas (0x0800-0xffff, 0x100000-0x100fff) are not overwritten.
490 MAKE SURE TO DISABLE INTERRUPTS, AND INSTALL NEW GDT AND IDTS
491 BEFORE OVERWRITING THESE MEMORY AREAS.
493 The permissible values for DX is an OR of these values:
495 SYSLINUX: 0000h Normal cleanup
497 PXELINUX: 0000h Normal cleanup
498 0003h Keep UNDI and PXE stacks loaded
500 ISOLINUX: 0000h Normal cleanup
502 EXTLINUX: 0000h Normal cleanup
504 All other values are undefined, and may have different
505 meanings in future versions of Syslinux.
508 AX=000Dh [2.08] Cleanup and replace bootstrap code
509 Input: AX 000Dh
510 DX derivative-specific flags (see previous function)
511 EDI bootstrap code (linear address, can be in high memory)
512 ECX bootstrap code length in bytes (must fit in low mem)
513 EBX(!) initial value of EDX after bootstrap
514 ESI initial value of ESI after bootstrap
515 DS initial value of DS after bootstrap
516 Output: Does not return
518 This routine performs final cleanup, then takes a piece of
519 code, copies it over the primary bootstrap at address 7C00h,
520 and jumps to it. This can be used to chainload boot sectors,
521 MBRs, bootstraps, etc.
523 Normal boot sectors expect DL to contain the drive number,
524 and, for hard drives (DL >= 80h) DS:SI to contain a pointer to
525 the 16-byte partition table entry. The memory between
526 600h-7FFh is available to put the partition table entry in.
528 For PXELINUX, if the PXE stack is not unloaded, all registers
529 (except DS, ESI and EDX) and the stack will be set up as they
530 were set up by the PXE ROM.
533 AX=000Eh [2.11] Get configuration file name
534 Input: AX 0000Eh
535 Output: ES:BX null-terminated file name string
537 Returns the name of the configuration file. Note that it is
538 possible that the configuration file doesn't actually exist.
541 AX=000Fh [3.00] Get IPAPPEND strings [PXELINUX]
542 Input: AX 000Fh
543 Output: CX number of strings (currently 2)
544 ES:BX pointer to an array of NEAR pointers in
545 the same segment, one for each of the above
546 strings
548 Returns the same strings that the "ipappend" option would have
549 added to the command line, one for each bit of the "ipappend"
550 flag value, so entry 0 is the "ip=" string and entry 1 is the
551 "BOOTIF=" string.
554 AX=0010h [3.00] Resolve hostname [PXELINUX]
555 Input: ES:BX pointer to null-terminated hostname
556 Output: EAX IP address of hostname (zero if not found)
558 Queries the DNS server(s) for a specific hostname. If the
559 hostname does not contain a dot (.), the local domain name
560 is automatically appended.
562 This function only return CF=1 if the function is not
563 supported. If the function is supported, but the hostname did
564 not resolve, it returns with CF=0, EAX=0.
566 The IP address is returned in network byte order, i.e. if the
567 IP address is 1.2.3.4, EAX will contain 0x04030201. Note that
568 all uses of IP addresses in PXE are also in network byte order.
571 AX=0011h [3.05] Maximum number of shuffle descriptors
572 Input: AX 0011h
573 Output: CX maximum number of descriptors
575 This routine reports the maximum number of shuffle descriptors
576 permitted in a call to functions 0012h, 001Ah and 001Bh.
578 This is guaranteed to be at least 64. For the current
579 version, this is 682 for all derivatives.
582 AX=0012h [3.50] Cleanup, shuffle and boot
583 Input: AX 0012h
584 DX derivative-specific flags (see function 000Ch)
585 ES:DI shuffle descriptor list (must be in low memory)
586 CX number of shuffle descriptors
587 EBX(!) initial value of EDX after bootstrap
588 ESI initial value of ESI after bootstrap
589 DS initial value of DS after bootstrap
590 EBP CS:IP of routine to jump to
591 Output: Does not return
592 (if CX is too large the routine returns with CF=1)
594 This routine performs final cleanup, then performs a sequence
595 of copies, and jumps to a specified real mode entry point.
596 This is a more general version of function 000Dh, which can
597 also be used to load other types of programs.
599 The copies must not touch memory below address 7C00h.
601 ES:DI points to a list of CX descriptors each of the form:
603 Offset Size Meaning
604 0 dword destination address
605 4 dword source address
606 8 dword length in bytes
608 The copies are overlap-safe, like memmove().
610 Starting in version 3.50, if the source address is -1
611 (FFFFFFFFh) then the block specified by the destination
612 address and the length is set to all zero.
614 Starting in version 3.50, if the destination address is -1
615 (FFFFFFFFh) then the data block is loaded as a new set of
616 descriptors, and processing is continued (and unprocessed
617 descriptors are lost, this is thus typically only used as the
618 last descriptor in a block.) The block must still fit in the
619 internal descriptor buffer (see function 0011h), but can, of
620 course, itself chain another block.
623 Normal boot sectors expect DL to contain the drive number,
624 and, for hard drives (DL >= 80h) DS:SI to contain a pointer to
625 the 16-byte partition table entry. The memory between
626 600h-7FFh is available to put the partition table entry in.
628 For PXELINUX, if the PXE stack is not unloaded, all registers
629 (except DS, ESI and EDX) and the stack will be set up as they
630 were set up by the PXE ROM.
632 This interface was probably broken before version 3.50.
635 AX=0013h [3.08] Idle loop call
636 Input: AX 0013h
637 Output: None
639 Call this routine while sitting in an idle loop. It performs
640 any periodic activities required by the filesystem code. At
641 the moment, this is a no-op on all derivatives except
642 PXELINUX, where it executes PXE calls to answer ARP queries.
644 Starting with version 3.10, this API call harmlessly returns
645 failure (CF=1) if invoked on a platform which does not need
646 idle calls. Additionally, it's safe to call this API call on
647 previous Syslinux versions (2.00 or later); it will just
648 harmlessly fail. Thus, if this call returns failure (CF=1),
649 it means that there is no technical reason to call this
650 function again, although doing so is of course safe.
653 AX=0014h [3.10] Local boot [PXELINUX, ISOLINUX]
654 Input: AX 0014h
655 DX Local boot parameter
656 Output: Does not return
658 This function invokes the equivalent of the "localboot"
659 configuration file option. The parameter in DX is the same
660 parameter as would be entered after "localboot" in the
661 configuration file; this parameter is derivative-specific --
662 see syslinux.txt for the definition.
665 AX=0015h [3.10] Get feature flags
666 Input: AX 0015h
667 Output: ES:BX pointer to flags in memory
668 CX number of flag bytes
670 This function reports whether or not this Syslinux version and
671 derivative supports specific features. Keep in mind that
672 future versions might have more bits; remember to treat any
673 bits beyond the end of the array (as defined by the value in
674 CX) as zero.
676 Currently the following feature flag is defined:
678 Byte Bit Definition
679 ----------------------------------------------------
680 0 0 Local boot (AX=0014h) supported
681 1 Idle loop call (AX=0013h) is a no-op
683 All other flags are reserved.
686 AX=0016h [3.10] Run kernel image
687 Input: AX 0016h
688 DS:SI Filename of kernel image (zero-terminated string)
689 ES:BX Command line (zero-terminated string)
690 ECX IPAPPEND flags [PXELINUX]
691 EDX Type of file (since 3.50)
692 Output: Does not return if successful; returns with CF=1 if
693 the kernel image is not found.
695 This function is similiar to AX=0003h Run command, except that
696 the filename and command line are treated as if specified in a
697 KERNEL and APPEND statement of a LABEL statement, which means:
699 - The filename has to be exact; no variants are tried;
700 - No global APPEND statement is applied;
701 - ALLOWOPTIONS and IMPLICIT statements in the configuration
702 file do not apply. It is therefore important that the
703 COMBOOT module doesn't allow the end user to violate the
704 intent of the administrator.
706 Additionally, this function returns with a failure if the file
707 doesn't exist, instead of returning to the command line. (It
708 may still return to the command line if the image is somehow
709 corrupt, however.)
711 The file types are defined as follows:
713 Equivalent
714 EDX Config Extensions Type of file
715 0 KERNEL Determined by filename extension
716 1 LINUX none Linux kernel image
717 2 BOOT .bs .bin Bootstrap program
718 3 BSS .bss Boot sector with patch [SYSLINUX]
719 4 PXE .0 PXE Network Bootstrap Prog [PXELINUX]
720 5 FDIMAGE .img Floppy disk image [ISOLINUX]
721 6 COMBOOT .com .cbt 16-bit COMBOOT program
722 7 COM32 .c32 COM32 program
723 8 CONFIG Configuration file
726 AX=0017h [3.30] Report video mode change
727 Input: AX 0017h
728 BX Video mode flags
729 Bit 0: graphics mode
730 Bit 1: non-default mode
731 Bit 2: VESA mode
732 Bit 3: text functions not supported
733 CX For graphics modes, pixel columns
734 DX For graphics modes, pixel rows
735 Output: None
737 This function is used to report video mode changes to
738 Syslinux. It does NOT actually change the video mode, but
739 rather, allows Syslinux to take appropriate action in response
740 to a video mode change. Modes that cannot be exited either
741 with the conventional BIOS mode set command (INT 10h, AH=00h)
742 or the VESA VBE mode set command (INT 10h, AX=4F02h) should
743 not be used.
745 This function returns with a failure if BX contains any bits
746 which are undefined in the current version of Syslinux.
748 The following bits in BX are currently defined:
750 Bit 0: graphics mode
752 Indicates that the mode is a graphics mode, as opposed
753 to a text mode.
755 Bit 1: non-standard mode
757 A non-standard mode is any mode except text mode and
758 graphics mode 0012h (VGA 640x480, 16 color.)
760 Bit 2: VESA mode
762 This mode is a VESA mode, and has to be exited with
763 the VESA VBE API (INT 10h, AX=4F02h) as opposed to the
764 conventional BIOS API (INT 10h, AH=00h).
766 Bit 3: Text functions not supported
768 This indicates that the BIOS text output functions
769 (INT 10h, AH=02h, 03h, 06h, 09h, 0Eh, 11h) don't work.
770 If this bit is set, Syslinux will reset the mode
771 before printing any characters on the screen.
773 This is common for VESA modes.
776 AX=0018h [3.30] Query custom font
777 Input: AX 0018h
778 Output: AL Height of custom font in scan lines, or zero
779 ES:BX Pointer to custom font in memory
781 This call queries if a custom display font has been loaded via
782 the "font" configuration file command. If no custom font has
783 been loaded, AL contains zero.
786 AX=0019h [3.50] Read disk [SYSLINUX, ISOLINUX, EXTLINUX]
787 Input: AX 0019h
788 EDX Sector number
789 ESI Reserved - MUST BE ZERO
790 EDI Reserved - MUST BE ZERO
791 CX Sector count
792 ES:BX Buffer address
793 Output: None
795 Read disk blocks from the active filesystem (partition); for
796 disks, sector number zero is the boot sector. For ISOLINUX,
797 this call reads the CD-ROM.
799 For compatiblity with all systems, the buffer should
800 *neither* cross 64K boundaries, *nor* wrap around the segment.
802 This routine reports "boot failed" (and does not return) on
803 disk error.
805 Note: for ISOLINUX in hybrid mode, this call uses simulated
806 2048-byte CD-ROM sector numbers.
809 AX=001Ah [3.50] Cleanup, shuffle and boot to flat protected mode
810 Input: AX 001Ah
811 DX derivative-specific flags (see function 000Ch)
812 ES:DI shuffle descriptor list (must be in low memory)
813 CX number of shuffle descriptors
814 DS:SI pointer to register values (must be in low memory)
815 Output: Does not return
816 (if CX is too large the routine returns with CF=1)
818 This routine performs final cleanup, then performs a sequence
819 of copies, and jumps to a specified protected mode entry point.
820 This is otherwise similar to function 0012h; see that function
821 for the meaning of ES:DI and CX.
823 DS:SI points to the initial register file, which is a structure
824 of 9 dwords (available in <syslinux/bootpm.h>):
826 struct syslinux_pm_regs {
827 uint32_t eax; /* Offset 0 */
828 uint32_t ecx; /* Offset 4 */
829 uint32_t edx; /* Offset 8 */
830 uint32_t ebx; /* Offset 12 */
831 uint32_t esp; /* Offset 16 */
832 uint32_t ebp; /* Offset 20 */
833 uint32_t esi; /* Offset 24 */
834 uint32_t edi; /* Offset 28 */
836 uint32_t eip; /* Offset 32 */
837 };
839 Protected mode is entered with all data segments set up as a
840 flat 32-bit read/write segment and the code segment a flat 32-bit
841 read/execute segment. Interrupts and paging is off, CPL=0, DF=0;
842 however, GDT, LDT and IDT are undefined, so it is up to the
843 invoked code to set new descriptor tables to its liking.
846 AX=001Bh [3.50] Cleanup, shuffle and boot to real mode
847 Input: AX 001Bh
848 DX derivative-specific flags (see function 000Ch)
849 ES:DI shuffle descriptor list (must be in low memory)
850 CX number of shuffle descriptors
851 DS:SI pointer to register values (must be in low memory)
852 Output: Does not return
853 (if CX is too large the routine returns with CF=1)
855 This routine performs final cleanup, then performs a sequence
856 of copies, and jumps to a specified entry point.
857 This is similar to function 0012h but allow more control over
858 the initial register state; see that function for the meaning of
859 ES:DI and CX.
861 DS:SI points to the initial register file, which is a structure
862 in the following format (available in <syslinux/bootrm.h>;
863 note that this is a completely different structure from the
864 com32sys_t structure described at the top of this document!):
866 struct syslinux_rm_regs {
867 uint16_t es; /* Offset 0 */
868 uint16_t _unused_cs; /* Offset 2 */
869 uint16_t ds; /* Offset 4 */
870 uint16_t ss; /* Offset 6 */
871 uint16_t fs; /* Offset 8 */
872 uint16_t gs; /* Offset 10 */
874 reg32_t eax; /* Offset 12 */
875 reg32_t ecx; /* Offset 16 */
876 reg32_t edx; /* Offset 20 */
877 reg32_t ebx; /* Offset 24 */
878 reg32_t esp; /* Offset 28 */
879 reg32_t ebp; /* Offset 32 */
880 reg32_t esi; /* Offset 36 */
881 reg32_t edi; /* Offset 40 */
883 uint16_t ip; /* Offset 44 */
884 uint16_t cs; /* Offset 46 */
885 };
887 Interrupts are off and DF=0 on entry.
890 AX=001Ch [3.60] Get pointer to auxilliary data vector
891 Input: AX 001Ch
892 Output: ES:BX Auxilliary data vector
893 CX Size of the ADV (currently 500 bytes)
895 The auxillary data vector is a tagged data structure used
896 to carry a small amount of information (up to 500 bytes) from
897 one boot to another.
900 AX=001Dh [3.60] Write auxilliary data vector
901 Input: AX 001Dh
902 Output: None
904 Write the auxilliary data vector back to disk. Returns
905 failure for non-disk-based derivatives unless the "auxdata"
906 configuration command is used to specify a disk location
907 (not yet implemented.)
909 In a future version, PXELINUX may end up attempting to save
910 the ADV on the server via TFTP write.
913 AX=001Eh [3.74] Keyboard remapping table
914 Input: AX 001Eh
915 DX 0000h - all other values reserved
916 Output: AX format version (1)
917 CX length in bytes (256)
918 ES:BX pointer to keyboard table
920 This call queries the keyboard remapping table. For the current
921 version, the format code is always 1 and the length is always
922 256. This version can be updated simply by overwriting the version
923 in memory; this may not be true in the future.
926 AX=001Fh [BETA-3.74+] Get current working directory
927 Input: AX 0001Eh
928 Output: ES:BX null-terminated directory name string
930 Returns the current working directory. For SYSLINUX, ISOLINUX,
931 and PXELINUX, this will be an absolute path. For EXTLINUX, it
932 currently returns "./".
935 AX=0020h [BETA-3.74+] Open directory
936 Input: AX 001Fh
937 ES:SI /-null-terminated directory name
938 Output: SI directory handle
939 EAX clobbered
941 Open a directory for reading. Directory name must have a trailing
942 "/" before the null (otherwise, you're looking for a file)(This
943 may change as this is a BETA call).
946 AX=0021h [BETA-3.74+] Read directory
947 Input: AX 0020h
948 SI directory handle
949 ES:DI buffer for file name
950 Output: DL Type of file
951 SI directory handle, or 0 if end of directory was reached
952 EAX Size of file
953 EBX Inode of file
955 Read one filename from the directory, incrementing the directory
956 structure at SI as appropriate, storing the filename into the buffer
957 at ES:DI, and returning the type of the file in DL, the file length
958 in EAX, the INode/file number in EBX and the updated directory handle.
961 AX=0022h [BETA-3.74+] Close directory
962 Input: AX 001Fh
963 SI directory handle
964 Output SI 0
966 Closes a directory.