ota_private.h File Reference

Macros, enums, variables, and definitions internal to the OTA Agent module and shared by other OTA modules and testing files. More...

#include <stdio.h>
#include <stdint.h>
#include <stdbool.h>
#include "ota_config.h"
#include "ota_config_defaults.h"

Include dependency graph for ota_private.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	JsonDocParam_t
	JSON document parameter to store the details of keys and where to store them. More...
struct	JsonDocModel_t
	JSON document model to store the details of parameters expected in the job document. More...
struct	OtaAgentStatistics_t
	This is the OTA statistics structure to hold useful info. More...
struct	Sig_t
	OTA File Signature info. More...
struct	OtaFileContext_t
	OTA File Context Information. More...
struct	OtaEventData_t
	The OTA Agent event and data structures. More...
struct	OtaEventMsg_t
	Stores information about the event message. More...

Macros
#define	LOG2_BITS_PER_BYTE   3U
	Log base 2 of bits per byte.
#define	BITS_PER_BYTE   ( ( uint32_t ) 1U << LOG2_BITS_PER_BYTE )
	Number of bits in a byte. This is used by the block bitmap implementation.
#define	OTA_FILE_BLOCK_SIZE   ( ( uint32_t ) 1U << otaconfigLOG2_FILE_BLOCK_SIZE )
	Data section size of the file data block message (excludes the header).
#define	OTA_MAX_FILES   1U
	[MUST REMAIN 1! Future support.] Maximum number of concurrent OTA files.
#define	OTA_MAX_BLOCK_BITMAP_SIZE   128U
	Max allowed number of bytes to track all blocks of an OTA file. Adjust block size if more range is needed.
#define	OTA_REQUEST_MSG_MAX_SIZE   ( 3U * OTA_MAX_BLOCK_BITMAP_SIZE )
	Maximum size of the message.
#define	OTA_REQUEST_URL_MAX_SIZE   ( 1500 )
	Maximum size of the S3 presigned URL.
#define	OTA_ERASED_BLOCKS_VAL   0xffU
	The starting state of a group of erased blocks in the Rx block bitmap.
#define	OTA_MAX_FILE_SIZE   UINT32_MAX - OTA_FILE_BLOCK_SIZE + 1U
	The maximum file size supported by the library.
#define	OTA_MAX_JSON_TOKENS   64U
	Number of JSON tokens supported in a single parser call.
#define	OTA_MAX_JSON_STR_LEN   256U
	Limit our JSON string compares to something small to avoid going into the weeds.
#define	OTA_DOC_MODEL_MAX_PARAMS   32U
	The parameter list is backed by a 32 bit longword bitmap by design.
#define	OTA_JOB_PARAM_REQUIRED   ( bool ) true
	Used to denote a required document model parameter.
#define	OTA_JOB_PARAM_OPTIONAL   ( bool ) false
	Used to denote an optional document model parameter.
#define	OTA_DONT_STORE_PARAM   0xffff
	If destOffset in the model is 0xffffffff, do not store the value.
#define	OTA_STORE_NESTED_JSON   0x1fffU
	Store the reference to a nested JSON in a separate pointer.
#define	OTA_DATA_BLOCK_SIZE   ( ( 1U << otaconfigLOG2_FILE_BLOCK_SIZE ) + OTA_REQUEST_URL_MAX_SIZE + 30 )
	Header is 19 bytes.
#define	OTA_EVT_MASK_JOB_MSG_READY   0x00000001UL
#define	OTA_EVT_MASK_DATA_MSG_READY   0x00000002UL
#define	OTA_EVT_MASK_SHUTDOWN   0x00000004UL
#define	OTA_EVT_MASK_REQ_TIMEOUT   0x00000008UL
#define	OTA_EVT_MASK_USER_ABORT   0x000000016UL
#define	OTA_EVT_MASK_ALL_EVENTS   ( OTA_EVT_MASK_JOB_MSG_READY | OTA_EVT_MASK_DATA_MSG_READY | OTA_EVT_MASK_SHUTDOWN | OTA_EVT_MASK_REQ_TIMEOUT | OTA_EVT_MASK_USER_ABORT )
#define	OTA_NUM_JOB_PARAMS   ( 21 )
	Number of parameters in the job document.
#define	OTA_JOB_ID_MAX_SIZE   ( 72UL + 1UL )
	Maximum size of the Job ID.
#define	OTA_PROTOCOL_BUFFER_SIZE   20U
	Size of the buffer used to store the protocol field of the job document.
#define	kOTA_MaxSignatureSize   384 /* Max bytes supported for a file signature (3072 bit RSA is 384 bytes). */
	A composite cryptographic signature structure able to hold our largest supported signature.
#define	OTA_JSON_SEPARATOR   "."
	Separator used to define nested keys.
#define	OTA_JSON_CLIENT_TOKEN_KEY   "clientToken"
	Client token.
#define	OTA_JSON_TIMESTAMP_KEY   "timestamp"
	Used to calculate timeout and time spent on the operation.
#define	OTA_JSON_EXECUTION_KEY   "execution"
	Contains job execution parameters .
#define	OTA_JSON_JOB_ID_KEY   OTA_JSON_EXECUTION_KEY OTA_JSON_SEPARATOR "jobId"
	Name of the job.
#define	OTA_JSON_STATUS_DETAILS_KEY   OTA_JSON_EXECUTION_KEY OTA_JSON_SEPARATOR "statusDetails"
	Current status of the job.
#define	OTA_JSON_SELF_TEST_KEY   OTA_JSON_STATUS_DETAILS_KEY OTA_JSON_SEPARATOR "self_test"
	Specifies if the platform and service is is selftest.
#define	OTA_JSON_UPDATED_BY_KEY   OTA_JSON_STATUS_DETAILS_KEY OTA_JSON_SEPARATOR "updatedBy"
	Parameter to specify update status.
#define	OTA_JSON_UPDATED_BY_KEY_ONLY   "updatedBy"
	Specifies if the platform and service is is selftest. Not searched in sub fields.
#define	OTA_JSON_SELF_TEST_KEY_ONLY   "self_test"
	Parameter to specify update status. Not searched in sub fields.
#define	OTA_JSON_JOB_DOC_KEY   OTA_JSON_EXECUTION_KEY OTA_JSON_SEPARATOR "jobDocument"
	Parameters that specify the nature of the job.
#define	OTA_JSON_OTA_UNIT_KEY   OTA_JSON_JOB_DOC_KEY OTA_JSON_SEPARATOR "afr_ota"
	afr-ota.
#define	OTA_JSON_PROTOCOLS_KEY   OTA_JSON_OTA_UNIT_KEY OTA_JSON_SEPARATOR "protocols"
	Protocols over which the download can take place.
#define	OTA_JSON_FILE_GROUP_KEY   OTA_JSON_OTA_UNIT_KEY OTA_JSON_SEPARATOR "files"
	Parameters for specifying file configurations.
#define	OTA_JSON_STREAM_NAME_KEY   OTA_JSON_OTA_UNIT_KEY OTA_JSON_SEPARATOR "streamname"
	Name of the stream used for download.
#define	OTA_JSON_FILE_PATH_KEY   "filepath"
	Path to store the image on the device.
#define	OTA_JSON_FILE_SIZE_KEY   "filesize"
	Size of the file to be downloaded.
#define	OTA_JSON_FILE_ID_KEY   "fileid"
	Used to identify the file in case of multiple file downloads.
#define	OTA_JSON_FILE_ATTRIBUTE_KEY   "attr"
	Additional file attributes.
#define	OTA_JSON_FILE_CERT_NAME_KEY   "certfile"
	Location of the certificate on the device to find code signing.
#define	OTA_JSON_UPDATE_DATA_URL_KEY   "update_data_url"
	S3 bucket presigned url to fetch the image from .
#define	OTA_JSON_AUTH_SCHEME_KEY   "auth_scheme"
	Authentication scheme for downloading a the image over HTTP.
#define	OTA_JSON_FILETYPE_KEY   "fileType"
	Used to identify the file in case of multi file type support.

Enumerations
enum	IngestResult_t {   IngestResultFileComplete = -1 , IngestResultSigCheckFail = -2 , IngestResultFileCloseFail = -3 , IngestResultNullInput = -4 ,   IngestResultBadFileHandle = -5 , IngestResultUnexpectedBlock = -6 , IngestResultBlockOutOfRange = -7 , IngestResultBadData = -8 ,   IngestResultWriteBlockFailed = -9 , IngestResultNoDecodeMemory = -10 , IngestResultUninitialized = -127 , IngestResultAccepted_Continue = 0 ,   IngestResultDuplicate_Continue = 1 }
	Data ingest results. More...
enum	DocParseErr_t {   DocParseErrUnknown = -1 , DocParseErrNone = 0 , DocParseErrOutOfMemory , DocParseErrUserBufferInsuffcient ,   DocParseErrFieldTypeMismatch , DocParseErrBase64Decode , DocParseErrInvalidNumChar , DocParseErrDuplicatesNotAllowed ,   DocParseErrMalformedDoc , DocParseErr_InvalidJSONBuffer , DocParseErrNullModelPointer , DocParseErrNullBodyPointer ,   DocParseErrNullDocPointer , DocParseErrTooManyParams , DocParseErrParamKeyNotInModel , DocParseErrInvalidModelParamType ,   DocParseErrInvalidToken }
	Generic JSON document parser errors. More...
enum	ModelParamType_t {   ModelParamTypeStringCopy , ModelParamTypeStringInDoc , ModelParamTypeObject , ModelParamTypeArray ,   ModelParamTypeUInt32 , ModelParamTypeSigBase64 , ModelParamTypeIdent , ModelParamTypeArrayCopy }
	Document model parameter types used by the JSON document parser. More...
enum	OtaJobReason_t {   JobReasonReceiving = 0 , JobReasonSigCheckPassed , JobReasonSelfTestActive , JobReasonAccepted ,   JobReasonRejected , JobReasonAborted , NumJobReasons }
	Gives the reason to set for job parsing operation. More...
enum	OtaImageState_t {   OtaImageStateUnknown = 0 , OtaImageStateTesting = 1 , OtaImageStateAccepted = 2 , OtaImageStateRejected = 3 ,   OtaImageStateAborted = 4 , OtaLastImageState = OtaImageStateAborted }
	OTA Image states. More...
enum	OtaPalImageState_t { OtaPalImageStateUnknown = 0 , OtaPalImageStatePendingCommit , OtaPalImageStateValid , OtaPalImageStateInvalid }
	OTA Platform Image State. More...
enum	OtaEvent_t {   OtaAgentEventStart = 0 , OtaAgentEventStartSelfTest , OtaAgentEventRequestJobDocument , OtaAgentEventReceivedJobDocument ,   OtaAgentEventCreateFile , OtaAgentEventRequestFileBlock , OtaAgentEventReceivedFileBlock , OtaAgentEventRequestTimer ,   OtaAgentEventCloseFile , OtaAgentEventSuspend , OtaAgentEventResume , OtaAgentEventUserAbort ,   OtaAgentEventShutdown , OtaAgentEventMax }
	OTA Agent Events. More...

Detailed Description

Macros, enums, variables, and definitions internal to the OTA Agent module and shared by other OTA modules and testing files.

Macro Definition Documentation

OTA_NUM_JOB_PARAMS

#define OTA_NUM_JOB_PARAMS   ( 21 )

Number of parameters in the job document.

OTA_JOB_ID_MAX_SIZE

#define OTA_JOB_ID_MAX_SIZE   ( 72UL + 1UL )

Maximum size of the Job ID.

OTA_PROTOCOL_BUFFER_SIZE

#define OTA_PROTOCOL_BUFFER_SIZE   20U

Size of the buffer used to store the protocol field of the job document.

Enumeration Type Documentation

IngestResult_t

enum IngestResult_t

Data ingest results.

The negative error codes represent actual error in ingesting the data block whereas the positive error codes represent success and other conditions that are not ingest errors like duplicate block is received.

Enumerator
IngestResultFileComplete	The file transfer is complete and the signature check passed.
IngestResultSigCheckFail	The file transfer is complete but the signature check failed.
IngestResultFileCloseFail	There was a problem trying to close the receive file.
IngestResultNullInput	One of the input pointers is NULL.
IngestResultBadFileHandle	The receive file pointer is invalid.
IngestResultUnexpectedBlock	We were asked to ingest a block but were not expecting one.
IngestResultBlockOutOfRange	The received block is out of the expected range.
IngestResultBadData	The data block from the server was malformed.
IngestResultWriteBlockFailed	The PAL layer failed to write the file block.
IngestResultNoDecodeMemory	Memory could not be allocated for decoding .
IngestResultUninitialized	Software BUG: We forgot to set the result code.
IngestResultAccepted_Continue	The block was accepted and we're expecting more.
IngestResultDuplicate_Continue	The block was a duplicate but that's OK. Continue.

DocParseErr_t

enum DocParseErr_t

Generic JSON document parser errors.

Enumerator
DocParseErrUnknown	The error code has not yet been set by a logic path.
DocParseErrNone	No error in parsing the document.
DocParseErrOutOfMemory	We failed to allocate enough dynamic memory for a field.
DocParseErrUserBufferInsuffcient	The supplied user buffer is insufficient for a field.
DocParseErrFieldTypeMismatch	The field type parsed does not match the document model.
DocParseErrBase64Decode	There was an error decoding the base64 data.
DocParseErrInvalidNumChar	There was an invalid character in a numeric value field.
DocParseErrDuplicatesNotAllowed	A duplicate parameter was found in the job document.
DocParseErrMalformedDoc	The document didn't fulfill the model requirements.
DocParseErr_InvalidJSONBuffer	When the JSON is malformed and not parsed correctly.
DocParseErrNullModelPointer	The pointer to the document model was NULL.
DocParseErrNullBodyPointer	The document model's internal body pointer was NULL.
DocParseErrNullDocPointer	The pointer to the JSON document was NULL.
DocParseErrTooManyParams	The document model has more parameters than we can handle.
DocParseErrParamKeyNotInModel	The document model does not include the specified parameter key.
DocParseErrInvalidModelParamType	The document model specified an invalid parameter type.
DocParseErrInvalidToken	The Jasmine token was invalid, producing a NULL pointer.

ModelParamType_t

enum ModelParamType_t

Document model parameter types used by the JSON document parser.

OtaJobReason_t

enum OtaJobReason_t

Gives the reason to set for job parsing operation.