/**
 @page IAP_HID_III

 @verbatim
 * @file    IAP_HID/IAP_HID_III/readme.txt
 * @version V2.03
 * @date    2025-06-23
 * @brief   Description of HID IAP example (with AP Binary Encryption, Command key, and Digest).
 @endverbatim

@par Example Description:

<PRE>
Third-Party Tools Notice
-------------------------
This project uses third-party command-line tools located in the "Tools/" directory
for firmware post-processing.

- The SRecord tools (srec_cat.exe, etc.) are licensed under GNU General Public License, Version 3.

See the following documents in the "Tools/" folder for detailed license information:
- THIRD_PARTY_LICENSE_SRecord_readme.txt

This project uses third-party tools located in the "Src_IAP/" directory
for Mbed TLS Module (ARC4).

- The Mbed TLS Module tools (arc4.c, etc.) are licensed under the Apache License, Version 2.0.

See the following documents in the "Src_IAP/" folder for detailed license information:
- THIRD_PARTY_LICENSE_mbedtls_readme.txt
</PRE>

<PRE>
This example code shows how to update firmware by the In-application Programming using USB Device HID Class.
The command/data/response flow is as below. It supports two kinds of command channels, Output or Feature report. The F/W will
check the first command comes from which channel and keeps the following data at the same channel/way.

  Comamnd via Output Report (INTERRUPT OUT):
    Host                               Device
    ==========                         ==========
    Endpoint 4 Output Report    ->     Command Channel (COMMAND)
    Endpoint 0 GetInputReport   <-     Command Response (RESPONSE)
    Endpoint 3 Input Report     <-     Data for read command

  Comamnd via Feature Report (CONTROL):
    Host                               Device
    ==========                         ==========
    Endpoint 0 SetFeatureReport ->     Command Channel (COMMAND)
    Endpoint 0 GetInputReport   <-     Command Response (RESPONSE)
    Endpoint 0 GetFeatureReport <-     Data for read command


The IAP HID firmware supports the following protocol:


- COMMAND Format:

    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |      CMD      |     PAR0      |             CRC               |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ---------------|
   |                              PAR1                             |    Address     |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+       or       |
   |                              PAR2                             | User Parameter |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ---------------|
   |  PAYLOAD[0]   |  PAYLOAD[1]   |  PAYLOAD[2]   |  PAYLOAD[3]   |                |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+    52 Bytes    |
   |                              ...                              |    Payload     |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+                |
   |  PAYLOAD[48]  |  PAYLOAD[49]  |  PAYLOAD[50]  |  PAYLOAD[51]  |                |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ---------------|

    Field       Size (Bytes)       Descriptions
    ========    ===============    ======================
    CMD         1                  Command Code
    PAR0        1                  Parameter of command
    CRC         2                  CRC16 value of (Code, uPara, 0x0000, uStaddr, and uEndAddr)
    PAR1        4                  Start address of command
    PAR2        4                  End address or length of command
    PAPYLOAD    52                 Data payload
    ------------------------------------------------------
    Total       64


- COMMAND Example:

    Command | CMD  | PAR0 |PAR1/PAR2 | PAYLOAD    | Descriptions
    ==========================================================================================================
    Mass    | 0x0  | 0xA  | 0        | 0 Padding  | Mass Erase (Not support in IAP mode).
    Erase   |      |      | 0        |            |
    ----------------------------------------------------------------------------------------------------------
    Page    | 0x0  | 0x8  | uStAddr  | 0 Padding  | Erase specific page which assigned by
    Erase   |      |      | uEndAddr |            | uStAddr and uEndAddr.
    ----------------------------------------------------------------------------------------------------------
    Verify  | 0x1  | 0x0  | uStAddr  | Data       | Verify specific Flash Memory which assigned
            |      |      | uEndAddr |            | by uStAddr and uEndAddr.
    ----------------------------------------------------------------------------------------------------------
    Program | 0x1  | 0x1  | uStAddr  | Data       | Program specific Flash Memory which assigned
            |      |      | uEndAddr |            | by uStAddr and uEndAddr.
    ----------------------------------------------------------------------------------------------------------
    Read    | 0x1  | 0x2  | uStAddr  | 0 Padding  | Read specific Flash Memory which assigned by
            |      |      | uEndAddr |            | uStAddr and uEndAddr.
    ----------------------------------------------------------------------------------------------------------
    Blank   | 0x1  | 0x3  | uStAddr  | 0 Padding  | Blank check specific Flash Memory which
            |      |      | uEndAddr |            | assigned by uStAddr and uEndAddr.
    ----------------------------------------------------------------------------------------------------------
    CRC     | 0x2  | 0x0  | uStAddr  | 0 Padding  | Apply CRC16 checking of specific Flash Memory
            |      |      | uLength  |            | which assigned by uStAddr and uLength.
    ----------------------------------------------------------------------------------------------------------
    Info    | 0x3  | 0x0  | 0        | 0 Padding  | Return 4 words information.
            |      |      | 0        |            |
    ----------------------------------------------------------------------------------------------------------
    Reset   | 0x4  | 0x0  | 0        | 0 Padding  | Reset and start AP mode.
    to AP   |      |      | 0        |            |
    ----------------------------------------------------------------------------------------------------------
    Reset   | 0x4  | 0x1  | 0        | 0 Padding  | Reset and start IAP mode.
    to IAP  |      |      | 0        |            |
    ----------------------------------------------------------------------------------------------------------
    Exit    | 0x5  | 0x0  | 0        | 0 Padding  | Enter forever loop to exit IAP mode.
    IAP     |      |      | 0        |            |
    ----------------------------------------------------------------------------------------------------------
    User    | 0x50 | PAR0 | PAR1     | User       | User defined command and data.
    Command |   |  |      | PAR2     | Data       |
            | 0xFF |      |          |            |
    ----------------------------------------------------------------------------------------------------------


- RESPONSE Format:

    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |     RET[0]    |    RET[1]     |    RET[2]     |    RET[3]     |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                              ...                              |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                           Padding                             |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

    Field       Size (Bytes)       Descriptions
    ========    ===============    ======================
    RET[n]      n                  Return Code
    Padding     64 - n             0 Padding


- Return Code:

    Return        Return Code        Descriptions
    ========      ===============    ======================
    OK            0x4F (O)           Command operation Okey
    FAIL          0x46 (F)           Command operation failed


- How to Change Application Start Address

  The application start address shall be modified if the IAP code size is changed. For example, if you
  add more functions into IAP loader which causes the IAP code size changed from 2500 bytes to 3500 bytes
  , you shall modify application start address from 0xC00 (3072 Bytes) to 0x1000 (4096 Bytes).
  Note that the minimum scale of application start address is based on the Flash Page size. Following
  description shows how to modify RO base address of IAP Device, application, and IAP Host.

  IAP_CODE_SIZE:
  ==========================================
    Modify the define value of "IAP_CODE_SIZE" in "ht32_board_config.h" file.
    IAP loader uses this define to confirm PC/SP, apply AP CRC Checking.
    Application uses "IAP_CODE_SIZE" for NVIC VTO setting since the vector is not locate at 0x08000000.

      ht32_board_config.h
        |    ....
        |
        |    #define IAP_CODE_SIZE                             (1024 * 16)        /* IAP code size in Bytes              */
        |
        |    ....

  linker script:
  ==========================================
    Following linker script files define the RO base address.
    Please refer to the document of compiling tools for more information.

    For Keil MDK-ARM:
      MDK_ARMv5/linker_01.lin
      MDK_ARMv537/linker_01.lin

    For HT32-IDE:
      HT32-IDE/GNU_ARM/linker_01.ld
</PRE>

@par Directory contents:

- IAP_HID/IAP_HID_III/ht32_board_config.h                           Board configuration file
- IAP_HID/IAP_HID_III/Src_AP/main.c                                 Main program of application
- IAP_HID/IAP_HID_III/Src_AP/ap_handler.c                           AP handler who control the image update procedural
- IAP_HID/IAP_HID_III/Src_AP/ap_handler.h                           Header file of the AP handlers
- IAP_HID/IAP_HID_III/Src_AP/ap_crc16.c                             CRC algorithm
- IAP_HID/IAP_HID_III/Src_AP/ap_crc16.h                             Header file of CRC algorithm
- IAP_HID/IAP_HID_III/Src_AP/ht32_usbd_class.c                      USB Device Class related function
- IAP_HID/IAP_HID_III/Src_AP/ht32_usbd_class.h                      Header file of the USB Device Class
- IAP_HID/IAP_HID_III/Src_AP/ht32_usbd_descriptor.c                 Descriptor of USB Device
- IAP_HID/IAP_HID_III/Src_AP/ht32_usbd_descriptor.h                 Header file of the USB Device Descriptor
- IAP_HID/IAP_HID_III/Src_AP/ht32fxxxxx_int.c                       Interrupt handlers
- IAP_HID/IAP_HID_III/Src_AP/system_ht32fxxxxx.c                    System configuration file
- IAP_HID/IAP_HID_III/Src_AP/ht32fxxxxx_conf.h                      Firmware library configuration file
- IAP_HID/IAP_HID_III/Src_AP/ht32fxxxxx_usb_conf.h                  USB Device Library configuration file
- IAP_HID/IAP_HID_III/Src_IAP/iap_main.c                            Main program of IAP
- IAP_HID/IAP_HID_III/Src_IAP/iap_handler.c                         IAP handler who control the image update procedural
- IAP_HID/IAP_HID_III/Src_IAP/iap_handler.h                         Header file of the IAP handlers
- IAP_HID/IAP_HID_III/Src_IAP/iap_crc16.c                           CRC algorithm
- IAP_HID/IAP_HID_III/Src_IAP/iap_crc16.h                           Header file of CRC algorithm
- IAP_HID/IAP_HID_III/Src_IAP/iap_ht32_usbd_class.c                 USB Device Class related function
- IAP_HID/IAP_HID_III/Src_IAP/iap_ht32_usbd_class.h                 Header file of the USB Device Class
- IAP_HID/IAP_HID_III/Src_IAP/iap_ht32_usbd_descriptor.c            Descriptor of USB Device
- IAP_HID/IAP_HID_III/Src_IAP/iap_ht32_usbd_descriptor.h            Header file of the USB Device Descriptor
- IAP_HID/IAP_HID_III/Src_IAP/iap_ht32fxxxxx_int.c                  Interrupt handlers
- IAP_HID/IAP_HID_III/Src_IAP/iap_system_ht32fxxxxx.c               System configuration file
- IAP_HID/IAP_HID_III/Src_IAP/ht32fxxxxx_conf.h                     Firmware library configuration file
- IAP_HID/IAP_HID_III/Src_IAP/ht32fxxxxx_usb_conf.h                 USB Device Library configuration file
- IAP_HID/IAP_HID_III/Src_IAP/mbedtls/library/arc4.c                RC4 algorithm
- IAP_HID/IAP_HID_III/Src_IAP/mbedtls/include/mbedtls/arc4.h        Header file of RC4 algorithm
- IAP_HID/IAP_HID_III/Tools/HT32FXXXXX_IAP_Test_vnnn.exe            Pre-builded IAP UI.
- IAP_HID/IAP_HID_III/Tools/TPMakerIII_Encrypt_SETTING_EXAMPLE.png  Setting example of TPMaker III  Encrypt Tool.
- IAP_HID/IAP_HID_III/Tools/TPMakerIII_SETTING_EXAMPLE.png          Setting example of TPMaker III.

@par Hardware and Software Environment:

<PRE>
This example runs on HT32 Series Development board. This example uses the following endpoints.
  Endpoint    Transfer Type         Buffer Length
  ========    ====================  ==============
  0           Control               64 bytes
  4           Interrupt OUT         64 bytes
  3           Interrupt IN          64 bytes
</PRE>

@note

This example uses multi-project to manage both the IAP program and user's application. Multi-project
helps to build/download/debug both IAP and application in the same time. The following steps show
how to build/download/debug by multi-project setting.
<PRE>
  For Keil MDK-ARM:

    Build:    Double click on "MDK_ARM/Project_CHIPNAME.uvmpw" to open multi-project file. Press the
              "Batch Build" icon on the toolbar, or tick "Project -> Batch Build" to open the "Batch Build"
              window. Press "Build" or "Rebuild" button to build both IAP and application. The output file for
              the programming tools is as follows:

                  MDK_ARM/HT32/CHIPNAME/AP/Obj/IAP_AP.hex                 (HEX file of both IAP and application)
                  MDK_ARM/HT32/CHIPNAME/AP/Obj/IAP_AP.axf.bin/AP          (Binary file of application)

              Use files below when you enable IAP CRC Checking on Boot.

                  MDK_ARM/HT32/CHIPNAME/AP/Obj/IAP_AP_CRC.hex             (HEX file of both IAP and application)
                  MDK_ARM/HT32/CHIPNAME/AP/Obj/IAP_AP.axf.bin/AP_xxx.bin  (Binary file of application)
                  Note: xxx can be either:
                        Encrypt   - if ARC4_DECRYPTION_EN is enabled. (Default)
                        Plaintext - if ARC4_DECRYPTION_EN is disabled.

    Download: Make sure the active project is "Project_CHIPNAME_AP" by right-clicking on the project name
              "Project_CHIPNAME" in "Project" window and click "Set as Active Project". Press "LOAD" icon
              to download both IAP and application into Flash memory.

    Debug:    Make sure the active project is "Project_CHIPNAME_AP". Enter debug mode by pressing Ctrl+F5.
              The debug symbol of IAP will be loaded by the command below in "HT32Fxxxx_DebugSupport.ini".
                "LOAD HT32\CHIPNAME\IAP\Obj\IAP.axf INCREMENTAL"
              Since both images of IAP and application are loaded into uVision, trace the program switching
              behavior between IAP and application is possible.
</PRE>

@par USB Library debug mode

<PRE>
For debug purpose, your can turn on the USB Library debug mode by setting "USBDCORE_DEBUG" definition
value as 1 (which located at ht32_usbd_core.h). The debug message will be shown via the printf function
to the UART or ITM interface according to the retarget setting of firmware library.

NOTE THAT USB DEBUG MODE DEGRADES THE PERFORMANCE AND MAY CAUSE USB ERROR UNDER SOME CONDITIONS.

You shall turn off the USB debug mode on your final application. We strongly recommend turn off the
"Dump USB Debug data (USBDCORE_DEBUG_DATA)" option when you enable the USB debug mode and retarget the
message to UART.
</PRE>

@par Firmware Disclaimer Information

1. The customer hereby acknowledges and agrees that the program technical documentation, including the
   code, which is supplied by Holtek Semiconductor Inc., (hereinafter referred to as "HOLTEK") is the
   proprietary and confidential intellectual property of HOLTEK, and is protected by copyright law and
   other intellectual property laws.

2. The customer hereby acknowledges and agrees that the program technical documentation, including the
   code, is confidential information belonging to HOLTEK, and must not be disclosed to any third parties
   other than HOLTEK and the customer.

3. The program technical documentation, including the code, is provided "as is" and for customer reference
   only. After delivery by HOLTEK, the customer shall use the program technical documentation, including
   the code, at their own risk. HOLTEK disclaims any expressed, implied or statutory warranties, including
   the warranties of merchantability, satisfactory quality and fitness for a particular purpose.

 * <h2><center>Copyright (C) Holtek Semiconductor Inc. All rights reserved</center></h2>
 */
