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