scratch/lwip
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

PPP, PPPoS, renamed PPP_INPROC_MULTITHREADED to PPP_INPROC_IRQ_SAFE

Browse Source 
Follow-up of the #44565 bug fix, renamed the misnamed
PPP_INPROC_MULTITHREADED to PPP_INPROC_IRQ_SAFE because it is
IRQ safe but not thread safe.

Updated PPP documentation which now clearly state when and how
this feature can be used.
This commit is contained in:
Sylvain Rochet
2015-03-19 21:41:36 +01:00
parent 9eb900c448
commit ee752ab1ce
6 changed files with 68 additions and 79 deletions
Download Patch File Download Diff File Expand all files Collapse all files

48
doc/ppp.txt
View File

@@ -6,7 +6,7 @@ Table of Contents:
1 - Supported PPP protocols and features
2 - Raw API PPP example for all protocols
3 - PPPoS input path (raw API, thread safe API, TCPIP API)
3 - PPPoS input path (raw API, IRQ safe API, TCPIP API)
4 - Thread safe PPP API (PPPAPI)
5 - Upgrading from lwIP <= 1.4.x to lwIP >= 1.5.x
@@ -298,32 +298,34 @@ ppp_free(ppp);
3 PPPoS input path (raw API, thread safe API, TCPIP API)
========================================================
3 PPPoS input path (raw API, IRQ safe API, TCPIP API)
=====================================================
PPPoS requires a serial I/O SIO port (see include/lwip/sio.h).
Received data on serial port should be sent to lwIP using the pppos_input() or
pppos_input_sys() functions.
Received data on serial port should be sent to lwIP using the pppos_input()
function or the pppos_input_sys() function.
If PPP_INPROC_MULTITHREADED is 0 (the default), pppos_input() is not thread safe
and then *MUST* only be called inside the lwIP context. You should use that if
you are calling pppos_input() from your main loop context when NO_SYS=1.
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.
If PPP_INPROC_MULTITHREADED is 1, pppos_input() is thread safe and can be called
from a dedicated RX-thread or from interrupt context… *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. You should also avoid calling
pppos_input() if PPPoS session is not started yet.
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.
Using PPP_INPROC_MULTITHREADED is discouraged unless you really know what you
are doing, though it may greatly reduce your need of buffer if pppos_input() is
called byte after byte in your rx serial interrupt, your move ;-)
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 ;-)
Anyway, if you are using an OS (NO_SYS=0) and if PPP_INPROC_MULTITHREADED is 0,
you can use the pppos_input_tcpip() function to pass input data to the lwIP
core thread. 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 !
/*
* Fonction to call for received data
@@ -386,6 +388,10 @@ from previous lwIP version is pretty easy:
* 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.