diff options
Diffstat (limited to 'lwip/doc/ppp.txt')
| -rw-r--r-- | lwip/doc/ppp.txt | 529 |
1 files changed, 529 insertions, 0 deletions
diff --git a/lwip/doc/ppp.txt b/lwip/doc/ppp.txt new file mode 100644 index 0000000..8b88b3a --- /dev/null +++ b/lwip/doc/ppp.txt @@ -0,0 +1,529 @@ +PPP interface for lwIP + +Author: Sylvain Rochet + +Table of Contents: + +1 - Supported PPP protocols and features +2 - Raw API PPP example for all protocols +3 - PPPoS input path (raw API, IRQ safe API, TCPIP API) +4 - Thread safe PPP API (PPPAPI) +5 - Notify phase callback (PPP_NOTIFY_PHASE) +6 - Upgrading from lwIP <= 1.4.x to lwIP >= 2.0.x + + + +1 Supported PPP protocols and features +====================================== + +Supported Low level protocols: +* PPP over serial using HDLC-like framing, such as wired dialup modems + or mobile telecommunications GPRS/EDGE/UMTS/HSPA+/LTE modems +* PPP over Ethernet, such as xDSL modems +* PPP over L2TP (Layer 2 Tunneling Protocol) LAC (L2TP Access Concentrator), + IP tunnel over UDP, such as VPN access + +Supported auth protocols: +* PAP, Password Authentication Protocol +* CHAP, Challenge-Handshake Authentication Protocol, also known as CHAP-MD5 +* MSCHAPv1, Microsoft version of CHAP, version 1 +* MSCHAPv2, Microsoft version of CHAP, version 2 +* EAP, Extensible Authentication Protocol + +Supported address protocols: +* IPCP, IP Control Protocol, IPv4 addresses negotiation +* IP6CP, IPv6 Control Protocol, IPv6 link-local addresses negotiation + +Supported encryption protocols: +* MPPE, Microsoft Point-to-Point Encryption + +Supported compression or miscellaneous protocols, for serial links only: +* PFC, Protocol Field Compression +* ACFC, Address-and-Control-Field-Compression +* ACCM, Asynchronous-Control-Character-Map +* VJ, Van Jacobson TCP/IP Header Compression + + + +2 Raw API PPP example for all protocols +======================================= + +As usual, raw API for lwIP means the lightweight API which *MUST* only be used +for NO_SYS=1 systems or called inside lwIP core thread for NO_SYS=0 systems. + +/* + * Globals + * ======= + */ + +/* The PPP control block */ +ppp_pcb *ppp; + +/* The PPP IP interface */ +struct netif ppp_netif; + + +/* + * PPP status callback + * =================== + * + * PPP status callback is called on PPP status change (up, down, …) from lwIP + * core thread + */ + +/* PPP status callback example */ +static void status_cb(ppp_pcb *pcb, int err_code, void *ctx) { + struct netif *pppif = ppp_netif(pcb); + LWIP_UNUSED_ARG(ctx); + + switch(err_code) { + case PPPERR_NONE: { +#if LWIP_DNS + const ip_addr_t *ns; +#endif /* LWIP_DNS */ + printf("status_cb: Connected\n"); +#if PPP_IPV4_SUPPORT + printf(" our_ipaddr = %s\n", ipaddr_ntoa(&pppif->ip_addr)); + printf(" his_ipaddr = %s\n", ipaddr_ntoa(&pppif->gw)); + printf(" netmask = %s\n", ipaddr_ntoa(&pppif->netmask)); +#if LWIP_DNS + ns = dns_getserver(0); + printf(" dns1 = %s\n", ipaddr_ntoa(ns)); + ns = dns_getserver(1); + printf(" dns2 = %s\n", ipaddr_ntoa(ns)); +#endif /* LWIP_DNS */ +#endif /* PPP_IPV4_SUPPORT */ +#if PPP_IPV6_SUPPORT + printf(" our6_ipaddr = %s\n", ip6addr_ntoa(netif_ip6_addr(pppif, 0))); +#endif /* PPP_IPV6_SUPPORT */ + break; + } + case PPPERR_PARAM: { + printf("status_cb: Invalid parameter\n"); + break; + } + case PPPERR_OPEN: { + printf("status_cb: Unable to open PPP session\n"); + break; + } + case PPPERR_DEVICE: { + printf("status_cb: Invalid I/O device for PPP\n"); + break; + } + case PPPERR_ALLOC: { + printf("status_cb: Unable to allocate resources\n"); + break; + } + case PPPERR_USER: { + printf("status_cb: User interrupt\n"); + break; + } + case PPPERR_CONNECT: { + printf("status_cb: Connection lost\n"); + break; + } + case PPPERR_AUTHFAIL: { + printf("status_cb: Failed authentication challenge\n"); + break; + } + case PPPERR_PROTOCOL: { + printf("status_cb: Failed to meet protocol\n"); + break; + } + case PPPERR_PEERDEAD: { + printf("status_cb: Connection timeout\n"); + break; + } + case PPPERR_IDLETIMEOUT: { + printf("status_cb: Idle Timeout\n"); + break; + } + case PPPERR_CONNECTTIME: { + printf("status_cb: Max connect time reached\n"); + break; + } + case PPPERR_LOOPBACK: { + printf("status_cb: Loopback detected\n"); + break; + } + default: { + printf("status_cb: Unknown error code %d\n", err_code); + break; + } + } + +/* + * This should be in the switch case, this is put outside of the switch + * case for example readability. + */ + + if (err_code == PPPERR_NONE) { + return; + } + + /* ppp_close() was previously called, don't reconnect */ + if (err_code == PPPERR_USER) { + /* ppp_free(); -- can be called here */ + return; + } + + /* + * Try to reconnect in 30 seconds, if you need a modem chatscript you have + * to do a much better signaling here ;-) + */ + ppp_connect(pcb, 30); + /* OR ppp_listen(pcb); */ +} + + +/* + * Creating a new PPPoS session + * ============================ + * + * In lwIP, PPPoS is not PPPoSONET, in lwIP PPPoS is PPPoSerial. + */ + +#include "netif/ppp/pppos.h" + +/* + * PPPoS serial output callback + * + * ppp_pcb, PPP control block + * data, buffer to write to serial port + * len, length of the data buffer + * ctx, optional user-provided callback context pointer + * + * Return value: len if write succeed + */ +static u32_t output_cb(ppp_pcb *pcb, u8_t *data, u32_t len, void *ctx) { + return uart_write(UART, data, len); +} + +/* + * Create a new PPPoS interface + * + * ppp_netif, netif to use for this PPP link, i.e. PPP IP interface + * output_cb, PPPoS serial output callback + * status_cb, PPP status callback, called on PPP status change (up, down, …) + * ctx_cb, optional user-provided callback context pointer + */ +ppp = pppos_create(&ppp_netif, + output_cb, status_cb, ctx_cb); + + +/* + * Creating a new PPPoE session + * ============================ + */ + +#include "netif/ppp/pppoe.h" + +/* + * Create a new PPPoE interface + * + * ppp_netif, netif to use for this PPP link, i.e. PPP IP interface + * ethif, already existing and setup Ethernet interface to use + * service_name, PPPoE service name discriminator (not supported yet) + * concentrator_name, PPPoE concentrator name discriminator (not supported yet) + * status_cb, PPP status callback, called on PPP status change (up, down, …) + * ctx_cb, optional user-provided callback context pointer + */ +ppp = pppoe_create(&ppp_netif, + ðif, + service_name, concentrator_name, + status_cb, ctx_cb); + + +/* + * Creating a new PPPoL2TP session + * =============================== + */ + +#include "netif/ppp/pppol2tp.h" + +/* + * Create a new PPPoL2TP interface + * + * ppp_netif, netif to use for this PPP link, i.e. PPP IP interface + * netif, optional already existing and setup output netif, necessary if you + * want to set this interface as default route to settle the chicken + * and egg problem with VPN links + * ipaddr, IP to connect to + * port, UDP port to connect to (usually 1701) + * secret, L2TP secret to use + * secret_len, size in bytes of the L2TP secret + * status_cb, PPP status callback, called on PPP status change (up, down, …) + * ctx_cb, optional user-provided callback context pointer + */ +ppp = pppol2tp_create(&ppp_netif, + struct netif *netif, ip_addr_t *ipaddr, u16_t port, + u8_t *secret, u8_t secret_len, + ppp_link_status_cb_fn link_status_cb, void *ctx_cb); + + +/* + * Initiate PPP client connection + * ============================== + */ + +/* Set this interface as default route */ +ppp_set_default(ppp); + +/* + * Basic PPP client configuration. Can only be set if PPP session is in the + * dead state (i.e. disconnected). We don't need to provide thread-safe + * equivalents through PPPAPI because those helpers are only changing + * structure members while session is inactive for lwIP core. Configuration + * only need to be done once. + */ + +/* Ask the peer for up to 2 DNS server addresses. */ +ppp_set_usepeerdns(ppp, 1); + +/* Auth configuration, this is pretty self-explanatory */ +ppp_set_auth(ppp, PPPAUTHTYPE_ANY, "login", "password"); + +/* + * Initiate PPP negotiation, without waiting (holdoff=0), can only be called + * if PPP session is in the dead state (i.e. disconnected). + */ +u16_t holdoff = 0; +ppp_connect(ppp, holdoff); + + +/* + * Initiate PPP server listener + * ============================ + */ + +/* + * Basic PPP server configuration. Can only be set if PPP session is in the + * dead state (i.e. disconnected). We don't need to provide thread-safe + * equivalents through PPPAPI because those helpers are only changing + * structure members while session is inactive for lwIP core. Configuration + * only need to be done once. + */ +ip4_addr_t addr; + +/* Set our address */ +IP4_ADDR(&addr, 192,168,0,1); +ppp_set_ipcp_ouraddr(ppp, &addr); + +/* Set peer(his) address */ +IP4_ADDR(&addr, 192,168,0,2); +ppp_set_ipcp_hisaddr(ppp, &addr); + +/* Set primary DNS server */ +IP4_ADDR(&addr, 192,168,10,20); +ppp_set_ipcp_dnsaddr(ppp, 0, &addr); + +/* Set secondary DNS server */ +IP4_ADDR(&addr, 192,168,10,21); +ppp_set_ipcp_dnsaddr(ppp, 1, &addr); + +/* Auth configuration, this is pretty self-explanatory */ +ppp_set_auth(ppp, PPPAUTHTYPE_ANY, "login", "password"); + +/* Require peer to authenticate */ +ppp_set_auth_required(ppp, 1); + +/* + * Only for PPPoS, the PPP session should be up and waiting for input. + * + * Note: for PPPoS, ppp_connect() and ppp_listen() are actually the same thing. + * The listen call is meant for future support of PPPoE and PPPoL2TP server + * mode, where we will need to negotiate the incoming PPPoE session or L2TP + * session before initiating PPP itself. We need this call because there is + * two passive modes for PPPoS, ppp_set_passive and ppp_set_silent. + */ +ppp_set_silent(pppos, 1); + +/* + * Initiate PPP listener (i.e. wait for an incoming connection), can only + * be called if PPP session is in the dead state (i.e. disconnected). + */ +ppp_listen(ppp); + + +/* + * Closing PPP connection + * ====================== + */ + +/* + * Initiate the end of the PPP session, without carrier lost signal + * (nocarrier=0), meaning a clean shutdown of PPP protocols. + * You can call this function at anytime. + */ +u8_t nocarrier = 0; +ppp_close(ppp, nocarrier); +/* + * Then you must wait your status_cb() to be called, it may takes from a few + * seconds to several tens of seconds depending on the current PPP state. + */ + +/* + * Freeing a PPP connection + * ======================== + */ + +/* + * Free the PPP control block, can only be called if PPP session is in the + * dead state (i.e. disconnected). You need to call ppp_close() before. + */ +ppp_free(ppp); + + + +3 PPPoS input path (raw API, IRQ safe API, TCPIP API) +===================================================== + +Received data on serial port should be sent to lwIP using the pppos_input() +function or the pppos_input_tcpip() function. + +If NO_SYS is 1 and if PPP_INPROC_IRQ_SAFE is 0 (the default), pppos_input() +is not IRQ safe and then *MUST* only be called inside your main loop. + +Whatever the NO_SYS value, if PPP_INPROC_IRQ_SAFE is 1, pppos_input() is IRQ +safe and can be safely called from an interrupt context, using that is going +to reduce your need of buffer if pppos_input() is called byte after byte in +your rx serial interrupt. + +if NO_SYS is 0, the thread safe way outside an interrupt context is to use +the pppos_input_tcpip() function to pass input data to the lwIP core thread +using the TCPIP API. This is thread safe in all cases but you should avoid +passing data byte after byte because it uses heavy locking (mailbox) and it +allocates pbuf, better fill them ! + +if NO_SYS is 0 and if PPP_INPROC_IRQ_SAFE is 1, you may also use pppos_input() +from an RX thread, however pppos_input() is not thread safe by itself. You can +do that *BUT* you should NEVER call pppos_connect(), pppos_listen() and +ppp_free() if pppos_input() can still be running, doing this is NOT thread safe +at all. Using PPP_INPROC_IRQ_SAFE from an RX thread is discouraged unless you +really know what you are doing, your move ;-) + + +/* + * Fonction to call for received data + * + * ppp, PPP control block + * buffer, input buffer + * buffer_len, buffer length in bytes + */ +void pppos_input(ppp, buffer, buffer_len); + +or + +void pppos_input_tcpip(ppp, buffer, buffer_len); + + + +4 Thread safe PPP API (PPPAPI) +============================== + +There is a thread safe API for all corresponding ppp_* functions, you have to +enable LWIP_PPP_API in your lwipopts.h file, then see +include/netif/ppp/pppapi.h, this is actually pretty obvious. + + + +5 Notify phase callback (PPP_NOTIFY_PHASE) +========================================== + +Notify phase callback, enabled using the PPP_NOTIFY_PHASE config option, let +you configure a callback that is called on each PPP internal state change. +This is different from the status callback which only warns you about +up(running) and down(dead) events. + +Notify phase callback can be used, for example, to set a LED pattern depending +on the current phase of the PPP session. Here is a callback example which +tries to mimic what we usually see on xDSL modems while they are negotiating +the link, which should be self-explanatory: + +static void ppp_notify_phase_cb(ppp_pcb *pcb, u8_t phase, void *ctx) { + switch (phase) { + + /* Session is down (either permanently or briefly) */ + case PPP_PHASE_DEAD: + led_set(PPP_LED, LED_OFF); + break; + + /* We are between two sessions */ + case PPP_PHASE_HOLDOFF: + led_set(PPP_LED, LED_SLOW_BLINK); + break; + + /* Session just started */ + case PPP_PHASE_INITIALIZE: + led_set(PPP_LED, LED_FAST_BLINK); + break; + + /* Session is running */ + case PPP_PHASE_RUNNING: + led_set(PPP_LED, LED_ON); + break; + + default: + break; + } +} + + + +6 Upgrading from lwIP <= 1.4.x to lwIP >= 2.0.x +=============================================== + +PPP API was fully reworked between 1.4.x and 2.0.x releases. However porting +from previous lwIP version is pretty easy: + +* Previous PPP API used an integer to identify PPP sessions, we are now + using ppp_pcb* control block, therefore all functions changed from "int ppp" + to "ppp_pcb *ppp" + +* struct netif was moved outside the PPP structure, you have to provide a netif + for PPP interface in pppoX_create() functions + +* PPP session are not started automatically after you created them anymore, + you have to call ppp_connect(), this way you can configure the session before + starting it. + +* Previous PPP API used CamelCase, we are now using snake_case. + +* Previous PPP API mixed PPPoS and PPPoE calls, this isn't the case anymore, + PPPoS functions are now prefixed pppos_ and PPPoE functions are now prefixed + pppoe_, common functions are now prefixed ppp_. + +* New PPPERR_ error codes added, check you have all of them in your status + callback function + +* Only the following include files should now be used in user application: + #include "netif/ppp/pppapi.h" + #include "netif/ppp/pppos.h" + #include "netif/ppp/pppoe.h" + #include "netif/ppp/pppol2tp.h" + + Functions from ppp.h can be used, but you don't need to include this header + file as it is already included by above header files. + +* PPP_INPROC_OWNTHREAD was broken by design and was removed, you have to create + your own serial rx thread + +* PPP_INPROC_MULTITHREADED option was misnamed and confusing and was renamed + PPP_INPROC_IRQ_SAFE, please read the "PPPoS input path" documentation above + because you might have been fooled by that + +* If you used tcpip_callback_with_block() on ppp_ functions you may wish to use + the PPPAPI API instead. + +* ppp_sighup and ppp_close functions were merged using an optional argument + "nocarrier" on ppp_close. + +* DNS servers are now only remotely asked if LWIP_DNS is set and if + ppp_set_usepeerdns() is set to true, they are now automatically registered + using the dns_setserver() function so you don't need to do that in the PPP + callback anymore. + +* PPPoS does not use the SIO API anymore, as such it now requires a serial + output callback in place of sio_write + +* PPP_MAXIDLEFLAG is now in ms instead of jiffies |