Finished documenting the UNDI API.
authorMichael Brown <mcb30@etherboot.org>
Mon, 23 May 2005 13:57:23 +0000 (13:57 +0000)
committerMichael Brown <mcb30@etherboot.org>
Mon, 23 May 2005 13:57:23 +0000 (13:57 +0000)
src/include/pxe_api.h

index 34527fd..60657a3 100644 (file)
@@ -85,14 +85,6 @@ typedef struct s_PXENV_GET_CACHED_INFO PXENV_GET_CACHED_INFO_t;
 #define BOOTP_REQ      1       /**< A BOOTP request packet */
 #define BOOTP_REP      2       /**< A BOOTP reply packet */
 
-#define HWTYPE_ETHER           1       /**< Ethernet (10Mb) */
-#define HWTYPE_EXP_ETHER       2       /**< Experimental Ethernet (3Mb) */
-#define HWTYPE_AX25            3       /**< Amateur Radio AX.25 */
-#define HWTYPE_TOKEN_RING      4       /**< Proteon ProNET Token Ring */
-#define HWTYPE_CHAOS           5       /**< Chaos */
-#define HWTYPE_IEEE            6       /**< IEEE 802 Networks */
-#define HWTYPE_ARCNET          7       /**< ARCNET */
-
 /** DHCP broadcast flag
  *
  * Request a broadcast response (DHCPOFFER or DHCPACK) from the DHCP
@@ -116,10 +108,7 @@ struct bootph {
        UINT8_t opcode;
        /** NIC hardware type.
         *
-        * Valid values are defined in RFC1010 ("Assigned numbers"),
-        * and are #HWTYPE_ETHER, #HWTYPE_EXP_ETHER, #HWTYPE_AX25,
-        * #HWTYPE_TOKEN_RING, #HWTYPE_CHAOS, #HWTYPE_IEEE and
-        * #HWTYPE_ARCNET.
+        * Valid values are as for s_PXENV_UNDI_GET_INFORMATION::HwType.
         */
        UINT8_t Hardware;
        UINT8_t Hardlen;                /**< MAC address length */
@@ -837,8 +826,65 @@ extern PXENV_EXIT_t pxenv_undi_close ( struct s_PXENV_UNDI_CLOSE *undi_close );
 /** PXE API function code for pxenv_undi_transmit() */
 #define        PXENV_UNDI_TRANSMIT             0x0008
 
+#define P_UNKNOWN      0               /**< Media header already filled in */
+#define P_IP           1               /**< IP protocol */
+#define P_ARP          2               /**< ARP protocol */
+#define P_RARP         3               /**< RARP protocol */
+#define P_OTHER                4               /**< Other protocol */
+
+#define XMT_DESTADDR   0x0000          /**< Unicast packet */
+#define XMT_BROADCAST  0x0001          /**< Broadcast packet */
+
+/** Maximum number of data blocks in a transmit buffer descriptor */
+#define MAX_DATA_BLKS  8
+
+/** A transmit buffer descriptor, as pointed to by s_PXENV_UNDI_TRANSMIT::TBD
+ */
+struct s_PXENV_UNDI_TBD {
+       UINT16_t ImmedLength;           /**< Length of the transmit buffer */
+       SEGOFF16_t Xmit;                /**< Address of the transmit buffer */
+       UINT16_t DataBlkCount;
+       /** Array of up to #MAX_DATA_BLKS additional transmit buffers */
+       struct DataBlk {
+               /** Always 1
+                *
+                * A value of 0 would indicate that #TDDataPtr were an
+                * #ADDR32_t rather than a #SEGOFF16_t.  The PXE
+                * specification version 2.1 explicitly states that
+                * this is not supported; #TDDataPtr will always be a
+                * #SEGOFF16_t.
+                */
+               UINT8_t TDPtrType;
+               UINT8_t TDRsvdByte;     /**< Must be zero */
+               UINT16_t TDDataLen;     /**< Length of this transmit buffer */
+               SEGOFF16_t TDDataPtr;   /**< Address of this transmit buffer */
+       } DataBlock[MAX_DATA_BLKS];
+} PACKED;
+
+typedef struct s_PXENV_UNDI_TBD PXENV_UNDI_TBD_t;
+
 /** Parameter block for pxenv_undi_transmit() */
 struct s_PXENV_UNDI_TRANSMIT {
+       PXENV_STATUS_t  Status;         /**< PXE status code */
+       /** Protocol
+        *
+        * Valid values are #P_UNKNOWN, #P_IP, #P_ARP or #P_RARP.  If
+        * the caller has already filled in the media header, this
+        * field must be set to #P_UNKNOWN.
+        */
+       UINT8_t Protocol;
+       /** Unicast/broadcast flag
+        *
+        * Valid values are #XMT_DESTADDR or #XMT_BROADCAST.
+        */
+       UINT8_t XmitFlag;
+       SEGOFF16_t DestAddr;            /**< Destination MAC address */
+       /** Address of the Transmit Buffer Descriptor
+        *
+        * This is a pointer to a struct s_PXENV_UNDI_TBD.
+        */
+       SEGOFF16_t TBD;
+       UINT32_t Reserved[2];           /**< Must be zero */
 } PACKED;
 
 typedef struct s_PXENV_UNDI_TRANSMIT PXENV_UNDI_TRANSMIT_t;
@@ -860,6 +906,9 @@ extern PXENV_EXIT_t pxenv_undi_transmit ( struct s_PXENV_UNDI_TRANSMIT
 
 /** Parameter block for pxenv_undi_set_mcast_address() */
 struct s_PXENV_UNDI_SET_MCAST_ADDRESS {
+       PXENV_STATUS_t  Status;         /**< PXE status code */
+       /** List of multicast addresses */
+       struct s_PXENV_UNDI_MCAST_ADDRESS R_Mcast_Buf;
 } PACKED;
 
 typedef struct s_PXENV_UNDI_SET_MCAST_ADDRESS PXENV_UNDI_SET_MCAST_ADDRESS_t;
@@ -881,6 +930,8 @@ extern PXENV_EXIT_t pxenv_undi_set_mcast_address (
 
 /** Parameter block for pxenv_undi_set_station_address() */
 struct s_PXENV_UNDI_SET_STATION_ADDRESS {
+       PXENV_STATUS_t  Status;         /**< PXE status code */
+       MAC_ADDR_t StationAddress;      /**< Station MAC address */
 } PACKED;
 
 typedef struct s_PXENV_UNDI_SET_STATION_ADDRESS PXENV_UNDI_SET_STATION_ADDRESS_t;
@@ -902,6 +953,18 @@ extern PXENV_EXIT_t pxenv_undi_set_station_address (
 
 /** Parameter block for pxenv_undi_set_packet_filter() */
 struct s_PXENV_UNDI_SET_PACKET_FILTER {
+       PXENV_STATUS_t  Status;         /**< PXE status code */
+       /** Receive packet filter
+        *
+        * This field takes the same values as
+        * s_PXENV_UNDI_OPEN::PktFilter.
+        *
+        * @note Yes, this field is a different size to
+        * s_PXENV_UNDI_OPEN::PktFilter.  Blame "the managers at Intel
+        * who apparently let a consultant come up with the spec
+        * without any kind of adult supervision" (quote from hpa).
+        */
+       UINT8_t filter;
 } PACKED;
 
 typedef struct s_PXENV_UNDI_SET_PACKET_FILTER PXENV_UNDI_SET_PACKET_FILTER_t;
@@ -921,8 +984,33 @@ extern PXENV_EXIT_t pxenv_undi_set_packet_filter (
 /** PXE API function code for pxenv_undi_get_information() */
 #define        PXENV_UNDI_GET_INFORMATION      0x000c
 
+#define ETHER_TYPE             1       /**< Ethernet (10Mb) */
+#define EXP_ETHER_TYPE         2       /**< Experimental Ethernet (3Mb) */
+#define AX25_TYPE              3       /**< Amateur Radio AX.25 */
+#define TOKEN_RING_TYPE                4       /**< Proteon ProNET Token Ring */
+#define CHAOS_TYPE             5       /**< Chaos */
+#define IEEE_TYPE              6       /**< IEEE 802 Networks */
+#define ARCNET_TYPE            7       /**< ARCNET */
+
 /** Parameter block for pxenv_undi_get_information() */
 struct s_PXENV_UNDI_GET_INFORMATION {
+       PXENV_STATUS_t  Status;         /**< PXE status code */
+       UINT16_t BaseIo;                /**< I/O base address */
+       UINT16_t IntNumber;             /**< IRQ number */
+       UINT16_t MaxTranUnit;           /**< Adapter MTU */
+       /** Hardware type
+        *
+        * Valid values are defined in RFC1010 ("Assigned numbers"),
+        * and are #ETHER_TYPE, #EXP_ETHER_TYPE, #AX25_TYPE,
+        * #TOKEN_RING_TYPE, #CHAOS_TYPE, #IEEE_TYPE or #ARCNET_TYPE.
+        */
+       UINT16_t HwType;
+       UINT16_t HwAddrLen;             /**< MAC address length */
+       MAC_ADDR_t CurrentNodeAddress;  /**< Current MAC address */
+       MAC_ADDR_t PermNodeAddress;     /**< Permanent (EEPROM) MAC address */
+       SEGSEL_t ROMAddress;            /**< Real-mode ROM segment address */
+       UINT16_t RxBufCt;               /**< Receive queue length */
+       UINT16_t TxBufCt;               /**< Transmit queue length */
 } PACKED;
 
 typedef struct s_PXENV_UNDI_GET_INFORMATION PXENV_UNDI_GET_INFORMATION_t;
@@ -944,6 +1032,11 @@ extern PXENV_EXIT_t pxenv_undi_get_information (
 
 /** Parameter block for pxenv_undi_get_statistics() */
 struct s_PXENV_UNDI_GET_STATISTICS {
+       PXENV_STATUS_t  Status;         /**< PXE status code */
+       UINT32_t XmtGoodFrames;         /**< Successful transmission count */
+       UINT32_t RcvGoodFrames;         /**< Successful reception count */
+       UINT32_t RcvCRCErrors;          /**< Receive CRC error count */
+       UINT32_t RcvResourceErrors;     /**< Receive queue overflow count */
 } PACKED;
 
 typedef struct s_PXENV_UNDI_GET_STATISTICS PXENV_UNDI_GET_STATISTICS_t;
@@ -965,6 +1058,7 @@ extern PXENV_EXIT_t pxenv_undi_get_statistics (
 
 /** Parameter block for pxenv_undi_clear_statistics() */
 struct s_PXENV_UNDI_CLEAR_STATISTICS {
+       PXENV_STATUS_t  Status;         /**< PXE status code */
 } PACKED;
 
 typedef struct s_PXENV_UNDI_CLEAR_STATISTICS PXENV_UNDI_CLEAR_STATISTICS_t;
@@ -986,6 +1080,7 @@ extern PXENV_EXIT_t pxenv_undi_clear_statistics (
 
 /** Parameter block for pxenv_undi_initiate_diags() */
 struct s_PXENV_UNDI_INITIATE_DIAGS {
+       PXENV_STATUS_t  Status;         /**< PXE status code */
 } PACKED;
 
 typedef struct s_PXENV_UNDI_INITIATE_DIAGS PXENV_UNDI_INITIATE_DIAGS_t;
@@ -1007,6 +1102,7 @@ extern PXENV_EXIT_t pxenv_undi_initiate_diags (
 
 /** Parameter block for pxenv_undi_force_interrupt() */
 struct s_PXENV_UNDI_FORCE_INTERRUPT {
+       PXENV_STATUS_t  Status;         /**< PXE status code */
 } PACKED;
 
 typedef struct s_PXENV_UNDI_FORCE_INTERRUPT PXENV_UNDI_FORCE_INTERRUPT_t;
@@ -1028,6 +1124,9 @@ extern PXENV_EXIT_t pxenv_undi_force_interrupt (
 
 /** Parameter block for pxenv_undi_get_mcast_address() */
 struct s_PXENV_UNDI_GET_MCAST_ADDRESS {
+       PXENV_STATUS_t  Status;         /**< PXE status code */
+       IP4_t InetAddr;                 /**< Multicast IP address */
+       MAC_ADDR_t MediaAddr;           /**< Multicast MAC address */
 } PACKED;
 
 typedef struct s_PXENV_UNDI_GET_MCAST_ADDRESS PXENV_UNDI_GET_MCAST_ADDRESS_t;
@@ -1047,8 +1146,50 @@ extern PXENV_EXIT_t pxenv_undi_get_mcast_address (
 /** PXE API function code for pxenv_undi_get_nic_type() */
 #define        PXENV_UNDI_GET_NIC_TYPE         0x0012
 
+#define PCI_NIC                2               /**< PCI network card */
+#define PnP_NIC                3               /**< ISAPnP network card */
+#define CardBus_NIC    4               /**< CardBus network card */
+
+/** Information for a PCI or equivalent NIC */
+struct pci_nic_info {
+       UINT16_t Vendor_ID;             /**< PCI vendor ID */
+       UINT16_t Dev_ID;                /**< PCI device ID */
+       UINT8_t Base_Class;             /**< PCI base class */
+       UINT8_t Sub_Class;              /**< PCI sub class */
+       UINT8_t Prog_Intf;              /**< PCI programming interface */
+       UINT8_t Rev;                    /**< PCI revision */
+       UINT16_t BusDevFunc;            /**< PCI bus:dev:fn address */
+       UINT16_t SubVendor_ID;          /**< PCI subvendor ID */
+       UINT16_t SubDevice_ID;          /**< PCI subdevice ID */
+} PACKED;
+/** Information for an ISAPnP or equivalent NIC */
+struct pnp_nic_info {
+       UINT32_t EISA_Dev_ID;           /**< EISA device ID */
+       UINT8_t Base_Class;             /**< Base class */
+       UINT8_t Sub_Class;              /**< Sub class */
+       UINT8_t Prog_Intf;              /**< Programming interface */
+       /** Card Select Number assigned to card */
+       UINT16_t CardSelNum;
+} PACKED;
+
 /** Parameter block for pxenv_undi_get_nic_type() */
 struct s_PXENV_UNDI_GET_NIC_TYPE {
+       PXENV_STATUS_t  Status;         /**< PXE status code */
+       /** NIC type
+        *
+        * Valid values are #PCI_NIC, #PnP_NIC or #CardBus_NIC.
+        */
+       UINT8_t NicType;
+       /** NIC information */
+       union nic_type_info {
+               /** NIC information (if #NicType==#PCI_NIC) */
+               struct pci_nic_info pci;
+               /** NIC information (if #NicType==#CardBus_NIC) */
+               struct pci_nic_info cardbus;
+               /** NIC information (if #NicType==#PnP_NIC) */
+               struct pnp_nic_info pnp;
+       } info;
 } PACKED;
 
 typedef struct s_PXENV_UNDI_GET_NIC_TYPE PXENV_UNDI_GET_NIC_TYPE_t;
@@ -1070,6 +1211,27 @@ extern PXENV_EXIT_t pxenv_undi_get_nic_type (
 
 /** Parameter block for pxenv_undi_get_iface_info() */
 struct s_PXENV_UNDI_GET_IFACE_INFO {
+       PXENV_STATUS_t  Status;         /**< PXE status code */
+       /** Interface type
+        *
+        * This is defined in the NDIS 2.0 specification to be one of
+        * the strings "802.3", "802.4", "802.5", "802.6", "DIX",
+        * "DIX+802.3", "APPLETALK", "ARCNET", "FDDI", "SDLC", "BSC",
+        * "HDLC", or "ISDN".
+        *
+        * "Normal" Ethernet, for various historical reasons, is
+        * "DIX+802.3".
+        */
+       UINT8_t IfaceType[16];
+       UINT32_t LinkSpeed;             /**< Link speed, in bits per second */
+       /** Service flags
+        *
+        * These are the "service flags" defined in the "MAC
+        * Service-Specific Characteristics" table in the NDIS 2.0
+        * specification.  Almost all of them are irrelevant to PXE.
+        */
+       UINT32_t ServiceFlags;
+       UINT32_t Reserved[4];           /**< Must be zero */
 } PACKED;
 
 typedef struct s_PXENV_UNDI_GET_IFACE_INFO PXENV_UNDI_GET_IFACE_INFO_t;
@@ -1089,8 +1251,23 @@ extern PXENV_EXIT_t pxenv_undi_get_iface_info (
 /** PXE API function code for pxenv_undi_get_state() */
 #define PXENV_UNDI_GET_STATE           0x0015
 
+/** pxenv_start_undi() has been called */
+#define PXE_UNDI_GET_STATE_STARTED     1
+/** pxenv_undi_initialize() has been called */
+#define PXE_UNDI_GET_STATE_INITIALIZED 2
+/** pxenv_undi_open() has been called */
+#define PXE_UNDI_GET_STATE_OPENED      3
+
 /** Parameter block for pxenv_undi_get_state() */
 struct s_PXENV_UNDI_GET_STATE {
+       PXENV_STATUS_t  Status;         /**< PXE status code */
+       /** Current state of the UNDI driver
+        *
+        * Valid values are #PXE_UNDI_GET_STATE_STARTED,
+        * #PXE_UNDI_GET_STATE_INITIALIZED or
+        * #PXE_UNDI_GET_STATE_OPENED.
+        */
+       UINT8_t UNDIstate;
 } PACKED;
 
 typedef struct s_PXENV_UNDI_GET_STATE PXENV_UNDI_GET_STATE_t;
@@ -1110,8 +1287,58 @@ extern PXENV_EXIT_t pxenv_undi_get_state ( struct s_PXENV_UNDI_GET_STATE
 /** PXE API function code for pxenv_undi_isr() */
 #define        PXENV_UNDI_ISR                  0x0014
 
+/** Determine whether or not this is our interrupt */
+#define PXENV_UNDI_ISR_IN_START                1
+/** Start processing interrupt */
+#define PXENV_UNDI_ISR_IN_PROCESS      2
+/** Continue processing interrupt */
+#define PXENV_UNDI_ISR_IN_GET_NEXT     3
+/** This interrupt was ours */
+#define PXENV_UNDI_ISR_OUT_OURS                0
+/** This interrupt was not ours */
+#define PXENV_UNDI_ISR_OUT_NOT_OURS    1
+/** Finished processing interrupt */
+#define PXENV_UNDI_ISR_OUT_DONE                0
+/** A packet transmission has completed */
+#define PXENV_UNDI_ISR_OUT_TRANSMIT    2
+/** A packet has been received */
+#define PXENV_UNDI_ISR_OUT_RECEIVE     3
+/** We are already in the middle of processing an interrupt */
+#define PXENV_UNDI_ISR_OUT_BUSY                4
+
+/** Unicast packet (or packet captured in promiscuous mode) */
+#define P_DIRECTED     0
+/** Broadcast packet */
+#define P_BROADCAST    1
+/** Multicast packet */
+#define P_MULTICAST    2
+
 /** Parameter block for pxenv_undi_isr() */
 struct s_PXENV_UNDI_ISR {
+       PXENV_STATUS_t  Status;         /**< PXE status code */
+       /** Function flag
+        *
+        * Valid values are #PXENV_UNDI_ISR_IN_START,
+        * #PXENV_UNDI_ISR_IN_PROCESS, #PXENV_UNDI_ISR_IN_GET_NEXT,
+        * #PXENV_UNDI_ISR_OUT_OURS, #PXENV_UNDI_ISR_OUT_NOT_OURS,
+        * #PXENV_UNDI_ISR_OUT_DONE, #PXENV_UNDI_ISR_OUT_TRANSMIT,
+        * #PXENV_UNDI_ISR_OUT_RECEIVE or #PXENV_UNDI_ISR_OUT_BUSY.
+        */
+       UINT16_t FuncFlag;
+       UINT16_t BufferLength;          /**< Data buffer length */
+       UINT16_t FrameLength;           /**< Total frame length */
+       UINT16_t FrameHeaderLength;     /**< Frame header length */
+       SEGOFF16_t Frame;               /**< Data buffer address */
+       /** Protocol type
+        *
+        * Valid values are #P_IP, #P_ARP, #P_RARP or #P_OTHER.
+        */
+       UINT8_t ProtType;
+       /** Packet type
+        *
+        * Valid values are #P_DIRECTED, #P_BROADCAST or #P_MULTICAST.
+        */
+       UINT8_t PktType;
 } PACKED;
 
 typedef struct s_PXENV_UNDI_ISR PXENV_UNDI_ISR_t;