/*
*         Copyright (c), NXP Semiconductors Gratkorn / Austria
*
*                     (C)NXP Semiconductors
*       All rights are reserved. Reproduction in whole or in part is 
*      prohibited without the written consent of the copyright owner.
*  NXP reserves the right to make changes without notice at any time.
* NXP makes no warranty, expressed, implied or statutory, including but
* not limited to any implied warranty of merchantability or fitness for any
* particular purpose, or that the use will not infringe any third party patent,
* copyright or trademark. NXP must not be liable for any loss or damage
*                          arising from its use.
*/

/*! \file
 * Doxygen-Mainfile of Basic Function Library Framework.
 * $Author: $
 * $Revision:  $
 * $Date: $
 *
 * History:
 *  CHu:$
 *
 */

/*!
\mainpage

<hr>
\section phsec_Intro Introduction

	<ul>
		<li> <strong>This document describes the Firmware Download Library that is intended
			     to run on NXP LPC1769 board which is connected to PN5180 development board.</strong>

                 <br><br></li>
		<li> <strong>Intended Audience:</strong> </li>
		<ul>
			<li> This document is a reference to be used by the SW designers, implementers and integrators. </li>
		</ul>
	</ul>

<hr>
\section phsec_Overview Overview

        <strong>The Firmware Download Library </strong> is an ANSI-C library abstracting the Download Mode Interface of the PN5180. 
                         The library structure provides a modular way of performing the PN5180 firmware upgrade using the APIs in a specific sequence. 
                         
<hr>


\section phsec_LayerModel LayerModel

<table border="0"><tr>
		<td>
			\image html layer_model_public.png
		</td>
	</tr></table>
	
<hr>

\section phsec_Features Features

        Features supported by <strong>Firmware Download Library </strong>are:
		<br>
		<ul>
			<li><strong>phDlhalHw_Pn5180_Download_PerformSoftReset() :</strong> This API performs a software reset of IC. </li>
			<li><strong>phDlhalHw_Pn5180_Download_GetFirmwareVersion() :</strong> This API provides the current firmware version. </li>
			<li><strong>phDlhalHw_Pn5180_Download_CheckIntegrity() :</strong> This API performs an integrity check of the Image in the IC. </li>
			<li><strong>phDlhalHw_Pn5180_Download_Read() :</strong> This API reads the EEPROM user memory content specified by the Start Address for Length to read bytes.</li>
			<li><strong>phDlhalHw_Pn5180_Download_CheckSessionState() :</strong> This API provides the download session state. </li>
			<li><strong>phDlhalHw_Pn5180_Download_GetDieId() :</strong> The API returns the die ID. </li>
			<li><strong>phDlhalHw_Pn5180_Download_PerformSecureFirmwareUpdate() :</strong> This API is used to perform the firmware upgrade.  </li>
			<li>The library allows downgrading of the firmware within the same Major version.</li>

		</ul>
<hr>

\section phsec_NonFeatures Non-Features

        Non-Features of <strong>Firmware Download Library </strong>are:
		<br>
		<ul>
			<li> The library allows upgrading/downgrading the firmware but does not allow to read the flash contents. </li>
			<li> Switching between the Normal mode and Download Mode shall be handled at application level and not covered in library. </li>
			<li> </li>
		</ul>

  
<hr>

\section phsec_ApiReference API Reference
	\subsection phsec_refDwldLib Download Library
	<br>The Donwload Library implements the API's required to perform firmware Update.
	<ul>
		<li> \ref phDownloadLib</li>
		<br>Pn5180Download Library .	
	</ul>	
	
<hr>	
\section phsec_Integration_Information Information about the Integration
		
        The Download Library can be integrated into the User application to perform the Firmware upgrade.

		PN5180 embeds a firmware and its stored in FLASH and EEPROM. Platform setting in EEPROM contains all customer platform settings.
		The Download mode is used to push a new firmware release. Only NXP can sign a firmware release and deliver it.
		
		NXP releases the firmware as Secure Binary that can be downloaded using the Download Library.
		
		Prerequisites for using Download Library, to be handled in user application are:
		<ul>
			<li> <strong> BAL Initialization.</strong>Initialise the communication interface. Communication happens over SPI interface in RAW mode. </li>
			<li> <strong>Entering Download Mode.</strong> This is performed by toggling the Reset Pin (Low-HIGH_LOW) with DWL_REQ pin held high. </li>
			<li> The NFC Controller is in Operation state.</li>
		</ul>
		
		During the download session, normal mode NFC functionality cannot be used. After a hard-reset, the PN5180 will either be in download mode if the DWL_REQ GPIO is raised or stalled in a halt mode if not.
	
		After any failure or exception case during the download, the session is kept open until a full firmware update sequence has been successfully performed.
		
		Functionality allows securing the firmware file with a signature against download of FW which is not signed by NXP.
		
		A hash chain is implemented to assure that the predefined download order for a firmware image is maintained. The hash chain chosen allows for the verification of the data before applying and storing it in the PN5180.
		
		Main scenario:<br>
		1. Host set the DWL_REQ GPIO to logical one for download mode.<br>
		2. Host performs an PN5180 reset (hard or soft).<br>
		3. Host reads the current hardware and firmware version from the PN5180.<br>
			a. Host checks session status if last download was completed.<br>
			b. Host applies the version checking rules to decide whether to start the download or exit download.<br>
		4. Host loads from a file the firmware binary code to be downloaded.<br>
		5. Host provides a first secured write commands that contains:<br>
			a. The version of the new firmware,<br>
			b. A digest value of the next frame,<br>
			c. The digital signature of the frame itself.<br>
		6. The Host loads the secure download protocol sequence to the PN5180 with secured write commands.<br>
		7. When the last secured write command has been send, the Host executes the CheckIntegrity command to check if the memories have been successfully written.<br>
		8. Host reads the new firmware version and check the session status if closed for reporting to the upper layer.<br>
		9. Host releases the DWL_REQ GPIO for download mode.<br>
		10. Host performs an PN5180 hard reset to re-boot the PN5180.<br>
		
		<table border="0"><tr>
		<td>
			\image html SequenceDiagram.png
		</td>
		</tr></table>
		
		To Perform Firmware download the API's needs to be used in a specific sequence mentioned below:
		<ul>
			<li> <strong>phDlhalHw_Pn5180_Download_Init</strong>: Initialization of the Download Library. </li>
			<li> <strong>phDlhalHw_Pn5180_Download_PerformSecureFirmwareUpdate</strong>: Performs a Firmware Update and checks the integrity of downloaded firmware.</li>
		</ul>
		<strong>Note:</strong> The firmware update API does not change the mode of operation.
<hr>

\section phMfpLib_DisclaimerInfo DISCLAIMER OF WARRANTIES:

<pre>
YOU AGREE THAT NXP HAS MADE NO EXPRESS WARRANTIES TO YOU REGARDING THE
SOFTWARE AND THAT THE SOFTWARE IS BEING PROVIDED TO YOU "AS IS" WITHOUT
WARRANTY OF ANY KIND.
NXP DISCLAIMS ALL WARRANTIES WITH REGARD TO THE SOFTWARE, EXPRESS OR
IMPLIED, INCLUDING, WITHOUT LIMITATION, ANY IMPLIED WARRANTIES OF FITNESS
FOR A PARTICULAR PURPOSE, MERCHANTABILITY, MERCHANTABLE QUALITY OR
NONINFRINGEMENT OF THIRD PARTY RIGHTS.
Some states or jurisdictions do not allow the exclusion of implied warranties so the above
limitations or parts of it may not apply to you.
</pre>
	
<hr>
\section phMfpLib_LiabilityInfo LIMITATION OF LIABILITY:

<pre>
IN NO EVENT WILL NXP BE LIABLE TO YOU FOR ANY LOSS OF USE, INTERRUPTION OF
BUSINESS, OR ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL
DAMAGES OF ANY KIND (INCLUDING LOST PROFITS) REGARDLESS OF THE FORM OF
ACTION WHETHER IN CONTRACT, TORT (INCLUDING NEGLIGENCE), STRICT PRODUCT
LIABILITY OR OTHERWISE, EVEN IF ENDUSER HAS BEEN ADVISED OF THE POSSIBILITY
OF SUCH DAMAGES.
Some states or jurisdictions do not allow the exclusion or limitation of incidental or consequential
damages, so the above limitation, exclusion or parts of it may not apply to you.
</pre>
	
<hr>
\section phsec_RevisionHistory Revision History

   <table border width=500>
    <tr>
     <td width="12%">1.0</td>
     <td width="32%">March 2016</td>
	 <td width="56%">First Release</td>
    </tr>
	</table>
	
*/
