NXP
Data Structures | Defines | Typedefs | Functions | Variables

Component : Pn5180Download Library

Library for Pn5180 secure firmware download. More...


Detailed Description

Library for Pn5180 secure firmware download.

Data Structures

struct  phDlhalHw_Pn5180_Download_IntegrityInformation
 Integrity information structure. More...
struct  phDlhalHw_Pn5180_Download_SessionStateInformation
 Download session state information structure. More...
struct  phDlhalHw_Pn5180_DL_DataParams
 PN5180 Download main structure. More...

Defines

#define PH_DLHAL_HW_PN5180_DOWNLOAD_MODE_ENABLE   1
 Download mode enable.
#define PH_DLHAL_HW_PN5180_DOWNLOAD_MODE_DISABLE   0
 Download mode disable.

Typedefs

typedef struct
phDlhalHw_Pn5180_Download_IntegrityInformation 
phDlhalHw_Pn5180_Download_IntegrityInformation_t
 Integrity information structure.
typedef struct
phDlhalHw_Pn5180_Download_SessionStateInformation 
phDlhalHw_Pn5180_Download_SessionStateInformation_t
 Download session state information structure.
typedef struct
phDlhalHw_Pn5180_DL_DataParams 
phDlhalHw_Pn5180_DL_DataParams_t
 PN5180 Download main structure.

Functions

phStatus_t phDlhalHw_Pn5180_Download_Init (phDlhalHw_Pn5180_DL_DataParams_t *pDlDataParams, void *pbalparams, uint8_t *pTxBuffer, uint16_t wTxBufSize, uint8_t *pRxBuffer, uint16_t wRxBufSize)
 Initialization of the PN5180 Download Library.
phStatus_t phDlhalHw_Pn5180_Download_PerformSecureFirmwareUpdate (phDlhalHw_Pn5180_DL_DataParams_t *pDlDataParams, uint8_t *pImage, uint32_t dwSizeOfImage)
 Perform a Secure Firmware Update and checks the integrity of updated firmware.
phStatus_t phDlhalHw_Pn5180_Download_Read (phDlhalHw_Pn5180_DL_DataParams_t *pDlDataParams, uint16_t wLength, uint32_t dwAddress, uint8_t **ppReadBuffer)
 Perform a read.
phStatus_t phDlhalHw_Pn5180_Download_CheckIntegrity (phDlhalHw_Pn5180_DL_DataParams_t *pDlDataParams, phDlhalHw_Pn5180_Download_IntegrityInformation_t *pIntegrityCheckResult)
 Perform an Integrity Check of the updated Image.
phStatus_t phDlhalHw_Pn5180_Download_CheckSessionState (phDlhalHw_Pn5180_DL_DataParams_t *pDlDataParams, phDlhalHw_Pn5180_Download_SessionStateInformation_t *sSSTAInfo)
 Check and return current download session state.
phStatus_t phDlhalHw_Pn5180_Download_PerformSoftReset (phDlhalHw_Pn5180_DL_DataParams_t *pDlDataParams)
 Issues a soft reset command.
phStatus_t phDlhalHw_Pn5180_Download_GetFirmwareVersion (phDlhalHw_Pn5180_DL_DataParams_t *pDlDataParams, uint8_t *pMajorVersion, uint8_t *pMinorVersion)
 Reads out version of current firmware.
phStatus_t phDlhalHw_Pn5180_Download_GetDieId (phDlhalHw_Pn5180_DL_DataParams_t *pDlDataParams, uint8_t *pDieId)
 Returns Die-ID.

Variables

uint8_t phDlhalHw_Pn5180_Download_IntegrityInformation::bFunctionCodeOk
 1: means function code integrity is good.
uint8_t phDlhalHw_Pn5180_Download_IntegrityInformation::bPatchCodeOk
 1: means patch code integrity is good.
uint8_t phDlhalHw_Pn5180_Download_IntegrityInformation::bUserDataOk
 1: means User Data integrity is good.
uint8_t phDlhalHw_Pn5180_Download_SessionStateInformation::bLifeCycle
 Holds the lifecycle information.
uint8_t phDlhalHw_Pn5180_DL_DataParams::bBalConnectionType
 Type of the underlying BAL connection.
void * phDlhalHw_Pn5180_DL_DataParams::pBalDataParams
 Points to the underlying layer over which HAL is going to communicate.
uint8_t * phDlhalHw_Pn5180_DL_DataParams::pTxBuffer
 Pointer to global transmit buffer used by the Exchange() function.
uint16_t phDlhalHw_Pn5180_DL_DataParams::wTxBufSize
 Size of the global transmit buffer.
uint8_t * phDlhalHw_Pn5180_DL_DataParams::pRxBuffer
 Pointer to global receive buffer used by the Exchange() function.
uint16_t phDlhalHw_Pn5180_DL_DataParams::wRxBufSize
 Size of the global receive buffer.
uint32_t phDlhalHw_Pn5180_DL_DataParams::dwAdditionalInfo
 Storage for additional error information.

Possible returning error codes

#define PH_DLHAL_HW_PN5180_DOWNLOAD_ERR_INVALID_ADDR   (PH_COMP_GENERIC + 0x01)
 Trying to read or write an invalid address.
#define PH_DLHAL_HW_PN5180_DOWNLOAD_ERR_GENERIC_ERROR   (PH_COMP_GENERIC + 0x02)
 Generic error occurred.
#define PH_DLHAL_HW_PN5180_DOWNLOAD_ERR_UNKNOWN_CMD   (PH_COMP_GENERIC + 0x0B)
 Unknown Command.
#define PH_DLHAL_HW_PN5180_DOWNLOAD_ERR_ABORTED_CMD   (PH_COMP_GENERIC + 0x0C)
 Chunk sequence is large .
#define PH_DLHAL_HW_PN5180_DOWNLOAD_ERR_PLL_ERROR   (PH_COMP_GENERIC + 0x0D)
 PLL configuration is wrong, flash not activated.
#define PH_DLHAL_HW_PN5180_DOWNLOAD_ERR_ADDRESS_RANGE_OVERFLOW   (PH_COMP_GENERIC + 0x1E)
 Write/read performed outside of address range.
#define PH_DLHAL_HW_PN5180_DOWNLOAD_ERR_BUFFER_OVERFLOW   (PH_COMP_GENERIC + 0x1F)
 Buffer overflow error.
#define PH_DLHAL_HW_PN5180_DOWNLOAD_ERR_MEMORY_BUSY   (PH_COMP_GENERIC + 0x20)
 EEPROM Memory operation in progress.
#define PH_DLHAL_HW_PN5180_DOWNLOAD_ERR_SIGNATURE_ERROR   (PH_COMP_GENERIC + 0x21)
 Signature mismatch.
#define PH_DLHAL_HW_PN5180_DOWNLOAD_ERR_FIRMWARE_VERSION_ERROR   (PH_COMP_GENERIC + 0x24)
 trying to write same firmware version.
#define PH_DLHAL_HW_PN5180_DOWNLOAD_ERR_PROTOCOL_ERROR   (PH_COMP_GENERIC + 0x28)
 Download protocol error.
#define PH_DLHAL_HW_PN5180_DOWNLOAD_ERR_DEGRADED   (PH_COMP_GENERIC + 0x2A)
 EEPROM corruption.

Define Documentation

#define PH_DLHAL_HW_PN5180_DOWNLOAD_MODE_ENABLE   1

Download mode enable.

#define PH_DLHAL_HW_PN5180_DOWNLOAD_MODE_DISABLE   0

Download mode disable.

#define PH_DLHAL_HW_PN5180_DOWNLOAD_ERR_INVALID_ADDR   (PH_COMP_GENERIC + 0x01)

Trying to read or write an invalid address.

#define PH_DLHAL_HW_PN5180_DOWNLOAD_ERR_GENERIC_ERROR   (PH_COMP_GENERIC + 0x02)

Generic error occurred.

#define PH_DLHAL_HW_PN5180_DOWNLOAD_ERR_UNKNOWN_CMD   (PH_COMP_GENERIC + 0x0B)

Unknown Command.

#define PH_DLHAL_HW_PN5180_DOWNLOAD_ERR_ABORTED_CMD   (PH_COMP_GENERIC + 0x0C)

Chunk sequence is large .

#define PH_DLHAL_HW_PN5180_DOWNLOAD_ERR_PLL_ERROR   (PH_COMP_GENERIC + 0x0D)

PLL configuration is wrong, flash not activated.

#define PH_DLHAL_HW_PN5180_DOWNLOAD_ERR_ADDRESS_RANGE_OVERFLOW   (PH_COMP_GENERIC + 0x1E)

Write/read performed outside of address range.

#define PH_DLHAL_HW_PN5180_DOWNLOAD_ERR_BUFFER_OVERFLOW   (PH_COMP_GENERIC + 0x1F)

Buffer overflow error.

#define PH_DLHAL_HW_PN5180_DOWNLOAD_ERR_MEMORY_BUSY   (PH_COMP_GENERIC + 0x20)

EEPROM Memory operation in progress.

#define PH_DLHAL_HW_PN5180_DOWNLOAD_ERR_SIGNATURE_ERROR   (PH_COMP_GENERIC + 0x21)

Signature mismatch.

#define PH_DLHAL_HW_PN5180_DOWNLOAD_ERR_FIRMWARE_VERSION_ERROR   (PH_COMP_GENERIC + 0x24)

trying to write same firmware version.

#define PH_DLHAL_HW_PN5180_DOWNLOAD_ERR_PROTOCOL_ERROR   (PH_COMP_GENERIC + 0x28)

Download protocol error.

#define PH_DLHAL_HW_PN5180_DOWNLOAD_ERR_DEGRADED   (PH_COMP_GENERIC + 0x2A)

EEPROM corruption.


Typedef Documentation

Integrity information structure.

this structure will hold the integrity information of all the applicable blocks.

Download session state information structure.

This structure will contain the session state and lifecycle information.

PN5180 Download main structure.

This structure holds all the data that are required for the PN5180 Download library operations.


Function Documentation

phStatus_t phDlhalHw_Pn5180_Download_Init ( phDlhalHw_Pn5180_DL_DataParams_t pDlDataParams,
void *  pbalparams,
uint8_t *  pTxBuffer,
uint16_t  wTxBufSize,
uint8_t *  pRxBuffer,
uint16_t  wRxBufSize 
)

Initialization of the PN5180 Download Library.

This function does the following.
1. Input parameter validation.
2. Assigns the BAL pointer.
3. Enters into download mode.
4. Initialize the transmit and receive buffers pointers.
5. Initialize the buffer sizes.
6. Initialize the buffers to 0.

Returns:
Status Code
Return values:
PH_ERR_SUCCESSwhen the Initialization is successful.
Parameters:
[in]pDlDataParamsDataParams to this layer.
[in]pbalparamsPointer to the underlying BAL component structure.
[in]pTxBufferPointer to buffer used for sending download commands to PN5180.
[in]wTxBufSizeSize of pTxBuffer. Depends on the BAL buffer size.
[in]pRxBufferPointer to buffer used for receiving download responses from PN5180.
[in]wRxBufSizeSize of pRxBuffer. Depends on the BAL buffer size.
phStatus_t phDlhalHw_Pn5180_Download_PerformSecureFirmwareUpdate ( phDlhalHw_Pn5180_DL_DataParams_t pDlDataParams,
uint8_t *  pImage,
uint32_t  dwSizeOfImage 
)

Perform a Secure Firmware Update and checks the integrity of updated firmware.

This function does the following.
1. Check Firmware version to ascertain we are not reloading the same version.
2. Perform the actual firmware update.
3. Perform a integrity checking After download.
4. Check if the session state is closed.

Returns:
Status Code
Return values:
PH_ERR_SUCCESSRegister successfully written.
PH_ERR_INVALID_PARAMETER- Invalid parameter passed.
PH_DLHAL_HW_PN5180_DOWNLOAD_ERR_FIRMWARE_VERSION_ERROR- the Firmware version on IC is same as being updated.
PH_DLHAL_HW_PN5180_DOWNLOAD_ERR_GENERIC_ERROR- when integrity check fails or the Session is not closed.
PH_DLHAL_HW_PN5180_DOWNLOAD_ERR_PROTOCOL_ERROR-Invalid response received.
Parameters:
[in]pDlDataParamsDataParams to this layer.
[in]pImagePointer to the download sequence image.
[in]dwSizeOfImageSize of the Image.
phStatus_t phDlhalHw_Pn5180_Download_Read ( phDlhalHw_Pn5180_DL_DataParams_t pDlDataParams,
uint16_t  wLength,
uint32_t  dwAddress,
uint8_t **  ppReadBuffer 
)

Perform a read.

This function can be used to read the User Area from EEPROM.The address must be within range 0x201380- 0x201F80.

Returns:
Status Code
Return values:
PH_ERR_SUCCESSRegister successfully written.
PH_ERR_INVALID_PARAMETER- Invalid parameter passed.
PH_DLHAL_HW_PN5180_DOWNLOAD_ERR_PROTOCOL_ERROR- Invalid response received.
Parameters:
[in]pDlDataParamsDataParams to this layer.
[in]wLengthLength of the data to read.
[in]dwAddressAddress to read FROM.
[in]ppReadBufferPointer to the buffer pointer.Contains First two bytes of length and then data read.
phStatus_t phDlhalHw_Pn5180_Download_CheckIntegrity ( phDlhalHw_Pn5180_DL_DataParams_t pDlDataParams,
phDlhalHw_Pn5180_Download_IntegrityInformation_t pIntegrityCheckResult 
)

Perform an Integrity Check of the updated Image.

This fuction will return the integrity information of the existing firmware and return the data in the phDlhalHw_Pn5180_Download_IntegrityInformation_t structure.

Returns:
Status Code
Return values:
PH_ERR_SUCCESSif the integrity information is read back successfully.
PH_DLHAL_HW_PN5180_DOWNLOAD_ERR_PROTOCOL_ERROR- Invalid response received.
Parameters:
[in]pDlDataParamsDataParams to this layer.
[out]pIntegrityCheckResultPointer to phDlhalHw_Pn5180_Download_IntegrityInformation_t structure where the result of the Integrity Check will be stored.
phStatus_t phDlhalHw_Pn5180_Download_CheckSessionState ( phDlhalHw_Pn5180_DL_DataParams_t pDlDataParams,
phDlhalHw_Pn5180_Download_SessionStateInformation_t sSSTAInfo 
)

Check and return current download session state.

An internal state is maintained in the firmware and the session is open when the firmware update is in progress. The session is closed only after the complete firmware is updated.

Returns:
Status Code
Return values:
PH_ERR_SUCCESSif the session state is successfully read-back.
PH_DLHAL_HW_PN5180_DOWNLOAD_ERR_PROTOCOL_ERROR- Invalid response received.
Parameters:
[in]pDlDataParamsDataParams to this layer.
[out]sSSTAInfoSessionState result .
phStatus_t phDlhalHw_Pn5180_Download_PerformSoftReset ( phDlhalHw_Pn5180_DL_DataParams_t pDlDataParams )

Issues a soft reset command.

Parameters:
In]pDlDataParams Dataparams to this layer.
Note:
This API just sends the reset command but doesn't check for proper execution of the command.
Returns:
Status Code
Return values:
PH_ERR_SUCCESSif the reset was successfully performed.
phStatus_t phDlhalHw_Pn5180_Download_GetFirmwareVersion ( phDlhalHw_Pn5180_DL_DataParams_t pDlDataParams,
uint8_t *  pMajorVersion,
uint8_t *  pMinorVersion 
)

Reads out version of current firmware.

this function will return the major and minor version.

Returns:
Status Code
Return values:
PH_ERR_SUCCESSif the firmware version is successfully read.
PH_DLHAL_HW_PN5180_DOWNLOAD_ERR_PROTOCOL_ERROR- Invalid response received.
Parameters:
[in]pDlDataParamsDataParams to this layer.
[out]pMajorVersionFirmware Major version output.
[out]pMinorVersionFirmware Minor version output.
phStatus_t phDlhalHw_Pn5180_Download_GetDieId ( phDlhalHw_Pn5180_DL_DataParams_t pDlDataParams,
uint8_t *  pDieId 
)

Returns Die-ID.

This function will return the Die-ID read out from the IC.

Returns:
Status Code
Return values:
PH_ERR_SUCCESSwhen the Die-ID is successfully read-out.
PH_DLHAL_HW_PN5180_DOWNLOAD_ERR_PROTOCOL_ERROR- Invalid response received.
Parameters:
[in]pDlDataParamsDataParams to this layer.
[out]pDieIdPointer to a buffer where the Die ID shall be stored. uint8_t[16].

Variable Documentation

1: means function code integrity is good.

1: means patch code integrity is good.

1: means User Data integrity is good.

Holds the lifecycle information.

  • 11d: creation
  • 13d: initializing
  • 17d: operational
  • 19d: termination

Type of the underlying BAL connection.

Refer to PH_DLHAL_HW_CONFIG_BAL_CONNECTION.

Pointer to global transmit buffer used by the Exchange() function.

Size of the global transmit buffer.

Pointer to global receive buffer used by the Exchange() function.

Size of the global receive buffer.

Storage for additional error information.




NXP Semiconductors | PN5180 DownloadLib V1.0 | Generated: Thu Apr 7 2016