From e44e3482bdb4d0ebde2d8b41830ac2cdb07948fb Mon Sep 17 00:00:00 2001 From: Yang Zhang Date: Fri, 28 Aug 2015 09:58:54 +0800 Subject: Add qemu 2.4.0 Change-Id: Ic99cbad4b61f8b127b7dc74d04576c0bcbaaf4f5 Signed-off-by: Yang Zhang --- qemu/roms/ipxe/src/doc/build_sys.dox | 419 ++++++++++++++++++++++++++++++++++ qemu/roms/ipxe/src/doc/pxe_extensions | 312 +++++++++++++++++++++++++ 2 files changed, 731 insertions(+) create mode 100644 qemu/roms/ipxe/src/doc/build_sys.dox create mode 100644 qemu/roms/ipxe/src/doc/pxe_extensions (limited to 'qemu/roms/ipxe/src/doc') diff --git a/qemu/roms/ipxe/src/doc/build_sys.dox b/qemu/roms/ipxe/src/doc/build_sys.dox new file mode 100644 index 000000000..9466f6621 --- /dev/null +++ b/qemu/roms/ipxe/src/doc/build_sys.dox @@ -0,0 +1,419 @@ +/** @page build_sys Build system + +@section overview Overview + +Building an Etherboot image consists of three stages: + + -# @ref compilation : Compiling all the source files into object files + -# @ref linking : Linking a particular image from selected object files + -# @ref finalisation : Producing the final output binary + +Though this is a remarkably complex process, it is important to note +that it all happens automatically. Whatever state your build tree is +in, you can always type, for example + +@code + + make bin/rtl8139.dsk + +@endcode + +and know that you will get a floppy disk image with an RTL8139 driver +built from the current sources. + +@section compilation Compilation + +@subsection comp_overview Overview + +Each source file (a @c .c or a @c .S file) is compiled into a @c .o +file in the @c bin/ directory. Etherboot makes minimal use of +conditional compilation (see @ref ifdef_harmful), and so you will find +that all objects get built, even the objects that correspond to +features that you are not intending to include in your image. For +example, all network card drivers will be compiled even if you are +just building a ROM for a 3c509 card. This is a deliberate design +decision; please do @b not attempt to "fix" the build system to avoid +doing this. + +Source files are defined to be any @c .c or @c .S files found in a +directory listed in the Makefile variable #SRCDIRS. You therefore do +@b not need to edit the Makefile just because you have added a new +source file (although you will need to edit the Makefile if you have +added a new source directory). To see a list of all source +directories and source files that the build system currently knows +about, you can use the commands + +@code + + make srcdirs + make srcs + +@endcode + +Rules for compiling @c .c and @c .S files are defined in the Makefile +variables #RULE_c and #RULE_S. Makefile rules are automatically +generated for each source file using these rules. The generated rules +can be found in the @c .d file corresponding to each source file; +these are located in bin/deps/. For example, the rules +generated for drivers/net/rtl8139.c can be found in +bin/deps/drivers/net/rtl8139.c.d. These rules allow you to +type, for example + +@code + + make bin/rtl8139.o + +@endcode + +and have rtl8139.o be built from +drivers/net/rtl8139.c using the generic rule #RULE_c for +compiling @c .c files. + +You can see the full list of object files that will be built using + +@code + + make bobjs + +@endcode + +@subsection comp_ar After compilation + +Once all objects have been compiled, they will be collected into a +build library ("blib") in bin/blib.a. + +@subsection comp_custom Customising compilation + +The Makefile rules for a particular object can be customised to a +certain extent by defining the Makefile variable CFLAGS_@. +For example, if you were to set + +@code + + CFLAGS_rtl8139 = -DFOO + +@endcode + +then bin/rtl8139.o would be compiled with the additional +flags -DFOO. To see the flags that will be used when +compiling a particular object, you can use e.g. + +@code + + make bin/rtl8139.flags + +@endcode + +If you need more flexibility than the CFLAGS_@ mechanism +provides, then you can exclude source files from the automatic rule +generation process by listing them in the Makefile variable +#NON_AUTO_SRCS. The command + +@code + + make autosrcs + +@endcode + +will show you which files are currently part of the automatic rule +generation process. + +@subsection comp_multiobj Multiple objects + +A single source file can be used to generate multiple object files. +This is used, for example, to generate the decompressing and the +non-decompressing prefixes from the same source files. + +By default, a single object will be built from each source file. To +override the list of objects for a source file, you can define the +Makefile variable OBJS_@. For example, the +arch/i386/prefix/dskprefix.S source file is built into two +objects, bin/dskprefix.o and zdskprefix.o by +defining the Makefile variable + +@code + + OBJS_dskprefix = dskprefix zdskprefix + +@endcode + +Since there would be little point in building two identical objects, +customised compilation flags (see @ref comp_custom) are defined as + +@code + + CFLAGS_zdskprefix = -DCOMPRESS + +@endcode + +Thus, arch/i386/prefix/dskprefix.S is built into @c +dskprefix.o using the normal set of flags, and into @c zdskprefix.o +using the normal set of flags plus -DCOMPRESS. + +@subsection comp_debug Special debugging targets + +In addition to the basic rules #RULE_c and #RULE_S for compiling +source files into object files, there are various other rules that can +be useful for debugging. + +@subsubsection comp_debug_c_to_c Preprocessed C + +You can see the results of preprocessing a @c .c file (including the +per-object flags defined via CFLAGS_@ if applicable) using +e.g. + +@code + + make bin/rtl8139.c + +@endcode + +and examining the resulting file (bin/rtl8139.c in this +case). + +@subsubsection comp_debug_x_to_s Assembler + +You can see the results of assembling a @c .c file, or of +preprocessing a @c .S file, using e.g. + +@code + + make bin/rtl8139.s + make bin/zdskprefix.s + +@endcode + +@subsubsection comp_debug_dbg Debugging-enabled targets + +You can build targets with debug messages (DBG()) enabled using e.g. + +@code + + make bin/rtl8139.dbg.o + make bin/rtl8139.dbg2.o + +@endcode + +You will probably not need to use these targets directly, since a +mechanism exists to select debugging levels at build time; see @ref +debug. + +@section linking Linking + +@subsection link_overview Overview + +Etherboot is designed to be small and extremely customisable. This is +achieved by linking in only the features that are really wanted in any +particular build. + +There are two places from which the list of desired features is +obtained: + + -# @ref link_config_h + -# @ref link_cmdline + +@subsection link_config_h config.h + +The config.h file is used to define global build options that are +likely to apply to all images that you build, such as the console +types, supported download protocols etc. See the documentation for +config.h for more details. + +@subsection link_cmdline The make command line + +When you type a command such as + +@code + + make bin/dfe538.zrom + +@endcode + +it is used to derive the following information: + + - We are building a compressed ROM image + - The DFE538 is a PCI NIC, so we need the decompressing PCI ROM prefix + - The PCI IDs for the DFE538 are 1186:1300 + - The DFE538 is an rtl8139-based card, therefore we need the rtl8139 driver + +You can see this process in action using the command + +@code + + make bin/dfe538.zrom.info + +@endcode + +which will print + +@code + + Elements : dfe538 + Prefix : zrom + Drivers : rtl8139 + ROM name : dfe538 + Media : rom + + ROM type : pci + PCI vendor : 0x1186 + PCI device : 0x1300 + + LD driver symbols : obj_rtl8139 + LD prefix symbols : obj_zpciprefix + LD ID symbols : pci_vendor_id=0x1186 pci_device_id=0x1300 + + LD target flags : -u obj_zpciprefix --defsym check_obj_zpciprefix=obj_zpciprefix -u obj_rtl8139 --defsym check_obj_rtl8139=obj_rtl8139 -u obj_config --defsym check_obj_config=obj_config --defsym pci_vendor_id=0x1186 --defsym pci_device_id=0x1300 + +@endcode + +This should be interpreted as follows: + +@code + + Elements : dfe538 + Prefix : zrom + +@endcode + +"Elements" is the list of components preceding the first dot in the +target name. "Prefix" is the component following the first dot in the +target name. (It's called a "prefix" because the code that makes it a +@c .zrom (rather than a @c .dsk, @c .zpxe or any other type of target) +usually ends up at the start of the resulting binary image.) + +@code + + Drivers : rtl8139 + +@endcode + +"Drivers" is the list of drivers corresponding to the "Elements". +Most drivers support several network cards. The PCI_ROM() and +ISA_ROM() macros are used in the driver source files to list the cards +that a particular driver can support. + +@code + + ROM name : dfe538 + +@endcode + +"ROM name" is the first element in the "Elements" list. It is used to +select the PCI IDs for a PCI ROM. + +@code + + Media : rom + +@endcode + +"Media" is the "Prefix" minus the leading @c z, if any. + +@code + + ROM type : pci + PCI vendor : 0x1186 + PCI device : 0x1300 + +@endcode + +These are derived from the "ROM name" and the PCI_ROM() or ISA_ROM() +macros in the driver source files. + +@code + + LD driver symbols : obj_rtl8139 + LD prefix symbols : obj_zpciprefix + +@endcode + +This is the interesting part. At this point, we have established that +we need the rtl8139 driver (i.e. @c rtl8139.o) and the decompressing +PCI prefix (i.e. @c zpciprefix.o). Our build system (via the +compiler.h header file) arranges that every object exports a symbol +obj_@; this can be seen by e.g. + +@code + + objdump -t bin/rtl8139.o + +@endcode + +which will show the line + +@code + + 00000000 g *ABS* 00000000 obj_rtl8139 + +@endcode + +By instructing the linker that we need the symbols @c obj_rtl8139 and +@c obj_zpciprefix, we can therefore ensure that these two objects are +included in our build. (The linker will also include any objects that +these two objects require, since that's the whole purpose of the +linker.) + +In a similar way, we always instruct the linker that we need the +symbol @c obj_config, in order to include the object @c config.o. @c +config.o is used to drag in the objects that were specified via +config.h; see @ref link_config_h. + +@code + + LD target flags : -u obj_zpciprefix --defsym check_obj_zpciprefix=obj_zpciprefix -u obj_rtl8139 --defsym check_obj_rtl8139=obj_rtl8139 -u obj_config --defsym check_obj_config=obj_config --defsym pci_vendor_id=0x1186 --defsym pci_device_id=0x1300 + +@endcode + +These are the flags that we pass to the linker in order to include the +objects that we want in our build, and to check that they really get +included. (This latter check is needed to work around what seems to +be a bug in @c ld). + +The linker does its job of linking all the required objects together +into a coherent build. The best way to see what is happening is to +look at one of the resulting linker maps; try, for example + +@code + + make bin/dfe538.dsk.map + +@endcode + +The linker map includes, amongst others: + + - A list of which objects are included in the build, and why. + - The results of processing the linker script, line-by-line. + - A complete symbol table of the resulting build. + +It is worth spending time examining the linker map to see how an +Etherboot image is assembled. + +Whatever format is selected, the Etherboot image is built into an ELF +file, simply because this is the default format used by @c ld. + +@section finalisation Finalisation + +@subsection final_overview Overview + +The ELF file resulting from @ref linking "linking" needs to be +converted into the final binary image. Usually, this is just a case +of running + +@code + + objcopy -O binary + +@endcode + +to convert the ELF file into a raw binary image. Certain image +formats require special additional treatment. + +@subsection final_rom ROM images + +ROM images must be rounded up to a suitable ROM size (e.g. 16kB or +32kB), and certain header information such as checksums needs to be +filled in. This is done by the @c makerom.pl program. + +@section debug Debugging-enabled builds + +*/ diff --git a/qemu/roms/ipxe/src/doc/pxe_extensions b/qemu/roms/ipxe/src/doc/pxe_extensions new file mode 100644 index 000000000..2411486d5 --- /dev/null +++ b/qemu/roms/ipxe/src/doc/pxe_extensions @@ -0,0 +1,312 @@ +FILE OPEN + +Op-Code: PXENV_FILE_OPEN (00e0h) + +Input: Far pointer to a t_PXENV_FILE_OPEN parameter structure + that has been initialised by the caller. + +Output: PXENV_EXIT_SUCCESS or PXENV_EXIT_FAILURE must be + returned in AX. The status field in the parameter + structure must be set to one of the values represented + by the PXENV_STATUS_xxx constants. + +Description: Opens a file specified by a URL for reading. Multiple + files may be opened and used concurrently. + + +typedef struct s_PXENV_FILE_OPEN { + PXENV_STATUS Status; + UINT16 FileHandle; + SEGOFF16 FileName; + UINT32 Reserved; +} t_PXENV_FILE_OPEN; + + +Set before calling API service: + +FileName: URL of file to be opened. Null terminated. + +Reserved: Must be zero. + + +Returned from API service: + +FileHandle: Handle for use in subsequent PXE FILE API calls. + +Status: See PXENV_STATUS_xxx constants. + + + + +FILE CLOSE + +Op-Code: PXENV_FILE_CLOSE (00e1h) + +Input: Far pointer to a t_PXENV_FILE_CLOSE parameter structure + that has been initialised by the caller. + +Output: PXENV_EXIT_SUCCESS or PXENV_EXIT_FAILURE must be + returned in AX. The status field in the parameter + structure must be set to one of the values represented + by the PXENV_STATUS_xxx constants. + +Description: Closes a previously opened file. + + +typedef struct s_PXENV_FILE_CLOSE { + PXENV_STATUS Status; + UINT16 FileHandle; +} t_PXENV_FILE_CLOSE; + + +Set before calling API service: + +FileHandle: Handle obtained when file was opened. + + +Returned from API service: + +Status: See PXENV_STATUS_xxx constants. + + + + +FILE SELECT + +Op-Code: PXENV_FILE_SELECT (00e2h) + +Input: Far pointer to a t_PXENV_FILE_SELECT parameter structure + that has been initialised by the caller. + +Output: PXENV_EXIT_SUCCESS or PXENV_EXIT_FAILURE must be + returned in AX. The status field in the parameter + structure must be set to one of the values represented + by the PXENV_STATUS_xxx constants. + +Description: Check a previously opened file's readiness for I/O. + + +typedef struct s_PXENV_FILE_SELECT { + PXENV_STATUS Status; + UINT16 FileHandle; + UINT16 Ready; +#define RDY_READ 0x0001 +} t_PXENV_FILE_SELECT; + + +Set before calling API service: + +FileHandle: Handle obtained when file was opened. + + +Returned from API service: + +Ready: Indication of readiness. This can be zero, or more, + of the RDY_xxx constants. Multiple values are + arithmetically or-ed together. + +Status: See PXENV_STATUS_xxx constants. + + + + +FILE READ + +Op-Code: PXENV_FILE_READ (00e3h) + +Input: Far pointer to a t_PXENV_FILE_READ parameter structure + that has been initialised by the caller. + +Output: PXENV_EXIT_SUCCESS or PXENV_EXIT_FAILURE must be + returned in AX. The status field in the parameter + structure must be set to one of the values represented + by the PXENV_STATUS_xxx constants. + + This API function is non-blocking. PXENV_EXIT_SUCCESS + and PXENV_STATUS_SUCCESS is returned if a data block + has been transferred into the caller's buffer. + PXENV_EXIT_FAILURE and PXENV_STATUS_TFTP_OPEN is + returned if no data is available to transfer; any + other status code reflects an error. + +Description: Read from a previously opened file. + + +typedef struct s_PXENV_FILE_READ { + PXENV_STATUS Status; + UINT16 FileHandle; + UINT16 BufferSize; + SEGOFF16 Buffer; +} t_PXENV_FILE_READ; + + +Set before calling API service: + +FileHandle: Handle obtained when file was opened. + +BufferSize: Maximum number of data bytes that can be copied into + Buffer. + +Buffer: Segment:Offset address of data buffer. + + +Returned from API service: + +BufferSize: Number of bytes written to the data buffer. End of + file if this is zero. + +Status: See PXENV_STATUS_xxx constants. + + + + +GET FILE SIZE + +Op-Code: PXENV_GET_FILE_SIZE (00e4h) + +Input: Far pointer to a t_PXENV_GET_FILE_SIZE parameter + structure that has been initialised by the caller. + +Output: PXENV_EXIT_SUCCESS or PXENV_EXIT_FAILURE must be + returned in AX. The status field in the parameter + structure must be set to one of the values represented + by the PXENV_STATUS_xxx constants. + +Description: Determine size of a previously opened file. + + +typedef struct s_PXENV_GET_FILE_SIZE { + PXENV_STATUS Status; + UINT16 FileHandle; + UINT32 FileSize; +} t_PXENV_GET_FILE_SIZE; + + +Set before calling API service: + +FileHandle: Handle obtained when file was opened. + + +Returned from API service: + +FileSize: Size of the file in bytes. + +Status: See PXENV_STATUS_xxx constants. + + + + +FILE EXEC + +Op-Code: PXENV_FILE_EXEC (00e5h) + +Input: Far pointer to a t_PXENV_FILE_EXEC parameter + structure that has been initialized by the caller. + +Output: PXENV_EXIT_SUCCESS or PXENV_EXIT_FAILURE must be + returned in AX. The Status field in the parameter + structure must be set to one of the values represented + by the PXENV_STATUS_xxx constants. + +Description: Execute a iPXE command. + +typedef struct s_PXENV_FILE_EXEC { + PXENV_STATUS_t Status; + SEGOFF16_t Command; +} t_PXENV_FILE_EXEC; + + +Set before calling API service: + +Command: Command to execute. Null terminated. + + +Returned from API service: + +Status: See PXENV_STATUS_xxx constants. + + + + +FILE API CHECK + +Op-Code: PXENV_FILE_API_CHECK (00e6h) + +Input: Far pointer to a t_PXENV_FILE_CHECK_API parameter + structure that has been initialized by the caller. + + On entry, the Magic field should contain the number + 0x91d447b2 or the call will fail. + +Output: PXENV_EXIT_SUCCESS or PXENV_EXIT_FAILURE must be + returned in AX. The Status field in the parameter + structure must be set to one of the values represented + by the PXENV_STATUS_xxx constants. + + If this API is present and the Magic field contains the + proper value on entry, AX will contain PXENV_EXIT_SUCCESS, + the Status field PXENV_STATUS_SUCCESS, and the Magic field + the number 0xe9c17b20. Any other combination should be + considered a failure. + +Description: Detect presence of this API. + + +typedef struct s_PXENV_FILE_CHECK_API { + PXENV_STATUS Status; + UINT16 Size; + UINT32 Magic; + UINT32 Provider; + UINT32 APIMask; + UINT32 Flags; +} t_PXENV_FILE_CHECK_API; + +Set before calling API service: + +Size: Set to sizeof(t_PXENV_FILE_CHECK_API) (20). +Magic: Set to 0x91d447b2. + + +Returned from API service: + +Size: Set to the number of bytes filled in (20). +Magic: Set to 0xe9c17b20. +Provider: Set to 0x45585067 ("iPXE"). Another implementation of this + API can use another value, e.g. to indicate a different + command set supported by FILE EXEC. +APIMask: Bitmask of supported API functions (one bit for each function + in the range 00e0h to 00ffh). +Flags: Set to zero, reserved for future use. + + + + +FILE EXIT HOOK + +Op-Code: PXENV_FILE_EXIT_HOOK (00e7h) + +Input: Far pointer to a t_PXENV_FILE_EXIT_HOOK parameter + structure that has been initialized by the caller. + +Output: PXENV_EXIT_SUCCESS or PXENV_EXIT_FAILURE must be + returned in AX. The Status field in the parameter + structure must be set to one of the values represented + by the PXENV_STATUS_xxx constants. + +Description: Modify the exit path to jump to the specified code. + Only valid for pxeprefix-based builds. + +typedef struct s_PXENV_FILE_EXIT_HOOK { + PXENV_STATUS_t Status; + SEGOFF16_t Hook; +} t_PXENV_FILE_EXIT_HOOK; + + +Set before calling API service: + +Hook: The SEG16:OFF16 of the code to jump to. + + +Returned from API service: + +Status: See PXENV_STATUS_xxx constants. -- cgit 1.2.3-korg