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 */