iPXE - Open Source Boot Firmware

[pxe] Introduce PXE exit hook for NBP chaining
[ipxe.git] / src / arch / i386 / include / pxe_api.h
1 #ifndef PXE_API_H
2 #define PXE_API_H
3
4 /*
5  * This program is free software; you can redistribute it and/or
6  * modify it under the terms of the GNU General Public License as
7  * published by the Free Software Foundation; either version 2 of the
8  * License, or any later version.
9  *
10  * This program is distributed in the hope that it will be useful, but
11  * WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
13  * General Public License for more details.
14  *
15  * You should have received a copy of the GNU General Public License
16  * along with this program; if not, write to the Free Software
17  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
18  *
19  * As an alternative, at your option, you may use this file under the
20  * following terms, known as the "MIT license":
21  *
22  * Copyright (c) 2005-2009 Michael Brown <mbrown@fensystems.co.uk>
23  *
24  * Permission is hereby granted, free of charge, to any person
25  * obtaining a copy of this software and associated documentation
26  * files (the "Software"), to deal in the Software without
27  * restriction, including without limitation the rights to use, copy,
28  * modify, merge, publish, distribute, sublicense, and/or sell copies
29  * of the Software, and to permit persons to whom the Software is
30  * furnished to do so, subject to the following conditions:
31  *
32  * The above copyright notice and this permission notice shall be
33  * included in all copies or substantial portions of the Software.
34  *
35  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
36  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
37  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
38  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
39  * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
40  * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
41  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
42  * SOFTWARE.
43  */
44
45 /** @file
46  *
47  * Preboot eXecution Environment (PXE) API
48  *
49  */
50
51 FILE_LICENCE ( GPL2_OR_LATER );
52
53 #include "pxe_types.h"
54
55 /** @addtogroup pxe Preboot eXecution Environment (PXE) API
56  *  @{
57  */
58
59 /** @defgroup pxe_api_call PXE entry points
60  *
61  * PXE entry points and calling conventions
62  *
63  *  @{
64  */
65
66 /** The PXENV+ structure */
67 struct s_PXENV {
68         /** Signature
69          *
70          * Contains the bytes 'P', 'X', 'E', 'N', 'V', '+'.
71          */
72         UINT8_t         Signature[6];
73         /** PXE API version
74          *
75          * MSB is major version number, LSB is minor version number.
76          * If the API version number is 0x0201 or greater, the !PXE
77          * structure pointed to by #PXEPtr should be used instead of
78          * this data structure.
79          */
80         UINT16_t        Version;
81         UINT8_t         Length;         /**< Length of this structure */
82         /** Checksum
83          *
84          * The byte checksum of this structure (using the length in
85          * #Length) must be zero.
86          */
87         UINT8_t         Checksum;
88         SEGOFF16_t      RMEntry;        /**< Real-mode PXENV+ entry point */
89         /** Protected-mode PXENV+ entry point offset
90          *
91          * PXE 2.1 deprecates this entry point.  For protected-mode
92          * API calls, use the !PXE structure pointed to by #PXEPtr
93          * instead.
94          */
95         UINT32_t        PMOffset;
96         /** Protected-mode PXENV+ entry point segment selector
97          *
98          * PXE 2.1 deprecates this entry point.  For protected-mode
99          * API calls, use the !PXE structure pointed to by #PXEPtr
100          * instead.
101          */
102         SEGSEL_t        PMSelector;
103         SEGSEL_t        StackSeg;       /**< Stack segment selector */
104         UINT16_t        StackSize;      /**< Stack segment size */
105         SEGSEL_t        BC_CodeSeg;     /**< Base-code code segment selector */
106         UINT16_t        BC_CodeSize;    /**< Base-code code segment size */
107         SEGSEL_t        BC_DataSeg;     /**< Base-code data segment selector */
108         UINT16_t        BC_DataSize;    /**< Base-code data segment size */
109         SEGSEL_t        UNDIDataSeg;    /**< UNDI data segment selector */
110         UINT16_t        UNDIDataSize;   /**< UNDI data segment size */
111         SEGSEL_t        UNDICodeSeg;    /**< UNDI code segment selector */
112         UINT16_t        UNDICodeSize;   /**< UNDI code segment size */
113         /** Address of the !PXE structure
114          *
115          * This field is present only if #Version is 0x0201 or
116          * greater.  If present, it points to a struct s_PXE.
117          */
118         SEGOFF16_t      PXEPtr;
119 } PACKED;
120
121 typedef struct s_PXENV PXENV_t;
122
123 /** The !PXE structure */
124 struct s_PXE {
125         /** Signature
126          *
127          * Contains the bytes '!', 'P', 'X', 'E'.
128          */
129         UINT8_t         Signature[4];
130         UINT8_t         StructLength;   /**< Length of this structure */
131         /** Checksum
132          *
133          * The byte checksum of this structure (using the length in
134          * #StructLength) must be zero.
135          */
136         UINT8_t         StructCksum;
137         /** Revision of this structure
138          *
139          * For PXE version 2.1, this field must be zero.
140          */
141         UINT8_t         StructRev;
142         UINT8_t         reserved_1;     /**< Must be zero */
143         /** Address of the UNDI ROM ID structure
144          *
145          * This is a pointer to a struct s_UNDI_ROM_ID.
146          */
147         SEGOFF16_t      UNDIROMID;
148         /** Address of the Base Code ROM ID structure
149          *
150          * This is a pointer to a struct s_BC_ROM_ID.
151          */
152         SEGOFF16_t      BaseROMID;
153         /** 16-bit !PXE entry point
154          *
155          * This is the entry point for either real mode, or protected
156          * mode with a 16-bit stack segment.
157          */
158         SEGOFF16_t      EntryPointSP;
159         /** 32-bit !PXE entry point
160          *
161          * This is the entry point for protected mode with a 32-bit
162          * stack segment.
163          */
164         SEGOFF16_t      EntryPointESP;
165         /** Status call-out function
166          *
167          * @v 0         (if in a time-out loop)
168          * @v n         Number of a received TFTP packet
169          * @ret 0       Continue operation
170          * @ret 1       Cancel operation
171          *
172          * This function will be called whenever the PXE stack is in
173          * protected mode, is waiting for an event (e.g. a DHCP reply)
174          * and wishes to allow the user to cancel the operation.
175          * Parameters are passed in register %ax; the return value
176          * must also be placed in register %ax.  All other registers
177          * and flags @b must be preserved.
178          *
179          * In real mode, an internal function (that checks for a
180          * keypress) will be used.
181          *
182          * If this field is set to -1, no status call-out function
183          * will be used and consequently the user will not be allowed
184          * to interrupt operations.
185          *
186          * @note The PXE specification version 2.1 defines the
187          * StatusCallout field, mentions it 11 times, but nowhere
188          * defines what it actually does or how it gets called.
189          * Fortunately, the WfM specification version 1.1a deigns to
190          * inform us of such petty details.
191          */
192         SEGOFF16_t      StatusCallout;
193         UINT8_t         reserved_2;     /**< Must be zero */
194         /** Number of segment descriptors
195          *
196          * If this number is greater than 7, the remaining descriptors
197          * follow immediately after #BC_CodeWrite.
198          */
199         UINT8_t         SegDescCnt;
200         /** First protected-mode selector
201          *
202          * This is the segment selector value for the first segment
203          * assigned to PXE.  Protected-mode selectors must be
204          * consecutive, according to the PXE 2.1 specification, though
205          * no reason is given.  Each #SEGDESC_t includes a field for
206          * the segment selector, so this information is entirely
207          * redundant.
208          */
209         SEGSEL_t        FirstSelector;
210         /** Stack segment descriptor */
211         SEGDESC_t       Stack;
212         /** UNDI data segment descriptor */
213         SEGDESC_t       UNDIData;
214         /** UNDI code segment descriptor */
215         SEGDESC_t       UNDICode;
216         /** UNDI writable code segment descriptor */
217         SEGDESC_t       UNDICodeWrite;
218         /** Base-code data segment descriptor */
219         SEGDESC_t       BC_Data;
220         /** Base-code code segment descriptor */
221         SEGDESC_t       BC_Code;
222         /** Base-code writable code segment descriptor */
223         SEGDESC_t       BC_CodeWrite;
224 } PACKED;
225
226 typedef struct s_PXE PXE_t;
227
228 /** @} */ /* pxe_api_call */
229
230 /** @defgroup pxe_preboot_api PXE Preboot API
231  *
232  * General high-level functions: #PXENV_UNLOAD_STACK, #PXENV_START_UNDI etc.
233  *
234  * @{
235  */
236
237 /** @defgroup pxenv_unload_stack PXENV_UNLOAD_STACK
238  *
239  *  UNLOAD BASE CODE STACK
240  *
241  *  @{
242  */
243
244 /** PXE API function code for pxenv_unload_stack() */
245 #define PXENV_UNLOAD_STACK              0x0070
246
247 /** Parameter block for pxenv_unload_stack() */
248 struct s_PXENV_UNLOAD_STACK {
249         PXENV_STATUS_t Status;                  /**< PXE status code */
250         UINT8_t reserved[10];                   /**< Must be zero */
251 } PACKED;
252
253 typedef struct s_PXENV_UNLOAD_STACK PXENV_UNLOAD_STACK_t;
254
255 extern PXENV_EXIT_t pxenv_unload_stack ( struct s_PXENV_UNLOAD_STACK
256                                          *unload_stack );
257
258 /** @} */ /* pxenv_unload_stack */
259
260 /** @defgroup pxenv_get_cached_info PXENV_GET_CACHED_INFO
261  *
262  *  GET CACHED INFO
263  *
264  *  @{
265  */
266
267 /** PXE API function code for pxenv_get_cached_info() */
268 #define PXENV_GET_CACHED_INFO           0x0071
269
270 /** The client's DHCPDISCOVER packet */
271 #define PXENV_PACKET_TYPE_DHCP_DISCOVER 1
272
273 /** The DHCP server's DHCPACK packet */
274 #define PXENV_PACKET_TYPE_DHCP_ACK      2
275
276 /** The Boot Server's Discover Reply packet
277  *
278  * This packet contains DHCP option 60 set to "PXEClient", a valid
279  * boot file name, and may or may not contain MTFTP options.
280  */
281 #define PXENV_PACKET_TYPE_CACHED_REPLY  3
282
283 /** Parameter block for pxenv_get_cached_info() */
284 struct s_PXENV_GET_CACHED_INFO {
285         PXENV_STATUS_t Status;                  /**< PXE status code */
286         /** Packet type.
287          *
288          * Valid values are #PXENV_PACKET_TYPE_DHCP_DISCOVER,
289          * #PXENV_PACKET_TYPE_DHCP_ACK or #PXENV_PACKET_TYPE_CACHED_REPLY
290          */
291         UINT16_t PacketType;
292         UINT16_t BufferSize;                    /**< Buffer size */
293         SEGOFF16_t Buffer;                      /**< Buffer address */
294         UINT16_t BufferLimit;                   /**< Maximum buffer size */
295 } PACKED;
296
297 typedef struct s_PXENV_GET_CACHED_INFO PXENV_GET_CACHED_INFO_t;
298
299 #define BOOTP_REQ       1       /**< A BOOTP request packet */
300 #define BOOTP_REP       2       /**< A BOOTP reply packet */
301
302 /** DHCP broadcast flag
303  *
304  * Request a broadcast response (DHCPOFFER or DHCPACK) from the DHCP
305  * server.
306  */
307 #define BOOTP_BCAST     0x8000
308
309 #define VM_RFC1048      0x63825363L     /**< DHCP magic cookie */
310
311 /** Maximum length of DHCP options */
312 #define BOOTP_DHCPVEND  1024
313
314 /** Format of buffer filled in by pxenv_get_cached_info()
315  *
316  * This somewhat convoluted data structure simply describes the layout
317  * of a DHCP packet.  Refer to RFC2131 section 2 for a full
318  * description.
319  */
320 struct bootph {
321         /** Message opcode.
322          *
323          * Valid values are #BOOTP_REQ and #BOOTP_REP.
324          */
325         UINT8_t opcode;
326         /** NIC hardware type.
327          *
328          * Valid values are as for s_PXENV_UNDI_GET_INFORMATION::HwType.
329          */
330         UINT8_t Hardware;
331         UINT8_t Hardlen;                /**< MAC address length */
332         /** Gateway hops
333          *
334          * Zero in packets sent by the client.  May be non-zero in
335          * replies from the DHCP server, if the reply comes via a DHCP
336          * relay agent.
337          */
338         UINT8_t Gatehops;
339         UINT32_t ident;                 /**< DHCP transaction id (xid) */
340         /** Elapsed time
341          *
342          * Number of seconds since the client began the DHCP
343          * transaction.
344          */
345         UINT16_t seconds;
346         /** Flags
347          *
348          * This is the bitwise-OR of any of the following values:
349          * #BOOTP_BCAST.
350          */
351         UINT16_t Flags;
352         /** Client IP address
353          *
354          * Set only if the client already has an IP address.
355          */
356         IP4_t cip;
357         /** Your IP address
358          *
359          * This is the IP address that the server assigns to the
360          * client.
361          */
362         IP4_t yip;
363         /** Server IP address
364          *
365          * This is the IP address of the BOOTP/DHCP server.
366          */
367         IP4_t sip;
368         /** Gateway IP address
369          *
370          * This is the IP address of the BOOTP/DHCP relay agent, if
371          * any.  It is @b not (necessarily) the address of the default
372          * gateway for routing purposes.
373          */
374         IP4_t gip;
375         MAC_ADDR_t CAddr;               /**< Client MAC address */
376         UINT8_t Sname[64];              /**< Server host name */
377         UINT8_t bootfile[128];          /**< Boot file name */
378         /** DHCP options
379          *
380          * Don't ask.  Just laugh.  Then burn a copy of the PXE
381          * specification and send Intel an e-mail asking them if
382          * they've figured out what a "union" does in C yet.
383          */
384         union bootph_vendor {
385                 UINT8_t d[BOOTP_DHCPVEND]; /**< DHCP options */
386                 /** DHCP options */
387                 struct bootph_vendor_v {
388                         /** DHCP magic cookie
389                          *
390                          * Should have the value #VM_RFC1048.
391                          */
392                         UINT8_t magic[4];
393                         UINT32_t flags; /**< BOOTP flags/opcodes */
394                         /** "End of BOOTP vendor extensions"
395                          *
396                          * Abandon hope, all ye who consider the
397                          * purpose of this field.
398                          */
399                         UINT8_t pad[56];
400                 } v;
401         } vendor;
402 } PACKED;
403
404 typedef struct bootph BOOTPLAYER_t;
405
406 extern PXENV_EXIT_t pxenv_get_cached_info ( struct s_PXENV_GET_CACHED_INFO
407                                             *get_cached_info );
408
409 /** @} */ /* pxenv_get_cached_info */
410
411 /** @defgroup pxenv_restart_tftp PXENV_RESTART_TFTP
412  *
413  *  RESTART TFTP
414  *
415  *  @{
416  */
417
418 /** PXE API function code for pxenv_restart_tftp() */
419 #define PXENV_RESTART_TFTP              0x0073
420
421 /** Parameter block for pxenv_restart_tftp() */
422 struct s_PXENV_TFTP_READ_FILE;
423
424 typedef struct s_PXENV_RESTART_TFTP PXENV_RESTART_TFTP_t;
425
426 extern PXENV_EXIT_t pxenv_restart_tftp ( struct s_PXENV_TFTP_READ_FILE
427                                          *restart_tftp );
428
429 /** @} */ /* pxenv_restart_tftp */
430
431 /** @defgroup pxenv_start_undi PXENV_START_UNDI
432  *
433  *  START UNDI
434  *
435  *  @{
436  */
437
438 /** PXE API function code for pxenv_start_undi() */
439 #define PXENV_START_UNDI                0x0000
440
441 /** Parameter block for pxenv_start_undi() */
442 struct s_PXENV_START_UNDI {
443         PXENV_STATUS_t Status;                  /**< PXE status code */
444         /** %ax register as passed to the Option ROM initialisation routine.
445          *
446          * For a PCI device, this should contain the bus:dev:fn value
447          * that uniquely identifies the PCI device in the system.  For
448          * a non-PCI device, this field is not defined.
449          */
450         UINT16_t AX;
451         /** %bx register as passed to the Option ROM initialisation routine.
452          *
453          * For an ISAPnP device, this should contain the Card Select
454          * Number assigned to the ISAPnP card.  For non-ISAPnP
455          * devices, this should contain 0xffff.
456          */
457         UINT16_t BX;
458         /** %dx register as passed to the Option ROM initialisation routine.
459          *
460          * For an ISAPnP device, this should contain the ISAPnP Read
461          * Port address as currently set in all ISAPnP cards.  If
462          * there are no ISAPnP cards, this should contain 0xffff.  (If
463          * this is a non-ISAPnP device, but there are ISAPnP cards in
464          * the system, this value is not well defined.)
465          */
466         UINT16_t DX;
467         /** %di register as passed to the Option ROM initialisation routine.
468          *
469          * This contains the #OFF16_t portion of a struct #s_SEGOFF16
470          * that points to the System BIOS Plug and Play Installation
471          * Check Structure.  (Refer to section 4.4 of the Plug and
472          * Play BIOS specification for a description of this
473          * structure.)
474          *
475          * @note The PXE specification defines the type of this field
476          * as #UINT16_t.  For x86, #OFF16_t and #UINT16_t are
477          * equivalent anyway; for other architectures #OFF16_t makes
478          * more sense.
479          */
480         OFF16_t DI;
481         /** %es register as passed to the Option ROM initialisation routine.
482          *
483          * This contains the #SEGSEL_t portion of a struct #s_SEGOFF16
484          * that points to the System BIOS Plug and Play Installation
485          * Check Structure.  (Refer to section 4.4 of the Plug and
486          * Play BIOS specification for a description of this
487          * structure.)
488          *
489          * @note The PXE specification defines the type of this field
490          * as #UINT16_t.  For x86, #SEGSEL_t and #UINT16_t are
491          * equivalent anyway; for other architectures #SEGSEL_t makes
492          * more sense.
493          */
494         SEGSEL_t ES;
495 } PACKED;
496
497 typedef struct s_PXENV_START_UNDI PXENV_START_UNDI_t;
498
499 extern PXENV_EXIT_t pxenv_start_undi ( struct s_PXENV_START_UNDI *start_undi );
500
501 /** @} */ /* pxenv_start_undi */
502
503 /** @defgroup pxenv_stop_undi PXENV_STOP_UNDI
504  *
505  *  STOP UNDI
506  *
507  *  @{
508  */
509
510 /** PXE API function code for pxenv_stop_undi() */
511 #define PXENV_STOP_UNDI                 0x0015
512
513 /** Parameter block for pxenv_stop_undi() */
514 struct s_PXENV_STOP_UNDI {
515         PXENV_STATUS_t Status;                  /**< PXE status code */
516 } PACKED;
517
518 typedef struct s_PXENV_STOP_UNDI PXENV_STOP_UNDI_t;
519
520 extern PXENV_EXIT_t pxenv_stop_undi ( struct s_PXENV_STOP_UNDI *stop_undi );
521
522 /** @} */ /* pxenv_stop_undi */
523
524 /** @defgroup pxenv_start_base PXENV_START_BASE
525  *
526  *  START BASE
527  *
528  *  @{
529  */
530
531 /** PXE API function code for pxenv_start_base() */
532 #define PXENV_START_BASE                0x0075
533
534 /** Parameter block for pxenv_start_base() */
535 struct s_PXENV_START_BASE {
536         PXENV_STATUS_t Status;                  /**< PXE status code */
537 } PACKED;
538
539 typedef struct s_PXENV_START_BASE PXENV_START_BASE_t;
540
541 extern PXENV_EXIT_t pxenv_start_base ( struct s_PXENV_START_BASE *start_base );
542
543 /** @} */ /* pxenv_start_base */
544
545 /** @defgroup pxenv_stop_base PXENV_STOP_BASE
546  *
547  *  STOP BASE
548  *
549  *  @{
550  */
551
552 /** PXE API function code for pxenv_stop_base() */
553 #define PXENV_STOP_BASE                 0x0076
554
555 /** Parameter block for pxenv_stop_base() */
556 struct s_PXENV_STOP_BASE {
557         PXENV_STATUS_t Status;                  /**< PXE status code */
558 } PACKED;
559
560 typedef struct s_PXENV_STOP_BASE PXENV_STOP_BASE_t;
561
562 extern PXENV_EXIT_t pxenv_stop_base ( struct s_PXENV_STOP_BASE *stop_base );
563
564 /** @} */ /* pxenv_stop_base */
565
566 /** @} */ /* pxe_preboot_api */
567
568 /** @defgroup pxe_tftp_api PXE TFTP API
569  *
570  * Download files via TFTP or MTFTP
571  *
572  * @{
573  */
574
575 /** @defgroup pxenv_tftp_open PXENV_TFTP_OPEN
576  *
577  *  TFTP OPEN
578  *
579  *  @{
580  */
581
582 /** PXE API function code for pxenv_tftp_open() */
583 #define PXENV_TFTP_OPEN                 0x0020
584
585 /** Parameter block for pxenv_tftp_open() */
586 struct s_PXENV_TFTP_OPEN {
587         PXENV_STATUS_t Status;                  /**< PXE status code */
588         IP4_t ServerIPAddress;                  /**< TFTP server IP address */
589         IP4_t GatewayIPAddress;                 /**< Relay agent IP address */
590         UINT8_t FileName[128];                  /**< File name */
591         UDP_PORT_t TFTPPort;                    /**< TFTP server UDP port */
592         /** Requested size of TFTP packets
593          *
594          * This is the TFTP "blksize" option.  This must be at least
595          * 512, since servers that do not support TFTP options cannot
596          * negotiate blocksizes smaller than this.
597          */
598         UINT16_t PacketSize;
599 } PACKED;
600
601 typedef struct s_PXENV_TFTP_OPEN PXENV_TFTP_OPEN_t;
602
603 extern PXENV_EXIT_t pxenv_tftp_open ( struct s_PXENV_TFTP_OPEN *tftp_open );
604
605 /** @} */ /* pxenv_tftp_open */
606
607 /** @defgroup pxenv_tftp_close PXENV_TFTP_CLOSE
608  *
609  *  TFTP CLOSE
610  *
611  *  @{
612  */
613
614 /** PXE API function code for pxenv_tftp_close() */
615 #define PXENV_TFTP_CLOSE                0x0021
616
617 /** Parameter block for pxenv_tftp_close() */
618 struct s_PXENV_TFTP_CLOSE {
619         PXENV_STATUS_t Status;                  /**< PXE status code */
620 } PACKED;
621
622 typedef struct s_PXENV_TFTP_CLOSE PXENV_TFTP_CLOSE_t;
623
624 extern PXENV_EXIT_t pxenv_tftp_close ( struct s_PXENV_TFTP_CLOSE *tftp_close );
625
626 /** @} */ /* pxenv_tftp_close */
627
628 /** @defgroup pxenv_tftp_read PXENV_TFTP_READ
629  *
630  *  TFTP READ
631  *
632  *  @{
633  */
634
635 /** PXE API function code for pxenv_tftp_read() */
636 #define PXENV_TFTP_READ                 0x0022
637
638 /** Parameter block for pxenv_tftp_read() */
639 struct s_PXENV_TFTP_READ {
640         PXENV_STATUS_t Status;                  /**< PXE status code */
641         UINT16_t PacketNumber;                  /**< TFTP packet number */
642         UINT16_t BufferSize;                    /**< Size of data buffer */
643         SEGOFF16_t Buffer;                      /**< Address of data buffer */
644 } PACKED;
645
646 typedef struct s_PXENV_TFTP_READ PXENV_TFTP_READ_t;
647
648 extern PXENV_EXIT_t pxenv_tftp_read ( struct s_PXENV_TFTP_READ *tftp_read );
649
650 /** @} */ /* pxenv_tftp_read */
651
652 /** @defgroup pxenv_tftp_read_file PXENV_TFTP_READ_FILE
653  *
654  *  TFTP/MTFTP READ FILE
655  *
656  *  @{
657  */
658
659 /** PXE API function code for pxenv_tftp_read_file() */
660 #define PXENV_TFTP_READ_FILE            0x0023
661
662 /** Parameter block for pxenv_tftp_read_file() */
663 struct s_PXENV_TFTP_READ_FILE {
664         PXENV_STATUS_t Status;                  /**< PXE status code */
665         UINT8_t FileName[128];                  /**< File name */
666         UINT32_t BufferSize;                    /**< Size of data buffer */
667         ADDR32_t Buffer;                        /**< Address of data buffer */
668         IP4_t ServerIPAddress;                  /**< TFTP server IP address */
669         IP4_t GatewayIPAddress;                 /**< Relay agent IP address */
670         /** File multicast IP address */
671         IP4_t McastIPAddress;
672         /** Client multicast listening port */
673         UDP_PORT_t TFTPClntPort;
674         /** Server multicast listening port */
675         UDP_PORT_t TFTPSrvPort;
676         /** TFTP open timeout.
677          *
678          * This is the timeout for receiving the first DATA or ACK
679          * packets during the MTFTP Listen phase.
680          */
681         UINT16_t TFTPOpenTimeOut;
682         /** TFTP reopen timeout.
683          *
684          * This is the timeout for receiving an ACK packet while in
685          * the MTFTP Listen phase (when at least one ACK packet has
686          * already been seen).
687          */
688         UINT16_t TFTPReopenDelay;
689 } PACKED;
690
691 typedef struct s_PXENV_TFTP_READ_FILE PXENV_TFTP_READ_FILE_t;
692
693 extern PXENV_EXIT_t pxenv_tftp_read_file ( struct s_PXENV_TFTP_READ_FILE
694                                            *tftp_read_file );
695
696 /** @} */ /* pxenv_tftp_read_file */
697
698 /** @defgroup pxenv_tftp_get_fsize PXENV_TFTP_GET_FSIZE
699  *
700  *  TFTP GET FILE SIZE
701  *
702  *  @{
703  */
704
705 /** PXE API function code for pxenv_tftp_get_fsize() */
706 #define PXENV_TFTP_GET_FSIZE            0x0025
707
708 /** Parameter block for pxenv_tftp_get_fsize() */
709 struct s_PXENV_TFTP_GET_FSIZE {
710         PXENV_STATUS_t Status;                  /**< PXE status code */
711         IP4_t ServerIPAddress;                  /**< TFTP server IP address */
712         IP4_t GatewayIPAddress;                 /**< Relay agent IP address */
713         UINT8_t FileName[128];                  /**< File name */
714         UINT32_t FileSize;                      /**< Size of the file */
715 } PACKED;
716
717 typedef struct s_PXENV_TFTP_GET_FSIZE PXENV_TFTP_GET_FSIZE_t;
718
719 extern PXENV_EXIT_t pxenv_tftp_get_fsize ( struct s_PXENV_TFTP_GET_FSIZE
720                                            *get_fsize );
721
722 /** @} */ /* pxenv_tftp_get_fsize */
723
724 /** @} */ /* pxe_tftp_api */
725
726 /** @defgroup pxe_udp_api PXE UDP API
727  *
728  * Transmit and receive UDP packets
729  *
730  * @{
731  */
732
733 /** @defgroup pxenv_udp_open PXENV_UDP_OPEN
734  *
735  *  UDP OPEN
736  *
737  *  @{
738  */
739
740 /** PXE API function code for pxenv_udp_open() */
741 #define PXENV_UDP_OPEN                  0x0030
742
743 /** Parameter block for pxenv_udp_open() */
744 struct s_PXENV_UDP_OPEN {
745         PXENV_STATUS_t  Status;         /**< PXE status code */
746         IP4_t           src_ip;         /**< IP address of this station */
747 } PACKED;
748
749 typedef struct s_PXENV_UDP_OPEN PXENV_UDP_OPEN_t;
750
751 extern PXENV_EXIT_t pxenv_udp_open ( struct s_PXENV_UDP_OPEN *udp_open );
752
753 /** @} */ /* pxenv_udp_open */
754
755 /** @defgroup pxenv_udp_close PXENV_UDP_CLOSE
756  *
757  *  UDP CLOSE
758  *
759  *  @{
760  */
761
762 /** PXE API function code for pxenv_udp_close() */
763 #define PXENV_UDP_CLOSE                 0x0031
764
765 /** Parameter block for pxenv_udp_close() */
766 struct s_PXENV_UDP_CLOSE {
767         PXENV_STATUS_t  Status;         /**< PXE status code */
768 } PACKED;
769
770 typedef struct s_PXENV_UDP_CLOSE PXENV_UDP_CLOSE_t;
771
772 extern PXENV_EXIT_t pxenv_udp_close ( struct s_PXENV_UDP_CLOSE *udp_close );
773
774 /** @} */ /* pxenv_udp_close */
775
776 /** @defgroup pxenv_udp_write PXENV_UDP_WRITE
777  *
778  *  UDP WRITE
779  *
780  *  @{
781  */
782
783 /** PXE API function code for pxenv_udp_write() */
784 #define PXENV_UDP_WRITE                 0x0033
785
786 /** Parameter block for pxenv_udp_write() */
787 struct s_PXENV_UDP_WRITE {
788         PXENV_STATUS_t  Status;         /**< PXE status code */
789         IP4_t           ip;             /**< Destination IP address */
790         IP4_t           gw;             /**< Relay agent IP address */
791         UDP_PORT_t      src_port;       /**< Source UDP port */
792         UDP_PORT_t      dst_port;       /**< Destination UDP port */
793         UINT16_t        buffer_size;    /**< UDP payload buffer size */
794         SEGOFF16_t      buffer;         /**< UDP payload buffer address */
795 } PACKED;
796
797 typedef struct s_PXENV_UDP_WRITE PXENV_UDP_WRITE_t;
798
799 extern PXENV_EXIT_t pxenv_udp_write ( struct s_PXENV_UDP_WRITE *udp_write );
800
801 /** @} */ /* pxenv_udp_write */
802
803 /** @defgroup pxenv_udp_read PXENV_UDP_READ
804  *
805  *  UDP READ
806  *
807  *  @{
808  */
809
810 /** PXE API function code for pxenv_udp_read() */
811 #define PXENV_UDP_READ                  0x0032
812
813 /** Parameter block for pxenv_udp_read() */
814 struct s_PXENV_UDP_READ {
815         PXENV_STATUS_t  Status;         /**< PXE status code */
816         IP4_t           src_ip;         /**< Source IP address */
817         IP4_t           dest_ip;        /**< Destination IP address */
818         UDP_PORT_t      s_port;         /**< Source UDP port */
819         UDP_PORT_t      d_port;         /**< Destination UDP port */
820         UINT16_t        buffer_size;    /**< UDP payload buffer size */
821         SEGOFF16_t      buffer;         /**< UDP payload buffer address */
822 } PACKED;
823
824 typedef struct s_PXENV_UDP_READ PXENV_UDP_READ_t;
825
826 extern PXENV_EXIT_t pxenv_udp_read ( struct s_PXENV_UDP_READ *udp_read );
827
828 /** @} */ /* pxenv_udp_read */
829
830 /** @} */ /* pxe_udp_api */
831
832 /** @defgroup pxe_undi_api PXE UNDI API
833  *
834  * Direct control of the network interface card
835  *
836  * @{
837  */
838
839 /** @defgroup pxenv_undi_startup PXENV_UNDI_STARTUP
840  *
841  *  UNDI STARTUP
842  *
843  *  @{
844  */
845
846 /** PXE API function code for pxenv_undi_startup() */
847 #define PXENV_UNDI_STARTUP              0x0001
848
849 #define PXENV_BUS_ISA           0       /**< ISA bus type */
850 #define PXENV_BUS_EISA          1       /**< EISA bus type */
851 #define PXENV_BUS_MCA           2       /**< MCA bus type */
852 #define PXENV_BUS_PCI           3       /**< PCI bus type */
853 #define PXENV_BUS_VESA          4       /**< VESA bus type */
854 #define PXENV_BUS_PCMCIA        5       /**< PCMCIA bus type */
855
856 /** Parameter block for pxenv_undi_startup() */
857 struct s_PXENV_UNDI_STARTUP {
858         PXENV_STATUS_t  Status;         /**< PXE status code */
859 } PACKED;
860
861 typedef struct s_PXENV_UNDI_STARTUP PXENV_UNDI_STARTUP_t;
862
863 extern PXENV_EXIT_t pxenv_undi_startup ( struct s_PXENV_UNDI_STARTUP
864                                          *undi_startup );
865
866 /** @} */ /* pxenv_undi_startup */
867
868 /** @defgroup pxenv_undi_cleanup PXENV_UNDI_CLEANUP
869  *
870  *  UNDI CLEANUP
871  *
872  *  @{
873  */
874
875 /** PXE API function code for pxenv_undi_cleanup() */
876 #define PXENV_UNDI_CLEANUP              0x0002
877
878 /** Parameter block for pxenv_undi_cleanup() */
879 struct s_PXENV_UNDI_CLEANUP {
880         PXENV_STATUS_t  Status;         /**< PXE status code */
881 } PACKED;
882
883 typedef struct s_PXENV_UNDI_CLEANUP PXENV_UNDI_CLEANUP_t;
884
885 extern PXENV_EXIT_t pxenv_undi_cleanup ( struct s_PXENV_UNDI_CLEANUP
886                                          *undi_cleanup );
887
888 /** @} */ /* pxenv_undi_cleanup */
889
890 /** @defgroup pxenv_undi_initialize PXENV_UNDI_INITIALIZE
891  *
892  *  UNDI INITIALIZE
893  *
894  *  @{
895  */
896
897 /** PXE API function code for pxenv_undi_initialize() */
898 #define PXENV_UNDI_INITIALIZE           0x0003
899
900 /** Parameter block for pxenv_undi_initialize() */
901 struct s_PXENV_UNDI_INITIALIZE {
902         PXENV_STATUS_t  Status;         /**< PXE status code */
903         /** NDIS 2.0 configuration information, or NULL
904          *
905          * This is a pointer to the data structure returned by the
906          * NDIS 2.0 GetProtocolManagerInfo() API call.  The data
907          * structure is documented, in a rather haphazard way, in
908          * section 4-17 of the NDIS 2.0 specification.
909          */
910         ADDR32_t ProtocolIni;
911         UINT8_t reserved[8];            /**< Must be zero */
912 } PACKED;
913
914 typedef struct s_PXENV_UNDI_INITIALIZE PXENV_UNDI_INITIALIZE_t;
915
916 extern PXENV_EXIT_t pxenv_undi_initialize ( struct s_PXENV_UNDI_INITIALIZE
917                                             *undi_initialize );
918
919 /** @} */ /* pxenv_undi_initialize */
920
921 /** @defgroup pxenv_undi_reset_adapter PXENV_UNDI_RESET_ADAPTER
922  *
923  *  UNDI RESET ADAPTER
924  *
925  *  @{
926  */
927
928 /** PXE API function code for pxenv_undi_reset_adapter() */
929 #define PXENV_UNDI_RESET_ADAPTER        0x0004
930
931 /** Maximum number of multicast MAC addresses */
932 #define MAXNUM_MCADDR   8
933
934 /** List of multicast MAC addresses */
935 struct s_PXENV_UNDI_MCAST_ADDRESS {
936         /** Number of multicast MAC addresses */
937         UINT16_t MCastAddrCount;
938         /** List of up to #MAXNUM_MCADDR multicast MAC addresses */
939         MAC_ADDR_t McastAddr[MAXNUM_MCADDR];
940 } PACKED;
941
942 typedef struct s_PXENV_UNDI_MCAST_ADDRESS PXENV_UNDI_MCAST_ADDRESS_t;
943
944 /** Parameter block for pxenv_undi_reset_adapter() */
945 struct s_PXENV_UNDI_RESET {
946         PXENV_STATUS_t  Status;         /**< PXE status code */
947         /** Multicast MAC addresses */
948         struct s_PXENV_UNDI_MCAST_ADDRESS R_Mcast_Buf;
949 } PACKED;
950
951 typedef struct s_PXENV_UNDI_RESET PXENV_UNDI_RESET_t;
952
953 extern PXENV_EXIT_t pxenv_undi_reset_adapter ( struct s_PXENV_UNDI_RESET
954                                                *undi_reset_adapter );
955
956 /** @} */ /* pxenv_undi_reset_adapter */
957
958 /** @defgroup pxenv_undi_shutdown PXENV_UNDI_SHUTDOWN
959  *
960  *  UNDI SHUTDOWN
961  *
962  *  @{
963  */
964
965 /** PXE API function code for pxenv_undi_shutdown() */
966 #define PXENV_UNDI_SHUTDOWN             0x0005
967
968 /** Parameter block for pxenv_undi_shutdown() */
969 struct s_PXENV_UNDI_SHUTDOWN {
970         PXENV_STATUS_t  Status;         /**< PXE status code */
971 } PACKED;
972
973 typedef struct s_PXENV_UNDI_SHUTDOWN PXENV_UNDI_SHUTDOWN_t;
974
975 extern PXENV_EXIT_t pxenv_undi_shutdown ( struct s_PXENV_UNDI_SHUTDOWN
976                                           *undi_shutdown );
977
978 /** @} */ /* pxenv_undi_shutdown */
979
980 /** @defgroup pxenv_undi_open PXENV_UNDI_OPEN
981  *
982  *  UNDI OPEN
983  *
984  *  @{
985  */
986
987 /** PXE API function code for pxenv_undi_open() */
988 #define PXENV_UNDI_OPEN                 0x0006
989
990 /** Accept "directed" packets
991  *
992  * These are packets addresses to either this adapter's MAC address or
993  * to any of the configured multicast MAC addresses (see
994  * #s_PXENV_UNDI_MCAST_ADDRESS).
995  */
996 #define FLTR_DIRECTED   0x0001
997 /** Accept broadcast packets */
998 #define FLTR_BRDCST     0x0002
999 /** Accept all packets; listen in promiscuous mode */
1000 #define FLTR_PRMSCS     0x0004
1001 /** Accept source-routed packets */
1002 #define FLTR_SRC_RTG    0x0008
1003
1004 /** Parameter block for pxenv_undi_open() */
1005 struct s_PXENV_UNDI_OPEN {
1006         PXENV_STATUS_t  Status;         /**< PXE status code */
1007         /** Open flags as defined in NDIS 2.0
1008          *
1009          * This is the OpenOptions field as passed to the NDIS 2.0
1010          * OpenAdapter() API call.  It is defined to be "adapter
1011          * specific", though 0 is guaranteed to be a valid value.
1012          */
1013         UINT16_t OpenFlag;
1014         /** Receive packet filter
1015          *
1016          * This is the bitwise-OR of any of the following flags:
1017          * #FLTR_DIRECTED, #FLTR_BRDCST, #FLTR_PRMSCS and
1018          * #FLTR_SRC_RTG.
1019          */
1020         UINT16_t PktFilter;
1021         /** Multicast MAC addresses */
1022         struct s_PXENV_UNDI_MCAST_ADDRESS R_Mcast_Buf;
1023 } PACKED;
1024
1025 typedef struct s_PXENV_UNDI_OPEN PXENV_UNDI_OPEN_t;
1026
1027 extern PXENV_EXIT_t pxenv_undi_open ( struct s_PXENV_UNDI_OPEN *undi_open );
1028
1029 /** @} */ /* pxenv_undi_open */
1030
1031 /** @defgroup pxenv_undi_close PXENV_UNDI_CLOSE
1032  *
1033  *  UNDI CLOSE
1034  *
1035  *  @{
1036  */
1037
1038 /** PXE API function code for pxenv_undi_close() */
1039 #define PXENV_UNDI_CLOSE                0x0007
1040
1041 /** Parameter block for pxenv_undi_close() */
1042 struct s_PXENV_UNDI_CLOSE {
1043         PXENV_STATUS_t  Status;         /**< PXE status code */
1044 } PACKED;
1045
1046 typedef struct s_PXENV_UNDI_CLOSE PXENV_UNDI_CLOSE_t;
1047
1048 extern PXENV_EXIT_t pxenv_undi_close ( struct s_PXENV_UNDI_CLOSE *undi_close );
1049
1050 /** @} */ /* pxenv_undi_close */
1051
1052 /** @defgroup pxenv_undi_transmit PXENV_UNDI_TRANSMIT
1053  *
1054  *  UNDI TRANSMIT PACKET
1055  *
1056  *  @{
1057  */
1058
1059 /** PXE API function code for pxenv_undi_transmit() */
1060 #define PXENV_UNDI_TRANSMIT             0x0008
1061
1062 #define P_UNKNOWN       0               /**< Media header already filled in */
1063 #define P_IP            1               /**< IP protocol */
1064 #define P_ARP           2               /**< ARP protocol */
1065 #define P_RARP          3               /**< RARP protocol */
1066 #define P_OTHER         4               /**< Other protocol */
1067
1068 #define XMT_DESTADDR    0x0000          /**< Unicast packet */
1069 #define XMT_BROADCAST   0x0001          /**< Broadcast packet */
1070
1071 /** Maximum number of data blocks in a transmit buffer descriptor */
1072 #define MAX_DATA_BLKS   8
1073
1074 /** A transmit buffer descriptor, as pointed to by s_PXENV_UNDI_TRANSMIT::TBD
1075  */
1076 struct s_PXENV_UNDI_TBD {
1077         UINT16_t ImmedLength;           /**< Length of the transmit buffer */
1078         SEGOFF16_t Xmit;                /**< Address of the transmit buffer */
1079         UINT16_t DataBlkCount;
1080         /** Array of up to #MAX_DATA_BLKS additional transmit buffers */
1081         struct DataBlk {
1082                 /** Always 1
1083                  *
1084                  * A value of 0 would indicate that #TDDataPtr were an
1085                  * #ADDR32_t rather than a #SEGOFF16_t.  The PXE
1086                  * specification version 2.1 explicitly states that
1087                  * this is not supported; #TDDataPtr will always be a
1088                  * #SEGOFF16_t.
1089                  */
1090                 UINT8_t TDPtrType;
1091                 UINT8_t TDRsvdByte;     /**< Must be zero */
1092                 UINT16_t TDDataLen;     /**< Length of this transmit buffer */
1093                 SEGOFF16_t TDDataPtr;   /**< Address of this transmit buffer */
1094         } DataBlock[MAX_DATA_BLKS];
1095 } PACKED;
1096
1097 typedef struct s_PXENV_UNDI_TBD PXENV_UNDI_TBD_t;
1098
1099 /** Parameter block for pxenv_undi_transmit() */
1100 struct s_PXENV_UNDI_TRANSMIT {
1101         PXENV_STATUS_t  Status;         /**< PXE status code */
1102         /** Protocol
1103          *
1104          * Valid values are #P_UNKNOWN, #P_IP, #P_ARP or #P_RARP.  If
1105          * the caller has already filled in the media header, this
1106          * field must be set to #P_UNKNOWN.
1107          */
1108         UINT8_t Protocol;
1109         /** Unicast/broadcast flag
1110          *
1111          * Valid values are #XMT_DESTADDR or #XMT_BROADCAST.
1112          */
1113         UINT8_t XmitFlag;
1114         SEGOFF16_t DestAddr;            /**< Destination MAC address */
1115         /** Address of the Transmit Buffer Descriptor
1116          *
1117          * This is a pointer to a struct s_PXENV_UNDI_TBD.
1118          */
1119         SEGOFF16_t TBD;
1120         UINT32_t Reserved[2];           /**< Must be zero */
1121 } PACKED;
1122
1123 typedef struct s_PXENV_UNDI_TRANSMIT PXENV_UNDI_TRANSMIT_t;
1124
1125 extern PXENV_EXIT_t pxenv_undi_transmit ( struct s_PXENV_UNDI_TRANSMIT
1126                                           *undi_transmit );
1127
1128 /** @} */ /* pxenv_undi_transmit */
1129
1130 /** @defgroup pxenv_undi_set_mcast_address PXENV_UNDI_SET_MCAST_ADDRESS
1131  *
1132  *  UNDI SET MULTICAST ADDRESS
1133  *
1134  *  @{
1135  */
1136
1137 /** PXE API function code for pxenv_undi_set_mcast_address() */
1138 #define PXENV_UNDI_SET_MCAST_ADDRESS    0x0009
1139
1140 /** Parameter block for pxenv_undi_set_mcast_address() */
1141 struct s_PXENV_UNDI_SET_MCAST_ADDRESS {
1142         PXENV_STATUS_t  Status;         /**< PXE status code */
1143         /** List of multicast addresses */
1144         struct s_PXENV_UNDI_MCAST_ADDRESS R_Mcast_Buf;
1145 } PACKED;
1146
1147 typedef struct s_PXENV_UNDI_SET_MCAST_ADDRESS PXENV_UNDI_SET_MCAST_ADDRESS_t;
1148
1149 extern PXENV_EXIT_t pxenv_undi_set_mcast_address (
1150                struct s_PXENV_UNDI_SET_MCAST_ADDRESS *undi_set_mcast_address );
1151
1152 /** @} */ /* pxenv_undi_set_mcast_address */
1153
1154 /** @defgroup pxenv_undi_set_station_address PXENV_UNDI_SET_STATION_ADDRESS
1155  *
1156  *  UNDI SET STATION ADDRESS
1157  *
1158  *  @{
1159  */
1160
1161 /** PXE API function code for pxenv_undi_set_station_address() */
1162 #define PXENV_UNDI_SET_STATION_ADDRESS  0x000a
1163
1164 /** Parameter block for pxenv_undi_set_station_address() */
1165 struct s_PXENV_UNDI_SET_STATION_ADDRESS {
1166         PXENV_STATUS_t  Status;         /**< PXE status code */
1167         MAC_ADDR_t StationAddress;      /**< Station MAC address */
1168 } PACKED;
1169
1170 typedef struct s_PXENV_UNDI_SET_STATION_ADDRESS PXENV_UNDI_SET_STATION_ADDRESS_t;
1171
1172 extern PXENV_EXIT_t pxenv_undi_set_station_address (
1173            struct s_PXENV_UNDI_SET_STATION_ADDRESS *undi_set_station_address );
1174
1175 /** @} */ /* pxenv_undi_set_station_address */
1176
1177 /** @defgroup pxenv_undi_set_packet_filter PXENV_UNDI_SET_PACKET_FILTER
1178  *
1179  *  UNDI SET PACKET FILTER
1180  *
1181  *  @{
1182  */
1183
1184 /** PXE API function code for pxenv_undi_set_packet_filter() */
1185 #define PXENV_UNDI_SET_PACKET_FILTER    0x000b
1186
1187 /** Parameter block for pxenv_undi_set_packet_filter() */
1188 struct s_PXENV_UNDI_SET_PACKET_FILTER {
1189         PXENV_STATUS_t  Status;         /**< PXE status code */
1190         /** Receive packet filter
1191          *
1192          * This field takes the same values as
1193          * s_PXENV_UNDI_OPEN::PktFilter.
1194          *
1195          * @note Yes, this field is a different size to
1196          * s_PXENV_UNDI_OPEN::PktFilter.  Blame "the managers at Intel
1197          * who apparently let a consultant come up with the spec
1198          * without any kind of adult supervision" (quote from hpa).
1199          */
1200         UINT8_t filter;
1201 } PACKED;
1202
1203 typedef struct s_PXENV_UNDI_SET_PACKET_FILTER PXENV_UNDI_SET_PACKET_FILTER_t;
1204
1205 extern PXENV_EXIT_t pxenv_undi_set_packet_filter (
1206                struct s_PXENV_UNDI_SET_PACKET_FILTER *undi_set_packet_filter );
1207
1208 /** @} */ /* pxenv_undi_set_packet_filter */
1209
1210 /** @defgroup pxenv_undi_get_information PXENV_UNDI_GET_INFORMATION
1211  *
1212  *  UNDI GET INFORMATION
1213  *
1214  *  @{
1215  */
1216
1217 /** PXE API function code for pxenv_undi_get_information() */
1218 #define PXENV_UNDI_GET_INFORMATION      0x000c
1219
1220 #define ETHER_TYPE              1       /**< Ethernet (10Mb) */
1221 #define EXP_ETHER_TYPE          2       /**< Experimental Ethernet (3Mb) */
1222 #define AX25_TYPE               3       /**< Amateur Radio AX.25 */
1223 #define TOKEN_RING_TYPE         4       /**< Proteon ProNET Token Ring */
1224 #define CHAOS_TYPE              5       /**< Chaos */
1225 #define IEEE_TYPE               6       /**< IEEE 802 Networks */
1226 #define ARCNET_TYPE             7       /**< ARCNET */
1227
1228 /** Parameter block for pxenv_undi_get_information() */
1229 struct s_PXENV_UNDI_GET_INFORMATION {
1230         PXENV_STATUS_t  Status;         /**< PXE status code */
1231         UINT16_t BaseIo;                /**< I/O base address */
1232         UINT16_t IntNumber;             /**< IRQ number */
1233         UINT16_t MaxTranUnit;           /**< Adapter MTU */
1234         /** Hardware type
1235          *
1236          * Valid values are defined in RFC1010 ("Assigned numbers"),
1237          * and are #ETHER_TYPE, #EXP_ETHER_TYPE, #AX25_TYPE,
1238          * #TOKEN_RING_TYPE, #CHAOS_TYPE, #IEEE_TYPE or #ARCNET_TYPE.
1239          */
1240         UINT16_t HwType;
1241         UINT16_t HwAddrLen;             /**< MAC address length */
1242         MAC_ADDR_t CurrentNodeAddress;  /**< Current MAC address */
1243         MAC_ADDR_t PermNodeAddress;     /**< Permanent (EEPROM) MAC address */
1244         SEGSEL_t ROMAddress;            /**< Real-mode ROM segment address */
1245         UINT16_t RxBufCt;               /**< Receive queue length */
1246         UINT16_t TxBufCt;               /**< Transmit queue length */
1247 } PACKED;
1248
1249 typedef struct s_PXENV_UNDI_GET_INFORMATION PXENV_UNDI_GET_INFORMATION_t;
1250
1251 extern PXENV_EXIT_t pxenv_undi_get_information (
1252                    struct s_PXENV_UNDI_GET_INFORMATION *undi_get_information );
1253
1254 /** @} */ /* pxenv_undi_get_information */
1255
1256 /** @defgroup pxenv_undi_get_statistics PXENV_UNDI_GET_STATISTICS
1257  *
1258  *  UNDI GET STATISTICS
1259  *
1260  *  @{
1261  */
1262
1263 /** PXE API function code for pxenv_undi_get_statistics() */
1264 #define PXENV_UNDI_GET_STATISTICS       0x000d
1265
1266 /** Parameter block for pxenv_undi_get_statistics() */
1267 struct s_PXENV_UNDI_GET_STATISTICS {
1268         PXENV_STATUS_t  Status;         /**< PXE status code */
1269         UINT32_t XmtGoodFrames;         /**< Successful transmission count */
1270         UINT32_t RcvGoodFrames;         /**< Successful reception count */
1271         UINT32_t RcvCRCErrors;          /**< Receive CRC error count */
1272         UINT32_t RcvResourceErrors;     /**< Receive queue overflow count */
1273 } PACKED;
1274
1275 typedef struct s_PXENV_UNDI_GET_STATISTICS PXENV_UNDI_GET_STATISTICS_t;
1276
1277 extern PXENV_EXIT_t pxenv_undi_get_statistics (
1278                      struct s_PXENV_UNDI_GET_STATISTICS *undi_get_statistics );
1279
1280 /** @} */ /* pxenv_undi_get_statistics */
1281
1282 /** @defgroup pxenv_undi_clear_statistics PXENV_UNDI_CLEAR_STATISTICS
1283  *
1284  *  UNDI CLEAR STATISTICS
1285  *
1286  *  @{
1287  */
1288
1289 /** PXE API function code for pxenv_undi_clear_statistics() */
1290 #define PXENV_UNDI_CLEAR_STATISTICS     0x000e
1291
1292 /** Parameter block for pxenv_undi_clear_statistics() */
1293 struct s_PXENV_UNDI_CLEAR_STATISTICS {
1294         PXENV_STATUS_t  Status;         /**< PXE status code */
1295 } PACKED;
1296
1297 typedef struct s_PXENV_UNDI_CLEAR_STATISTICS PXENV_UNDI_CLEAR_STATISTICS_t;
1298
1299 extern PXENV_EXIT_t pxenv_undi_clear_statistics (
1300                  struct s_PXENV_UNDI_CLEAR_STATISTICS *undi_clear_statistics );
1301
1302 /** @} */ /* pxenv_undi_clear_statistics */
1303
1304 /** @defgroup pxenv_undi_initiate_diags PXENV_UNDI_INITIATE_DIAGS
1305  *
1306  *  UNDI INITIATE DIAGS
1307  *
1308  *  @{
1309  */
1310
1311 /** PXE API function code for pxenv_undi_initiate_diags() */
1312 #define PXENV_UNDI_INITIATE_DIAGS       0x000f
1313
1314 /** Parameter block for pxenv_undi_initiate_diags() */
1315 struct s_PXENV_UNDI_INITIATE_DIAGS {
1316         PXENV_STATUS_t  Status;         /**< PXE status code */
1317 } PACKED;
1318
1319 typedef struct s_PXENV_UNDI_INITIATE_DIAGS PXENV_UNDI_INITIATE_DIAGS_t;
1320
1321 extern PXENV_EXIT_t pxenv_undi_initiate_diags (
1322                      struct s_PXENV_UNDI_INITIATE_DIAGS *undi_initiate_diags );
1323
1324 /** @} */ /* pxenv_undi_initiate_diags */
1325
1326 /** @defgroup pxenv_undi_force_interrupt PXENV_UNDI_FORCE_INTERRUPT
1327  *
1328  *  UNDI FORCE INTERRUPT
1329  *
1330  *  @{
1331  */
1332
1333 /** PXE API function code for pxenv_undi_force_interrupt() */
1334 #define PXENV_UNDI_FORCE_INTERRUPT      0x0010
1335
1336 /** Parameter block for pxenv_undi_force_interrupt() */
1337 struct s_PXENV_UNDI_FORCE_INTERRUPT {
1338         PXENV_STATUS_t  Status;         /**< PXE status code */
1339 } PACKED;
1340
1341 typedef struct s_PXENV_UNDI_FORCE_INTERRUPT PXENV_UNDI_FORCE_INTERRUPT_t;
1342
1343 extern PXENV_EXIT_t pxenv_undi_force_interrupt (
1344                    struct s_PXENV_UNDI_FORCE_INTERRUPT *undi_force_interrupt );
1345
1346 /** @} */ /* pxenv_undi_force_interrupt */
1347
1348 /** @defgroup pxenv_undi_get_mcast_address PXENV_UNDI_GET_MCAST_ADDRESS
1349  *
1350  *  UNDI GET MULTICAST ADDRESS
1351  *
1352  *  @{
1353  */
1354
1355 /** PXE API function code for pxenv_undi_get_mcast_address() */
1356 #define PXENV_UNDI_GET_MCAST_ADDRESS    0x0011
1357
1358 /** Parameter block for pxenv_undi_get_mcast_address() */
1359 struct s_PXENV_UNDI_GET_MCAST_ADDRESS {
1360         PXENV_STATUS_t  Status;         /**< PXE status code */
1361         IP4_t InetAddr;                 /**< Multicast IP address */
1362         MAC_ADDR_t MediaAddr;           /**< Multicast MAC address */
1363 } PACKED;
1364
1365 typedef struct s_PXENV_UNDI_GET_MCAST_ADDRESS PXENV_UNDI_GET_MCAST_ADDRESS_t;
1366
1367 extern PXENV_EXIT_t pxenv_undi_get_mcast_address (
1368                struct s_PXENV_UNDI_GET_MCAST_ADDRESS *undi_get_mcast_address );
1369
1370 /** @} */ /* pxenv_undi_get_mcast_address */
1371
1372 /** @defgroup pxenv_undi_get_nic_type PXENV_UNDI_GET_NIC_TYPE
1373  *
1374  *  UNDI GET NIC TYPE
1375  *
1376  *  @{
1377  */
1378
1379 /** PXE API function code for pxenv_undi_get_nic_type() */
1380 #define PXENV_UNDI_GET_NIC_TYPE         0x0012
1381
1382 #define PCI_NIC         2               /**< PCI network card */
1383 #define PnP_NIC         3               /**< ISAPnP network card */
1384 #define CardBus_NIC     4               /**< CardBus network card */
1385
1386 /** Information for a PCI or equivalent NIC */
1387 struct pci_nic_info {
1388         UINT16_t Vendor_ID;             /**< PCI vendor ID */
1389         UINT16_t Dev_ID;                /**< PCI device ID */
1390         UINT8_t Base_Class;             /**< PCI base class */
1391         UINT8_t Sub_Class;              /**< PCI sub class */
1392         UINT8_t Prog_Intf;              /**< PCI programming interface */
1393         UINT8_t Rev;                    /**< PCI revision */
1394         UINT16_t BusDevFunc;            /**< PCI bus:dev:fn address */
1395         UINT16_t SubVendor_ID;          /**< PCI subvendor ID */
1396         UINT16_t SubDevice_ID;          /**< PCI subdevice ID */
1397 } PACKED;
1398  
1399 /** Information for an ISAPnP or equivalent NIC */
1400 struct pnp_nic_info {
1401         UINT32_t EISA_Dev_ID;           /**< EISA device ID */
1402         UINT8_t Base_Class;             /**< Base class */
1403         UINT8_t Sub_Class;              /**< Sub class */
1404         UINT8_t Prog_Intf;              /**< Programming interface */
1405         /** Card Select Number assigned to card */
1406         UINT16_t CardSelNum;
1407 } PACKED;
1408
1409 /** Parameter block for pxenv_undi_get_nic_type() */
1410 struct s_PXENV_UNDI_GET_NIC_TYPE {
1411         PXENV_STATUS_t  Status;         /**< PXE status code */
1412         /** NIC type
1413          *
1414          * Valid values are #PCI_NIC, #PnP_NIC or #CardBus_NIC.
1415          */
1416         UINT8_t NicType;
1417         /** NIC information */
1418         union nic_type_info {
1419                 /** NIC information (if #NicType==#PCI_NIC) */
1420                 struct pci_nic_info pci;
1421                 /** NIC information (if #NicType==#CardBus_NIC) */
1422                 struct pci_nic_info cardbus;
1423                 /** NIC information (if #NicType==#PnP_NIC) */
1424                 struct pnp_nic_info pnp;
1425         } info;
1426 } PACKED;
1427
1428 typedef struct s_PXENV_UNDI_GET_NIC_TYPE PXENV_UNDI_GET_NIC_TYPE_t;
1429
1430 extern PXENV_EXIT_t pxenv_undi_get_nic_type ( 
1431                          struct s_PXENV_UNDI_GET_NIC_TYPE *undi_get_nic_type );
1432
1433 /** @} */ /* pxenv_undi_get_nic_type */
1434
1435 /** @defgroup pxenv_undi_get_iface_info PXENV_UNDI_GET_IFACE_INFO
1436  *
1437  *  UNDI GET IFACE INFO
1438  *
1439  *  @{
1440  */
1441
1442 /** PXE API function code for pxenv_undi_get_iface_info() */
1443 #define PXENV_UNDI_GET_IFACE_INFO       0x0013
1444
1445 /** Broadcast supported */
1446 #define SUPPORTED_BROADCAST             0x0001
1447 /** Multicast supported */
1448 #define SUPPORTED_MULTICAST             0x0002
1449 /** Functional/group addressing supported */
1450 #define SUPPORTED_GROUP                 0x0004
1451 /** Promiscuous mode supported */
1452 #define SUPPORTED_PROMISCUOUS           0x0008
1453 /** Software settable station address */
1454 #define SUPPORTED_SET_STATION_ADDRESS   0x0010
1455 /** InitiateDiagnostics supported */
1456 #define SUPPORTED_DIAGNOSTICS           0x0040
1457 /** Reset MAC supported */
1458 #define SUPPORTED_RESET                 0x0400
1459 /** Open / Close Adapter supported */
1460 #define SUPPORTED_OPEN_CLOSE            0x0800
1461 /** Interrupt Request supported */
1462 #define SUPPORTED_IRQ                   0x1000
1463
1464 /** Parameter block for pxenv_undi_get_iface_info() */
1465 struct s_PXENV_UNDI_GET_IFACE_INFO {
1466         PXENV_STATUS_t  Status;         /**< PXE status code */
1467         /** Interface type
1468          *
1469          * This is defined in the NDIS 2.0 specification to be one of
1470          * the strings "802.3", "802.4", "802.5", "802.6", "DIX",
1471          * "DIX+802.3", "APPLETALK", "ARCNET", "FDDI", "SDLC", "BSC",
1472          * "HDLC", or "ISDN".
1473          *
1474          * "Normal" Ethernet, for various historical reasons, is
1475          * "DIX+802.3".
1476          */
1477         UINT8_t IfaceType[16];
1478         UINT32_t LinkSpeed;             /**< Link speed, in bits per second */
1479         /** Service flags
1480          *
1481          * These are the "service flags" defined in the "MAC
1482          * Service-Specific Characteristics" table in the NDIS 2.0
1483          * specification.  Almost all of them are irrelevant to PXE.
1484          */
1485         UINT32_t ServiceFlags;
1486         UINT32_t Reserved[4];           /**< Must be zero */
1487 } PACKED;
1488
1489 typedef struct s_PXENV_UNDI_GET_IFACE_INFO PXENV_UNDI_GET_IFACE_INFO_t;
1490
1491 extern PXENV_EXIT_t pxenv_undi_get_iface_info (
1492                      struct s_PXENV_UNDI_GET_IFACE_INFO *undi_get_iface_info );
1493
1494 /** @} */ /* pxenv_undi_get_iface_info */
1495
1496 /** @defgroup pxenv_undi_get_state PXENV_UNDI_GET_STATE
1497  *
1498  *  UNDI GET STATE
1499  *
1500  *  @{
1501  */
1502
1503 /** PXE API function code for pxenv_undi_get_state() */
1504 #define PXENV_UNDI_GET_STATE            0x0015
1505
1506 /** pxenv_start_undi() has been called */
1507 #define PXE_UNDI_GET_STATE_STARTED      1
1508 /** pxenv_undi_initialize() has been called */
1509 #define PXE_UNDI_GET_STATE_INITIALIZED  2
1510 /** pxenv_undi_open() has been called */
1511 #define PXE_UNDI_GET_STATE_OPENED       3
1512
1513 /** Parameter block for pxenv_undi_get_state() */
1514 struct s_PXENV_UNDI_GET_STATE {
1515         PXENV_STATUS_t  Status;         /**< PXE status code */
1516         /** Current state of the UNDI driver
1517          *
1518          * Valid values are #PXE_UNDI_GET_STATE_STARTED,
1519          * #PXE_UNDI_GET_STATE_INITIALIZED or
1520          * #PXE_UNDI_GET_STATE_OPENED.
1521          */
1522         UINT8_t UNDIstate;
1523 } PACKED;
1524
1525 typedef struct s_PXENV_UNDI_GET_STATE PXENV_UNDI_GET_STATE_t;
1526
1527 extern PXENV_EXIT_t pxenv_undi_get_state ( struct s_PXENV_UNDI_GET_STATE
1528                                            *undi_get_state );
1529
1530 /** @} */ /* pxenv_undi_get_state */
1531
1532 /** @defgroup pxenv_undi_isr PXENV_UNDI_ISR
1533  *
1534  *  UNDI ISR
1535  *
1536  *  @{
1537  */
1538
1539 /** PXE API function code for pxenv_undi_isr() */
1540 #define PXENV_UNDI_ISR                  0x0014
1541
1542 /** Determine whether or not this is our interrupt */
1543 #define PXENV_UNDI_ISR_IN_START         1
1544 /** Start processing interrupt */
1545 #define PXENV_UNDI_ISR_IN_PROCESS       2
1546 /** Continue processing interrupt */
1547 #define PXENV_UNDI_ISR_IN_GET_NEXT      3
1548 /** This interrupt was ours */
1549 #define PXENV_UNDI_ISR_OUT_OURS         0
1550 /** This interrupt was not ours */
1551 #define PXENV_UNDI_ISR_OUT_NOT_OURS     1
1552 /** Finished processing interrupt */
1553 #define PXENV_UNDI_ISR_OUT_DONE         0
1554 /** A packet transmission has completed */
1555 #define PXENV_UNDI_ISR_OUT_TRANSMIT     2
1556 /** A packet has been received */
1557 #define PXENV_UNDI_ISR_OUT_RECEIVE      3
1558 /** We are already in the middle of processing an interrupt */
1559 #define PXENV_UNDI_ISR_OUT_BUSY         4
1560
1561 /** Unicast packet (or packet captured in promiscuous mode) */
1562 #define P_DIRECTED      0
1563 /** Broadcast packet */
1564 #define P_BROADCAST     1
1565 /** Multicast packet */
1566 #define P_MULTICAST     2
1567
1568 /** Parameter block for pxenv_undi_isr() */
1569 struct s_PXENV_UNDI_ISR {
1570         PXENV_STATUS_t  Status;         /**< PXE status code */
1571         /** Function flag
1572          *
1573          * Valid values are #PXENV_UNDI_ISR_IN_START,
1574          * #PXENV_UNDI_ISR_IN_PROCESS, #PXENV_UNDI_ISR_IN_GET_NEXT,
1575          * #PXENV_UNDI_ISR_OUT_OURS, #PXENV_UNDI_ISR_OUT_NOT_OURS,
1576          * #PXENV_UNDI_ISR_OUT_DONE, #PXENV_UNDI_ISR_OUT_TRANSMIT,
1577          * #PXENV_UNDI_ISR_OUT_RECEIVE or #PXENV_UNDI_ISR_OUT_BUSY.
1578          */
1579         UINT16_t FuncFlag;
1580         UINT16_t BufferLength;          /**< Data buffer length */
1581         UINT16_t FrameLength;           /**< Total frame length */
1582         UINT16_t FrameHeaderLength;     /**< Frame header length */
1583         SEGOFF16_t Frame;               /**< Data buffer address */
1584         /** Protocol type
1585          *
1586          * Valid values are #P_IP, #P_ARP, #P_RARP or #P_OTHER.
1587          */
1588         UINT8_t ProtType;
1589         /** Packet type
1590          *
1591          * Valid values are #P_DIRECTED, #P_BROADCAST or #P_MULTICAST.
1592          */
1593         UINT8_t PktType;
1594 } PACKED;
1595
1596 typedef struct s_PXENV_UNDI_ISR PXENV_UNDI_ISR_t;
1597
1598 extern PXENV_EXIT_t pxenv_undi_isr ( struct s_PXENV_UNDI_ISR *undi_isr );
1599
1600 /** @} */ /* pxenv_undi_isr */
1601
1602 /** @} */ /* pxe_undi_api */
1603
1604 /** @defgroup pxe_file_api PXE FILE API
1605  *
1606  * POSIX-like file operations
1607  *
1608  * @{
1609  */
1610
1611 /** @defgroup pxenv_file_open PXENV_FILE_OPEN
1612  *
1613  * FILE OPEN
1614  *
1615  * @{
1616  */
1617
1618 /** PXE API function code for pxenv_file_open() */
1619 #define PXENV_FILE_OPEN                 0x00e0
1620
1621 /** Parameter block for pxenv_file_open() */
1622 struct s_PXENV_FILE_OPEN {
1623         PXENV_STATUS_t Status;          /**< PXE status code */
1624         UINT16_t FileHandle;            /**< File handle */
1625         SEGOFF16_t FileName;            /**< File URL */
1626         UINT32_t Reserved;              /**< Reserved */
1627 } PACKED;
1628
1629 typedef struct s_PXENV_FILE_OPEN PXENV_FILE_OPEN_t;
1630
1631 extern PXENV_EXIT_t pxenv_file_open ( struct s_PXENV_FILE_OPEN *file_open );
1632
1633 /** @} */ /* pxenv_file_open */
1634
1635 /** @defgroup pxenv_file_close PXENV_FILE_CLOSE
1636  *
1637  * FILE CLOSE
1638  *
1639  * @{
1640  */
1641
1642 /** PXE API function code for pxenv_file_close() */
1643 #define PXENV_FILE_CLOSE                0x00e1
1644
1645 /** Parameter block for pxenv_file_close() */
1646 struct s_PXENV_FILE_CLOSE {
1647         PXENV_STATUS_t Status;          /**< PXE status code */
1648         UINT16_t FileHandle;            /**< File handle */
1649 } PACKED;
1650
1651 typedef struct s_PXENV_FILE_CLOSE PXENV_FILE_CLOSE_t;
1652
1653 extern PXENV_EXIT_t pxenv_file_close ( struct s_PXENV_FILE_CLOSE
1654                                        *file_close );
1655
1656 /** @} */ /* pxenv_file_close */
1657
1658 /** @defgroup pxenv_file_select PXENV_FILE_SELECT
1659  *
1660  * FILE SELECT
1661  *
1662  * @{
1663  */
1664
1665 /** PXE API function code for pxenv_file_select() */
1666 #define PXENV_FILE_SELECT               0x00e2
1667
1668 /** File is ready for reading */
1669 #define RDY_READ                        0x0001
1670
1671 /** Parameter block for pxenv_file_select() */
1672 struct s_PXENV_FILE_SELECT {
1673         PXENV_STATUS_t Status;          /**< PXE status code */
1674         UINT16_t FileHandle;            /**< File handle */
1675         UINT16_t Ready;                 /**< Indication of readiness */
1676 } PACKED;
1677
1678 typedef struct s_PXENV_FILE_SELECT PXENV_FILE_SELECT_t;
1679
1680 extern PXENV_EXIT_t pxenv_file_select ( struct s_PXENV_FILE_SELECT
1681                                         *file_select );
1682
1683 /** @} */ /* pxenv_file_select */
1684
1685 /** @defgroup pxenv_file_read PXENV_FILE_READ
1686  *
1687  * FILE READ
1688  *
1689  * @{
1690  */
1691
1692 /** PXE API function code for pxenv_file_read() */
1693 #define PXENV_FILE_READ         0x00e3
1694
1695 /** Parameter block for pxenv_file_read() */
1696 struct s_PXENV_FILE_READ {
1697         PXENV_STATUS_t Status;          /**< PXE status code */
1698         UINT16_t FileHandle;            /**< File handle */
1699         UINT16_t BufferSize;            /**< Data buffer size */
1700         SEGOFF16_t Buffer;              /**< Data buffer */
1701 } PACKED;
1702
1703 typedef struct s_PXENV_FILE_READ PXENV_FILE_READ_t;
1704
1705 extern PXENV_EXIT_t pxenv_file_read ( struct s_PXENV_FILE_READ *file_read );
1706
1707 /** @} */ /* pxenv_file_read */
1708
1709 /** @defgroup pxenv_get_file_size PXENV_GET_FILE_SIZE
1710  *
1711  * GET FILE SIZE
1712  *
1713  * @{
1714  */
1715
1716 /** PXE API function code for pxenv_get_file_size() */
1717 #define PXENV_GET_FILE_SIZE             0x00e4
1718
1719 /** Parameter block for pxenv_get_file_size() */
1720 struct s_PXENV_GET_FILE_SIZE {
1721         PXENV_STATUS_t Status;          /**< PXE status code */
1722         UINT16_t FileHandle;            /**< File handle */
1723         UINT32_t FileSize;              /**< File size */
1724 } PACKED;
1725
1726 typedef struct s_PXENV_GET_FILE_SIZE PXENV_GET_FILE_SIZE_t;
1727
1728 extern PXENV_EXIT_t pxenv_get_file_size ( struct s_PXENV_GET_FILE_SIZE
1729                                           *get_file_size );
1730
1731 /** @} */ /* pxenv_get_file_size */
1732
1733 /** @defgroup pxenv_file_exec PXENV_FILE_EXEC
1734  *
1735  * FILE EXEC
1736  *
1737  * @{
1738  */
1739
1740 /** PXE API function code for pxenv_file_exec() */
1741 #define PXENV_FILE_EXEC                 0x00e5
1742
1743 /** Parameter block for pxenv_file_exec() */
1744 struct s_PXENV_FILE_EXEC {
1745         PXENV_STATUS_t Status;          /**< PXE status code */
1746         SEGOFF16_t Command;             /**< Command to execute */
1747 } PACKED;
1748
1749 typedef struct s_PXENV_FILE_EXEC PXENV_FILE_EXEC_t;
1750
1751 extern PXENV_EXIT_t pxenv_file_exec ( struct s_PXENV_FILE_EXEC *file_exec );
1752
1753 /** @} */ /* pxenv_file_exec */
1754
1755 /** @defgroup pxenv_file_api_check PXENV_FILE_API_CHECK
1756  *
1757  * FILE API CHECK
1758  *
1759  * @{
1760  */
1761
1762 /** PXE API function code for pxenv_file_api_check() */
1763 #define PXENV_FILE_API_CHECK            0x00e6
1764
1765 /** Parameter block for pxenv_file_api_check() */
1766 struct s_PXENV_FILE_API_CHECK {
1767         PXENV_STATUS_t Status;          /**< PXE status code */
1768         UINT16_t Size;                  /**< Size of structure  */
1769         UINT32_t Magic;                 /**< Magic number */
1770         UINT32_t Provider;              /**< Implementation identifier */
1771         UINT32_t APIMask;               /**< Supported API functions */
1772         UINT32_t Flags;                 /**< Reserved for the future */
1773 } PACKED;
1774
1775 typedef struct s_PXENV_FILE_API_CHECK PXENV_FILE_API_CHECK_t;
1776
1777 extern PXENV_EXIT_t pxenv_file_api_check ( struct s_PXENV_FILE_API_CHECK *file_api_check );
1778
1779 /** @} */ /* pxenv_file_api_check */
1780
1781 /** @defgroup pxenv_file_exit_hook PXENV_FILE_EXIT_HOOK
1782  *
1783  * FILE EXIT HOOK
1784  *
1785  * @{
1786  */
1787
1788 /** PXE API function code for pxenv_file_exit_hook() */
1789 #define PXENV_FILE_EXIT_HOOK                    0x00e7
1790
1791 /** Parameter block for pxenv_file_exit_hook() */
1792 struct s_PXENV_FILE_EXIT_HOOK {
1793         PXENV_STATUS_t Status;          /**< PXE status code */
1794         SEGOFF16_t Hook;                /**< SEG16:OFF16 to jump to */
1795 } PACKED;
1796
1797 typedef struct s_PXENV_FILE_EXIT_HOOK PXENV_FILE_EXIT_HOOK_t;
1798
1799 extern PXENV_EXIT_t pxenv_file_exit_hook ( struct s_PXENV_FILE_EXIT_HOOK *file_exit_hook );
1800
1801 /** @} */ /* pxenv_file_exit_hook */
1802
1803 /** @} */ /* pxe_file_api */
1804
1805 /** @defgroup pxe_loader_api PXE Loader API
1806  *
1807  * The UNDI ROM loader API
1808  *
1809  * @{
1810  */
1811
1812 /** Parameter block for undi_loader() */
1813 struct s_UNDI_LOADER {
1814         /** PXE status code */
1815         PXENV_STATUS_t Status;
1816         /** %ax register as for PXENV_START_UNDI */
1817         UINT16_t AX;
1818         /** %bx register as for PXENV_START_UNDI */
1819         UINT16_t BX;
1820         /** %dx register as for PXENV_START_UNDI */
1821         UINT16_t DX;
1822         /** %di register as for PXENV_START_UNDI */
1823         OFF16_t DI;
1824         /** %es register as for PXENV_START_UNDI */
1825         SEGSEL_t ES;
1826         /** UNDI data segment
1827          *
1828          * @note The PXE specification defines the type of this field
1829          * as #UINT16_t.  For x86, #SEGSEL_t and #UINT16_t are
1830          * equivalent anyway; for other architectures #SEGSEL_t makes
1831          * more sense.
1832          */
1833         SEGSEL_t UNDI_DS;
1834         /** UNDI code segment
1835          *
1836          * @note The PXE specification defines the type of this field
1837          * as #UINT16_t.  For x86, #SEGSEL_t and #UINT16_t are
1838          * equivalent anyway; for other architectures #SEGSEL_t makes
1839          * more sense.
1840          */
1841         SEGSEL_t UNDI_CS;
1842         /** Address of the !PXE structure (a struct s_PXE) */
1843         SEGOFF16_t PXEptr;
1844         /** Address of the PXENV+ structure (a struct s_PXENV) */
1845         SEGOFF16_t PXENVptr;
1846 } PACKED;
1847
1848 typedef struct s_UNDI_LOADER UNDI_LOADER_t;
1849
1850 extern PXENV_EXIT_t undi_loader ( struct s_UNDI_LOADER *undi_loader );
1851
1852 /** @} */ /* pxe_loader_api */
1853
1854 /** @} */ /* pxe */
1855
1856 /** @page pxe_notes Etherboot PXE implementation notes
1857
1858 @section pxe_routing IP routing
1859
1860 Several PXE API calls (e.g. pxenv_tftp_open() and pxenv_udp_write())
1861 allow for the caller to specify a "relay agent IP address", often in a
1862 field called "gateway" or similar.  The PXE specification states that
1863 "The IP layer should provide space for a minimum of four routing
1864 entries obtained from the default router and static route DHCP option
1865 tags in the DHCPACK message, plus any non-zero giaddr field from the
1866 DHCPOFFER message(s) accepted by the client".
1867
1868 The DHCP static route option ("option static-routes" in dhcpd.conf)
1869 works only for classed IP routing (i.e. it provides no way to specify
1870 a subnet mask).  Since virtually everything now uses classless IP
1871 routing, the DHCP static route option is almost totally useless, and
1872 is (according to the dhcp-options man page) not implemented by any of
1873 the popular DHCP clients.
1874
1875 This leaves the caller-specified "relay agent IP address", the giaddr
1876 field from the DHCPOFFER message(s) and the default gateway(s)
1877 provided via the routers option ("option routers" in dhcpd.conf) in
1878 the DHCPACK message.  Each of these is a default gateway address.
1879 It's a fair bet that the routers option should take priority over the
1880 giaddr field, since the routers option has to be explicitly specified
1881 by the DHCP server operator.  Similarly, it's fair to assume that the
1882 caller-specified "relay agent IP address", if present, should take
1883 priority over any other routing table entries.
1884
1885 @bug Etherboot currently ignores all potential sources of routing
1886 information other than the first router provided to it by a DHCP
1887 routers option.
1888
1889 @section pxe_x86_modes x86 processor mode restrictions
1890
1891 On the x86 platform, different PXE API calls have different
1892 restrictions on the processor modes (real or protected) that can be
1893 used.  See the individual API call descriptions for the restrictions
1894 that apply to any particular call.
1895
1896 @subsection pxe_x86_pmode16 Real mode, or protected-mode with 16-bit stack
1897
1898 The PXE specification states that the API function can be called in
1899 protected mode only if the s_PXE::StatusCallout field is set to a
1900 non-zero value, and that the API function cannot be called with a
1901 32-bit stack segment.
1902
1903 Etherboot does not enforce either of these restrictions; they seem (as
1904 with so much of the PXE specification) to be artifacts of the Intel
1905 implementation.
1906
1907 */
1908
1909 #endif /* PXE_API_H */