| blob | cb3488b6f65747afecde1abecbc9fcb5147573bd |
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)
89 This corresponds to the following C prototype, available in the file
90 com32/include/com32.h:
92 /* The standard prototype for _start() */
93 int _start(unsigned int __nargs,
94 char *__cmdline,
95 void (*__intcall)(uint8_t, com32sys_t *, com32sys_t *),
96 void *__bounce_ptr,
97 unsigned int __bounce_len,
98 void (*__farcall)(uint32_t, uint16_t, com32sys_t *, com32sys_t *));
100 The intcall helper function can be used to issue BIOS or SYSLINUX API
101 calls, and takes the interrupt number as first argument. The second
102 argument is a pointer to the input register definition, an instance of
103 the following structure (also available in com32.h):
105 typedef union {
106 uint32_t l;
107 uint16_t w[2];
108 uint8_t b[4];
109 } reg32_t;
111 typedef struct {
112 uint16_t gs; /* Offset 0 */
113 uint16_t fs; /* Offset 2 */
114 uint16_t es; /* Offset 4 */
115 uint16_t ds; /* Offset 6 */
117 reg32_t edi; /* Offset 8 */
118 reg32_t esi; /* Offset 12 */
119 reg32_t ebp; /* Offset 16 */
120 reg32_t _unused; /* Offset 20 */
121 reg32_t ebx; /* Offset 24 */
122 reg32_t edx; /* Offset 28 */
123 reg32_t ecx; /* Offset 32 */
124 reg32_t eax; /* Offset 36 */
126 reg32_t eflags; /* Offset 40 */
127 } com32sys_t;
129 The third argument is a pointer to the output register definition, an
130 instance of the same structure. The third argument can also be zero
131 (NULL).
133 Since BIOS or SYSLINUX API calls can generally only manipulate data
134 below address 0x100000, a "bounce buffer" in low memory, at least 64K
135 in size, is available, to copy data in and out.
137 The farcall helper function behaves similarly, but takes as its first
138 argument the CS:IP (in the form (CS << 16) + IP) of procedure to be
139 invoked via a FAR CALL.
142 ++++ SYSLINUX API CALLS +++
144 SYSLINUX provides the following API calls. SYSLINUX 1.xx only
145 supported INT 20h - terminate program. [] indicates the first version
146 of SYSLINUX which supported this feature (correctly.)
148 NOTE: Most of the API functionality is still experimental. Expect to
149 find bugs.
152 ++++ DOS-COMPATIBLE API CALLS ++++
154 INT 20h [1.48] Terminate program
155 INT 21h AH=00h [2.00] Terminate program
156 INT 21h AH=4Ch [2.00] Terminate program
158 All of these terminate the program.
161 INT 21h AH=01h [2.01] Get Key with Echo
163 Reads a key from the console input, with echo to the console
164 output. The read character is returned in AL. Extended
165 characters received from the keyboard are returned as NUL (00h)
166 + the extended character code.
169 INT 21h AH=02h [2.01] Write Character
171 Writes a character in DL to the console (video and serial)
172 output.
175 INT 21h AH=04h [2.01] Write Character to Serial Port
177 Writes a character in DL to the serial console output
178 (if enabled.) If no serial port is configured, this routine
179 does nothing.
182 INT 21h AH=08h [2.09] Get Key without Echo
184 Reads a key fron the console input, without echoing it to the
185 console output. The read character is returned in AL.
188 INT 21h AH=09h [2.01] Write DOS String to Console
190 Writes a DOS $-terminated string in DS:DX to the console.
193 INT 21h AH=0Bh [2.00] Check Keyboard
195 Returns AL=FFh if there is a keystroke waiting (which can then
196 be read with INT 21h, AH=01h or AH=08h), otherwise AL=00h.
199 INT 21h AH=30h [2.00] Check DOS Version
201 This function returns AX=BX=CX=DX=0, corresponding to a
202 hypothetical "DOS 0.0", but the high parts of EAX-EBX-ECX-EDX
203 spell "SYSLINUX":
205 EAX=59530000h EBX=4C530000h ECX=4E490000h EDX=58550000h
207 This function can thus be used to distinguish running on
208 SYSLINUX from running on DOS.
211 ++++ SYSLINUX-SPECIFIC API CALLS ++++
213 SYSLINUX-specific API calls are executed using INT 22h, with a
214 function number in AX. INT 22h is used by DOS for internal purposes;
215 do not execute INT 22h under DOS.
217 DOS-compatible function INT 21h, AH=30h can be used to detect if the
218 SYSLINUX API calls are available.
220 Any register not specifically listed as modified is preserved;
221 however, future versions of SYSLINUX may add additional output
222 registers to existing calls.
224 All calls return CF=0 on success, CF=1 on failure. The noted outputs
225 apply if CF=0 only unless otherwise noted. All calls clobber the
226 arithmetric flags (CF, PF, AF, ZF, SF and OF) but leave all other
227 flags unchanged unless otherwise noted.
230 AX=0001h [2.00] Get Version
232 Input: AX 0001h
233 Output: AX number of INT 22h API functions available
234 CH SYSLINUX major version number
235 CL SYSLINUX minor version number
236 DL SYSLINUX derivative ID (e.g. 32h = PXELINUX)
237 ES:SI SYSLINUX version string
238 ES:DI SYSLINUX copyright string
240 This API call returns the SYSLINUX version and API
241 information.
244 AX=0002h [2.01] Write String
246 Input: AX 0002h
247 ES:BX null-terminated string
248 Output: None
250 Writes a null-terminated string on the console.
253 AX=0003h [2.01] Run command
255 Input: AX 0003h
256 ES:BX null-terminated command string
257 Output: Does not return
259 This API call terminates the program and executes the command
260 string as if the user had entered it at the SYSLINUX command
261 line. This API call does not return.
264 AX=0004h [2.01] Run default command
266 Input: AX 0004h
267 Output: Does not return
269 This API call terminates the program and executes the default
270 command string as if the user had pressed Enter alone on the
271 SYSLINUX command line. This API call does not return.
274 AX=0005h [2.00] Force text mode
276 Input: AX 0005h
277 Output: None
279 If the screen was in graphics mode (due to displaying a splash
280 screen using the <Ctrl-X> command in a message file, or
281 similar), return to text mode.
284 AX=0006h [2.08] Open file
286 Input: AX 0006h
287 ES:SI null-terminated filename
288 Output: SI file handle
289 EAX length of file in bytes
290 CX file block size
292 Open a file for reading. The exact syntax of the filenames
293 allowed depends on the particular SYSLINUX derivative.
295 The SYSLINUX file system is block-oriented. The size of a
296 block will always be a power of two and no greater than 16K.
298 Note: SYSLINUX considers a zero-length file to be nonexistent.
301 AX=0007h [2.08] Read file
303 Input: AX 0007h
304 SI file handle
305 ES:BX buffer
306 CX number of blocks to read
307 Output: SI file handle, or 0 if EOF was reached
309 Read blocks from a file. Note that the file handle that is
310 returned in SI may not be the same value that was passed in.
312 If end of file was reached (SI=0), the file was automatically
313 closed.
315 The address of the buffer (ES:BX) should be at least 512-byte
316 aligned. SYSLINUX guarantees at least this alignment for the
317 COMBOOT load segment or the COM32 bounce buffer.
319 Keep in mind that a "file" may be a TFTP connection, and that
320 leaving a file open for an extended period of time may result
321 in a timeout.
323 WARNING: Calling this function with an invalid file handle
324 will probably crash the system.
327 AX=0008h [2.08] Close file
329 Input: AX 0008h
330 SI file handle
331 Output: None
333 Close a file before reaching the end of file.
335 WARNING: Calling this function with an invalid file handle
336 will probably crash the system.
339 AX=0009h [2.00] Call PXE Stack [PXELINUX ONLY]
341 Input: AX 0009h
342 BX PXE function number
343 ES:DI PXE data buffer
344 Output: AX PXE return status code
346 Invoke an arbitrary PXE stack function. On SYSLINUX/ISOLINUX,
347 this function returns with an error (CF=1) and no action is
348 taken. On PXELINUX, this function always returns with CF=0
349 indicating that the PXE stack was successfully invoked; check
350 the status code in AX and in the first word of the data buffer
351 to determine if the PXE call succeeded or not.
353 The PXE stack will have the UDP stack OPEN; if you change that
354 you cannot call any of the file-related API functions, and
355 must restore UDP OPEN before returning to PXELINUX.
357 PXELINUX reserves UDP port numbers from 49152 to 65535 for its
358 own use; port numbers below that range is available.
361 AX=000Ah [2.00] Get Derivative-Specific Information
363 [SYSLINUX, EXTLINUX]
364 Input: AX 000Ah
365 Output: AL 31h (SYSLINUX), 34h (EXTLINUX)
366 DL drive number
367 ES:BX pointer to partition table entry (if DL >= 80h)
369 Note: This function was broken in EXTLINUX 3.00-3.02.
372 [PXELINUX]
373 Input: AX 000Ah
374 Output: AL 32h (PXELINUX)
375 DX PXE API version detected (DH=major, DL=minor)
376 ES:BX pointer to PXENV+ or !PXE structure
377 FS:SI pointer to original stack with invocation record
379 Note: DX notes the API version detected by PXELINUX,
380 which may be more conservative than the actual version
381 available. For exact information examine the API
382 version entry in the PXENV+ structure, or the API
383 version entries in the ROMID structures pointed from
384 the !PXE structure.
386 PXELINUX will use, and provide, the !PXE structure
387 over the PXENV+ structure. Examine the structure
388 signature to determine which particular structure was
389 provided.
391 The FS:SI pointer points to the top of the original stack
392 provided by the PXE stack, with the following values
393 pushed at the time PXELINUX is started:
395 [fs:si+0] GS <- top of stack
396 [fs:si+2] FS
397 [fs:si+4] ES
398 [fs:si+6] DS
399 [fs:si+8] EDI
400 [fs:si+12] ESI
401 [fs:si+16] EBP
402 [fs:si+20] -
403 [fs:si+24] EBX
404 [fs:si+28] EDX
405 [fs:si+32] ECX
406 [fs:si+36] EAX
407 [fs:si+40] EFLAGS
408 [fs:si+44] PXE return IP <- t.o.s. when PXELINUX invoked
409 [fs:si+46] PXE return CS
412 [ISOLINUX]
413 Input: AX 000Ah
414 Output: AL 33h (ISOLINUX)
415 DL drive number
416 ES:BX pointer to El Torito spec packet
418 Note: Some very broken El Torito implementations do
419 not provide the spec packet information. If so, ES:BX
420 may point to all zeroes or to garbage. Call INT 13h,
421 AX=4B01h to obtain the spec packet directly from the
422 BIOS if necessary.
424 This call gives information specific to a particular SYSLINUX
425 derivative. The value returned in AL is the same as is
426 returned in DL by INT 22h AX=0001h.
429 AX=000Bh [2.00] Get Serial Console Configuration
431 Input: AX 000Bh
432 Output: DX serial port I/O base (e.g. 3F8h = COM1...)
433 CX baud rate divisor (1 = 115200 bps, 2 = 57600 bps...)
434 BX flow control configuration bits (see syslinux.doc)
435 -> bit 15 is set if the video console is disabled
437 If no serial port is configured, DX will be set to 0 and the
438 other registers are undefined.
441 AX=000Ch [2.00] Perform final cleanup
442 Input: AX 000Ch
443 DX derivative-specific flags (0000h = clean up all)
444 Output: Does not return
446 This routine performs any "final cleanup" the boot loader
447 would normally perform before loading a kernel, such as
448 unloading the PXE stack in the case of PXELINUX. AFTER
449 INVOKING THIS CALL, NO OTHER API CALLS MAY BE INVOKED, NOR MAY
450 THE PROGRAM TERMINATE AND RETURN TO THE BOOT LOADER. This
451 call basically tells the boot loader "get out of the way, I'll
452 handle it from here."
454 For COM32 images, the boot loader will continue to provide
455 interrupt and BIOS call thunking services as long its memory
456 areas (0x0800-0xffff, 0x100000-0x100fff) are not overwritten.
457 MAKE SURE TO DISABLE INTERRUPTS, AND INSTALL NEW GDT AND IDTS
458 BEFORE OVERWRITING THESE MEMORY AREAS.
460 The permissible values for DX is an OR of these values:
462 SYSLINUX: 0000h Normal cleanup
464 PXELINUX: 0000h Normal cleanup
465 0003h Keep UNDI and PXE stacks loaded
467 ISOLINUX: 0000h Normal cleanup
469 EXTLINUX: 0000h Normal cleanup
471 All other values are undefined, and may have different
472 meanings in future versions of SYSLINUX.
475 AX=000Dh [2.08] Cleanup and replace bootstrap code
476 Input: AX 000Dh
477 DX derivative-specific flags (see previous function)
478 EDI bootstrap code (linear address, can be in high memory)
479 ECX bootstrap code length in bytes (must fit in low mem)
480 EBX(!) initial value of EDX after bootstrap
481 ESI initial value of ESI after bootstrap
482 DS initial value of DS after bootstrap
483 Output: Does not return
485 This routine performs final cleanup, then takes a piece of
486 code, copies it over the primary bootstrap at address 7C00h,
487 and jumps to it. This can be used to chainload boot sectors,
488 MBRs, bootstraps, etc.
490 Normal boot sectors expect DL to contain the drive number,
491 and, for hard drives (DL >= 80h) DS:SI to contain a pointer to
492 the 16-byte partition table entry. The memory between
493 600h-7FFh is available to put the partition table entry in.
495 For PXELINUX, if the PXE stack is not unloaded, all registers
496 (except DS, ESI and EDX) and the stack will be set up as they
497 were set up by the PXE ROM.
500 AX=000Eh [2.11] Get configuration file name
501 Input: AX 0000Eh
502 Output: ES:BX null-terminated file name string
504 Returns the name of the configuration file. Note that it is
505 possible that the configuration file doesn't actually exist.
508 AX=000Fh [3.00] Get IPAPPEND strings [PXELINUX]
509 Input: AX 000Fh
510 Output: CX number of strings (currently 2)
511 ES:BX pointer to an array of NEAR pointers in
512 the same segment, one for each of the above
513 strings
515 Returns the same strings that the "ipappend" option would have
516 added to the command line, one for each bit of the "ipappend"
517 flag value, so entry 0 is the "ip=" string and entry 1 is the
518 "BOOTIF=" string.
521 AX=0010h [3.00] Resolve hostname [PXELINUX]
522 Input: ES:BX pointer to null-terminated hostname
523 Output: EAX IP address of hostname (zero if not found)
525 Queries the DNS server(s) for a specific hostname. If the
526 hostname does not contain a dot (.), the local domain name
527 is automatically appended.
529 This function only return CF=1 if the function is not
530 supported. If the function is supported, but the hostname did
531 not resolve, it returns with CF=0, EAX=0.
533 The IP address is returned in network byte order, i.e. if the
534 IP address is 1.2.3.4, EAX will contain 0x04030201. Note that
535 all uses of IP addresses in PXE are also in network byte order.
538 AX=0011h [3.05] Maximum number of shuffle descriptors
539 Input: AX 0011h
540 Output: CX maximum number of descriptors
542 This routine reports the maximum number of shuffle descriptors
543 permitted in a call to function 0012h.
545 Typical values are 682 and 1365.
548 AX=0012h [3.05] Cleanup, shuffle and boot
549 Input: AX 0012h
550 DX derivative-specific flags (see previous function)
551 ES:DI shuffle descriptor list (must be in low memory)
552 CX number of shuffle descriptors
553 EBX(!) initial value of EDX after bootstrap
554 ESI initial value of ESI after bootstrap
555 DS initial value of DS after bootstrap
556 EBP CS:IP of routine to jump to
557 Output: Does not return
558 (if CX is too large the routine returns with CF=1)
560 This routine performs final cleanup, then performs a sequence
561 of copies, and jumps to a specified real mode entry point.
562 This is a more general version of function 000Dh, which can
563 also be used to load other types of programs.
565 The copies must not touch memory below address 7C00h.
567 ES:DI points to a list of CX descriptors each of the form:
569 Offset Size Meaning
570 0 dword destination address
571 4 dword source address
572 8 dword length in bytes
574 The copies are overlap-safe, like memmove().
576 Normal boot sectors expect DL to contain the drive number,
577 and, for hard drives (DL >= 80h) DS:SI to contain a pointer to
578 the 16-byte partition table entry. The memory between
579 600h-7FFh is available to put the partition table entry in.
581 For PXELINUX, if the PXE stack is not unloaded, all registers
582 (except DS, ESI and EDX) and the stack will be set up as they
583 were set up by the PXE ROM.
586 AX=0013h [3.08] Idle loop call
587 Input: AX 0013h
588 Output: None
590 Call this routine while sitting in an idle loop. It performs
591 any periodic activities required by the filesystem code. At
592 the moment, this is a no-op on all derivatives except
593 PXELINUX, where it executes PXE calls to answer ARP queries.
595 Starting with version 3.10, this API call harmlessly returns
596 failure (CF=1) if invoked on a platform which does not need
597 idle calls. Additionally, it's safe to call this API call on
598 previous SYSLINUX versions (2.00 or later); it will just
599 harmlessly fail. Thus, if this call returns failure (CF=1),
600 it means that there is no technical reason to call this
601 function again, although doing so is of course safe.
604 AX=0014h [3.10] Local boot [PXELINUX, ISOLINUX]
605 Input: AX 0014h
606 DX Local boot parameter
607 Output: Does not return
609 This function invokes the equivalent of the "localboot"
610 configuration file option. The parameter in DX is the same
611 parameter as would be entered after "localboot" in the
612 configuration file; this parameter is derivative-specific --
613 see syslinux.doc for the definition.
616 AX=0015h [3.10] Get feature flags
617 Input: AX 0015h
618 Output: ES:BX pointer to flags in memory
619 CX number of flag bytes
621 This function reports whether or not this SYSLINUX version and
622 derivative supports specific features. Keep in mind that
623 future versions might have more bits; remember to treat any
624 bits beyond the end of the array (as defined by the value in
625 CX) as zero.
627 Currently the following feature flag is defined:
629 Byte Bit Definition
630 ----------------------------------------------------
631 0 0 Local boot (AX=0014h) supported
632 1 Idle loop call (AX=0013h) is a no-op
634 All other flags are reserved.
637 AX=0016h [3.10] Run kernel image
638 Input: AX 0016h
639 DS:SI Filename of kernel image (zero-terminated string)
640 ES:BX Command line (zero-terminated string)
641 ECX IPAPPEND flags [PXELINUX]
642 EDX Reserved - MUST BE ZERO
643 Output: Does not return if successful; returns with CF=1 if
644 the kernel image is not found.
646 This function is similiar to AX=0003h Run command, except that
647 the filename and command line are treated as if specified in a
648 KERNEL and APPEND statement of a LABEL statement, which means:
650 - The filename has to be exact; no variants are tried;
651 - No global APPEND statement is applied;
652 - ALLOWOPTIONS and IMPLICIT statements in the configuration
653 file do not apply. It is therefore important that the
654 COMBOOT module doesn't allow the end user to violate the
655 intent of the administrator.
657 Additionally, this function returns with a failure if the file
658 doesn't exist, instead of returning to the command line. (It
659 may still return to the command line if the image is somehow
660 corrupt, however.)