Add port API plus implementation of port API on ESP32, NRF52 and STM3…

…2F4 and associated automation scripts. (u-blox#2)

.gitignore

@@ -0,0 +1,15 @@
+/port/platform/espressif/esp32/sdk/esp-idf/runner/build
+/port/platform/nordic/nrf52/sdk/gcc/runner/build
+/port/platform/nordic/nrf52/sdk/gcc/runner/_build
+/port/platform/nordic/nrf52/sdk/ses/runner/Output
+/port/platform/nordic/nrf52/sdk/ses/runner/*.jlink
+/port/platform/stm/stm32f4/sdk/cube/runner/Debug
+/port/platform/stm/stm32f4/sdk/cube/runner/Release
+/port/platform/stm/stm32f4/sdk/cube/runner/.settings
+/port/platform/stm/stm32f4/sdk/cube/runner/*.launch
+/port/platform/stm/stm32f4/sdk/cube/test_only_*
+sdkconfig
+*.emSession
+*.pyc
+doxygen_output
+_jenkins_work

README.md

@@ -0,0 +1,30 @@
+# Introduction
+This repository contains the C code support library for u-blox modules.  The library presents a high level C API for use in a customer application (e.g. connect to a network, open a TCP socket, establish location, etc.) and implements that API on selected popular MCUs many of which are also available inside a u-blox module.  Connect these u-blox modules together, or connect a u-blox module to one of those MCUs, configure the library code to reflect how the two are connected and away you go.
+
+![Architecture](architecture.jpg)
+
+# What Is Included
+The APIs for each type of u-blox module can be found in the relevant directory (e.g `cell` for cellular modules).  The `common` directory contains APIs and 'helper' modules that are shared by u-blox modules (e.g. an AT client).  All APIs are documented in the API header files.
+
+Examples demonstrating the use of the APIs can be found in the `examples` directory.
+
+Each API includes a `test` sub-directory containing the tests for that API which you may compile and run if you wish.
+
+Build information for each platform can be found in the `platform` sub-directory of `port`; more on this below.
+
+In order for u-blox to support multiple platforms with this code there is also a `port` API.  This is not intended to be a generic porting API, it is simply sufficient to support the APIs we require.  If you have not chosen a supported platform you may still be able to use the high level APIs here unchanged by implementing the `port` API for your platform.
+
+# How To Use This Repo
+The native SDKs for each supported platform are used directly, unchanged, by this code.  To use this repo you must first choose your platform and the SDK for that platform.  For instance, you might choose the STM32F4 platform, which employs ST's STM32Cube IDE.  Instructions for how to install and use each SDK can be found in the `port/platform/<vendor>/<chipset>/<sdk>` directory; for the STM32F4 platform this would be `port/platform/stm/stm32f4/cube`.
+
+Having chosen your platform and installed the tool chain, navigate to the directory below that to find the required build information.  For instance, you may find a `runner` directory, which is a generic build that compiles any or all of the examples and tests that can run on a given platform.  In that directory you will find detailed information on how to perform the build.
+
+Configuration information for the examples and the tests can be found in the `cfg` directory of your chosen platform.  Depending on how you have connected your MCU to a u-blox module you may need to override this configuration, e.g. to change which MCU pin is connected to which pin of the u-blox module.  The `README.md` for your chosen SDK will tell you how to override conditional compilation flags in order to do this.
+
+# License
+The software in this repository is Apache 2.0 licensed and copyright u-blox with the following exceptions:
+
+- the heap management code (`heap_useNewlib.c`), required because some of the platforms that use newlib and FreeRTOS don't provide the necessary memory management for them to play together, is copyright Dave Nadler.
+- the `stm32f4` platform directory necessarily includes porting files from the STM32F4 SDK that are copyright ST Microelectronics.
+
+In all cases copyright, and our thanks, remain with the original authors.

astyle.cfg

@@ -0,0 +1,25 @@
+# Configuration file for AStyle
+# K&R style
+--style=kr
+# space padding around operators: a = bar((b - c) * a, d--);
+--pad-oper
+# space padding between a header (e.g. 'if', 'for', 'while'...) and the following bracket
+--pad-header
+# Pointer sticks to the name: char *pThing
+--align-pointer=name
+# Reference sticks to the name: char &thing
+--align-reference=name
+# Nice long max continuation indent, as long as the line length
+--max-continuation-indent=100
+# No minimum conditional indent, align everything wherever it occurs
+--min-conditional-indent=0
+# All conditions have braces
+--add-braces
+# Indent the case in switch statements
+--indent-switches
+# All tabs become [4] spaces
+--convert-tabs
+# Max line length
+--max-code-length=100
+# When breaking lines, leave the logical operator on the end of the line
+--break-after-logical

cfg/README.md

@@ -0,0 +1,4 @@
+# Introduction
+This directory contains generic, platform independent configuration information:
+
+- `cfg_sw.h`: generic SW configuration, e.g. switching logging on or off.

cfg/u_cfg_sw.h

@@ -0,0 +1,39 @@
+/*
+ * Copyright 2020 u-blox Ltd
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#ifndef _U_CFG_SW_H_
+#define _U_CFG_SW_H_
+
+/* No #includes allowed here */
+
+/** @file
+ * @brief This header file contains software configuration information
+ * for ubxlib.
+ */
+
+/* ----------------------------------------------------------------
+ * COMPILE-TIME MACROS
+ * -------------------------------------------------------------- */
+
+#ifndef U_CFG_ENABLE_LOGGING
+/** Enable or disable logging from ubxlib.
+ */
+# define U_CFG_ENABLE_LOGGING                 1
+#endif
+
+#endif // _U_CFG_SW_H_
+
+// End of file

common/error/api/u_error_common.h

@@ -0,0 +1,70 @@
+/*
+ * Copyright 2020 u-blox Ltd
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#ifndef _U_ERROR_COMMON_H_
+#define _U_ERROR_COMMON_H_
+
+/* No #includes allowed here */
+
+/** @file
+ *@brief This header file defines the error codes for ubxlib.
+ */
+
+/* ----------------------------------------------------------------
+ * COMPILE-TIME MACROS
+ * -------------------------------------------------------------- */
+
+/** Base error code: you may override this with a NEGATIVE number
+ * if you wish.
+ */
+#ifndef U_ERROR_BASE
+# define U_ERROR_BASE 0
+#endif
+
+/* ----------------------------------------------------------------
+ * TYPES
+ * -------------------------------------------------------------- */
+
+/** Error codes.
+ */
+typedef enum {
+    U_ERROR_COMMON_FORCE_INT32 = 0x7FFFFFFF, /* Force this enum to be 32 bit
+                                              * as it can be used as a size
+                                              * also. */
+    U_ERROR_COMMON_SUCCESS = 0,
+    U_ERROR_COMMON_UNKNOWN = U_ERROR_BASE - 1,
+    U_ERROR_COMMON_NOT_INITIALISED = U_ERROR_BASE - 2,
+    U_ERROR_COMMON_NOT_IMPLEMENTED = U_ERROR_BASE - 3,
+    U_ERROR_COMMON_NOT_SUPPORTED = U_ERROR_BASE - 4,
+    U_ERROR_COMMON_INVALID_PARAMETER = U_ERROR_BASE - 5,
+    U_ERROR_COMMON_NO_MEMORY = U_ERROR_BASE - 6,
+    U_ERROR_COMMON_NOT_RESPONDING = U_ERROR_BASE - 7,
+    U_ERROR_COMMON_PLATFORM = U_ERROR_BASE - 8,
+    U_ERROR_COMMON_TIMEOUT = U_ERROR_BASE - 9,
+    U_ERROR_COMMON_MIN = U_ERROR_BASE - 255,
+    U_ERROR_CELL_MAX = U_ERROR_BASE - 256,
+    U_ERROR_CELL_MIN = U_ERROR_BASE - 511,
+    U_ERROR_BLE_MAX = U_ERROR_BASE - 512,
+    U_ERROR_BLE_MIN = U_ERROR_BASE - 1023,
+    U_ERROR_GNSS_MAX = U_ERROR_BASE - 1024,
+    U_ERROR_GNSS_MIN = U_ERROR_BASE - 2047,
+    U_ERROR_WIFI_MAX = U_ERROR_BASE - 2048,
+    U_ERROR_WIFI_MIN = U_ERROR_BASE - 4095
+} uErrorCode_t;
+
+#endif // _ERROR_COMMON_H_
+
+// End of file

port/README.md

@@ -0,0 +1,9 @@
+# Introduction
+These directories provide the porting layer that allows the high level C APIs to be built and run on a supported MCU.
+
+No attempt is made to create a full MCU porting API; only the APIs necessary to run the high level C APIs are implemented here.
+
+# Usage
+The `api` directory defines the port API, each API function documented in the header file.  The `clib` directory contains implementations of C library APIs that may be missing on some platforms (e.g. `strtok_r`, the re-entrant version of the `strtok` library function).  In the `platform` directory you will find the implementation of the porting API on various target MCUs and the necessary instructions to create a working binary and tests on each of those target MCUs.  Please refer to the `README.md` files in your chosen target platform directory for more information.
+
+The `test` directory contains tests for the `port` API that can be run on any platform.

port/api/u_port.h

@@ -0,0 +1,116 @@
+/*
+ * Copyright 2020 u-blox Ltd
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#ifndef _U_PORT_H_
+#define _U_PORT_H_
+
+/* No #includes allowed here */
+
+/** @file
+ * @brief
+ * Common stuff for porting layer.  These functions are thread-safe.
+ */
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* ----------------------------------------------------------------
+ * COMPILE-TIME MACROS
+ * -------------------------------------------------------------- */
+
+/** Used only by U_PORT_STRINGIFY_QUOTED.
+ */
+#define U_PORT_STRINGIFY_LITERAL(x) #x
+
+/** Stringify a macro, i.e. if you have:
+ *
+ * \#define foo bar
+ *
+ * ...U_PORT_STRINGIFY_QUOTED(foo) is "bar".
+ */
+#define U_PORT_STRINGIFY_QUOTED(x) U_PORT_STRINGIFY_LITERAL(x)
+
+/* ----------------------------------------------------------------
+ * TYPES
+ * -------------------------------------------------------------- */
+
+/* ----------------------------------------------------------------
+ * FUNCTIONS
+ * -------------------------------------------------------------- */
+
+/** Start the platform.  This configures clocks, resources, etc.
+ * and then calls pEntryPoint, i.e. the application, in an RTOS task.
+ * This is used as a standard way to start the system for all of the
+ * u-blox examples and all of the u-blox tests.
+ * You may have your own mechanism for initialisating the HW and
+ * starting an RTOS task, in which case you need not use this
+ * function.
+ * This function only returns if there is an error;
+ * code execution ends up in pEntryPoint, which should
+ * never return.
+ *
+ * @param pEntryPoint    the function to run.
+ * @param pParameter     a pointer that will be passed to pEntryPoint
+ *                       when it is called. Usually NULL.
+ * @param stackSizeBytes the number of bytes of memory to dynamically
+ *                       allocate for stack; ignored if the RTOS
+ *                       has already been started and no new
+ *                       task needs to be created for the entry point.
+ * @param priority       the priority at which to run a task that
+ *                       is pEntryPoint; ignored if the RTOS
+ *                       has already been started and no new
+ *                       task needs to be created for the entry point.
+ * @return               negative error code.
+ */
+int32_t uPortPlatformStart(void (*pEntryPoint)(void *),
+                           void *pParameter,
+                           size_t stackSizeBytes,
+                           int32_t priority);
+
+/** Initialise the porting layer.  Should be called by
+ * the application entry point before running any other
+ * ubxlib function except uPortPlatformStart().
+ * If the port is already initialised this function does
+ * nothing and returns success, hence it can safely
+ * be called at any time.
+ *
+ * @return zero on success else negative error code.
+ */
+int32_t uPortInit();
+
+/** Deinitialise the porting layer.
+ */
+void uPortDeinit();
+
+/** Get the current OS tick converted to a time in milliseconds.
+ * This is guaranteed to be unaffected by any time setting activity.
+ * It is NOT maintained while the processor is in deep sleep, i.e.
+ * with clocks stopped; port initialisation should be called on
+ * return from deep sleep and that will restart this time from
+ * zero once more.
+ *
+ * @return the current OS tick converted to milliseconds.
+ */
+int64_t uPortGetTickTimeMs();
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif // _U_PORT_H_
+
+// End of file

port/api/u_port_debug.h

@@ -0,0 +1,66 @@
+/*
+ * Copyright 2020 u-blox Ltd
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#ifndef _U_PORT_DEBUG_H_
+#define _U_PORT_DEBUG_H_
+
+/* No #includes allowed here */
+
+/** @file
+ * @brief Porting layer for debug functions.  These functions are thread-safe.
+ */
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* ----------------------------------------------------------------
+ * COMPILE-TIME MACROS
+ * -------------------------------------------------------------- */
+
+/** Define U_CFG_ENABLE_LOGGING to enable debug prints.  How they
+ * leave the building is dictated by the platform.
+ */
+#if U_CFG_ENABLE_LOGGING
+# define uPortLog(format, ...) \
+             /*lint -e{507} suppress size incompatiblity warnings in printf() */ \
+             uPortLogF(format, ##__VA_ARGS__)
+#else
+# define uPortLog(...)
+#endif
+
+/* ----------------------------------------------------------------
+ * TYPES
+ * -------------------------------------------------------------- */
+
+/* ----------------------------------------------------------------
+ * FUNCTIONS
+ * -------------------------------------------------------------- */
+
+/** printf()-style logging.
+ *
+ * @param pFormat a printf() style format string.
+ * @param ...     variable argument list.
+ */
+void uPortLogF(const char *pFormat, ...);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif // _U_PORT_DEBUG_H_
+
+// End of file