documentation: rawapi: update to current lwIP design

*_init() -> lwip_init()
*tmr() -> sys_check_timeouts()
netif_set_link_up() / netif_up() clarification
updated netif_add() prototype
source code style fix in examples
This commit is contained in:
Sylvain Rochet 2015-09-21 23:19:18 +02:00
parent 74939c20c4
commit 6746f1d13c

View File

@ -303,17 +303,6 @@ function to be called is set using the tcp_err() function.
parameter since the pcb may already have been deallocated. parameter since the pcb may already have been deallocated.
--- Lower layer TCP interface
TCP provides a simple interface to the lower layers of the
system. During system initialization, the function tcp_init() has
to be called before any other TCP function is called. When the system
is running, the two timer functions tcp_fasttmr() and tcp_slowtmr()
must be called with regular intervals. The tcp_fasttmr() should be
called every TCP_FAST_INTERVAL milliseconds (defined in tcp.h) and
tcp_slowtmr() should be called every TCP_SLOW_INTERVAL milliseconds.
--- UDP interface --- UDP interface
The UDP interface is similar to that of TCP, but due to the lower The UDP interface is similar to that of TCP, but due to the lower
@ -365,8 +354,8 @@ level of complexity of UDP, the interface is significantly simpler.
--- System initalization --- System initalization
A truly complete and generic sequence for initializing the lwip stack A truly complete and generic sequence for initializing the lwip stack
cannot be given because it depends on the build configuration (lwipopts.h) cannot be given because it depends on additional initializations for
and additional initializations for your runtime environment (e.g. timers). your runtime environment (e.g. timers).
We can give you some idea on how to proceed when using the raw API. We can give you some idea on how to proceed when using the raw API.
We assume a configuration using a single Ethernet netif and the We assume a configuration using a single Ethernet netif and the
@ -374,51 +363,13 @@ UDP and TCP transport layers, IPv4 and the DHCP client.
Call these functions in the order of appearance: Call these functions in the order of appearance:
- stats_init() - lwip_init()
Clears the structure where runtime statistics are gathered. Initialize the lwIP stack and all of its subsystems.
- sys_init() - netif_add(struct netif *netif, const ip4_addr_t *ipaddr,
const ip4_addr_t *netmask, const ip4_addr_t *gw,
Not of much use since we set the NO_SYS 1 option in lwipopts.h, void *state, netif_init_fn init, netif_input_fn input)
to be called for easy configuration changes.
- mem_init()
Initializes the dynamic memory heap defined by MEM_SIZE.
- memp_init()
Initializes the memory pools defined by MEMP_NUM_x.
- pbuf_init()
Initializes the pbuf memory pool defined by PBUF_POOL_SIZE.
- etharp_init()
Initializes the ARP table and queue.
Note: you must call etharp_tmr at a ARP_TMR_INTERVAL (5 seconds) regular interval
after this initialization.
- ip_init()
Doesn't do much, it should be called to handle future changes.
- udp_init()
Clears the UDP PCB list.
- tcp_init()
Clears the TCP PCB list and clears some internal TCP timers.
Note: you must call tcp_fasttmr() and tcp_slowtmr() at the
predefined regular intervals after this initialization.
- netif_add(struct netif *netif, ip_addr_t *ipaddr,
ip_addr_t *netmask, ip_addr_t *gw,
void *state, err_t (* init)(struct netif *netif),
err_t (* input)(struct pbuf *p, struct netif *netif))
Adds your network interface to the netif_list. Allocate a struct Adds your network interface to the netif_list. Allocate a struct
netif and pass a pointer to this structure as the first argument. netif and pass a pointer to this structure as the first argument.
@ -432,7 +383,9 @@ Call these functions in the order of appearance:
{ {
u8_t i; u8_t i;
for(i = 0; i < ETHARP_HWADDR_LEN; i++) netif->hwaddr[i] = some_eth_addr[i]; for (i = 0; i < ETHARP_HWADDR_LEN; i++) {
netif->hwaddr[i] = some_eth_addr[i];
}
init_my_eth_device(); init_my_eth_device();
return ERR_OK; return ERR_OK;
} }
@ -445,18 +398,30 @@ Call these functions in the order of appearance:
Registers the default network interface. Registers the default network interface.
- netif_set_link_up(struct netif *netif)
This is the hardware link state; e.g. whether cable is plugged for wired
Ethernet interface. This function must be called even if you don't know
the current state. Having link up and link down events is optional but
DHCP and IPv6 discover benefit well from those events.
- netif_set_up(struct netif *netif) - netif_set_up(struct netif *netif)
When the netif is fully configured this function must be called. This is the administrative (= software) state of the netif, when the
netif is fully configured this function must be called.
- dhcp_start(struct netif *netif) - dhcp_start(struct netif *netif)
Creates a new DHCP client for this interface on the first call. Creates a new DHCP client for this interface on the first call.
Note: you must call dhcp_fine_tmr() and dhcp_coarse_tmr() at
the predefined regular intervals after starting the client.
You can peek in the netif->dhcp struct for the actual DHCP status. You can peek in the netif->dhcp struct for the actual DHCP status.
- sys_check_timeouts()
When the system is running, you have to periodically call
sys_check_timeouts() which will handle all timers for all protocols in
the stack; add this to your main loop or equivalent.
--- Optimalization hints --- Optimalization hints