| blob | 04d5deb893b9b4c68a0ad393e629f236f52a851f |
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 ++++ COM32R file format ++++
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.
64 A COM32R program must start with the byte sequence B8 FE 4C CD 21 (mov
65 eax,21cd4cfeh) as a magic number.
67 The COM32R format replaces the earlier COM32 format, which was linked
68 to a fixed address (0x101000).
70 A COM32R file should have extension ".c32".
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.
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.
81 The following arguments are passed to the program on the stack:
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)
96 The libcom32 startup code loads this into a structure named __com32,
97 defined in <com32.h>:
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;
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>):
117 typedef union {
118 uint32_t l;
119 uint16_t w[2];
120 uint8_t b[4];
121 } reg32_t;
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 */
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 */
138 reg32_t eflags; /* Offset 40 */
139 } com32sys_t;
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).
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.
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.
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.)
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>.
164 ++++ SYSLINUX API CALLS +++
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.)
170 NOTE: Most of the API functionality is still experimental. Expect to
171 find bugs.
174 ++++ DOS-COMPATIBLE API CALLS ++++
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
180 All of these terminate the program.
183 INT 21h AH=01h [2.01] Get Key with Echo
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.
191 INT 21h AH=02h [2.01] Write Character
193 Writes a character in DL to the console (video and serial)
194 output.
197 INT 21h AH=04h [2.01] Write Character to Serial Port
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.
204 INT 21h AH=08h [2.09] Get Key without Echo
206 Reads a key fron the console input, without echoing it to the
207 console output. The read character is returned in AL.
210 INT 21h AH=09h [2.01] Write DOS String to Console
212 Writes a DOS $-terminated string in DS:DX to the console.
215 INT 21h AH=0Bh [2.00] Check Keyboard
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.
221 INT 21h AH=30h [2.00] Check DOS Version
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":
227 EAX=59530000h EBX=4C530000h ECX=4E490000h EDX=58550000h
229 This function can thus be used to distinguish running on
230 Syslinux from running on DOS.
233 ++++ SYSLINUX-SPECIFIC API CALLS ++++
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.
239 DOS-compatible function INT 21h, AH=30h can be used to detect if the
240 Syslinux API calls are available.
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.
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.
252 AX=0001h [2.00] Get Version
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
262 This API call returns the Syslinux version and API
263 information.
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.
270 AX=0002h [2.01] Write String
272 Input: AX 0002h
273 ES:BX null-terminated string
274 Output: None
276 Writes a null-terminated string on the console.
279 AX=0003h [2.01] Run command
281 Input: AX 0003h
282 ES:BX null-terminated command string
283 Output: Does not return
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.
290 AX=0004h [2.01] Run default command
292 Input: AX 0004h
293 Output: Does not return
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.
300 AX=0005h [2.00] Force text mode
302 Input: AX 0005h
303 Output: None
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.
310 AX=0006h [2.08] Open file
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
318 Open a file for reading. The exact syntax of the filenames
319 allowed depends on the particular Syslinux derivative.
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.
324 Note: Syslinux considers a zero-length file to be nonexistent.
326 In 3.70 or later, EAX can contain -1 indicating that the file
327 length is unknown.
329 32-BIT VERSION:
331 int cs_pm->open_file(const char *filename, struct com32_filedata *data)
333 filename - null-terminated filename
334 data - pointer to a file data buffer
336 Returns the file handle, or -1 on failure.
337 The file data buffer contains block size and file size.
340 AX=0007h [2.08] Read file
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]
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.
352 If end of file was reached (SI=0), the file was automatically
353 closed.
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.
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.
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.
367 WARNING: Calling this function with an invalid file handle
368 will probably crash the system.
370 32-BIT VERSION:
372 size_t cs_pm->read_file(uint16_t *handle, void *buf, size_t blocks)
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
378 Returns number of bytes read, or 0 on failure.
381 AX=0008h [2.08] Close file
383 Input: AX 0008h
384 SI file handle
385 Output: None
387 Close a file before reaching the end of file.
389 WARNING: Calling this function with an invalid file handle
390 will probably crash the system.
392 32-BIT VERSION:
394 void cs_pm->close_file(uint16_t handle)
396 handle - file handle to close
399 AX=0009h [2.00] Call PXE Stack [PXELINUX ONLY]
401 Input: AX 0009h
402 BX PXE function number
403 ES:DI PXE parameter structure buffer
404 Output: AX PXE return status code
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.
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.
417 PXELINUX reserves UDP port numbers from 49152 to 65535 for its
418 own use; port numbers below that range is available.
421 AX=000Ah [2.00] Get Derivative-Specific Information
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]
436 Note: This function was broken in EXTLINUX 3.00-3.02.
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.
443 Note that FS:SI is a pointer to a memory location
444 containing the original ES:DI value, not the value
445 itself.
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]
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.
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.
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:
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
489 GS:DI points to a structure of the following form:
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
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]
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.
517 AX=000Bh [2.00] Get Serial Console Configuration
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
525 If no serial port is configured, DX will be set to 0 and the
526 other registers are undefined.
529 AX=000Ch [2.00] Perform final cleanup
530 Input: AX 000Ch
531 DX derivative-specific flags (0000h = clean up all)
532 Output: None
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."
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.
548 The permissible values for DX is an OR of these values:
550 SYSLINUX: 0000h Normal cleanup
552 PXELINUX: 0000h Normal cleanup
553 0003h Keep UNDI and PXE stacks loaded
555 ISOLINUX: 0000h Normal cleanup
557 EXTLINUX: 0000h Normal cleanup
559 All other values are undefined, and may have different
560 meanings in future versions of Syslinux.
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
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.
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.
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.
588 AX=000Eh [2.11] Get configuration file name
589 Input: AX 0000Eh
590 Output: ES:BX null-terminated file name string
592 Returns the name of the configuration file. Note that it is
593 possible that the configuration file doesn't actually exist.
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
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.
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)
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.
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.
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.
627 AX=0011h [3.05] Obsoleted in 3.80
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)
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.
647 The copies must not touch memory below address 7C00h.
649 ES:DI points to a list of CX descriptors each of the form:
651 Offset Size Meaning
652 0 dword destination address
653 4 dword source address
654 8 dword length in bytes
656 The copies are overlap-safe, like memmove().
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.
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.
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.
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.
680 This interface was probably broken before version 3.50.
683 AX=0013h [3.08] Idle loop call
684 Input: AX 0013h
685 Output: None
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.
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.
701 AX=0014h [3.10] Local boot [PXELINUX, ISOLINUX]
702 Input: AX 0014h
703 DX Local boot parameter
704 Output: Does not return
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.
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
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.
724 Currently the following feature flag is defined:
726 Byte Bit Definition
727 ----------------------------------------------------
728 0 0 Local boot (AX=0014h) supported
729 1 Idle loop call (AX=0013h) is a no-op
731 All other flags are reserved.
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.
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:
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.
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.)
759 The file types are defined as follows:
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
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
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.
793 This function returns with a failure if BX contains any bits
794 which are undefined in the current version of Syslinux.
796 The following bits in BX are currently defined:
798 Bit 0: graphics mode
800 Indicates that the mode is a graphics mode, as opposed
801 to a text mode.
803 Bit 1: non-standard mode
805 A non-standard mode is any mode except text mode and
806 graphics mode 0012h (VGA 640x480, 16 color.)
808 Bit 2: VESA mode
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).
814 Bit 3: Text functions not supported
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.
821 This is common for VESA modes.
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
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.
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
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.
847 For compatiblity with all systems, the buffer should
848 *neither* cross 64K boundaries, *nor* wrap around the segment.
850 This routine reports "boot failed" (and does not return) on
851 disk error.
853 Note: for ISOLINUX in hybrid mode, this call uses simulated
854 2048-byte CD-ROM sector numbers.
857 AX=001Ah [3.50] Obsoleted in 3.80
860 AX=001Bh [3.50] Obsoleted in 3.80
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)
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.
873 AX=001Dh [3.60] Write auxilliary data vector
874 Input: AX 001Dh
875 Output: None
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.)
882 In a future version, PXELINUX may end up attempting to save
883 the ADV on the server via TFTP write.
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
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.
899 AX=001Fh [3.74] Get current working directory
900 Input: AX 0001Fh
901 Output: ES:BX null-terminated directory name string
903 Returns the current working directory.
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
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.
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
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.
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
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.
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.
943 ESI points to a list of descriptors each of the form:
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)
950 The copies are overlap-safe, like memmove().
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.
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.
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:
967 0 16-bit protected mode (dst is CS.base)
968 1 Flat 32-bit protected mode (dst is EIP)
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.
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.
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.
987 ++++ 32-BIT ONLY API CALLS ++++
989 void *cs_pm->lmalloc(size_t bytes)
991 Allocate a buffer in low memory (below 1 MB).
994 void cs_pm->lfree(void *ptr)
996 Free a buffer allocated with cs_pm->lmalloc().
999 DIR *cs_pm->opendir(const char *pathname)
1001 Open a directory.
1004 struct dirent *cs_pm->readdir(DIR *dir)
1006 Read an entry from a directory. The entry is returned in a
1007 static buffer.
1010 int cs_pm->closedir(DIR *dir)
1012 Close a directory.