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