src/driver/eth/net.h

   1 /**
   2  *   @file  net.h
   3  *
   4  *   @brief
   5  *      The file has data structures and API definitions for the
   6  *      NET Boot Module
   7  *
   8  *  \par
   9  *  NOTE:
  10  *      (C) Copyright 2008, Texas Instruments, Inc.
  11  *
  12  *  \par
  13  */
  14 #ifndef __NET_H__
  15 #define __NET_H__
  16
  17 /**
  18  * @brief   This is the MAX MTU of the packet that can be received in
  19  * the network module. This is configured to Ethernet standards at 1518
  20  */
  21 #define NET_MAX_MTU             1518
  22
  23 /**
  24  * @brief   This field indicates that the route is a network route
  25  * and any packet destined to the specific network is directly accessible.
  26  * Network Routes have the Next Hop address and the IP address to be the
  27  * same.
  28  *
  29  * @sa
  30  *  ip_add_route
  31  * @sa
  32  *  ip_del_route
  33  */
  34 #define FLG_RT_NETWORK      0x1
  35
  36 /**
  37  * @brief   This field indicates that the route is a default route.
  38  * This is a last entry in the routing table and is an indication that
  39  * the IP address to which the packet is destined is not directly accessible
  40  * but needs to be sent through a gateway (i.e. Next Hop)
  41  *
  42  * @sa
  43  *  ip_add_route
  44  * @sa
  45  *  ip_del_route
  46  */
  47 #define FLG_RT_DEFAULT      0x2
  48
  49 /**
  50  * @brief
  51  *  The structure describes the Network Device Configuration.
  52  *
  53  * @details
  54  *  This structures stores configuration data which is used populated
  55  *  by the Device layer and passed to the network boot module.
  56  */
  57 typedef struct NET_DRV_DEVICE
  58 {
  59     /**
  60      * @brief  The physical port number to use
  61      */
  62     Uint32  port_num;
  63
  64     /**
  65      * @brief   This is the MAC Address which is populated by the device
  66      * team. All packets sent by the NET module will use this MAC Address.
  67      */
  68     Uint8   mac_address[6];
  69
  70     /**
  71      * @brief   This is the IP Address associated with the networking device
  72      * Device team can specify an IP address which will be used for all
  73      * further communications. If BOOTP is enabled and this is 0; then the
  74      * BOOTP protocol kicks in to determine an IP Address to be used.
  75      */
  76     IPN     ip_address;
  77
  78     /**
  79      * @brief   This is the network mask. This is only required to be specified
  80      * if the device team has specified an IP address. If BOOTP is being used
  81      * this should be set to 0.
  82      */
  83     IPN     net_mask;
  84
  85     /**
  86      * @brief   This is the TFTP Server IP Address which is to be used to
  87      * download the file. This can be retreived from the BOOTP options but if
  88      * BOOTP is not being used; the Server IP address can be specified here.
  89      * This is ignored by the NET Boot Module if BOOTP is being used.
  90      */
  91     IPN     server_ip;
  92
  93     /**
  94      *  @brief  Set this to TRUE to override the server IP received from
  95      *          the bootp server and use the server_ip value above.
  96      */
  97     Bool    use_bootp_server_ip;
  98
  99     /**
 100      * @brief   This is the File Name which is to be downloaded from the TFTP
 101      * server. This can be retreived by decoding the BOOTP options but if BOOTP
 102      * is not being used then the file name can be specified here. This is ignored
 103      * by the NET Boot Module if BOOTP is being used.
 104      */
 105     Int8   file_name[64];
 106
 107     /**
 108      * @brief  Set this to TRUE to override the file_name received from the
 109      *         bootp server and use the file_name value above.
 110      */
 111     Bool    use_bootp_file_name;
 112
 113     /**
 114      * @brief   This API is used to start the Ethernet controller. This is a call
 115      * back function which is invoked by the NET boot module when it has been opened.
 116      */
 117     Int32 (*start) (struct NET_DRV_DEVICE* ptr_device);
 118
 119     /**
 120      * @brief   This API is used to stop the Ethernet controller. This is a call
 121      * back function which is invoked by the NET boot module when it has been closed.
 122      */
 123     Int32 (*stop) (struct NET_DRV_DEVICE* ptr_device);
 124
 125     /**
 126      * @brief   The API is invoked by the NET module to send data to the driver
 127      * for transmission.
 128      */
 129     Int32 (*send) (struct NET_DRV_DEVICE* ptr_device, Uint8* buffer, Int32 buffer_size);
 130
 131     /**
 132      * @brief   The API is invoked by the NET module to receive data from the
 133      * driver. The driver populates the buffer passed with the received data
 134      * and returns the number of bytes received. If there is no data which
 135      * has been received then the function returns 0
 136      */
 137     Int32 (*receive) (struct NET_DRV_DEVICE* ptr_device, Uint8* buffer);
 138
 139 }NET_DRV_DEVICE;
 140
 141 /**
 142  * @brief
 143  *  The structure describes the SOCKET structure
 144  *
 145  * @details
 146  *  This is a very primitive 'SOCKET' layer structure which is populated
 147  *  by the application layer and registered with the UDP module. This is
 148  *  the basic interface through which packets are sent/received by the
 149  *  application layer and NET boot module. The structure is exported as it
 150  *  allows even device developers to write their own UDP application.
 151  */
 152 typedef struct SOCKET
 153 {
 154     /**
 155      * @brief   This is the local port on which the application is waiting
 156      * for packets to arrive.
 157      */
 158     Uint16  local_port;
 159
 160     /**
 161      * @brief   This is the remote port to which the application will send
 162      * data.
 163      */
 164     Uint16  remote_port;
 165
 166     /**
 167      * @brief   The remote IP address to which the application will send data.
 168      */
 169     IPN     remote_address;
 170
 171     /**
 172      * @brief   This is the application supplied call back function which is
 173      * invoked by the UDP module when a packet is received on the specific
 174      * port.
 175      */
 176     Int32   (*app_fn) (Int32 sock, Uint8* ptr_data, Int32 num_bytes);
 177 }SOCKET;
 178
 179 /**
 180  * @brief
 181  *  The structure describes the NET Stats
 182  *
 183  * @details
 184  *  The structure keeps track of the network boot module statistics. This
 185  *  is useful for debugging the network boot operations and drivers
 186  */
 187 typedef struct NET_STATS
 188 {
 189     /**
 190      * @brief   Total number of packets received.
 191      */
 192     Uint32      num_pkt_rxed;
 193
 194     /**
 195      * @brief   Total number of received packets dropped at the the layer2.
 196      * The stat is incremented because of the following reasons:-
 197      *  - Incorrect L2 Protocol received (Only IPv4 and ARP are handled)
 198      *  - Dst MAC Address is not directed unicast or broadcast.
 199      */
 200     Uint32      rx_l2_dropped;
 201
 202     /**
 203      * @brief   Total number of received packets dropped at the the ARP layer.
 204      * The stat is incremented because of the following reasons:-
 205      *  - Source MAC Address in the ARP packet is not meant for the stack.
 206      *  - Source IP Address in the ARP packet is not meant for the stack.
 207      */
 208     Uint32      rx_arp_dropped;
 209
 210     /**
 211      * @brief   Total number of received packets dropped at the the IPv4 layer.
 212      * The stat is incremented because of the following reasons:-
 213      *  - Invalid IP Header (Version 4 is only supported)
 214      *  - Incorrect Destination IP Address
 215      *  - Invalid IP checksum.
 216      */
 217     Uint32      rx_ip_dropped;
 218
 219     /**
 220      * @brief   Total number of received packets dropped at the the UDP layer.
 221      * The stat is incremented because of the following reasons:-
 222      *  - Invalid UDP checksum.
 223      *  - Packet length is below min UDP size.
 224      *  - No application is registered to handle the packet.
 225      */
 226     Uint32      rx_udp_dropped;
 227
 228     /**
 229      * @brief   Total number of packets transmitted.
 230      */
 231     Uint32      num_pkt_txed;
 232 }NET_STATS;
 233
 234 #ifdef _BIG_ENDIAN
 235  #define  ntohs(a) (a)
 236  #define  htons(a) (a)
 237  #define  htonl(a) (a)
 238  #define  ntohl(a) (a)
 239  #define  READ32(x)    (((Uint32)(*(Uint16 *)(x))<<16)|(Uint32)(*(Uint16 *)(((Uint8 *)(x))+2)))
 240 #else
 241  #define  htons(a)    ( (((a)>>8)&0xff) + (((a)<<8)&0xff00) )
 242  #define  ntohs(a)   htons(a)
 243  #define  htonl(a)    ( (((a)>>24)&0xff) + (((a)>>8)&0xff00) + \
 244                         (((a)<<8)&0xff0000) + (((a)<<24)&0xff000000) )
 245  #define  ntohl(a)   htonl(a)
 246  #define  READ32(x)    ((Uint32)(*(Uint16 *)(x))|((Uint32)(*(Uint16 *)(((Uint8 *)(x))+2))<<16))
 247 #endif
 248
 249 /**********************************************************************
 250  **************************** Exported Data ***************************
 251  **********************************************************************/
 252
 253 /**
 254  * @brief   This is the NET Boot Module function table which has been
 255  * exported. Device developers who wish to use the NET Boot Module are
 256  * advised to populate the address of this into the BOOT Mode descriptor.
 257  */
 258 extern BOOT_MODULE_FXN_TABLE net_boot_module;
 259
 260 /**
 261  * @brief   This is the NET Boot Module statistics.
 262  */
 263 extern NET_STATS             net_stats;
 264
 265 /**********************************************************************
 266  **************************** Exported Functions **********************
 267  **********************************************************************/
 268
 269 /* IPv4 Route Management Functions: Use these API to manually add/delete routes
 270  * to the NET Boot Module. If BOOTP is being used the routes are automatically
 271  * added; but if BOOTP is not used; the device layer needs to ensure that
 272  * routes are correctly configured */
 273 extern Int32 ip_add_route (Uint32 flag, IPN ip_address, IPN net_mask, IPN next_hop);
 274 extern void  ip_del_route (Uint32 flag);
 275
 276 /* Socket Functions: These are a very primitive stripped down versions of the
 277  * BSD socket API which are available to device authors to write their own
 278  * UDP application if one is so desired. BOOTP and TFTP are two applications
 279  * provided as a part of the NET Boot Module which use these. */
 280 extern Int32 udp_sock_open (SOCKET* ptr_socket);
 281 extern Int32 udp_sock_send (Int32 sock, Uint8* ptr_app_data, Int32 num_bytes);
 282 extern void  udp_sock_close(Int32 sock);
 283
 284 /* TFTP Functions: This is a TFTP exported API available to device authors to
 285  * be able to retrieve a file from the TFTP Server. */
 286 extern Int32 tftp_get_file (IPN server_ip, Int8* filename);
 287
 288 /* NET Core Functions: This function is useful if the device authors are writing
 289  * their own application; this is an ERROR Signal to the NET Boot Module that something
 290  * catastrophic has happened and that the application is not enable to proceed further. */
 291 extern void net_set_error(void);
 292
 293
 294 #endif /* __NET_H__ */