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 2023-02-06 15:07:37 -06:00 committed by GitHub
parent a916761e7d
commit ab18927533
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 97 additions and 45 deletions

View File

@ -3,10 +3,10 @@
set(PICO_SDK_VERSION_MAJOR 1) set(PICO_SDK_VERSION_MAJOR 1)
# PICO_BUILD_DEFINE: PICO_SDK_VERSION_MINOR, SDK minor version number, type=int, group=pico_base # 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 # 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_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 # 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_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 # 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) set(PICO_SDK_VERSION_PRE_RELEASE_ID develop)

View File

@ -145,7 +145,7 @@ typedef struct async_when_pending_worker {
#define ASYNC_CONTEXT_FLAG_POLLED 0x4 #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 * \ingroup pico_async_context
*/ */
typedef struct async_context_type { typedef struct async_context_type {
@ -166,6 +166,12 @@ typedef struct async_context_type {
void (*deinit)(async_context_t *self); void (*deinit)(async_context_t *self);
} async_context_type_t; } 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 { struct async_context {
const async_context_type_t *type; const async_context_type_t *type;
async_when_pending_worker_t *when_pending_list; async_when_pending_worker_t *when_pending_list;

View File

@ -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 '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 '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 * 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 * 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. * 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: * 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. * * \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 * 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 * 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 * \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 * 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, * 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. * \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 * \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 * 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); 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 * \ingroup pico_cyw43_arch
* *
* This method initializes and returns a pointer to the static async_context associated * 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 * 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. * 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_end
* \sa cyw43_arch_lwip_protect * \sa cyw43_arch_lwip_protect
* \sa async_context_acquire_lock_blocking
* \sa cyw43_arch_async_context
*/ */
static inline void cyw43_arch_lwip_begin(void) { static inline void cyw43_arch_lwip_begin(void) {
cyw43_thread_enter(); 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 * 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. * 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_begin
* \sa cyw43_arch_lwip_protect * \sa cyw43_arch_lwip_protect
* \sa async_context_release_lock
* \sa cyw43_arch_async_context
*/ */
static inline void cyw43_arch_lwip_end(void) { static inline void cyw43_arch_lwip_end(void) {
cyw43_thread_exit(); 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 * 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) * 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_begin
* \sa cyw43_arch_lwip_protect * \sa cyw43_arch_lwip_protect
* \sa async_context_lock_check
* \sa cyw43_arch_async_context
*/ */
/*! /*!

View File

@ -1,32 +1,20 @@
/** /**
* \defgroup pico_lwip pico_lwip * \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 - * If you wish to run in NO_SYS=1 mode, then you can link \c \b pico_lwip along with \ref pico_lwip_nosys.
* * \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 -
* *
* 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 - * Additionally you must link in \ref pico_lwip_arch unless you provide your own compiler bindings for lwIP.
* * \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 -
* *
* 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_core -
* * \c \b pico_lwip_core4 - * * \c \b pico_lwip_core4 -
@ -34,12 +22,25 @@
* * \c \b pico_lwip_netif - * * \c \b pico_lwip_netif -
* * \c \b pico_lwip_sixlowpan - * * \c \b pico_lwip_sixlowpan -
* * \c \b pico_lwip_ppp - * * \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 * * \c \b pico_lwip_snmp -
* 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_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.
*/ */

View File

@ -14,8 +14,15 @@
extern "C" { extern "C" {
#endif #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 /*! \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 * 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); bool lwip_freertos_init(async_context_t *context);
/*! \brief De-initialize lwIP (NO_SYS=0 mode) support for FreeRTOS /*! \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 * Note that since lwIP may only be initialized once, and doesn't itself provide a shutdown mechanism, lwIP
* itself may still consume resources. * itself may still consume resources.

View File

@ -14,18 +14,25 @@
extern "C" { extern "C" {
#endif #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 /*! \brief Initializes lwIP (NO_SYS=1 mode) support support using the provided async_context
* \ingroup pico_lwip * \ingroup pico_lwip_nosys
* *
* If the initialization succeeds, \ref lwip_nosys_deinit() can be called to shutdown lwIP support * 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. * \param context the async_context instance that provides the abstraction for handling asynchronous work.
* \return true if the initialization succeeded * \return true if the initialization succeeded
*/ */
bool lwip_nosys_init(async_context_t *context); bool lwip_nosys_init(async_context_t *context);
/*! \brief De-initialize lwIP (NO_SYS=1 mode) support /*! \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 * Note that since lwIP may only be initialized once, and doesn't itself provide a shutdown mechanism, lwIP
* itself may still consume resources * itself may still consume resources

View File

@ -1,7 +1,7 @@
/** /**
* \defgroup tinyusb_device tinyusb_device * \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 * \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.
*/ */