Create README.md (#37)

Author: tianmc1

src/ota/README.md

@@ -0,0 +1,85 @@
+# OTA Platform Abstraction Layer (PAL) Test
+
+## On this page:
+1. [Introduction](#1-introduction)
+2. [OTA PAL Test Cases](#2-ota-pal-test-cases)
+3. [Prerequisites For OTA PAL Test](#3-prerequisites-for-ota-pal-test)
+4. [Configure OTA PAL Test](#4-configure-ota-pal-test)
+5. [Running OTA PAL Test](#5-running-ota-pal-test)
+
+## 1. Introduction
+
+OTA PAL tests help to verify OTA PAL implementation. OTA PAL interface can be found [here](https://freertos.org/Documentation/api-ref/ota-for-aws-iot-embedded-sdk/docs/doxygen/output/html/ota_pal_interface.html).
+
+OTA PAL tests have the following required parameters that should be setup in `SetupOtaPalTestParam()` implementation:
+* pageSize: page size of flash. All test writes will be aligned to this page size.
+
+## 2. OTA PAL Test Cases
+
+The OTA PAL tests verify the implementation by running various test cases.
+
+|Test Case	|Test Case Detail	|Expected result	|
+|---	|---	|---	|
+|otaPal_CloseFile_ValidSignature	| Test otaPal_CloseFile with a valid signature and signature verification certificate	| otaPal_CloseFile returns OtaPalSuccess	|
+|otaPal_CloseFile_InvalidSignatureBlockWritten	|Call otaPal_CloseFile with an invalid signature in the file context after writing a block of dummy data to the file 	| otaPal_CloseFile returns OtaPalSignatureCheckFailed	|
+|otaPal_CloseFile_InvalidSignatureNoBlockWritten	| Call otaPal_CloseFile with an invalid signature in the file context without writing to the file	| otaPal_CloseFile returns OtaPalSignatureCheckFailed	|
+|otaPal_CloseFile_NonexistingCodeSignerCertificate	| Call otaPal_CloseFile with a signature verification certificate path does not exist in the system.	| otaPal_CloseFile returns OtaPalBadSignerCert|
+|otaPal_CreateFileForRx_CreateAnyFile	| Create a file with any name with otaPal_CreateFileForRx	| otaPal_CreateFileForRx	returns OtaPalSuccess|
+|otaPal_Abort_OpenFile	|Abort on an open file 	| otaPal_Abort returns OtaPalSuccess	|
+|otaPal_Abort_FileWithBlockWritten	| Abort after writing a block to an open file	| otaPal_Abort returns OtaPalSuccess	|
+|otaPal_Abort_NullFileHandle	|Call otaPal_Abort on a NULL file handle 	| otaPal_Abort returns OtaPalSuccess	|
+|otaPal_Abort_NonExistentFile	|Call otaPal_Abort on a non-existent file 	| otaPal_Abort returns OtaPalSuccess	|
+|otaPal_WriteBlock_WriteSingleByte	| Write one byte of data into created OTA file	| otaPal_WriteBlock returns 1	|
+|otaPal_WriteBlock_WriteManyBlocks	| Write multiple blocks of data into created OTA file	|otaPal_WriteBlock returns number of bytes written 	|
+|otaPal_SetPlatformImageState_AcceptedStateWithoutClose	| Set the platform state to accepted before closing the file	| otaPal_SetPlatformImageState returns OtaPalCommitFailed	|
+|otaPal_SetPlatformImageState_InvalidImageState	| Set an invalid platform image state exceeding the range	| otaPal_SetPlatformImageState returns	OtaPalBadImageState|
+|otaPal_SetPlatformImageState_UnknownImageState	| Set the image state to unknown	| otaPal_SetPlatformImageState returns	OtaPalBadImageState |
+|otaPal_GetPlatformImageState_InvalidImageStateFromFileCloseFailure	| Set the platform image state to aborted	| otaPal_SetPlatformImageState returns success	|
+
+
+Assert may be used to check invalid parameters. In that case, you may need to replace
+the assert macro to return negative value in your implementation
+to ensure invalid parameter error can be catched by assert.<br><br>
+For example, if you are using FreeRTOS configASSERT macro to check invalid parameters,
+you can replace the macro with the following code:
+```
+#define configASSERT( x )   if( !( x ) ) { return NEGATIVE_VALUE_TO_INDICATE_ERROR; }
+```
+
+## 3. Prerequisites For OTA PAL Test
+
+The OTA PAL test assumes the tested platform already has the following components integrated.
+
+* **OTA PAL implementation**
+    
+* **Unity test framework**
+    The OTA PAL tests make use of the Unity test framework. Reference the [website](https://github.com/ThrowTheSwitch/Unity) for integration guide.
+
+## 4. Configure OTA PAL Test
+Please refer to top level [README](https://github.com/FreeRTOS/FreeRTOS-Libraries-Integration-Tests/blob/main/README.md) on high level project setup.
+This section covers OTA PAL test specific configuration.
+
+1. Implement the setup function, **SetupOtaPalParam**, for OTA PAL test to provide test parameters. The following are required test parameters:
+
+```C
+typedef struct OtaPalTestParam
+{
+    uint32_t pageSize;
+} OtaPalTestParam_t;
+
+void SetupOtaPalTestParam( OtaPalTestParam_t * pTestParam );
+```
+
+
+## 5. Running OTA PAL Test
+
+Open test_execution_config.h and define `OTA_PAL_TEST_ENABLED` to 1.
+
+In test_param_config.h, update the following options:
+
+* OTA_PAL_TEST_CERT_TYPE: Select the certificate type used
+* OTA_PAL_CERTIFICATE_FILE: Path to on device certificate, if applicable.
+* OTA_PAL_FIRMWARE_FILE: Name of the firmware file, if applicable.
+* OTA_PAL_USE_FILE_SYSTEM: Set to 1 if the OTA PAL uses file system abtraction.
+
+Build and flash the application using toolchain of your choice. When RunQualificationTest() is called, the OTA PAL tests will run. Test results are outputted to serial.