#include <stdint.h>
#include <stdbool.h>
#include "sha256sw.h"
#include "../inc/hw_flash.h"

Include dependency graph for hapi.h:

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

Data Structures
struct	HARD_API_T

Macros
#define	FLASH_API_KEY 0xB7E3A08FU

#define	FLASH_BANK_0 FLASH_CMDCTL_BANKSEL_BANK0

#define	FLASH_BANK_1 FLASH_CMDCTL_BANKSEL_BANK1

#define	HAPI_TABLE_BASE_ADDR 0x0F00004C

#define	P_HAPITAB ((const HARD_API_T *)HAPI_TABLE_BASE_ADDR)

#define	HapiEnterStandby(copyList) (P_HAPITAB->pEnterStandby((copyList)))
	Enter standby power state Stores the full state of the CPU to MSP call stack so that it can get restored once we come back out of standby (at which point CPU is reset). When exiting standby the CPU will appear to return from this function. More...

#define	HapiCrc32(data, nBytes) (P_HAPITAB->pCrc32((data), (nBytes)))
	Calculate CRC32 over a data image CRC32 implementation that uses a 256-entry LUT. More...

#define	HapiApplyCopyList(list) (P_HAPITAB->pApplyCopyList((list)))
	Process copy list Processes a copy list in a flexible CopyList format. Used by trims in FCFG, for user-defined initialization in CCFG and may be used by peripheral drivers to do HW reinitialization during wakeup from standby. The copy list is processed as a sequence of 32b command words, followed by zero or more literal words (LW): More...

#define	HapiFlashSectorErase(key, addr) (P_HAPITAB->pFlashSectorErase((key), (addr)))
	Erase a flash sector. More...

#define	HapiFlashBankErase(key, bankSelect) (P_HAPITAB->pFlashBankErase((key), (bankSelect)))
	Erase the specified bank. More...

#define	HapiFlashProgram(key, data, addr, nBytes) (P_HAPITAB->pFlashProgram((key), (data), (addr), (nBytes)))
	Program to flash (FCFG, CCFG or MAIN) More...

#define	HapiCountBits(word) (P_HAPITAB->pCountBits((word)))
	Return Hamming weight (# bits that are set) of word. More...

#define	HapiSecdedEncode(parity, data, nWords64) (P_HAPITAB->pSecdedEncode((parity), (data), (nWords64)))
	Perform SECDED encoding over data array and produce parity array. More...

#define	HapiSecdedDecode(data, parity, nWords64) (P_HAPITAB->pSecdedDecode((data), (parity), (nWords64)))
	Perform SECDED correction/detection over data array using parity array Uses the usual (72,64) SECDED generator matrix. More...

#define	HapiSha256SwHashData(handle, data, length, digest) (P_HAPITAB->pSha256SwHashData((handle), SHA2SW_HASH_TYPE_256, (data), (length), (digest)))
	Performs a complete SHA256 hash operation, producing a final digest for the data. More...

#define	HapiSha256SwStart(handle) (P_HAPITAB->pSha256SwStart((handle), SHA2SW_HASH_TYPE_256))
	Initialize a SHA256SW_Handle, preparing for hashing data. More...

#define	HapiSha256SwAddData(handle, data, length) (P_HAPITAB->pSha256SwAddData((handle), (data), (length)))
	Add data to a SHA256 operation. More...

#define	HapiSha256SwFinalize(handle, digest) (P_HAPITAB->pSha256SwFinalize((handle), (digest)))
	Finalize a SHA256 operation, creating the final digest. More...

#define	HapiResetDevice() (P_HAPITAB->pResetDevice())
	Perform system reset of the device. More...

#define	HapiSha256SWProcessBlock(d, w) (P_HAPITAB->pSHA256SWProcessBlock((d), (w)))

#define	HapiSha256SW_K256 (*P_HAPITAB->pSHA256SW_K256)

#define	HapiSha256SW_initialDigest256 (*P_HAPITAB->pSHA256SW_initialDigest256)

#define	HapiWaitUs(nUs) (P_HAPITAB->pWaitUs((nUs)))
	Wait function. More...

#define	HapiClz(x) (P_HAPITAB->pClz((x)))
	Count leading zeros. More...

#define	HapiSbSetUpdateImageAddress(addr) (P_HAPITAB->pSbSetUpdateImageAddress((addr)))
	Set the update image address in the 3v3 flags. More...

#define	HapiSbGetUpdateImageAddress() (P_HAPITAB->pSbGetUpdateImageAddress())
	Get the current update image address from the 3v3 flags. More...

#define	HapiSbSetId(id) (P_HAPITAB->pSbSetId((id)))
	Set the update request ID field in the 3v3 flags. More...

#define	HapiSbGetId() (P_HAPITAB->pSbGetId())
	Get the current update request ID from the 3v3 flags. More...

#define	HapiSbSetStatus(status) (P_HAPITAB->pSbSetStatus((status)))
	Set the update status field in the 3v3 flags. More...

#define	HapiSbGetStatus() (P_HAPITAB->pSbGetStatus())
	Get the current update status from the 3v3 flags. More...

#define	HapiSetTcmSync(syncVal) (P_HAPITAB->pSetTcmSync((syncVal)))
	Set TCM sync value to facilitate TCM Gasket configuration. More...

Macro Definition Documentation

§ FLASH_API_KEY

#define FLASH_API_KEY 0xB7E3A08FU

Magic value used to protect against inadvertent flash erasures/programming. (prevents corruption due to random jumps into the flash API, for example due to stack overflow or errant function pointers) Must be passed in key argument to all flash functions

Referenced by FlashEraseBank(), FlashEraseSector(), and FlashProgram().

§ FLASH_BANK_0

#define FLASH_BANK_0 FLASH_CMDCTL_BANKSEL_BANK0

§ FLASH_BANK_1

#define FLASH_BANK_1 FLASH_CMDCTL_BANKSEL_BANK1

§ HAPI_TABLE_BASE_ADDR

#define HAPI_TABLE_BASE_ADDR 0x0F00004C

§ P_HAPITAB

#define P_HAPITAB ((const HARD_API_T *)HAPI_TABLE_BASE_ADDR)

§ HapiEnterStandby

#define HapiEnterStandby ( copyList ) (P_HAPITAB->pEnterStandby((copyList)))

Enter standby power state Stores the full state of the CPU to MSP call stack so that it can get restored once we come back out of standby (at which point CPU is reset). When exiting standby the CPU will appear to return from this function.

Parameters

[in] copyList If non-null, the copy list to apply through ApplyCopyList() in the AsmExitStandby function while waiting for flash to become ready.

Precondition

Execution state is privileged and call stack being used is MSP
MSP call stack must reside in retained SRAM (obviously)
Interrupts have been turned off with CPSID but interrupts enabled in NVIC
Wakeup event(s) have been configured in AON event fabric
SCB.SCR.DSLP_EN=0 (if not, in debug standby exit will enter standby again)

Warning: The preconditions must be followed to the letter or bad things will happen

Note: Clobbers r0-r3 (normal per AAPCS)

§ HapiCrc32

#define HapiCrc32	(	data,
		nBytes
	)	(P_HAPITAB->pCrc32((data), (nBytes)))

Calculate CRC32 over a data image CRC32 implementation that uses a 256-entry LUT.

Parameters

[in]	data	Pointer to the image data
[in]	nBytes	Size of image in bytes

Returns: CRC-32 checksum of the image

§ HapiApplyCopyList

#define HapiApplyCopyList ( list ) (P_HAPITAB->pApplyCopyList((list)))

Process copy list Processes a copy list in a flexible CopyList format. Used by trims in FCFG, for user-defined initialization in CCFG and may be used by peripheral drivers to do HW reinitialization during wakeup from standby. The copy list is processed as a sequence of 32b command words, followed by zero or more literal words (LW):

Command	31:28	27:20	19:2	1:0	LW	Description
EOL	0000	0000_0000	0000_0000_0000_0000_00	00	0	End-of-list
WAIT(N)	0001	0000_0000	nnnn_nnnn_nnnn_nnnn_nn	00	0	Wait N/12 us
NOP = WAIT(0)	0001	0000_0000	0000_0000_0000_0000_00	00	0	No operation
CPY(A*,N)	aaaa	nnnn_nnnn	aaaa_aaaa_aaaa_aaaa_aa	00	N	Copy N literal words to address A*
CPY(A,1)	aaaa	aaaa_aaaa	aaaa_aaaa_aaaa_aaaa_aa	01	1	Copy single literal word to full address A
JMP(A)	aaaa	aaaa_aaaa	aaaa_aaaa_aaaa_aaaa_aa	10	0	Jump to new list at full address A
CALL(A)	aaaa	aaaa_aaaa	aaaa_aaaa_aaaa_aaaa_aa	11	0	Recurse to list at full address A

A* is a reduced address space that covers all SRAM and peripheral space. Bits 27:20 of this address will be assumed to be all zero. Full addresses must have 32b alignment

Parameters

[in] list Pointer to the copy list

Referenced by CopyList_apply().

§ HapiFlashSectorErase

#define HapiFlashSectorErase	(	key,
		addr
	)	(P_HAPITAB->pFlashSectorErase((key), (addr)))

Erase a flash sector.

Erase the flash sector that begins at address addr. Function will not return before erase operation completes or error occurs. Only main sectors and the CCFG sector is supported and are subject to flash write/erase restrictions. No default data is written back to CCFG after an erase.

Warning: No accesses to flash may occur during an erase operation. Interrupts must be disabled prior to calling or care taken that no reads to flash occur. DMA operations targeting flash must be suspended.

Parameters

key	Magic number FLASH_API_KEY (0xB7E3A08F) to protect against inadvertent flash erasures
addr	First address of a main sector or the CCFG sector

Returns

Return code

Referenced by FlashEraseSector().

§ HapiFlashBankErase

#define HapiFlashBankErase	(	key,
		bankSelect
	)	(P_HAPITAB->pFlashBankErase((key), (bankSelect)))

Erase the specified bank.

This function will erase all main flash sectors in the specified bank

Warning: Please note that code can not execute in flash while any part of the flash is being programmed or erased. The application must disable interrupts that have interrupt routines in flash.

Parameters

key	A magic number that must be FLASH_API_KEY. The key protects against random jumps into the flash API
bankSelect	The selection between which bank to erase. FLASH_BANK_0 or FLASH_BANK_1.

Returns

Returns the status of the sector erase:

FAPI_STATUS_SUCCESS (0) : Success.
FAPI_STATUS_INCORRECT_DATABUFFER_LENGTH : Invalid argument.
FAPI_STATUS_FSM_ERROR : A programming error is encountered.

Referenced by FlashEraseBank().

§ HapiFlashProgram

#define HapiFlashProgram	(	key,
		data,
		addr,
		nBytes
	)	(P_HAPITAB->pFlashProgram((key), (data), (addr), (nBytes)))

Program to flash (FCFG, CCFG or MAIN)

This function programs a sequence of bytes into the on-chip flash. Programming each location consists of the result of an AND operation of the new data and the existing data; in other words bits that contain 1 can remain 1 or be changed to 0, but bits that are 0 cannot be changed to 1. Therefore, a byte can be programmed multiple times as long as these rules are followed; if a program operation attempts to change a 0 bit to a 1 bit, that bit will not have its value changed.

Programming may cross main sector boundaries. This function does not return until the data has been programmed or a programming error occurs.

Note: It is recommended to disable cache and line buffer before programming the flash and re-enable/clear cache and line buffer when the program operation completes.

Warning: Please note that code can not execute in flash while any part of the flash is being programmed or erased. The application must disable interrupts that have interrupt routines in flash.; The data pointer can not point to flash.

Parameters

key	A magic number that must be FLASH_API_KEY. The key protects against random jumps into the flash API
data	A pointer to the data to be programmed
addr	The starting address in flash to be programmed
nBytes	The number of bytes to be programmed

Returns

Returns status of the flash programming:

FAPI_STATUS_SUCCESS (0) : Success.
FAPI_STATUS_INCORRECT_DATABUFFER_LENGTH : Too many bytes were requested.
FAPI_STATUS_FSM_ERROR : A programming error is encountered.

Referenced by FlashProgram().

§ HapiCountBits

#define HapiCountBits ( word ) (P_HAPITAB->pCountBits((word)))

Return Hamming weight (# bits that are set) of word.

Parameters

[in] word 32-bit word to count bits for

Returns: Number of bits set in word (0-32)

§ HapiSecdedEncode

#define HapiSecdedEncode	(	parity,
		data,
		nWords64
	)	(P_HAPITAB->pSecdedEncode((parity), (data), (nWords64)))

Perform SECDED encoding over data array and produce parity array.

Uses the usual (72,64) SECDED generator matrix:

    DDDDDDDD DDDDDDDD DDDDDDDD DDDDDDDD DDDDDDDD DDDDDDDD DDDDDDDD DDDDDDDD  PPPPPPPP
    66665555 55555544 44444444 33333333 33222222 22221111 11111100 00000000  00000000
    32109876 54321098 76543210 98765432 10987654 32109876 54321098 76543210  76543210
-------------------------------------------------------------------------------------
P7: 11111111 11111111 11111111 11111111 11111111 11111111 11111111 11111111  01111111
P6: 11111111 11111111 11111111 11111111 11111111 11111111 11111111 11111110  00000000
P5: 11111111 11111111 11111111 11111111 00000000 00000000 00000000 00000001  00000000
P4: 11111111 11111111 00000000 00000000 11111111 11111111 00000000 00000001  00000000
P3: 11111111 00000000 11111111 00000000 11111111 00000000 11111111 00000001  00000000
P2: 11110000 11110000 11110000 11110000 11110000 11110000 11110000 11110001  00000000
P1: 11001100 11001100 11001100 11001100 11001100 11001100 11001100 11001101  00000000
P0: 10101010 10101010 10101010 10101010 10101010 10101010 10101010 10101011  00000000

Parameters

[out]	parity	Pointer to where to store parity bytes (one byte per 64b word of data)
[in]	data	Pointer to the data (4B aligned)
[in]	nWords64	Number of 64b words of data / bytes of parity

§ HapiSecdedDecode

#define HapiSecdedDecode	(	data,
		parity,
		nWords64
	)	(P_HAPITAB->pSecdedDecode((data), (parity), (nWords64)))

Perform SECDED correction/detection over data array using parity array Uses the usual (72,64) SECDED generator matrix.

Parameters

[in,out]	data	Pointer to the data (4B aligned)
[in]	parity	Pointer to the parity bytes (one byte per 64b word of data)
[in]	nWords64	Number of 64b words of data / bytes of parity

Returns: <0: uncorrectable error detected >=0: number of bits corrected

§ HapiSha256SwHashData

#define HapiSha256SwHashData	(	handle,
		data,
		length,
		digest
	)	(P_HAPITAB->pSha256SwHashData((handle), SHA2SW_HASH_TYPE_256, (data), (length), (digest)))

Performs a complete SHA256 hash operation, producing a final digest for the data.

This function wraps HapiSha256SwStart(), HapiSha256SwAddData(), and HapiSha256SwFinalize().

There is no need to call HapiSha256SwStart() prior to calling this function.

The total length of data that can be hashed by this implementation is 512MiB (0x20000000 bytes.)

Parameters

[in]	handle	A SHA256SW_Handle.
[in]	data	Data (message) to hash. May point to zero.
[in]	length	The number of bytes (pointed to by `data` parameter) to add to the hash.
[out]	digest	Output location for the final digest. Must be able to hold 32 bytes of output and be 32-bit aligned.

Return values

SHA2SW_STATUS_SUCCESS	(0) The hash operation succeeded.
SHA2SW_STATUS_ERROR	The hash operation failed.
SHA2SW_STATUS_UNSUPPORTED	Requested Hash Type is unsupported.
SHA2SW_STATUS_LENGTH_TOO_LARGE	The requested length of data to hash is more than the implementation supports.
SHA2SW_STATUS_NULL_INPUT	One or more of the pointer inputs is NULL.

§ HapiSha256SwStart

#define HapiSha256SwStart ( handle ) (P_HAPITAB->pSha256SwStart((handle), SHA2SW_HASH_TYPE_256))

Initialize a SHA256SW_Handle, preparing for hashing data.

Parameters

[in] handle A SHA256SW_Handle.

Return values

SHA2SW_STATUS_SUCCESS	(0) The hash operation succeeded.
SHA2SW_STATUS_UNSUPPORTED	Requested Hash Type is unsupported.
SHA2SW_STATUS_NULL_INPUT	One or more of the pointer inputs is NULL.

See also: HapiSha256SwAddData(); HapiSha256SwFinalize()

§ HapiSha256SwAddData

#define HapiSha256SwAddData	(	handle,
		data,
		length
	)	(P_HAPITAB->pSha256SwAddData((handle), (data), (length)))

Add data to a SHA256 operation.

Adds data to a hash operation. The handle must have been initialized by a call to HapiSha256SwStart first.

The total length of data that can be hashed by this implementation is 512MiB (0x20000000 bytes.)

After passing in all data to be hashed, call HapiSha256SwFinalize() to obtain the final digest.

Precondition: handle was previously passed to HapiSha256SwStart().

Parameters

[in]	handle	A SHA256SW_Handle.
[in]	data	Data (message) to add to the hash. May point to zero.
[in]	length	The number of bytes (pointed to by `data` parameter) to add to the hash.

Return values

SHA2SW_STATUS_SUCCESS	(0) The hash operation succeeded.
SHA2SW_STATUS_LENGTH_TOO_LARGE	The requested length of data to hash is more than the implementation supports.
SHA2SW_STATUS_NULL_INPUT	One or more of the pointer inputs is NULL.

See also: HapiSha256SwStart(); HapiSha256SwFinalize()

§ HapiSha256SwFinalize

#define HapiSha256SwFinalize	(	handle,
		digest
	)	(P_HAPITAB->pSha256SwFinalize((handle), (digest)))

Finalize a SHA256 operation, creating the final digest.

After calling this function, handle should not be used again until it has been reinitialized via a call to HapiSha256SwStart().

Precondition: handle was previously passed to HapiSha256SwStart() and data to be hashed was passed to HapiSha256SwAddData()

Parameters

[in]	handle	A SHA256SW_Handle.
[out]	digest	Output location for the final digest. Must be able to hold 32 bytes of output and be 32-bit aligned.

Return values

SHA2SW_STATUS_SUCCESS	(0) The hash operation succeeded.
SHA2SW_STATUS_NULL_INPUT	One or more of the pointer inputs is NULL.

See also: HapiSha256SwStart(); HapiSha256SwAddData()

§ HapiResetDevice

#define HapiResetDevice ( ) (P_HAPITAB->pResetDevice())

Perform system reset of the device.

This function will perform a system reset of the device equal to a pin reset. Software can determine that this was the cause of reset once rebooted. The function will never return.

§ HapiSha256SWProcessBlock

#define HapiSha256SWProcessBlock	(	d,
		w
	)	(P_HAPITAB->pSHA256SWProcessBlock((d), (w)))

§ HapiSha256SW_K256

#define HapiSha256SW_K256 (*P_HAPITAB->pSHA256SW_K256)

§ HapiSha256SW_initialDigest256

#define HapiSha256SW_initialDigest256 (*P_HAPITAB->pSHA256SW_initialDigest256)

§ HapiWaitUs

#define HapiWaitUs ( nUs ) (P_HAPITAB->pWaitUs((nUs)))

Wait function.

Parameters

[in] nUs Number of microseconds to wait (min: 1 us, max: 2^26 us)

Referenced by HapiWaitUs_veneer().

§ HapiClz

#define HapiClz ( x ) (P_HAPITAB->pClz((x)))

Count leading zeros.

Parameters

[in] x Value to count leading zeros for

Returns: Number of leading zeroes (0 to 32)

§ HapiSbSetUpdateImageAddress

#define HapiSbSetUpdateImageAddress ( addr ) (P_HAPITAB->pSbSetUpdateImageAddress((addr)))

Set the update image address in the 3v3 flags.

Parameters

[in] addr Address pointing to the image you wish for ROM to verify and update to

Returns: The new value of the update image address

§ HapiSbGetUpdateImageAddress

#define HapiSbGetUpdateImageAddress ( ) (P_HAPITAB->pSbGetUpdateImageAddress())

Get the current update image address from the 3v3 flags.

Returns: The current value of update image address

§ HapiSbSetId

#define HapiSbSetId ( id ) (P_HAPITAB->pSbSetId((id)))

Set the update request ID field in the 3v3 flags.

Parameters

[in] id The ID of the request you wish for ROM to do

Returns: The new value of the update request ID

§ HapiSbGetId

#define HapiSbGetId ( ) (P_HAPITAB->pSbGetId())

Get the current update request ID from the 3v3 flags.

Returns: The current value of the update request ID

§ HapiSbSetStatus

#define HapiSbSetStatus ( status ) (P_HAPITAB->pSbSetStatus((status)))

Set the update status field in the 3v3 flags.

Parameters

[in] status The update status you wish to write to the 3v3 flags

Returns: The new value of the update status

§ HapiSbGetStatus

#define HapiSbGetStatus ( ) (P_HAPITAB->pSbGetStatus())

Get the current update status from the 3v3 flags.

Returns: The current value of the update status

§ HapiSetTcmSync

#define HapiSetTcmSync ( syncVal ) (P_HAPITAB->pSetTcmSync((syncVal)))

Set TCM sync value to facilitate TCM Gasket configuration.

This function must be called before and after updating the TCM Gasket config on the device. Calling this function with a s of 1 will prepare the TCM for reconfiguration. Calling this function with a s of 0 will complete the reconfiguration and synchronize the changes.

Precondition: The caller must ensure that all bus masters are disabled and that all interrupts are disabled prior to calling this function

Parameters

[in] syncVal The new sync value [0, 1]

Returns: The result of the operation. True if it was successfull and false otherwise

Data Structures

Macros

Macro Definition Documentation

§ FLASH_API_KEY

§ FLASH_BANK_0

§ FLASH_BANK_1

§ HAPI_TABLE_BASE_ADDR

§ P_HAPITAB

§ HapiEnterStandby

§ HapiCrc32

§ HapiApplyCopyList

§ HapiFlashSectorErase

§ HapiFlashBankErase

§ HapiFlashProgram

§ HapiCountBits

§ HapiSecdedEncode

§ HapiSecdedDecode

§ HapiSha256SwHashData

§ HapiSha256SwStart

§ HapiSha256SwAddData

§ HapiSha256SwFinalize

§ HapiResetDevice

§ HapiSha256SWProcessBlock

§ HapiSha256SW_K256

§ HapiSha256SW_initialDigest256

§ HapiWaitUs

§ HapiClz

§ HapiSbSetUpdateImageAddress

§ HapiSbGetUpdateImageAddress

§ HapiSbSetId

§ HapiSbGetId

§ HapiSbSetStatus

§ HapiSbGetStatus

§ HapiSetTcmSync