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