Zephyr change only: specify device and network configuration from dev…

…ice tree.

For Zephyr, it is now possible to specify the device and the network configurations in the device tree, rather than in the C structures passed to uDeviceOpen() and uNetworkInterfaceUp().  See port/platform/zephyr/README.md for how to do this.

ble/api/u_ble_cfg.h

@@ -44,6 +44,12 @@ extern "C" {
  * TYPES
  * -------------------------------------------------------------- */
 
+/* NOTE TO MAINTAINERS: if you change this enum you will need to
+ * change u-blox,ubxlib-network-ble.yaml over in
+ * /port/platform/zephyr/dts/bindings to match and you will also
+ * need to update the table in the Zephyr u_port_board_cfg.c file
+ * that maps string to enum.
+ */
 typedef enum {
     U_BLE_CFG_ROLE_DISABLED = 0, /**< BLE disabled. */
     U_BLE_CFG_ROLE_CENTRAL, /**< central only mode. */

cell/api/u_cell_module_type.h

@@ -39,7 +39,14 @@
  * TYPES
  * -------------------------------------------------------------- */
 
+/* IMPORTANT IMPORTANT IMPORTANT IMPORTANT IMPORTANT IMPORTANT
+ *
+ * NOTE TO MAINTAINERS: if you change this enum you will need to
+ * change u-blox,ubxlib-device-cellular.yaml over in
+ * /port/platform/zephyr/dts/bindings to match.
+ */
 /** The possible types of cellular module.
+ *
  * Note: if you add a new module type here, check the
  * U_CELL_PRIVATE_MODULE_xxx macros in u_cell_private.h
  * to see if they need updating and also update the
@@ -84,6 +91,10 @@ typedef enum {
     U_CELL_MODULE_TYPE_MAX_NUM
 } uCellModuleType_t;
 
+/* IMPORTANT IMPORTANT IMPORTANT IMPORTANT IMPORTANT IMPORTANT
+ * See note above.
+ */
+
 /** @}*/
 
 #endif // _U_CELL_MODULE_TYPES_H_

cell/api/u_cell_net.h

@@ -86,6 +86,10 @@ extern "C" {
 # define U_CELL_NET_MAX_APN_LENGTH_BYTES 101
 #endif
 
+/* NOTE TO MAINTAINERS: if you change this #define you will
+ * need to change u-blox,ubxlib-network-cell.yaml over in
+ * /port/platform/zephyr/dts/bindings to match.
+ */
 #ifndef U_CELL_NET_CONNECT_TIMEOUT_SECONDS
 /** The time in seconds allowed for a connection to complete.
  * This is a long time since, in the worst case, deep scan

common/device/api/u_device.h

@@ -34,6 +34,13 @@
  * (chip or module). These functions are generally used in conjunction
  * with those in the network API, see u_network.h for further information.
  * These functions are thread-safe.
+ *
+ * IMPORTANT NOTE TO MAINTAINERS: the structures and enums here are
+ * also written in .yaml form over in the files
+ * /port/platform/zephyr/dts/bindings/u-blox,ubxlib-device*.yaml for use
+ * with the Zephyr platform.  If you change anything here you must
+ * change those file to match and you may also need to change the
+ * code in the Zephyr u_port_board_cfg.c file that parses the values.
  */
 
 #ifdef __cplusplus
@@ -106,6 +113,12 @@ typedef int32_t uDeviceVersion_t;
  * know nothing about the network.
  */
 
+/* NOTE TO MAINTAINERS: if you change this structure you may
+ * need to change u-blox,ubxlib-device-xxx.yaml over in
+ * /port/platform/zephyr/dts/bindings to match and you may also
+ * need to change the code in the Zephyr u_port_board_cfg.c file
+ * that parses the values.
+ */
 /** UART transport configuration.
  */
 typedef struct {
@@ -164,6 +177,12 @@ typedef struct {
        this structure must be set to 1 or higher". */
 } uDeviceCfgVirtualSerial_t;
 
+/* NOTE TO MAINTAINERS: if you change this structure you may
+ * need to change u-blox,ubxlib-device-gnss.yaml over in
+ * /port/platform/zephyr/dts/bindings to match and you may also
+ * need to change the code in the Zephyr u_port_board_cfg.c file
+ * that parses the values.
+ */
 /** I2C transport configuration.
  */
 typedef struct {
@@ -200,6 +219,12 @@ typedef struct {
        this structure must be set to 1 or higher". */
 } uDeviceCfgI2c_t;
 
+/* NOTE TO MAINTAINERS: if you change this structure you may
+ * need to change u-blox,ubxlib-device-gnss.yaml over in
+ * /port/platform/zephyr/dts/bindings to match and you may also
+ * need to change the code in the Zephyr u_port_board_cfg.c file
+ * that parses the values.
+ */
 /** SPI transport configuration.
  */
 typedef struct {
@@ -223,8 +248,14 @@ typedef struct {
        this structure must be set to 1 or higher". */
 } uDeviceCfgSpi_t;
 
+/* NOTE TO MAINTAINERS: if you change this structure you will
+ * need to change u-blox,ubxlib-device-cellular.yaml over in
+ * /port/platform/zephyr/dts/bindings to match and you may also
+ * need to change the code in the Zephyr u_port_board_cfg.c file
+ * that parses the values.
+ */
 /** Cellular device configuration.
-*/
+ */
 typedef struct {
     uDeviceVersion_t version;  /**< Version of this structure; allow your
                                     compiler to initialise this to zero
@@ -259,6 +290,12 @@ typedef struct {
        of this structure must be set to 1 or higher". */
 } uDeviceCfgCell_t;
 
+/* NOTE TO MAINTAINERS: if you change this structure you will
+ * need to change u-blox,ubxlib-device-gnss.yaml over in
+ * /port/platform/zephyr/dts/bindings to match and you may also
+ * need to change the code in the Zephyr u_port_board_cfg.c file
+ * that parses the values.
+ */
 /** GNSS device configuration.
  */
 typedef struct {
@@ -309,6 +346,12 @@ typedef struct {
        this structure must be set to 1 or higher". */
 } uDeviceCfgGnss_t;
 
+/* NOTE TO MAINTAINERS: if you change this structure you will
+ * need to change u-blox,ubxlib-device-short-range.yaml over in
+ * /port/platform/zephyr/dts/bindings to match and you may also
+ * need to change the code in the Zephyr u_port_board_cfg.c file
+ * that parses the values.
+ */
 /** Short-range device configuration.
  */
 typedef struct {
@@ -330,6 +373,12 @@ typedef struct {
        this structure must be set to 1 or higher". */
 } uDeviceCfgShortRange_t;
 
+/* NOTE TO MAINTAINERS: if you change this structure you will
+ * need to change u-blox,ubxlib-device.yaml over in
+ * /port/platform/zephyr/dts/bindings to match and you may also
+ * need to change the code in the Zephyr u_port_board_cfg.c file
+ * that parses the values.
+ */
 /** The complete device configuration.
  */
 typedef struct {
@@ -349,6 +398,36 @@ typedef struct {
         uDeviceCfgSpi_t cfgSpi;
         uDeviceCfgVirtualSerial_t cfgVirtualSerial;
     } transportCfg;
+    const char *pCfgName; /**< A name for the configuration, only currently
+                               used by Zephyr to permit population of this
+                               structure from the device tree, in which
+                               case all of the other parameters in this
+                               structure may be overridden by a device
+                               tree node with this name; MUST point to
+                               a true constant string (the contents will
+                               not be copied by this code).  Otherwise,
+                               allow your compiler to initalise this
+                               to zero and it will be ignored.
+                               Zephyr users please consult
+                               /port/platform/zephyr/README.md for
+                               instructions on how to use the device
+                               tree to configure your ubxlib devices.
+                               NOTE TO ZEPHYR USERS: you only need to
+                               populate this field if you wish to use the
+                               device tree as your configuration source
+                               and you have more than one device of any
+                               given type in your device tree (e.g. two
+                               GNSS modules); otherwise you may leave
+                               it as NULL and the single device of any
+                               given device you happen to have in your
+                               device tree will be adopted.  You do,
+                               however, need to populate the
+                               deviceType member here if you have more
+                               than one ubxlib device in your device tree.
+                               IMPORTANT NOTE TO ZEPHYR USERS: if you get
+                               pCfgName wrong this will NOT throw an error,
+                               since pCfgName may be used for other
+                               purposes in future; you need to get it right. */
     /* This is the end of version 0 of this structure:
        should any fields be added to this structure in
        future they must be added AFTER this point and
@@ -401,7 +480,12 @@ int32_t uDeviceGetDefaults(uDeviceType_t deviceType,
 /** Open a device instance; if this function returns successfully
  * the device is powered-up and ready to be configured.
  *
- * @param[in] pDeviceCfg      device configuration, cannot be NULL.
+ * @param[in] pDeviceCfg      device configuration, should not be
+ *                            NULL unless you are using Zephyr and
+ *                            have provided a device configuration
+ *                            through the Zephyr device tree;
+ *                            see /port/platform/zephyr/README.md
+ *                             for instructions on how to do that.
  * @param[out] pDeviceHandle  a place to put the device handle;
  *                            cannot be NULL.
  * @return                    zero on success else a negative error

common/device/src/u_device.c

@@ -29,13 +29,16 @@
 #include "u_error_common.h"
 
 #include "u_port_os.h"
+#include "u_port_board_cfg.h"
 
 #include "u_device.h"
 #include "u_device_shared.h"
 
 #include "u_location.h"
 #include "u_location_shared.h"
 
+#include "u_network_shared.h"
+
 #include "u_device_private.h"
 #include "u_device_private_cell.h"
 #include "u_device_private_gnss.h"
@@ -254,46 +257,58 @@ int32_t uDeviceGetDefaults(uDeviceType_t deviceType,
 
 int32_t uDeviceOpen(const uDeviceCfg_t *pDeviceCfg, uDeviceHandle_t *pDeviceHandle)
 {
+    uDeviceCfg_t localDeviceCfg = {0};
     // Lock the API
     int32_t errorCode = uDeviceLock();
 
     uDeviceHandle_t deviceHandleCandidate = NULL;
 
     if (errorCode == 0 && pDeviceCfg != NULL) {
         errorCode = uDeviceCallback("open", (void *)pDeviceCfg->deviceType, NULL);
+        localDeviceCfg = *pDeviceCfg;
+    }
+
+    if (errorCode == 0) {
+        // Allow the device configuration from the board
+        // configuration of the platform to override what
+        // we were given; only used by Zephyr
+        errorCode = uPortBoardCfgDevice(&localDeviceCfg);
     }
 
     if (errorCode == 0) {
         errorCode = (int32_t) U_ERROR_COMMON_INVALID_PARAMETER;
-        if ((pDeviceCfg != NULL) && (pDeviceCfg->version == 0) && (pDeviceHandle != NULL)) {
-            switch (pDeviceCfg->deviceType) {
+        if ((pDeviceHandle != NULL) && (localDeviceCfg.version == 0)) {
+            switch (localDeviceCfg.deviceType) {
                 case U_DEVICE_TYPE_CELL:
-                    errorCode = uDevicePrivateCellAdd(pDeviceCfg, &deviceHandleCandidate);
+                    errorCode = uDevicePrivateCellAdd(&localDeviceCfg, &deviceHandleCandidate);
                     if (errorCode == 0) {
-                        U_DEVICE_INSTANCE(deviceHandleCandidate)->moduleType = pDeviceCfg->deviceCfg.cfgCell.moduleType;
+                        U_DEVICE_INSTANCE(deviceHandleCandidate)->moduleType = localDeviceCfg.deviceCfg.cfgCell.moduleType;
                     }
                     break;
                 case U_DEVICE_TYPE_GNSS:
-                    errorCode = uDevicePrivateGnssAdd(pDeviceCfg, &deviceHandleCandidate);
+                    errorCode = uDevicePrivateGnssAdd(&localDeviceCfg, &deviceHandleCandidate);
                     if (errorCode == 0) {
-                        U_DEVICE_INSTANCE(deviceHandleCandidate)->moduleType = pDeviceCfg->deviceCfg.cfgGnss.moduleType;
+                        U_DEVICE_INSTANCE(deviceHandleCandidate)->moduleType = localDeviceCfg.deviceCfg.cfgGnss.moduleType;
                     }
                     break;
                 case U_DEVICE_TYPE_SHORT_RANGE:
-                    errorCode = uDevicePrivateShortRangeAdd(pDeviceCfg, &deviceHandleCandidate);
+                    errorCode = uDevicePrivateShortRangeAdd(&localDeviceCfg, &deviceHandleCandidate);
                     if (errorCode == 0) {
-                        U_DEVICE_INSTANCE(deviceHandleCandidate)->moduleType = pDeviceCfg->deviceCfg.cfgSho.moduleType;
+                        U_DEVICE_INSTANCE(deviceHandleCandidate)->moduleType = localDeviceCfg.deviceCfg.cfgSho.moduleType;
                     }
                     break;
                 case U_DEVICE_TYPE_SHORT_RANGE_OPEN_CPU:
-                    errorCode = uDevicePrivateShortRangeOpenCpuAdd(pDeviceCfg, &deviceHandleCandidate);
+                    errorCode = uDevicePrivateShortRangeOpenCpuAdd(&localDeviceCfg, &deviceHandleCandidate);
                     if (errorCode == 0) {
-                        U_DEVICE_INSTANCE(deviceHandleCandidate)->moduleType = pDeviceCfg->deviceCfg.cfgSho.moduleType;
+                        U_DEVICE_INSTANCE(deviceHandleCandidate)->moduleType = localDeviceCfg.deviceCfg.cfgSho.moduleType;
                     }
                     break;
                 default:
                     break;
             }
+            if (errorCode == 0) {
+                U_DEVICE_INSTANCE(deviceHandleCandidate)->pCfgName = localDeviceCfg.pCfgName;
+            }
         }
 
         // ...and done
@@ -342,6 +357,8 @@ int32_t uDeviceClose(uDeviceHandle_t devHandle, bool powerOff)
             void *pDeviceType = (void *) deviceType;
             void *pPowerOff = (void *) powerOff;
             errorCode = uDeviceCallback("close", pDeviceType, pPowerOff);
+            // Free any storage allocated for network configuration data
+            uNetworkCfgFree(devHandle);
         }
 
         // ...and done

common/device/src/u_device_shared.h

@@ -69,7 +69,7 @@ extern "C" {
  */
 typedef struct {
     int32_t networkType; /**< the type for this network. */
-    const void *pCfg; /**< constant network configuration provided by application. */
+    void *pCfg; /**< network configuration provided by application. */
     void *pContext; /**< optional context data for this network interface. */
     void *pStatusCallbackData; /**< optional status callback for this network interface. */
 } uDeviceNetworkData_t;
@@ -81,6 +81,8 @@ typedef struct {
 typedef struct {
     uint32_t magic;             /**< magic number for detecting a stale uDeviceInstance_t. */
     uDeviceType_t deviceType;   /**< type of device. */
+    const char
+    *pCfgName;       /**< the name of the device configuration, where applicable (may be NULL). */
     int32_t moduleType;         /**< module identification (when applicable). */
     void *pContext;             /**< private instance data for the device. */
     void *pUserContext;         /**< user context attached to device. */

common/error/api/u_error_common.h

@@ -76,6 +76,7 @@ typedef enum {
     U_ERROR_COMMON_IGNORED = U_ERROR_BASE - 21,
     U_ERROR_COMMON_TOO_BIG = U_ERROR_BASE - 22,
     U_ERROR_COMMON_NOT_COMPILED = U_ERROR_BASE - 23,
+    U_ERROR_COMMON_CONFIGURATION = U_ERROR_BASE - 24,
     U_ERROR_COMMON_MIN = U_ERROR_BASE - 255,
     U_ERROR_CELL_MAX = U_ERROR_BASE - 256,
     U_ERROR_CELL_MIN = U_ERROR_BASE - 511,

common/network/api/u_network.h

@@ -23,6 +23,7 @@
  * please keep #includes to your .c files. */
 
 #include "u_device.h"
+#include "u_network_type.h"
 
 /** \addtogroup network Network
  *  @{
@@ -75,34 +76,6 @@ extern "C" {
  * TYPES
  * -------------------------------------------------------------- */
 
-/** Network types.
- */
-//lint -estring(788, uNetworkType_t::U_NETWORK_TYPE_MAX_NUM)
-//lint -estring(788, uNetworkType_t::U_NETWORK_TYPE_NONE)
-//  Suppress not used within defaulted switch
-typedef enum {
-    U_NETWORK_TYPE_NONE,
-    U_NETWORK_TYPE_BLE,
-    U_NETWORK_TYPE_CELL,
-    U_NETWORK_TYPE_WIFI,
-    U_NETWORK_TYPE_GNSS,
-    U_NETWORK_TYPE_MAX_NUM
-} uNetworkType_t;
-
-/** A version number for the network configuration structure. In
- * general you should allow the compiler to initialise any variable
- * of this type to zero and ignore it.  It is only set to a value
- * other than zero when variables in a new and extended version of
- * the structure it is a part of are being used, the version number
- * being employed by this code to detect that and, more importantly,
- * to adopt default values for any new elements when the version
- * number is STILL ZERO, maintaining backwards compatibility with
- * existing application code.  The structure this is a part of will
- * include instructions as to when a non-zero version number should
- * be set.
- */
-typedef int32_t uNetworkCfgVersion_t;
-
 /** Network status information for BLE.
  */
 typedef struct {
@@ -230,6 +203,11 @@ typedef struct {
  *                         type and allow cross-checking.
  *                         Can be set to NULL on subsequent calls
  *                         if the configuration is unchanged.
+ *                         Zephyr users may prefer to set the
+ *                         network (and device) configuration
+ *                         through the Zephyr device tree;
+ *                         see /port/platform/zephyr/README.md
+ *                         for instructions on how to do that.
  * @return                 zero on success else negative error code.
  */
 int32_t uNetworkInterfaceUp(uDeviceHandle_t devHandle, uNetworkType_t netType,