Initial commit for the SUOSERIAL sample code.

features/suoserial_sample_code/.project

@@ -0,0 +1,104 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<projectDescription>
+	<name>suoserial_sample_code</name>
+	<comment></comment>
+	<projects>
+	</projects>
+	<buildSpec>
+		<buildCommand>
+			<name>org.eclipse.cdt.managedbuilder.core.genmakebuilder</name>
+			<triggers>clean,full,incremental,</triggers>
+			<arguments>
+			</arguments>
+		</buildCommand>
+		<buildCommand>
+			<name>org.eclipse.cdt.managedbuilder.core.ScannerConfigBuilder</name>
+			<triggers>full,incremental,</triggers>
+			<arguments>
+			</arguments>
+		</buildCommand>
+	</buildSpec>
+	<natures>
+		<nature>org.eclipse.cdt.core.cnature</nature>
+		<nature>org.eclipse.cdt.managedbuilder.core.managedBuildNature</nature>
+		<nature>org.eclipse.cdt.managedbuilder.core.ScannerConfigNature</nature>
+	</natures>
+	<linkedResources>
+		<link>
+			<name>sdk</name>
+			<type>2</type>
+			<locationURI>virtual:/virtual</locationURI>
+		</link>
+		<link>
+			<name>startup</name>
+			<type>2</type>
+			<locationURI>SDKROOT/sdk/bsp/startup</locationURI>
+		</link>
+		<link>
+			<name>sdk/FreeRTOS</name>
+			<type>2</type>
+			<locationURI>SDKROOT/sdk/free_rtos</locationURI>
+		</link>
+		<link>
+			<name>sdk/adapters</name>
+			<type>2</type>
+			<locationURI>SDKROOT/sdk/middleware/adapters</locationURI>
+		</link>
+		<link>
+			<name>sdk/bsp_include</name>
+			<type>2</type>
+			<locationURI>SDKROOT/sdk/bsp/include</locationURI>
+		</link>
+		<link>
+			<name>sdk/config</name>
+			<type>2</type>
+			<locationURI>SDKROOT/sdk/bsp/config</locationURI>
+		</link>
+		<link>
+			<name>sdk/cpm</name>
+			<type>2</type>
+			<locationURI>SDKROOT/sdk/bsp/system/sys_man</locationURI>
+		</link>
+		<link>
+			<name>sdk/ldscripts</name>
+			<type>2</type>
+			<locationURI>SDKROOT/sdk/bsp/ldscripts/non_ble_projects</locationURI>
+		</link>
+		<link>
+			<name>sdk/memory</name>
+			<type>2</type>
+			<locationURI>SDKROOT/sdk/bsp/memory</locationURI>
+		</link>
+		<link>
+			<name>sdk/middleware_config</name>
+			<type>2</type>
+			<locationURI>SDKROOT/sdk/middleware/config</locationURI>
+		</link>
+		<link>
+			<name>sdk/osal</name>
+			<type>2</type>
+			<locationURI>SDKROOT/sdk/middleware/osal</locationURI>
+		</link>
+		<link>
+			<name>sdk/peripherals</name>
+			<type>2</type>
+			<locationURI>SDKROOT/sdk/bsp/peripherals</locationURI>
+		</link>
+		<link>
+			<name>sdk/segger_tools</name>
+			<type>2</type>
+			<locationURI>SDKROOT/sdk/middleware/segger_tools</locationURI>
+		</link>
+		<link>
+			<name>sdk/util</name>
+			<type>2</type>
+			<locationURI>SDKROOT/sdk/bsp/util</locationURI>
+		</link>
+	</linkedResources>
+	<variableList>
+		<variable>
+			<name>SDKROOT</name>
+			<value>$%7BWORKSPACE_LOC%7D</value>
+		</variable>
+	</variableList>
+</projectDescription>

features/suoserial_sample_code/Readme.md

@@ -0,0 +1,44 @@
+SUOSERIAL Demonstration Example{#suouart}
+======================
+
+This example demonstrates Software Update over UART, namely `SUOSERIAL`. The application has been ported from the DA1469x family of devices which also supports Software Update over USB. The same name convention is chosen here as more serial interfaces might be supported in the future. An executable, namely `host_suoserial`, is provided to run the example with a development kit connected to a PC which runs either Windows or Linux OS. The source code used to create this executable is provided in `host_suoserial.c`
+
+## HW and SW Configuration
+
+  - **Hardware Configuration**
+    - This example runs on the DA1459x family of devices.
+    - A [Pro Development Kit](https://www.renesas.com/us/en/products/wireless-connectivity/bluetooth-low-energy/da14592-016fdevkt-p-smartbond-da14592-bluetooth-low-energy-52-soc-development-kit-pro) (DevKit) is needed for this example.
+  - **Software Configuration**
+    - Download the latest [SDK](https://www.renesas.com/us/en/products/wireless-connectivity/bluetooth-low-energy/da14592-smartbond-multi-core-bluetooth-le-52-soc-embedded-flash?gad_source=1) version for the target family of devices.
+
+    - SEGGER J-Link tools are normally downloaded and installed as part of the [e2 Studio](https://www.renesas.com/us/en/software-tool/smartbond-development-tools) installation.
+
+## How to run the example
+
+### Initial Setup
+
+- Download the source code from [GitHub](https://github.com/dialog-semiconductor/BLE_SDK10_DA1459x_examples). 
+- Import the project into your workspace (there should be no path dependencies). If you are not familiar with these processes it's advised that you first familiarize yourself with the [Getting Started](https://lpccs-docs.renesas.com/um-b-166-da1459x_getting_started/index.html) guide.
+- Connect the target device to your host PC via USB1. The mentioned port is used to power the device and to support serial and JTAG interfaces. These two interfaces can be used both for flashing and debugging purposes.
+- This example employs the `SUOTA` flash partition so that there is room for both the current and update firmwares. As such, it's imperative that the flash memory be erased before flashing the target application. This is imperative every time a new flash partition is loaded.
+- Compile the source code (either in Release or Debug mode) and flash it into the chip. Please note that the debug flavor should be used merely for debugging purposes since it should increase the generated binary file, significantly. In addition, the source code is built to work with the embedded flash Working with external flash memory devices is out of the scope of this demonstration example.  
+- Once the application image is flashed, press the RESET button on the daughter board to start executing the application. 
+- Open a command prompt at `<path_on_your_machine>/suoserial_sample_code/suoserial_host`. 
+- If the host runs on a Windows machine hit `host_usb.exe <COM port> pxp_reporter.1.0.0.1.img -verbose`.
+  - Where `COM port` is the lower virtual COM port of Pro Development Kit. 
+  - `pxp_reporter.1.0.0.1.img` is a pre-compiled proximity reporter SDK sample code that integrates the SUOSERIAL service. That means that, once the FW update completes a new SW update over UART can take place.
+  - Debug message can be enabled with the `-verbose` option.
+
+- If the verbose functionality is enabled various info should be displayed throughout the update process: 
+
+![test_result](assets/suoserial_cmd_output.png)
+
+Once the update process is completed successfully, DA1459x will reset and start advertising the `pxp_reporter` application. 
+
+![pxp_reporter](assets/pxp_reporter.png)
+
+### Command Flow Overview
+
+The below sequence diagram provides of an overview of the commands/responses exchanged between the `host_suoserial` executable running on the PC and the DA1459x running the `suoserial` service. 
+
+![command_flow](assets/command_flow.png)

features/suoserial_sample_code/assets/command_flow.txt

@@ -0,0 +1,112 @@
+@startuml
+participant Host as ht
+participant DA1459x as tgt
+
+activate ht
+ht -> ht: check for '>'
+ht -> tgt: '\\n'
+note left
+Sending a \n will prompt the DA1459x to
+write another > character to the serial port
+end note
+ht -> ht : check for '>'
+ht -> tgt: '\\n'
+tgt -> ht: '>'
+activate tgt
+ht -> ht: check for '>'
+
+ht -> tgt: getsuoserialbuffsz
+tgt -> ht: OK 4096
+note left
+This is the size of the DA1459x command buffer.
+It dictates how much code we can transfer at
+one time
+end note
+
+ht -> tgt: alloc 2048
+note left
+alloc instructs the DA1459x to allocate a working buffer.
+Note for each nibble of firmware we transfer, one byte
+is sent to to the DA1469x in ASCII format. A 
+buffer of 4096 returned by getsuoserialbuffsz means
+we can send 2048 bytes of code at a time.
+end note
+tgt -> ht: OK
+
+ht -> tgt: fwupdate
+note left
+Note commands prior to fwupdate are echoed back to the host,
+though they are not depicted. This allows the DA1459x to
+act as a CLI. Commands are not echoed once the firware 
+update process is started (e.g. after the fwupdate command
+is received).
+end note
+tgt -> ht: OK
+
+ht -> tgt: SUOSERIAL_WRITE_STATUS 0 2 0100
+tgt -> ht: OK
+
+ht -> tgt: SUOSERIAL_MEM_DEV 0 4 00000013
+note left
+Indicate the image is to be stored in flash
+end note
+tgt -> ht: INFO SUOSERIAL_IMG_STARTED OK
+
+ht -> tgt: SUOSERIAL_PATCH_LEN 0 2 0008
+note left
+0008 is litte endian --> 0x0800 = 2048
+This instructs the DA1459x to confirm when 
+this many bytes have been received and is used
+as a flow control mechanism
+end note
+tgt -> ht: OK
+
+ht -> tgt: SUOSERIAL_PATCH_DATA 0 2048 <2048 Bytes of data>
+note left
+Transfer a block of code. The DA1459x confirms it was 
+received without issue.
+end note
+tgt -> ht: INFO SUOSERIAL_CMP_OK
+
+== Keep sending blocks of 2048 until less than 2048 bytes left to send ==
+
+ht -> tgt: SUOSERIAL_PATCH_LEN 0 2 3404
+note left
+Here we need to transfer the remainder of the
+image, but the final block is less than 2048 bytes.
+We adjust the PATCH_LEN so the DA1459x will inform
+us when the remainder has been processed. 
+3404 --> 0x0434 = 1076 bytes remaining to transfer
+end note
+tgt -> ht: OK
+
+ht -> tgt: SUOSERIAL_PATCH_DATA 0 1076 <1076 Bytes of data>
+note left
+Transfer the final block
+end note
+
+tgt -> ht: INFO SUOSERIAL_CMP_OK
+
+ht -> tgt: SUOSERIAL_READ_MEM_INFO 0 1 00
+tgt -> ht: OK 287796
+note left
+Confirm the size of the image we transferred
+end note
+
+ht -> tgt: SUOSERIAL_MEM_DEV 0 4 000000FE
+note left
+Indicate to the DA1459x the image transfer is complete
+end note
+tgt -> ht: INFO SUOSERIAL_CMP_OK
+
+ht -> tgt: SUOSERIAL_MEM_DEV 0 4 000000FD
+note left
+Instruct the DA1459x to reset. Once it does, the new image
+will run.
+end note
+tgt -> ht: SUOSERIAL_CMP_OK
+deactivate ht
+deactivate tgt
+
+...DA1459x resets and loads new firmware image...
+@enduml

features/suoserial_sample_code/config/custom_config_eflash.h

@@ -0,0 +1,96 @@
+/**
+ ****************************************************************************************
+ *
+ * @file custom_config_eflash.h
+ *
+ * @brief Board Support Package. User Configuration file for cached eFLASH mode.
+ *
+ * Copyright (C) 2020-2024 Renesas Electronics Corporation and/or its affiliates.
+ * All rights reserved. Confidential Information.
+ *
+ * This software ("Software") is supplied by Renesas Electronics Corporation and/or its
+ * affiliates ("Renesas"). Renesas grants you a personal, non-exclusive, non-transferable,
+ * revocable, non-sub-licensable right and license to use the Software, solely if used in
+ * or together with Renesas products. You may make copies of this Software, provided this
+ * copyright notice and disclaimer ("Notice") is included in all such copies. Renesas
+ * reserves the right to change or discontinue the Software at any time without notice.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS". RENESAS DISCLAIMS ALL WARRANTIES OF ANY KIND,
+ * WHETHER EXPRESS, IMPLIED, OR STATUTORY, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+ * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. TO THE
+ * MAXIMUM EXTENT PERMITTED UNDER LAW, IN NO EVENT SHALL RENESAS BE LIABLE FOR ANY DIRECT,
+ * INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING FROM, OUT OF OR IN
+ * CONNECTION WITH THE SOFTWARE, EVEN IF RENESAS HAS BEEN ADVISED OF THE POSSIBILITY OF
+ * SUCH DAMAGES. USE OF THIS SOFTWARE MAY BE SUBJECT TO TERMS AND CONDITIONS CONTAINED IN
+ * AN ADDITIONAL AGREEMENT BETWEEN YOU AND RENESAS. IN CASE OF CONFLICT BETWEEN THE TERMS
+ * OF THIS NOTICE AND ANY SUCH ADDITIONAL LICENSE AGREEMENT, THE TERMS OF THE AGREEMENT
+ * SHALL TAKE PRECEDENCE. BY CONTINUING TO USE THIS SOFTWARE, YOU AGREE TO THE TERMS OF
+ * THIS NOTICE.IF YOU DO NOT AGREE TO THESE TERMS, YOU ARE NOT PERMITTED TO USE THIS
+ * SOFTWARE.
+ *
+ ****************************************************************************************
+ */
+#ifndef CUSTOM_CONFIG_EFLASH_H_
+#define CUSTOM_CONFIG_EFLASH_H_
+
+#include "bsp_definitions.h"
+
+#undef CONFIG_USE_BLE
+
+#define USE_PARTITION_TABLE_EFLASH_WITH_SUOTA
+
+/*************************************************************************************************\
+ * System configuration
+ */
+#define dg_configEXEC_MODE                      ( MODE_IS_CACHED )
+#define dg_configCODE_LOCATION                  ( NON_VOLATILE_IS_EMBEDDED_FLASH )
+
+#define dg_configUSE_WDOG                       ( 1 )
+
+#define dg_configUSE_SW_CURSOR                  ( 1 )
+
+/*************************************************************************************************\
+ * FreeRTOS configuration
+ */
+#define OS_FREERTOS                             /* Define this to use FreeRTOS */
+#define configTOTAL_HEAP_SIZE                   ( 20 * 1024 )   /* FreeRTOS Total Heap Size */
+
+/*************************************************************************************************\
+ * Peripherals configuration
+ */
+#define dg_configNVMS_VES                       ( 0 )
+#define dg_configNVPARAM_ADAPTER                ( 1 )
+
+#define dg_configUART_ADAPTER                   ( 1 )     /* Enable the UART Adapter abstraction layer and API */
+
+/* Enable circular DMA so no data are overwritten in the RX HW FIFOs upon file transfers. */
+#define dg_configUART_RX_CIRCULAR_DMA           ( 1 )
+/* This value has been adjusted so that no data loss is encountered in file transfer operations. */
+#define dg_configUART2_RX_CIRCULAR_DMA_BUF_SIZE ( 1024 )
+
+#if (dg_configUART_ADAPTER == 1)
+#undef CONFIG_RETARGET                                    /* Using UART2 for example, must disable RETARGET as it users UART2 */
+#define CONFIG_RTT
+#endif
+
+#define dg_configSUOUART_SUPPORT                 ( 1 )
+
+#if (dg_configSUOUART_SUPPORT == 1)
+/*
+ * Once the SUOUART task is executed there will be no time for lower
+ * priority tasks (typically that should be the idle task) to execute
+ * and thus denoting its presence to the WDOG service. Therefore, it's
+ * imperative that WDOG monitoring for these tasks be disabled since
+ * there is no API to get the IDLE task's WDOG ID. Otherwise, the
+ * idle task's monitoring would just be suspended as long as SUOUART
+ * was up and running.
+ */
+#define dg_configWDOG_GUARD_IDLE_TASK            ( 0 )
+#endif
+
+/* Include bsp default values */
+#include "bsp_defaults.h"
+/* Include middleware default values */
+#include "middleware_defaults.h"
+
+#endif /* CUSTOM_CONFIG_EFLASH_H_ */

features/suoserial_sample_code/makefile.targets

@@ -0,0 +1,10 @@
+LDSCRIPT_PATH=../ldscripts
+
+.PHONY: generate_ldscripts FORCE
+
+FORCE:
+
+generate_ldscripts : mem.ld sections.ld
+
+%.ld : $(LDSCRIPT_PATH)/%.ld.h FORCE
+	"$(CC)" -I "$(BSP_CONFIG_DIR)" -I "$(MIDDLEWARE_CONFIG_DIR)" $(PRE_BUILD_EXTRA_DEFS) -imacros "$(APP_CONFIG_H)" $(LD_DEFS) -Ddg_configDEVICE=$(DEVICE) -E -P -c "$<" -o "$@"