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__
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
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
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
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;
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];
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;
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;
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;
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;
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];
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;
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);
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);
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);
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);
139 }NET_DRV_DEVICE;
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;
160 /**
161 * @brief This is the remote port to which the application will send
162 * data.
163 */
164 Uint16 remote_port;
166 /**
167 * @brief The remote IP address to which the application will send data.
168 */
169 IPN remote_address;
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;
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;
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;
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;
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;
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;
228 /**
229 * @brief Total number of packets transmitted.
230 */
231 Uint32 num_pkt_txed;
232 }NET_STATS;
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
249 /**********************************************************************
250 **************************** Exported Data ***************************
251 **********************************************************************/
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;
260 /**
261 * @brief This is the NET Boot Module statistics.
262 */
263 extern NET_STATS net_stats;
265 /**********************************************************************
266 **************************** Exported Functions **********************
267 **********************************************************************/
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);
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);
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);
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);
294 #endif /* __NET_H__ */