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