BREAKING CHANGE: fix for ESP-IDF platform linker workaround. (#844)

Commit bf8cd21 introduced a mechanism for leaving out one or more of cell, GNSS or short-range [BLE and Wifi] from a build.  As noted at the time, there is a bug in the ESP-IDF linker which means that, if a file happens to contain functions which ALL have WEAK counterparts, the linker will entirely ignore the .c file and use the WEAK versions instead; this is counter-productive, resulting in everything returning "NOT SUPPORTED".

A workaround for this problem was included in the commit: a dummy function with no WEAK counterpart was introduced to those files which, when called from somewhere, would cause the ESP-IDF linker to correctly link the non-WEAK functions.  However, the places we chose to call the _key_ dummy functions from (the functions for the uDevice and uNetwork APIs which provide the "root" of the linker tree) were, unfortunately, themselves functions that had WEAK counterparts, so the workaround kind of ate itself.

This is now fixed: those key dummy functions are now _always_ called and separate "_link.c" files are brought in, with the implementation of those dummy functions, for the cases where the code is left out (to keep all of the linkers happy).

IMPORTANT, THE BREAKING PART: if you bring the ubxlib files into your build in your own way (so not using ubxlib.mk or ubxlib.cmake or PlatformIO) and you are leaving out one or more of cellular, GNSS or short-range [BLE and Wifi], you MUST NOW BRING INTO YOUR BUILD the "_link.c" files for the part that you are _leaving_out_, otherwise linking will fail.

Note: the non-PlatformIO-flavour-Arduino-build does not support leaving bits out; please use the PlatformIO Arduino build if you need that capability.

ble/src/u_ble_extmod.c

@@ -44,10 +44,6 @@
 #include "u_ble.h"
 #include "u_ble_private.h"
 
-// The headers below are necessary to work around an Espressif linker problem, see uBleInit()
-#include "u_network.h"
-#include "u_network_config_ble.h"
-#include "u_network_private_ble.h"
 
 /* ----------------------------------------------------------------
  * COMPILE-TIME MACROS
@@ -72,16 +68,6 @@
 // Initialise the ble driver.
 int32_t uBleInit(void)
 {
-    // Workaround for Espressif linker missing out files that
-    // only contain functions which also have weak alternatives
-    // (see https://www.esp32.com/viewtopic.php?f=13&t=8418&p=35899)
-    // Basically any file that might end up containing only functions
-    // that also have WEAK linked counterparts will be lost, so we need
-    // to add a dummy function in those files and call it from somewhere
-    // that will always be present in the build, which for BLE we
-    // choose to be here
-    uNetworkPrivateBleLink();
-
     uBleSpsPrivateInit();
     return uShortRangeInit();
 }

cell/src/u_cell.c

@@ -57,10 +57,6 @@
 #include "u_cell_mux_private.h"
 
 // The headers below necessary to work around an Espressif linker problem, see uCellInit()
-#include "u_device_private_cell.h"
-#include "u_network.h"
-#include "u_network_config_cell.h"
-#include "u_network_private_cell.h"
 #include "u_sock.h"
 #include "u_cell_sock.h"     // For uCellSockPrivateLink()
 #include "u_cell_sec.h"      // For uCellSecPrivateLink()
@@ -174,8 +170,6 @@ int32_t uCellInit()
     // to add a dummy function in those files and call it from somewhere
     // that will always be present in the build, which for cellular we
     // choose to be here
-    uDevicePrivateCellLink();
-    uNetworkPrivateCellLink();
     uCellSockPrivateLink();
     uCellSecPrivateLink();
     uCellSecTlsPrivateLink();

common/device/src/u_device.c

@@ -100,6 +100,18 @@ int32_t uDeviceInit()
 {
     int32_t errorCode = uDeviceMutexCreate();
 
+    // Workaround for Espressif linker missing out files that
+    // only contain functions which also have weak alternatives
+    // (see https://www.esp32.com/viewtopic.php?f=13&t=8418&p=35899).
+    // Basically any file that might end up containing only functions
+    // that also have WEAK linked counterparts will be lost, so we need
+    // to add a dummy function in those files and call it from somewhere
+    // that will always be present in the build, which for cellular we
+    // choose to be here
+    uDevicePrivateCellLink();
+    uDevicePrivateGnssLink();
+    uDevicePrivateShortRangeLink();
+
     if (errorCode == 0) {
         uDevicePrivateInit();
         errorCode = uDevicePrivateCellInit();

common/device/src/u_device_private_cell_link.c

@@ -0,0 +1,41 @@
+/*
+ * Copyright 2019-2022 u-blox
+ *
+ * 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.
+ */
+
+/** @file
+ * @brief Workaround for Espressif linker missing out files that
+ * only contain functions which also have weak alternatives
+ * (see https://www.esp32.com/viewtopic.php?f=13&t=8418&p=35899).
+ * The workaround is to introduce a function to a "wanted" .c file
+ * that has no WEAK alternative.  However, when that .c file is left
+ * out, for the stubs to take over, the code will then obviously
+ * fail to link.  This file must be included when cellular is being
+ * left out of the build.
+ */
+
+#ifdef U_CFG_OVERRIDE
+# include "u_cfg_override.h"  // For a customer's configuration override
+#endif
+
+/* ----------------------------------------------------------------
+ * PUBLIC FUNCTION
+ * -------------------------------------------------------------- */
+
+void uDevicePrivateCellLink()
+{
+    //dummy
+}
+
+// End of file

common/device/src/u_device_private_gnss_link.c

@@ -0,0 +1,41 @@
+/*
+ * Copyright 2019-2022 u-blox
+ *
+ * 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.
+ */
+
+/** @file
+ * @brief Workaround for Espressif linker missing out files that
+ * only contain functions which also have weak alternatives
+ * (see https://www.esp32.com/viewtopic.php?f=13&t=8418&p=35899).
+ * The workaround is to introduce a function to a "wanted" .c file
+ * that has no WEAK alternative.  However, when that .c file is left
+ * out, for the stubs to take over, the code will then obviously
+ * fail to link.  This file must be included when GNSS is being
+ * left out of the build.
+ */
+
+#ifdef U_CFG_OVERRIDE
+# include "u_cfg_override.h"  // For a customer's configuration override
+#endif
+
+/* ----------------------------------------------------------------
+ * PUBLIC FUNCTION
+ * -------------------------------------------------------------- */
+
+void uDevicePrivateGnssLink()
+{
+    //dummy
+}
+
+// End of file

common/device/src/u_device_private_short_range_link.c

@@ -0,0 +1,41 @@
+/*
+ * Copyright 2019-2022 u-blox
+ *
+ * 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.
+ */
+
+/** @file
+ * @brief Workaround for Espressif linker missing out files that
+ * only contain functions which also have weak alternatives
+ * (see https://www.esp32.com/viewtopic.php?f=13&t=8418&p=35899).
+ * The workaround is to introduce a function to a "wanted" .c file
+ * that has no WEAK alternative.  However, when that .c file is left
+ * out, for the stubs to take over, the code will then obviously
+ * fail to link.  This file must be included when short-range is being
+ * left out of the build.
+ */
+
+#ifdef U_CFG_OVERRIDE
+# include "u_cfg_override.h"  // For a customer's configuration override
+#endif
+
+/* ----------------------------------------------------------------
+ * PUBLIC FUNCTION
+ * -------------------------------------------------------------- */
+
+void uDevicePrivateShortRangeLink()
+{
+    //dummy
+}
+
+// End of file

common/network/src/u_network.c

@@ -140,6 +140,19 @@ int32_t uNetworkInterfaceUp(uDeviceHandle_t devHandle,
                             uNetworkType_t netType,
                             const void *pCfg)
 {
+    // Workaround for Espressif linker missing out files that
+    // only contain functions which also have weak alternatives
+    // (see https://www.esp32.com/viewtopic.php?f=13&t=8418&p=35899).
+    // Basically any file that might end up containing only functions
+    // that also have WEAK linked counterparts will be lost, so we need
+    // to add a dummy function in those files and call it from somewhere
+    // that will always be present in the build, which for cellular we
+    // choose to be here
+    uNetworkPrivateBleLink();
+    uNetworkPrivateCellLink();
+    uNetworkPrivateGnssLink();
+    uNetworkPrivateWifiLink();
+
     // Lock the API
     int32_t errorCode = uDeviceLock();
     uDeviceInstance_t *pInstance;

common/network/src/u_network_private_ble_extmod_link.c

@@ -0,0 +1,41 @@
+/*
+ * Copyright 2019-2022 u-blox
+ *
+ * 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.
+ */
+
+/** @file
+ * @brief Workaround for Espressif linker missing out files that
+ * only contain functions which also have weak alternatives
+ * (see https://www.esp32.com/viewtopic.php?f=13&t=8418&p=35899).
+ * The workaround is to introduce a function to a "wanted" .c file
+ * that has no WEAK alternative.  However, when that .c file is left
+ * out, for the stubs to take over, the code will then obviously
+ * fail to link.  This file must be included when BLE is being
+ * left out of the build.
+ */
+
+#ifdef U_CFG_OVERRIDE
+# include "u_cfg_override.h"  // For a customer's configuration override
+#endif
+
+/* ----------------------------------------------------------------
+ * PUBLIC FUNCTION
+ * -------------------------------------------------------------- */
+
+void uNetworkPrivateBleLink()
+{
+    //dummy
+}
+
+// End of file

common/network/src/u_network_private_cell_link.c

@@ -0,0 +1,41 @@
+/*
+ * Copyright 2019-2022 u-blox
+ *
+ * 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.
+ */
+
+/** @file
+ * @brief Workaround for Espressif linker missing out files that
+ * only contain functions which also have weak alternatives
+ * (see https://www.esp32.com/viewtopic.php?f=13&t=8418&p=35899).
+ * The workaround is to introduce a function to a "wanted" .c file
+ * that has no WEAK alternative.  However, when that .c file is left
+ * out, for the stubs to take over, the code will then obviously
+ * fail to link.  This file must be included when cellular is being
+ * left out of the build.
+ */
+
+#ifdef U_CFG_OVERRIDE
+# include "u_cfg_override.h"  // For a customer's configuration override
+#endif
+
+/* ----------------------------------------------------------------
+ * PUBLIC FUNCTION
+ * -------------------------------------------------------------- */
+
+void uNetworkPrivateCellLink()
+{
+    //dummy
+}
+
+// End of file

common/network/src/u_network_private_gnss_link.c

@@ -0,0 +1,41 @@
+/*
+ * Copyright 2019-2022 u-blox
+ *
+ * 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.
+ */
+
+/** @file
+ * @brief Workaround for Espressif linker missing out files that
+ * only contain functions which also have weak alternatives
+ * (see https://www.esp32.com/viewtopic.php?f=13&t=8418&p=35899).
+ * The workaround is to introduce a function to a "wanted" .c file
+ * that has no WEAK alternative.  However, when that .c file is left
+ * out, for the stubs to take over, the code will then obviously
+ * fail to link.  This file must be included when GNSS is being
+ * left out of the build.
+ */
+
+#ifdef U_CFG_OVERRIDE
+# include "u_cfg_override.h"  // For a customer's configuration override
+#endif
+
+/* ----------------------------------------------------------------
+ * PUBLIC FUNCTION
+ * -------------------------------------------------------------- */
+
+void uNetworkPrivateGnssLink()
+{
+    //dummy
+}
+
+// End of file

common/network/src/u_network_private_wifi_link.c

@@ -0,0 +1,41 @@
+/*
+ * Copyright 2019-2022 u-blox
+ *
+ * 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.
+ */
+
+/** @file
+ * @brief Workaround for Espressif linker missing out files that
+ * only contain functions which also have weak alternatives
+ * (see https://www.esp32.com/viewtopic.php?f=13&t=8418&p=35899).
+ * The workaround is to introduce a function to a "wanted" .c file
+ * that has no WEAK alternative.  However, when that .c file is left
+ * out, for the stubs to take over, the code will then obviously
+ * fail to link.  This file must be included when Wifi is being
+ * left out of the build.
+ */
+
+#ifdef U_CFG_OVERRIDE
+# include "u_cfg_override.h"  // For a customer's configuration override
+#endif
+
+/* ----------------------------------------------------------------
+ * PUBLIC FUNCTION
+ * -------------------------------------------------------------- */
+
+void uNetworkPrivateWifiLink()
+{
+    //dummy
+}
+
+// End of file