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 }NET_DRV_DEVICE;
 139
 140 /**
 141  * @brief
 142  *  The structure describes the SOCKET structure
 143  *
 144  * @details
 145  *  This is a very primitive 'SOCKET' layer structure which is populated
 146  *  by the application layer and registered with the UDP module. This is
 147  *  the basic interface through which packets are sent/received by the
 148  *  application layer and NET boot module. The structure is exported as it
 149  *  allows even device developers to write their own UDP application.
 150  */
 151 typedef struct SOCKET
 152 {
 153     /**
 154      * @brief   This is the local port on which the application is waiting
 155      * for packets to arrive.
 156      */
 157     Uint16  local_port;
 158
 159     /**
 160      * @brief   This is the remote port to which the application will send
 161      * data.
 162      */
 163     Uint16  remote_port;
 164
 165     /**
 166      * @brief   The remote IP address to which the application will send data.
 167      */
 168     IPN     remote_address;
 169
 170     /**
 171      * @brief   This is the application supplied call back function which is
 172      * invoked by the UDP module when a packet is received on the specific
 173      * port.
 174      */
 175     Int32   (*app_fn) (Int32 sock, Uint8* ptr_data, Int32 num_bytes);
 176 }SOCKET;
 177
 178 /**
 179  * @brief
 180  *  The structure describes the NET Stats
 181  *
 182  * @details
 183  *  The structure keeps track of the network boot module statistics. This
 184  *  is useful for debugging the network boot operations and drivers
 185  */
 186 typedef struct NET_STATS
 187 {
 188     /**
 189      * @brief   Total number of packets received.
 190      */
 191     Uint32      num_pkt_rxed;
 192
 193     /**
 194      * @brief   Total number of received packets dropped at the the layer2.
 195      * The stat is incremented because of the following reasons:-
 196      *  - Incorrect L2 Protocol received (Only IPv4 and ARP are handled)
 197      *  - Dst MAC Address is not directed unicast or broadcast.
 198      */
 199     Uint32      rx_l2_dropped;
 200
 201     /**
 202      * @brief   Total number of received packets dropped at the the ARP layer.
 203      * The stat is incremented because of the following reasons:-
 204      *  - Source MAC Address in the ARP packet is not meant for the stack.
 205      *  - Source IP Address in the ARP packet is not meant for the stack.
 206      */
 207     Uint32      rx_arp_dropped;
 208
 209     /**
 210      * @brief   Total number of received packets dropped at the the IPv4 layer.
 211      * The stat is incremented because of the following reasons:-
 212      *  - Invalid IP Header (Version 4 is only supported)
 213      *  - Incorrect Destination IP Address
 214      *  - Invalid IP checksum.
 215      */
 216     Uint32      rx_ip_dropped;
 217
 218     /**
 219      * @brief   Total number of received packets dropped at the the UDP layer.
 220      * The stat is incremented because of the following reasons:-
 221      *  - Invalid UDP checksum.
 222      *  - Packet length is below min UDP size.
 223      *  - No application is registered to handle the packet.
 224      */
 225     Uint32      rx_udp_dropped;
 226
 227     /**
 228      * @brief   Total number of packets transmitted.
 229      */
 230     Uint32      num_pkt_txed;
 231 }NET_STATS;
 232
 233 #ifdef _BIG_ENDIAN
 234  #define  ntohs(a) (a)
 235  #define  htons(a) (a)
 236  #define  htonl(a) (a)
 237  #define  ntohl(a) (a)
 238  #define  READ32(x)    (((Uint32)(*(Uint16 *)(x))<<16)|(Uint32)(*(Uint16 *)(((Uint8 *)(x))+2)))
 239 #else
 240  #define  htons(a)    ( (((a)>>8)&0xff) + (((a)<<8)&0xff00) )
 241  #define  ntohs(a)   htons(a)
 242  #define  htonl(a)    ( (((a)>>24)&0xff) + (((a)>>8)&0xff00) + \
 243                         (((a)<<8)&0xff0000) + (((a)<<24)&0xff000000) )
 244  #define  ntohl(a)   htonl(a)
 245  #define  READ32(x)    ((Uint32)(*(Uint16 *)(x))|((Uint32)(*(Uint16 *)(((Uint8 *)(x))+2))<<16))
 246 #endif
 247
 248 /**********************************************************************
 249  **************************** Exported Data ***************************
 250  **********************************************************************/
 251
 252 /**
 253  * @brief   This is the NET Boot Module function table which has been
 254  * exported. Device developers who wish to use the NET Boot Module are
 255  * advised to populate the address of this into the BOOT Mode descriptor.
 256  */
 257 extern BOOT_MODULE_FXN_TABLE net_boot_module;
 258
 259 /**
 260  * @brief   This is the NET Boot Module statistics.
 261  */
 262 extern NET_STATS             net_stats;
 263
 264 /**********************************************************************
 265  **************************** Exported Functions **********************
 266  **********************************************************************/
 267
 268 /* IPv4 Route Management Functions: Use these API to manually add/delete routes
 269  * to the NET Boot Module. If BOOTP is being used the routes are automatically
 270  * added; but if BOOTP is not used; the device layer needs to ensure that
 271  * routes are correctly configured */
 272 extern Int32 ip_add_route (Uint32 flag, IPN ip_address, IPN net_mask, IPN next_hop);
 273 extern void  ip_del_route (Uint32 flag);
 274
 275 /* Socket Functions: These are a very primitive stripped down versions of the
 276  * BSD socket API which are available to device authors to write their own
 277  * UDP application if one is so desired. BOOTP and TFTP are two applications
 278  * provided as a part of the NET Boot Module which use these. */
 279 extern Int32 udp_sock_open (SOCKET* ptr_socket);
 280 extern Int32 udp_sock_send (Int32 sock, Uint8* ptr_app_data, Int32 num_bytes);
 281 extern void  udp_sock_close(Int32 sock);
 282
 283 /* TFTP Functions: This is a TFTP exported API available to device authors to
 284  * be able to retrieve a file from the TFTP Server. */
 285 extern Int32 tftp_get_file (IPN server_ip, Int8* filename);
 286
 287 /* NET Core Functions: This function is useful if the device authors are writing
 288  * their own application; this is an ERROR Signal to the NET Boot Module that something
 289  * catastrophic has happened and that the application is not enable to proceed further. */
 290 extern void net_set_error(void);
 291
 292
 293 #endif /* __NET_H__ */