diff --git a/pico_sdk_version.cmake b/pico_sdk_version.cmake index 63b3002..3d75a5c 100644 --- a/pico_sdk_version.cmake +++ b/pico_sdk_version.cmake @@ -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) diff --git a/src/rp2_common/pico_async_context/include/pico/async_context.h b/src/rp2_common/pico_async_context/include/pico/async_context.h index d9691a4..2b5d233 100644 --- a/src/rp2_common/pico_async_context/include/pico/async_context.h +++ b/src/rp2_common/pico_async_context/include/pico/async_context.h @@ -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; diff --git a/src/rp2_common/pico_cyw43_arch/include/pico/cyw43_arch.h b/src/rp2_common/pico_cyw43_arch/include/pico/cyw43_arch.h index 8518eb8..df6bab6 100644 --- a/src/rp2_common/pico_cyw43_arch/include/pico/cyw43_arch.h +++ b/src/rp2_common/pico_cyw43_arch/include/pico/cyw43_arch.h @@ -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 */ /*! diff --git a/src/rp2_common/pico_lwip/doc.h b/src/rp2_common/pico_lwip/doc.h index 33b15c1..0825fab 100644 --- a/src/rp2_common/pico_lwip/doc.h +++ b/src/rp2_common/pico_lwip/doc.h @@ -1,32 +1,20 @@ /** * \defgroup pico_lwip pico_lwip - * \brief Wrapper libraries for lwIP + * \brief Integration/wrapper libraries for lwIP + * the documentation for which is here. * - * 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. */ diff --git a/src/rp2_common/pico_lwip/include/pico/lwip_freertos.h b/src/rp2_common/pico_lwip/include/pico/lwip_freertos.h index cd04171..b1b9ab5 100644 --- a/src/rp2_common/pico_lwip/include/pico/lwip_freertos.h +++ b/src/rp2_common/pico_lwip/include/pico/lwip_freertos.h @@ -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. diff --git a/src/rp2_common/pico_lwip/include/pico/lwip_nosys.h b/src/rp2_common/pico_lwip/include/pico/lwip_nosys.h index 75cece3..cdde9ab 100644 --- a/src/rp2_common/pico_lwip/include/pico/lwip_nosys.h +++ b/src/rp2_common/pico_lwip/include/pico/lwip_nosys.h @@ -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 diff --git a/src/rp2_common/tinyusb/doc.h b/src/rp2_common/tinyusb/doc.h index 6c361e0..a9d8da5 100644 --- a/src/rp2_common/tinyusb/doc.h +++ b/src/rp2_common/tinyusb/doc.h @@ -1,7 +1,7 @@ /** * \defgroup tinyusb_device tinyusb_device - * \brief TinyUSB Device-mode support for the RP2040 + * TinyUSB Device-mode support for the RP2040. The TinyUSB documentation site can be found here. * * \defgroup tinyusb_host tinyusb_host - * \brief TinyUSB Host-mode support for the RP2040 + * TinyUSB Host-mode support for the RP2040. */