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

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)

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;

src/rp2_common/pico_cyw43_arch/include/pico/cyw43_arch.h

@@ -55,11 +55,27 @@ 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.
  *
+ * \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:
  *
@@ -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
  */
 
 /*!

src/rp2_common/pico_lwip/doc.h

@@ -1,8 +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.
+ *
+ * If you wish to run in NO_SYS=1 mode, then you can link \c \b pico_lwip along with \ref pico_lwip_nosys.
+ *
+ * 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.
+ *
+ * Additionally you must link in \ref pico_lwip_arch unless you provide your own compiler bindings for lwIP.
+ *
+ * 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 -
@@ -12,7 +24,7 @@
  * * \c \b pico_lwip_ppp -
  * * \c \b pico_lwip_api -
  *
- * The following libraries are provided that contain the equivalent lwIP application support:
+ * The following libraries are provided that contain exactly the equivalent lwIP application support:
  *
  * * \c \b pico_lwip_snmp -
  * * \c \b pico_lwip_http -
@@ -26,20 +38,9 @@
  * * \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:
+ */
- *
+
- * * \c \b pico_lwip_core -
+/** \defgroup pico_lwip_arch pico_lwip_arch
- * * \c \b pico_lwip_core4 -
+ * \ingroup pico_lwip
- * * \c \b pico_lwip_core6 -
+ * \brief lwIP compiler adapters. This is not included by default in \c \b pico_lwip in case you wish to implement your own.
- * * \c \b pico_lwip_netif -
- * * \c \b pico_lwip_sixlowpan -
- * * \c \b pico_lwip_ppp -
- *
- * The following additional libraries are provided:
- *
- * * \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_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.
  */

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.

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
+*  \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);
 
 /*! \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

src/rp2_common/tinyusb/doc.h

@@ -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.
  */