Initial c661x version
[keystone-rtos/ibl.git] / 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__
45 #include "iblloc.h"
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
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
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
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];
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;
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;
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;
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;
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);
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);
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);
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;
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
184     /**
185      * @brief   This is the local port on which the application is waiting 
186      * for packets to arrive. 
187      */
188     Uint16  local_port;
190     /**
191      * @brief   This is the remote port to which the application will send 
192      * data.
193      */
194     Uint16  remote_port;
196     /**
197      * @brief   The remote IP address to which the application will send data.
198      */
199     IPN     remote_address;
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;
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
219     /**
220      * @brief   Total number of packets received.
221      */
222     Uint32      num_pkt_rxed;
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;
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;    
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;
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;
258     /**
259      * @brief   Total number of packets transmitted.
260      */
261     Uint32      num_pkt_txed;
262 }NET_STATS;
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
279 /**********************************************************************
280  **************************** Exported Data ***************************
281  **********************************************************************/
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;
290 /**
291  * @brief   This is the NET Boot Module statistics.
292  */
293 extern NET_STATS             net_stats;
295 /**********************************************************************
296  **************************** Exported Functions **********************
297  **********************************************************************/
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);
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);
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);
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);
324 #endif /* __NET_H__ */