rawapi.txt 17 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437
  1. Raw TCP/IP interface for lwIP
  2. Authors: Adam Dunkels, Leon Woestenberg, Christiaan Simons
  3. lwIP provides two Application Program's Interfaces (APIs) for programs
  4. to use for communication with the TCP/IP code:
  5. * low-level "core" / "callback" or "raw" API.
  6. * higher-level "sequential" API.
  7. The sequential API provides a way for ordinary, sequential, programs
  8. to use the lwIP stack. It is quite similar to the BSD socket API. The
  9. model of execution is based on the blocking open-read-write-close
  10. paradigm. Since the TCP/IP stack is event based by nature, the TCP/IP
  11. code and the application program must reside in different execution
  12. contexts (threads).
  13. ** The remainder of this document discusses the "raw" API. **
  14. The raw TCP/IP interface allows the application program to integrate
  15. better with the TCP/IP code. Program execution is event based by
  16. having callback functions being called from within the TCP/IP
  17. code. The TCP/IP code and the application program both run in the same
  18. thread. The sequential API has a much higher overhead and is not very
  19. well suited for small systems since it forces a multithreaded paradigm
  20. on the application.
  21. The raw TCP/IP interface is not only faster in terms of code execution
  22. time but is also less memory intensive. The drawback is that program
  23. development is somewhat harder and application programs written for
  24. the raw TCP/IP interface are more difficult to understand. Still, this
  25. is the preferred way of writing applications that should be small in
  26. code size and memory usage.
  27. Both APIs can be used simultaneously by different application
  28. programs. In fact, the sequential API is implemented as an application
  29. program using the raw TCP/IP interface.
  30. --- Callbacks
  31. Program execution is driven by callbacks. Each callback is an ordinary
  32. C function that is called from within the TCP/IP code. Every callback
  33. function is passed the current TCP or UDP connection state as an
  34. argument. Also, in order to be able to keep program specific state,
  35. the callback functions are called with a program specified argument
  36. that is independent of the TCP/IP state.
  37. The function for setting the application connection state is:
  38. - void tcp_arg(struct tcp_pcb *pcb, void *arg)
  39. Specifies the program specific state that should be passed to all
  40. other callback functions. The "pcb" argument is the current TCP
  41. connection control block, and the "arg" argument is the argument
  42. that will be passed to the callbacks.
  43. --- TCP connection setup
  44. The functions used for setting up connections is similar to that of
  45. the sequential API and of the BSD socket API. A new TCP connection
  46. identifier (i.e., a protocol control block - PCB) is created with the
  47. tcp_new() function. This PCB can then be either set to listen for new
  48. incoming connections or be explicitly connected to another host.
  49. - struct tcp_pcb *tcp_new(void)
  50. Creates a new connection identifier (PCB). If memory is not
  51. available for creating the new pcb, NULL is returned.
  52. - err_t tcp_bind(struct tcp_pcb *pcb, struct ip_addr *ipaddr,
  53. u16_t port)
  54. Binds the pcb to a local IP address and port number. The IP address
  55. can be specified as IP_ADDR_ANY in order to bind the connection to
  56. all local IP addresses.
  57. If another connection is bound to the same port, the function will
  58. return ERR_USE, otherwise ERR_OK is returned.
  59. - struct tcp_pcb *tcp_listen(struct tcp_pcb *pcb)
  60. Commands a pcb to start listening for incoming connections. When an
  61. incoming connection is accepted, the function specified with the
  62. tcp_accept() function will be called. The pcb will have to be bound
  63. to a local port with the tcp_bind() function.
  64. The tcp_listen() function returns a new connection identifier, and
  65. the one passed as an argument to the function will be
  66. deallocated. The reason for this behavior is that less memory is
  67. needed for a connection that is listening, so tcp_listen() will
  68. reclaim the memory needed for the original connection and allocate a
  69. new smaller memory block for the listening connection.
  70. tcp_listen() may return NULL if no memory was available for the
  71. listening connection. If so, the memory associated with the pcb
  72. passed as an argument to tcp_listen() will not be deallocated.
  73. - struct tcp_pcb *tcp_listen_with_backlog(struct tcp_pcb *pcb, u8_t backlog)
  74. Same as tcp_listen, but limits the number of outstanding connections
  75. in the listen queue to the value specified by the backlog argument.
  76. To use it, your need to set TCP_LISTEN_BACKLOG=1 in your lwipopts.h.
  77. - void tcp_accepted(struct tcp_pcb *pcb)
  78. Inform lwIP that an incoming connection has been accepted. This would
  79. usually be called from the accept callback. This allows lwIP to perform
  80. housekeeping tasks, such as allowing further incoming connections to be
  81. queued in the listen backlog.
  82. - void tcp_accept(struct tcp_pcb *pcb,
  83. err_t (* accept)(void *arg, struct tcp_pcb *newpcb,
  84. err_t err))
  85. Specified the callback function that should be called when a new
  86. connection arrives on a listening connection.
  87. - err_t tcp_connect(struct tcp_pcb *pcb, struct ip_addr *ipaddr,
  88. u16_t port, err_t (* connected)(void *arg,
  89. struct tcp_pcb *tpcb,
  90. err_t err));
  91. Sets up the pcb to connect to the remote host and sends the
  92. initial SYN segment which opens the connection.
  93. The tcp_connect() function returns immediately; it does not wait for
  94. the connection to be properly setup. Instead, it will call the
  95. function specified as the fourth argument (the "connected" argument)
  96. when the connection is established. If the connection could not be
  97. properly established, either because the other host refused the
  98. connection or because the other host didn't answer, the "connected"
  99. function will be called with an the "err" argument set accordingly.
  100. The tcp_connect() function can return ERR_MEM if no memory is
  101. available for enqueueing the SYN segment. If the SYN indeed was
  102. enqueued successfully, the tcp_connect() function returns ERR_OK.
  103. --- Sending TCP data
  104. TCP data is sent by enqueueing the data with a call to
  105. tcp_write(). When the data is successfully transmitted to the remote
  106. host, the application will be notified with a call to a specified
  107. callback function.
  108. - err_t tcp_write(struct tcp_pcb *pcb, void *dataptr, u16_t len,
  109. u8_t copy)
  110. Enqueues the data pointed to by the argument dataptr. The length of
  111. the data is passed as the len parameter. The copy argument is either
  112. 0 or 1 and indicates whether the new memory should be allocated for
  113. the data to be copied into. If the argument is 0, no new memory
  114. should be allocated and the data should only be referenced by
  115. pointer.
  116. The tcp_write() function will fail and return ERR_MEM if the length
  117. of the data exceeds the current send buffer size or if the length of
  118. the queue of outgoing segment is larger than the upper limit defined
  119. in lwipopts.h. The number of bytes available in the output queue can
  120. be retrieved with the tcp_sndbuf() function.
  121. The proper way to use this function is to call the function with at
  122. most tcp_sndbuf() bytes of data. If the function returns ERR_MEM,
  123. the application should wait until some of the currently enqueued
  124. data has been successfully received by the other host and try again.
  125. - void tcp_sent(struct tcp_pcb *pcb,
  126. err_t (* sent)(void *arg, struct tcp_pcb *tpcb,
  127. u16_t len))
  128. Specifies the callback function that should be called when data has
  129. successfully been received (i.e., acknowledged) by the remote
  130. host. The len argument passed to the callback function gives the
  131. amount bytes that was acknowledged by the last acknowledgment.
  132. --- Receiving TCP data
  133. TCP data reception is callback based - an application specified
  134. callback function is called when new data arrives. When the
  135. application has taken the data, it has to call the tcp_recved()
  136. function to indicate that TCP can advertise increase the receive
  137. window.
  138. - void tcp_recv(struct tcp_pcb *pcb,
  139. err_t (* recv)(void *arg, struct tcp_pcb *tpcb,
  140. struct pbuf *p, err_t err))
  141. Sets the callback function that will be called when new data
  142. arrives. The callback function will be passed a NULL pbuf to
  143. indicate that the remote host has closed the connection. If
  144. there are no errors and the callback function is to return
  145. ERR_OK, then it must free the pbuf. Otherwise, it must not
  146. free the pbuf so that lwIP core code can store it.
  147. - void tcp_recved(struct tcp_pcb *pcb, u16_t len)
  148. Must be called when the application has received the data. The len
  149. argument indicates the length of the received data.
  150. --- Application polling
  151. When a connection is idle (i.e., no data is either transmitted or
  152. received), lwIP will repeatedly poll the application by calling a
  153. specified callback function. This can be used either as a watchdog
  154. timer for killing connections that have stayed idle for too long, or
  155. as a method of waiting for memory to become available. For instance,
  156. if a call to tcp_write() has failed because memory wasn't available,
  157. the application may use the polling functionality to call tcp_write()
  158. again when the connection has been idle for a while.
  159. - void tcp_poll(struct tcp_pcb *pcb, u8_t interval,
  160. err_t (* poll)(void *arg, struct tcp_pcb *tpcb))
  161. Specifies the polling interval and the callback function that should
  162. be called to poll the application. The interval is specified in
  163. number of TCP coarse grained timer shots, which typically occurs
  164. twice a second. An interval of 10 means that the application would
  165. be polled every 5 seconds.
  166. --- Closing and aborting connections
  167. - err_t tcp_close(struct tcp_pcb *pcb)
  168. Closes the connection. The function may return ERR_MEM if no memory
  169. was available for closing the connection. If so, the application
  170. should wait and try again either by using the acknowledgment
  171. callback or the polling functionality. If the close succeeds, the
  172. function returns ERR_OK.
  173. The pcb is deallocated by the TCP code after a call to tcp_close().
  174. - void tcp_abort(struct tcp_pcb *pcb)
  175. Aborts the connection by sending a RST (reset) segment to the remote
  176. host. The pcb is deallocated. This function never fails.
  177. If a connection is aborted because of an error, the application is
  178. alerted of this event by the err callback. Errors that might abort a
  179. connection are when there is a shortage of memory. The callback
  180. function to be called is set using the tcp_err() function.
  181. - void tcp_err(struct tcp_pcb *pcb, void (* err)(void *arg,
  182. err_t err))
  183. The error callback function does not get the pcb passed to it as a
  184. parameter since the pcb may already have been deallocated.
  185. --- Lower layer TCP interface
  186. TCP provides a simple interface to the lower layers of the
  187. system. During system initialization, the function tcp_init() has
  188. to be called before any other TCP function is called. When the system
  189. is running, the two timer functions tcp_fasttmr() and tcp_slowtmr()
  190. must be called with regular intervals. The tcp_fasttmr() should be
  191. called every TCP_FAST_INTERVAL milliseconds (defined in tcp.h) and
  192. tcp_slowtmr() should be called every TCP_SLOW_INTERVAL milliseconds.
  193. --- UDP interface
  194. The UDP interface is similar to that of TCP, but due to the lower
  195. level of complexity of UDP, the interface is significantly simpler.
  196. - struct udp_pcb *udp_new(void)
  197. Creates a new UDP pcb which can be used for UDP communication. The
  198. pcb is not active until it has either been bound to a local address
  199. or connected to a remote address.
  200. - void udp_remove(struct udp_pcb *pcb)
  201. Removes and deallocates the pcb.
  202. - err_t udp_bind(struct udp_pcb *pcb, struct ip_addr *ipaddr,
  203. u16_t port)
  204. Binds the pcb to a local address. The IP-address argument "ipaddr"
  205. can be IP_ADDR_ANY to indicate that it should listen to any local IP
  206. address. The function currently always return ERR_OK.
  207. - err_t udp_connect(struct udp_pcb *pcb, struct ip_addr *ipaddr,
  208. u16_t port)
  209. Sets the remote end of the pcb. This function does not generate any
  210. network traffic, but only set the remote address of the pcb.
  211. - err_t udp_disconnect(struct udp_pcb *pcb)
  212. Remove the remote end of the pcb. This function does not generate
  213. any network traffic, but only removes the remote address of the pcb.
  214. - err_t udp_send(struct udp_pcb *pcb, struct pbuf *p)
  215. Sends the pbuf p. The pbuf is not deallocated.
  216. - void udp_recv(struct udp_pcb *pcb,
  217. void (* recv)(void *arg, struct udp_pcb *upcb,
  218. struct pbuf *p,
  219. struct ip_addr *addr,
  220. u16_t port),
  221. void *recv_arg)
  222. Specifies a callback function that should be called when a UDP
  223. datagram is received.
  224. --- System initalization
  225. A truly complete and generic sequence for initializing the lwip stack
  226. cannot be given because it depends on the build configuration (lwipopts.h)
  227. and additional initializations for your runtime environment (e.g. timers).
  228. We can give you some idea on how to proceed when using the raw API.
  229. We assume a configuration using a single Ethernet netif and the
  230. UDP and TCP transport layers, IPv4 and the DHCP client.
  231. Call these functions in the order of appearance:
  232. - stats_init()
  233. Clears the structure where runtime statistics are gathered.
  234. - sys_init()
  235. Not of much use since we set the NO_SYS 1 option in lwipopts.h,
  236. to be called for easy configuration changes.
  237. - mem_init()
  238. Initializes the dynamic memory heap defined by MEM_SIZE.
  239. - memp_init()
  240. Initializes the memory pools defined by MEMP_NUM_x.
  241. - pbuf_init()
  242. Initializes the pbuf memory pool defined by PBUF_POOL_SIZE.
  243. - etharp_init()
  244. Initializes the ARP table and queue.
  245. Note: you must call etharp_tmr at a ARP_TMR_INTERVAL (5 seconds) regular interval
  246. after this initialization.
  247. - ip_init()
  248. Doesn't do much, it should be called to handle future changes.
  249. - udp_init()
  250. Clears the UDP PCB list.
  251. - tcp_init()
  252. Clears the TCP PCB list and clears some internal TCP timers.
  253. Note: you must call tcp_fasttmr() and tcp_slowtmr() at the
  254. predefined regular intervals after this initialization.
  255. - netif_add(struct netif *netif, struct ip_addr *ipaddr,
  256. struct ip_addr *netmask, struct ip_addr *gw,
  257. void *state, err_t (* init)(struct netif *netif),
  258. err_t (* input)(struct pbuf *p, struct netif *netif))
  259. Adds your network interface to the netif_list. Allocate a struct
  260. netif and pass a pointer to this structure as the first argument.
  261. Give pointers to cleared ip_addr structures when using DHCP,
  262. or fill them with sane numbers otherwise. The state pointer may be NULL.
  263. The init function pointer must point to a initialization function for
  264. your ethernet netif interface. The following code illustrates it's use.
  265. err_t netif_if_init(struct netif *netif)
  266. {
  267. u8_t i;
  268. for(i = 0; i < ETHARP_HWADDR_LEN; i++) netif->hwaddr[i] = some_eth_addr[i];
  269. init_my_eth_device();
  270. return ERR_OK;
  271. }
  272. For ethernet drivers, the input function pointer must point to the lwip
  273. function ethernet_input() declared in "netif/etharp.h". Other drivers
  274. must use ip_input() declared in "lwip/ip.h".
  275. - netif_set_default(struct netif *netif)
  276. Registers the default network interface.
  277. - netif_set_up(struct netif *netif)
  278. When the netif is fully configured this function must be called.
  279. - dhcp_start(struct netif *netif)
  280. Creates a new DHCP client for this interface on the first call.
  281. Note: you must call dhcp_fine_tmr() and dhcp_coarse_tmr() at
  282. the predefined regular intervals after starting the client.
  283. You can peek in the netif->dhcp struct for the actual DHCP status.
  284. --- Optimalization hints
  285. The first thing you want to optimize is the lwip_standard_checksum()
  286. routine from src/core/inet.c. You can override this standard
  287. function with the #define LWIP_CHKSUM <your_checksum_routine>.
  288. There are C examples given in inet.c or you might want to
  289. craft an assembly function for this. RFC1071 is a good
  290. introduction to this subject.
  291. Other significant improvements can be made by supplying
  292. assembly or inline replacements for htons() and htonl()
  293. if you're using a little-endian architecture.
  294. #define LWIP_PLATFORM_BYTESWAP 1
  295. #define LWIP_PLATFORM_HTONS(x) <your_htons>
  296. #define LWIP_PLATFORM_HTONL(x) <your_htonl>
  297. Check your network interface driver if it reads at
  298. a higher speed than the maximum wire-speed. If the
  299. hardware isn't serviced frequently and fast enough
  300. buffer overflows are likely to occur.
  301. E.g. when using the cs8900 driver, call cs8900if_service(ethif)
  302. as frequently as possible. When using an RTOS let the cs8900 interrupt
  303. wake a high priority task that services your driver using a binary
  304. semaphore or event flag. Some drivers might allow additional tuning
  305. to match your application and network.
  306. For a production release it is recommended to set LWIP_STATS to 0.
  307. Note that speed performance isn't influenced much by simply setting
  308. high values to the memory options.