Various Documentation Updates + bump version to SDK1.5.0-develop (#1220)
* minor cleanup of lwip+tinyusb docs, and bump sdk verison number to 1.5.0-develop * Update cyw43_arch docs for async_context_use * remove accidental copy of some comments
This commit is contained in:
Graham Sanderson
GitHub
parent
a916761e7d
commit
ab18927533
@ -3,10 +3,10 @@
|
||||
set(PICO_SDK_VERSION_MAJOR 1)
|
||||
# PICO_BUILD_DEFINE: PICO_SDK_VERSION_MINOR, SDK minor version number, type=int, group=pico_base
|
||||
# PICO_CMAKE_CONFIG: PICO_SDK_VERSION_MINOR, SDK minor version number, type=int, group=pico_base
|
||||
set(PICO_SDK_VERSION_MINOR 4)
|
||||
set(PICO_SDK_VERSION_MINOR 5)
|
||||
# PICO_BUILD_DEFINE: PICO_SDK_VERSION_REVISION, SDK version revision, type=int, group=pico_base
|
||||
# PICO_CMAKE_CONFIG: PICO_SDK_VERSION_REVISION, SDK version revision, type=int, group=pico_base
|
||||
set(PICO_SDK_VERSION_REVISION 1)
|
||||
set(PICO_SDK_VERSION_REVISION 0)
|
||||
# PICO_BUILD_DEFINE: PICO_SDK_VERSION_PRE_RELEASE_ID, optional SDK pre-release version identifier, type=string, group=pico_base
|
||||
# PICO_CMAKE_CONFIG: PICO_SDK_VERSION_PRE_RELEASE_ID, optional SDK pre-release version identifier, type=string, group=pico_base
|
||||
set(PICO_SDK_VERSION_PRE_RELEASE_ID develop)
|
||||
|
||||
@ -145,7 +145,7 @@ typedef struct async_when_pending_worker {
|
||||
#define ASYNC_CONTEXT_FLAG_POLLED 0x4
|
||||
|
||||
/*!
|
||||
* \brief Implementation of an async_context
|
||||
* \brief Implementation of an async_context type, providing methods common to that type
|
||||
* \ingroup pico_async_context
|
||||
*/
|
||||
typedef struct async_context_type {
|
||||
@ -166,6 +166,12 @@ typedef struct async_context_type {
|
||||
void (*deinit)(async_context_t *self);
|
||||
} async_context_type_t;
|
||||
|
||||
/*!
|
||||
* \brief Base structure type of all async_contexts. For details about its use, see \ref pico_async_context.
|
||||
* \ingroup pico_async_context
|
||||
*
|
||||
* Individual async_context_types with additional state, should contain this structure at the start.
|
||||
*/
|
||||
struct async_context {
|
||||
const async_context_type_t *type;
|
||||
async_when_pending_worker_t *when_pending_list;
|
||||
|
||||
@ -55,12 +55,28 @@ extern "C" {
|
||||
*
|
||||
* * \em 'poll' - This not multi-core/IRQ safe, and requires the user to call \ref cyw43_arch_poll periodically from their main loop
|
||||
* * \em 'thread_safe_background' - This is multi-core/thread/task safe, and maintenance of the driver and TCP/IP stack is handled automatically in the background
|
||||
* * \em 'freertos' - This is multi-core/thread/task safe, and uses a separate FreeRTOS task to handle lwIP and and driver work.
|
||||
*
|
||||
* As of right now, lwIP is the only supported TCP/IP stack, however the use of \c pico_cyw43_arch is intended to be independent of
|
||||
* the particular TCP/IP stack used (and possibly Bluetooth stack used) in the future. For this reason, the integration of lwIP
|
||||
* is handled in the base (\c pico_cyw43_arch) library based on the #define \ref CYW43_LWIP used by the \c cyw43_driver.
|
||||
*
|
||||
* Whilst you can use the \c pico_cyw43_arch library directly and specify \ref CYW$#_LWIP (and other defines) yourself, several
|
||||
* \note As of version 1.5.0 of the Raspberry Pi Pico SDK, the \c pico_cyw43_arch library no longer directly implements
|
||||
* the distinct behavioral abstractions. This is now handled by the more general \ref pico_async_context library. The
|
||||
* user facing behavior of pico_cyw43_arch has not changed as a result of this implementation detail, however pico_cyw43_arch
|
||||
* is now just a thin wrapper which creates an appropriate async_context and makes a simple call to add lwIP or cyw43_driver support
|
||||
* as appropriate. You are free to perform this context creation and adding of lwIP, cyw43_driver or indeed any other additional
|
||||
* future protocol/driver support to your async_context, however for now pico_cyw43_arch does still provide a few cyw43_ specific (i.e. Pico W)
|
||||
* APIs still for connection management, locking and GPIO interaction.
|
||||
*
|
||||
* \note The connection management APIs at least may be moved
|
||||
* to a more generic library in a future release. The locking methods are now backed by their \ref pico_async_context equivalents, and
|
||||
* those methods may be used interchangeably (see \ref cyw43_arch_lwip_begin, \ref cyw43_arch_lwip_end and \ref cyw43_arch_lwip_check for more details).
|
||||
*
|
||||
* \note For examples of creating of your own async_context and addition of \c cyw43_driver and \c lwIP support, please
|
||||
* refer to the specific source files \c cyw43_arch_poll.c, \c cyw43_arch_threadsafe_background.c and \c cyw43_arch_freertos.c.
|
||||
*
|
||||
* Whilst you can use the \c pico_cyw43_arch library directly and specify \ref CYW$#_LWIP (and other defines) yourself, several
|
||||
* other libraries are made available to the build which aggregate the defines and other dependencies for you:
|
||||
*
|
||||
* * \b pico_cyw43_arch_lwip_poll - For using the RAW lwIP API (in `NO_SYS=1` mode) without any background processing or multi-core/thread safety.
|
||||
@ -145,7 +161,7 @@ extern "C" {
|
||||
* which defaults to \c CYW43_COUNTRY_WORLDWIDE. Worldwide settings may not give the best performance; consider
|
||||
* setting PICO_CYW43_ARCH_DEFAULT_COUNTRY_CODE to a different value or calling \ref cyw43_arch_init_with_country
|
||||
*
|
||||
* By default this method initializes the cyw43_arch code's own \ref async_context by calling
|
||||
* By default this method initializes the cyw43_arch code's own async_context by calling
|
||||
* \ref cyw43_arch_init_default_async_context, however the user can specify use of their own async_context
|
||||
* by calling \ref cyw43_arch_set_async_context() before calling this method
|
||||
*
|
||||
@ -161,7 +177,7 @@ int cyw43_arch_init(void);
|
||||
* was enabled at build time). This method must be called prior to using any other \c pico_cyw43_arch,
|
||||
* \c cyw43_driver or lwIP functions.
|
||||
*
|
||||
* By default this method initializes the cyw43_arch code's own \ref async_context by calling
|
||||
* By default this method initializes the cyw43_arch code's own async_context by calling
|
||||
* \ref cyw43_arch_init_default_async_context, however the user can specify use of their own async_context
|
||||
* by calling \ref cyw43_arch_set_async_context() before calling this method
|
||||
*
|
||||
@ -202,7 +218,7 @@ async_context_t *cyw43_arch_async_context(void);
|
||||
void cyw43_arch_set_async_context(async_context_t *context);
|
||||
|
||||
/*!
|
||||
* \brief Initialize the default \ref async_context for the current cyw43_arch type
|
||||
* \brief Initialize the default async_context for the current cyw43_arch type
|
||||
* \ingroup pico_cyw43_arch
|
||||
*
|
||||
* This method initializes and returns a pointer to the static async_context associated
|
||||
@ -246,8 +262,13 @@ void cyw43_arch_wait_for_work_until(absolute_time_t until);
|
||||
* If you are using single-core polling only (pico_cyw43_arch_poll) then these calls are no-ops
|
||||
* anyway it is good practice to call them anyway where they are necessary.
|
||||
*
|
||||
* \note as of SDK release 1.5.0, this is now equivalent to calling \ref pico_async_context_acquire_lock_blocking
|
||||
* on the async_context associated with cyw43_arch and lwIP.
|
||||
*
|
||||
* \sa cyw43_arch_lwip_end
|
||||
* \sa cyw43_arch_lwip_protect
|
||||
* \sa async_context_acquire_lock_blocking
|
||||
* \sa cyw43_arch_async_context
|
||||
*/
|
||||
static inline void cyw43_arch_lwip_begin(void) {
|
||||
cyw43_thread_enter();
|
||||
@ -264,8 +285,13 @@ static inline void cyw43_arch_lwip_begin(void) {
|
||||
* If you are using single-core polling only (pico_cyw43_arch_poll) then these calls are no-ops
|
||||
* anyway it is good practice to call them anyway where they are necessary.
|
||||
*
|
||||
* \note as of SDK release 1.5.0, this is now equivalent to calling \ref async_context_release_lock
|
||||
* on the async_context associated with cyw43_arch and lwIP.
|
||||
*
|
||||
* \sa cyw43_arch_lwip_begin
|
||||
* \sa cyw43_arch_lwip_protect
|
||||
* \sa async_context_release_lock
|
||||
* \sa cyw43_arch_async_context
|
||||
*/
|
||||
static inline void cyw43_arch_lwip_end(void) {
|
||||
cyw43_thread_exit();
|
||||
@ -306,8 +332,13 @@ static inline int cyw43_arch_lwip_protect(int (*func)(void *param), void *param)
|
||||
* This method will assert in debug mode, if the above conditions are not met (i.e. it is not safe to
|
||||
* call into the lwIP API)
|
||||
*
|
||||
* \note as of SDK release 1.5.0, this is now equivalent to calling \ref async_context_lock_check
|
||||
* on the async_context associated with cyw43_arch and lwIP.
|
||||
*
|
||||
* \sa cyw43_arch_lwip_begin
|
||||
* \sa cyw43_arch_lwip_protect
|
||||
* \sa async_context_lock_check
|
||||
* \sa cyw43_arch_async_context
|
||||
*/
|
||||
|
||||
/*!
|
||||
|
||||
@ -1,32 +1,20 @@
|
||||
/**
|
||||
* \defgroup pico_lwip pico_lwip
|
||||
* \brief Wrapper libraries for <a href="https://savannah.nongnu.org/projects/lwip/lwIP">lwIP</a>
|
||||
* \brief Integration/wrapper libraries for <a href="https://savannah.nongnu.org/projects/lwip/lwIP">lwIP</a>
|
||||
* the documentation for which is <a href="https://www.nongnu.org/lwip/2_1_x/index.html">here</a>.
|
||||
*
|
||||
* The following libraries are provided that contain the equivalent lwIP functionality groups:
|
||||
* The main \c \b pico_lwip library itself aggregates the lwIP RAW API: \c \b pico_lwip_core, \c \b pico_lwip_core4, \c \b pico_lwip_core6, \c \b pico_lwip_api, \c \b pico_lwip_netif, \c \b pico_lwip_sixlowpan and \c \b pico_lwip_ppp.
|
||||
*
|
||||
* * \c \b pico_lwip_core -
|
||||
* * \c \b pico_lwip_core4 -
|
||||
* * \c \b pico_lwip_core6 -
|
||||
* * \c \b pico_lwip_netif -
|
||||
* * \c \b pico_lwip_sixlowpan -
|
||||
* * \c \b pico_lwip_ppp -
|
||||
* * \c \b pico_lwip_api -
|
||||
* If you wish to run in NO_SYS=1 mode, then you can link \c \b pico_lwip along with \ref pico_lwip_nosys.
|
||||
*
|
||||
* The following libraries are provided that contain the equivalent lwIP application support:
|
||||
* If you wish to run in NO_SYS=0 mode, then you can link \c \b pico_lwip with (for instance) \ref pico_lwip_freertos,
|
||||
* and also link in pico_lwip_api for the additional blocking/thread-safe APIs.
|
||||
*
|
||||
* * \c \b pico_lwip_snmp -
|
||||
* * \c \b pico_lwip_http -
|
||||
* * \c \b pico_lwip_makefsdata -
|
||||
* * \c \b pico_lwip_iperf -
|
||||
* * \c \b pico_lwip_smtp -
|
||||
* * \c \b pico_lwip_sntp -
|
||||
* * \c \b pico_lwip_mdns -
|
||||
* * \c \b pico_lwip_netbios -
|
||||
* * \c \b pico_lwip_tftp -
|
||||
* * \c \b pico_lwip_mbedtls -
|
||||
* * \c \b pico_lwip_mqtt -
|
||||
* Additionally you must link in \ref pico_lwip_arch unless you provide your own compiler bindings for lwIP.
|
||||
*
|
||||
* The SDK Provides a common set of functionality in \c \p pico_lwip which aggregates:
|
||||
* Additional individual pieces of lwIP functionality are available à la cart, by linking any of the libraries below.
|
||||
*
|
||||
* The following libraries are provided that contain exactly the equivalent lwIP functionality groups:
|
||||
*
|
||||
* * \c \b pico_lwip_core -
|
||||
* * \c \b pico_lwip_core4 -
|
||||
@ -34,12 +22,25 @@
|
||||
* * \c \b pico_lwip_netif -
|
||||
* * \c \b pico_lwip_sixlowpan -
|
||||
* * \c \b pico_lwip_ppp -
|
||||
* * \c \b pico_lwip_api -
|
||||
*
|
||||
* The following additional libraries are provided:
|
||||
* The following libraries are provided that contain exactly the equivalent lwIP application support:
|
||||
*
|
||||
* * \c \b pico_lwip - Aggregates the lwIP RAW API: \c \b pico_lwip_core, \c \b pico_lwip_core4, \c \b pico_lwip_core6, \c \b pico_lwip_api, \c \b pico_lwip_netif, \c \b pico_lwip_sixlowpan and \c \b pico_lwip_ppp. It does
|
||||
* not include \c \b pico_lwip_api, which requires NO_SYS=0. You should include the latter separately if you want it.
|
||||
* * \c \b pico_lwip_snmp -
|
||||
* * \c \b pico_lwip_http -
|
||||
* * \c \b pico_lwip_makefsdata -
|
||||
* * \c \b pico_lwip_iperf -
|
||||
* * \c \b pico_lwip_smtp -
|
||||
* * \c \b pico_lwip_sntp -
|
||||
* * \c \b pico_lwip_mdns -
|
||||
* * \c \b pico_lwip_netbios -
|
||||
* * \c \b pico_lwip_tftp -
|
||||
* * \c \b pico_lwip_mbedtls -
|
||||
* * \c \b pico_lwip_mqtt -
|
||||
*
|
||||
* * \c \b pico_lwip_arch - lwIP required compiler adapters. This is not included in \c \b pico_lwip in case you wish to replace them.
|
||||
* * \c \b pico_lwip_nosys - basic stub functions for NO_SYS mode.
|
||||
*/
|
||||
|
||||
/** \defgroup pico_lwip_arch pico_lwip_arch
|
||||
* \ingroup pico_lwip
|
||||
* \brief lwIP compiler adapters. This is not included by default in \c \b pico_lwip in case you wish to implement your own.
|
||||
*/
|
||||
|
||||
@ -14,8 +14,15 @@
|
||||
extern "C" {
|
||||
#endif
|
||||
|
||||
/** \file pico/lwip_freertos.h
|
||||
* \defgroup pico_lwip_freertos pico_lwip_freertos
|
||||
* \ingroup pico_lwip
|
||||
* \brief Glue library for integration lwIP in \c NO_SYS=0 mode with the SDK. Simple \c init and \c deinit
|
||||
* are all that is required to hook up lwIP (with full blocking API support) via an \ref async_context instance.
|
||||
*/
|
||||
|
||||
/*! \brief Initializes lwIP (NO_SYS=0 mode) support support for FreeRTOS using the provided async_context
|
||||
* \ingroup pico_lwip
|
||||
* \ingroup pico_lwip_freertos
|
||||
*
|
||||
* If the initialization succeeds, \ref lwip_freertos_deinit() can be called to shutdown lwIP support
|
||||
*
|
||||
@ -27,7 +34,7 @@ extern "C" {
|
||||
bool lwip_freertos_init(async_context_t *context);
|
||||
|
||||
/*! \brief De-initialize lwIP (NO_SYS=0 mode) support for FreeRTOS
|
||||
* \ingroup pico_lwip
|
||||
* \ingroup pico_lwip_freertos
|
||||
*
|
||||
* Note that since lwIP may only be initialized once, and doesn't itself provide a shutdown mechanism, lwIP
|
||||
* itself may still consume resources.
|
||||
|
||||
@ -14,18 +14,25 @@
|
||||
extern "C" {
|
||||
#endif
|
||||
|
||||
/** \file pico/lwip_nosys.h
|
||||
* \defgroup pico_lwip_nosys pico_lwip_nosys
|
||||
* \ingroup pico_lwip
|
||||
* \brief Glue library for integration lwIP in \c NO_SYS=1 mode with the SDK. Simple \c init and \c deinit
|
||||
* are all that is required to hook up lwIP via an \ref async_context instance.
|
||||
*/
|
||||
|
||||
/*! \brief Initializes lwIP (NO_SYS=1 mode) support support using the provided async_context
|
||||
* \ingroup pico_lwip
|
||||
*
|
||||
* If the initialization succeeds, \ref lwip_nosys_deinit() can be called to shutdown lwIP support
|
||||
*
|
||||
* \param context the async_context instance that provides the abstraction for handling asynchronous work.
|
||||
* \return true if the initialization succeeded
|
||||
* \ingroup pico_lwip_nosys
|
||||
*
|
||||
* If the initialization succeeds, \ref lwip_nosys_deinit() can be called to shutdown lwIP support
|
||||
*
|
||||
* \param context the async_context instance that provides the abstraction for handling asynchronous work.
|
||||
* \return true if the initialization succeeded
|
||||
*/
|
||||
bool lwip_nosys_init(async_context_t *context);
|
||||
|
||||
/*! \brief De-initialize lwIP (NO_SYS=1 mode) support
|
||||
* \ingroup pico_lwip
|
||||
* \ingroup pico_lwip_nosys
|
||||
*
|
||||
* Note that since lwIP may only be initialized once, and doesn't itself provide a shutdown mechanism, lwIP
|
||||
* itself may still consume resources
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
/**
|
||||
* \defgroup tinyusb_device tinyusb_device
|
||||
* \brief <a href="https://github.com/hathach/tinyusb">TinyUSB</a> Device-mode support for the RP2040
|
||||
* <a href="https://github.com/hathach/tinyusb">TinyUSB</a> Device-mode support for the RP2040. The TinyUSB documentation site can be found <a href="https://docs.tinyusb.org/en/latest/">here</a>.
|
||||
*
|
||||
* \defgroup tinyusb_host tinyusb_host
|
||||
* \brief <a href="https://github.com/hathach/tinyusb">TinyUSB</a> Host-mode support for the RP2040
|
||||
* <a href="https://github.com/hathach/tinyusb">TinyUSB</a> Host-mode support for the RP2040.
|
||||
*/
|
||||
|
||||
Loading…
Reference in New Issue
Block a user