/*
 * Copyright (c) 2021-2025 Yuntu Microelectronics Co., Ltd.
 * All rights reserved.
 *
 * SPDX-License-Identifier: BSD-3-Clause
 */

/*!
 * @file hcu_driver.h
 * @version 1.4.1
 *
 * @brief HCU Driver V2 - public API for Hardware Cryptography Unit operations.
 *
 * This header declares the driver-layer interface for the single HCU V2 engine.
 * The API launches AES, SM4, CMAC, CCM, and SHA operations, selects the data
 * transport method (polling, interrupt, or DMA), and stores the runtime state
 * needed to preserve chained cryptography contexts across message blocks.
 *
 * The public APIs are organized into these categories:
 *   - Driver Lifecycle & Common Control
 *   - AES / SM4 Block Cipher Operations
 *   - Message Authentication & CCM Operations
 *   - SHA Operations
 *   - Compatibility Hooks & Interrupt Support
 *
 * @note Input and output buffers passed to the driver are expected to be
 *       32-bit aligned.
 * @note Block-cipher message lengths are expressed in bytes and must match the
 *       HCU block-processing rules documented on each API.
 */

#ifndef HCU_DRV_H
#define HCU_DRV_H

#include <stdint.h>
#include <stdbool.h>
#include "status.h"
#include "osif.h"
#include "dma_driver.h"
#include "callbacks.h"

/*!
 * @defgroup hcu_driver_v2 HCU Driver V2
 * @ingroup hcu_v2
 * @brief Public driver API for the Hardware Cryptography Unit V2.
 * @details The driver configures a singleton HCU engine, loads hardware or
 *          software keys, and routes message traffic through the HCU FIFOs
 *          using polling, interrupt, or DMA service paths.
 * @{
 */

/*******************************************************************************
 * Definitions
 ******************************************************************************/

/*!
 * @brief AES or SM4 key width selection.
 *
 * Choose the number of key bits to load when written through
 * the driver.
 *
 * | Value              | Description           |
 * |--------------------|-----------------------|
 * | KEY_SIZE_128_BITS  | Use a 128-bit key.    |
 * | KEY_SIZE_192_BITS  | Use a 192-bit key.    |
 * | KEY_SIZE_256_BITS  | Use a 256-bit key.    |
 */
typedef enum
{
    KEY_SIZE_128_BITS = 0x00U, /*!< Use a 128-bit key. */
    KEY_SIZE_192_BITS = 0x01U, /*!< Use a 192-bit key. */
    KEY_SIZE_256_BITS = 0x02U, /*!< Use a 256-bit key. */
} hcu_key_size_t;

/*!
 * @brief Message block position for chained cryptography requests.
 *
 * The HCU driver uses these values to tell the engine whether the current
 * request starts a chained message, continues it, ends it, or covers the whole
 * message in a single call.
 *
 * | Value      | Description                                  |
 * |------------|----------------------------------------------|
 * | MSG_START  | First block of a multi-block message.        |
 * | MSG_END    | Final block of a multi-block message.        |
 * | MSG_ALL    | Entire message is supplied in one call.      |
 * | MSG_MIDDLE | Middle block of a multi-block message.       |
 */
typedef enum
{
    MSG_START = 0x02U,  /*!< Mark the current buffer as the first block. */
    MSG_END = 0x01U,    /*!< Mark the current buffer as the final block. */
    MSG_ALL = 0x03U,    /*!< Mark the current buffer as a complete message. */
    MSG_MIDDLE = 0x00U, /*!< Mark the current buffer as an intermediate block. */
} hcu_msg_type_t;

/*!
 * @brief SHA algorithm selection.
 *
 * | Value       | Description        |
 * |-------------|--------------------|
 * | HCU_SHA_256 | Select SHA-256.    |
 * | HCU_SHA_384 | Select SHA-384.    |
 */
typedef enum
{
    HCU_SHA_256 = 0x01U, /*!< Select the SHA-256 engine configuration. */
    HCU_SHA_384 = 0x02U, /*!< Select the SHA-384 engine configuration. */
} hcu_sha_type_t;

/*!
 * @brief Direction flag for cipher and authentication requests.
 *
 * | Value    | Description      |
 * |----------|------------------|
 * | MODE_ENC | Encrypt / create |
 * | MODE_DEC | Decrypt / verify |
 */
typedef enum
{
    MODE_ENC = 1U, /*!< Run the engine in encrypt or generate mode. */
    MODE_DEC = 0U  /*!< Run the engine in decrypt or authorize mode. */
} hcu_mode_sel_t;

/*!
 * @brief Global input and output byte-lane swap mode.
 *
 * | Value                  | Description                           |
 * |------------------------|---------------------------------------|
 * | MODE_SWAPPING_NO       | Leave data ordering unchanged.        |
 * | MODE_SWAPPING_HALFWORD | Swap 16-bit half-words.               |
 * | MODE_SWAPPING_BYTE     | Swap bytes within each word.          |
 * | MODE_SWAPPING_BIT      | Reverse bit order within each byte.   |
 */
typedef enum
{
    MODE_SWAPPING_NO = 0U,       /*!< Keep the native register byte order. */
    MODE_SWAPPING_HALFWORD = 1U, /*!< Swap 16-bit half-words on data paths. */
    MODE_SWAPPING_BYTE = 2U,     /*!< Swap byte order on data paths. */
    MODE_SWAPPING_BIT = 3U,      /*!< Reverse the bit order on data paths. */
} hcu_swapping_t;

/*!
 * @brief Data transport strategy between memory and the HCU FIFOs.
 *
 * | Value               | Description                                  |
 * |---------------------|----------------------------------------------|
 * | HCU_USING_POLLING   | Driver drains FIFO handshakes in the caller. |
 * | HCU_USING_INTERRUPT | IRQ handler services FIFO handshakes.        |
 * | HCU_USING_DMA       | DMA channels move FIFO payload data.         |
 */
typedef enum
{
    HCU_USING_POLLING = 0U,   /*!< Serve the request synchronously by polling. */
    HCU_USING_INTERRUPT = 1U, /*!< Serve the request through HCU interrupts. */
    HCU_USING_DMA = 2U,       /*!< Serve the request through DMA transfers. */
} hcu_carry_type_t;

/*!
 * @brief Driver-visible algorithm identifier stored in the runtime state.
 *
 * These values describe the active command recorded in @ref hcu_state_t.
 *
 * | Value          | Description               |
 * |----------------|---------------------------|
 * | ALG_DISABLE    | No active algorithm.      |
 * | AES_ECB_MODE   | AES ECB request.          |
 * | AES_CBC_MODE   | AES CBC request.          |
 * | AES_CTR_MODE   | AES CTR request.          |
 * | AES_CCM_MODE   | AES CCM request.          |
 * | AES_CMAC_MODE  | AES CMAC request.         |
 * | SM4_ECB_MODE   | SM4 ECB request.          |
 * | SHA_256_MODE   | SHA-256 request.          |
 * | SHA_384_MODE   | SHA-384 request.          |
 */
typedef enum
{
    ALG_DISABLE = 0x000U,   /*!< No algorithm is active. */
    AES_ECB_MODE = 0x001U,  /*!< Track an AES ECB command. */
    AES_CBC_MODE = 0x002U,  /*!< Track an AES CBC command. */
    AES_CTR_MODE = 0x003U,  /*!< Track an AES CTR command. */
    AES_CCM_MODE = 0x004U,  /*!< Track an AES CCM command. */
    AES_CMAC_MODE = 0x005U, /*!< Track an AES CMAC command. */
    SM4_ECB_MODE = 0x010U,  /*!< Track an SM4 ECB command. */
    SHA_256_MODE = 0x200U,  /*!< Track a SHA-256 command. */
    SHA_384_MODE = 0x300U   /*!< Track a SHA-384 command. */
} hcu_alg_mode_t;

/*!
 * @brief Additional parameters used by AES-CCM requests.
 *
 * This structure carries the nonce, additional authenticated data (AAD), tag,
 * and total payload length required by the CCM formatting stage.
 *
 * | Field       | Description                                      |
 * |-------------|--------------------------------------------------|
 * | nonce       | Pointer to the CCM nonce bytes.                  |
 * | nonceSize   | Nonce length in bytes.                           |
 * | addData     | Pointer to AAD bytes.                            |
 * | addDataSize | AAD length in bytes.                             |
 * | tag         | Pointer to the authentication tag buffer.        |
 * | tagSize     | Requested tag length in bytes.                   |
 * | msgLen      | Total plaintext or ciphertext length in bytes.   |
 */
typedef struct
{
    uint8_t *nonce;       /*!< Nonce buffer used to build the CCM B0 block. */
    uint8_t nonceSize;    /*!< Nonce length in bytes. */
    uint8_t *addData;     /*!< Additional authenticated data buffer. */
    uint16_t addDataSize; /*!< Additional authenticated data length in bytes. */
    uint8_t *tag;         /*!< Tag buffer written or consumed by the command. */
    uint8_t tagSize;      /*!< Authentication tag length in bytes. */
    uint64_t msgLen;      /*!< Total payload length processed by the CCM flow. */
} hcu_ccm_config_t;

/*!
 * @brief Parameters used by AES-CMAC generation or authorization.
 *
 * | Field  | Description                            |
 * |--------|----------------------------------------|
 * | macPtr | Pointer to the MAC buffer.             |
 * | macLen | Requested or expected MAC length.      |
 */
typedef struct
{
    uint8_t *macPtr; /*!< MAC buffer used for generation or authorization. */
    uint8_t macLen;  /*!< MAC length in bytes. */
} hcu_cmac_config_t;

/*!
 * @brief Driver initialization parameters.
 *
 * | Field             | Description                                        |
 * |-------------------|----------------------------------------------------|
 * | swap              | Global data swap setting written into HCU->CR.     |
 * | carryType         | Polling, interrupt, or DMA transfer strategy.      |
 * | ingressDMAChannel | DMA channel used for input FIFO transfers.         |
 * | egressDMAChannel  | DMA channel used for output FIFO transfers.        |
 */
typedef struct
{
    hcu_swapping_t swap;           /*!< Data swap mode applied to HCU traffic. */
    hcu_carry_type_t carryType;    /*!< Transport path used for FIFO servicing. */
    uint8_t ingressDMAChannel;     /*!< DMA channel for memory-to-HCU transfers. */
    uint8_t egressDMAChannel;      /*!< DMA channel for HCU-to-memory transfers. */
} hcu_user_config_t;

/*!
 * @brief Runtime state owned by the HCU driver.
 *
 * Applications allocate this structure and pass it to @ref HCU_DRV_Init, but
 * the fields are maintained by the driver. The layout may change between SDK
 * revisions and should not be modified directly by application code.
 */
typedef struct
{
    volatile bool cmdInProgress;   /*!< True while the driver is servicing an active command. */
    bool isLastBlock;              /*!< True when the current request terminates a chained message. */
    bool blockingCmd;              /*!< Reserved flag for blocking command handling. */
    security_callback_t callback;  /*!< Callback pointer stored by HCU_DRV_InstallCallback(). */
    void *callbackParam;           /*!< User pointer stored together with @ref callback. */
    semaphore_t cmdComplete;       /*!< Synchronization object created during initialization. */
    uint32_t const *dataInputPtr;  /*!< Current input pointer used by polling, IRQ, or DMA service. */
    uint32_t *dataOutputPtr;       /*!< Current output pointer used by polling, IRQ, or DMA service. */
    uint64_t msgLen;               /*!< Active payload length in bytes. */
    uint64_t inputCount;           /*!< Remaining input bytes not yet written into the FIFO. */
    uint64_t outputCount;          /*!< Remaining output bytes not yet read from the FIFO. */
    uint8_t ingressDMAChannel;     /*!< Active DMA channel assigned to input transfers. */
    uint8_t egressDMAChannel;      /*!< Active DMA channel assigned to output transfers. */
    hcu_ccm_config_t *ccmConfig;   /*!< Active CCM metadata used by chained CCM commands. */
    hcu_cmac_config_t *cmacConfig; /*!< Active CMAC metadata used by chained CMAC commands. */
    uint32_t *futileData;          /*!< Scratch words used to cache IV, CV, MAC, or SHA context data. */
    status_t status;               /*!< Last status recorded by the command backend. */
    hcu_mode_sel_t mode;           /*!< Direction of the active cipher or authentication command. */
    hcu_carry_type_t carryType;    /*!< Active FIFO transport mode. */
    hcu_alg_mode_t algorithm;      /*!< Active algorithm identifier tracked by the driver. */
} hcu_state_t;

/*!
 * @brief Input and output parameters for AES or SM4 commands.
 *
 * | Field          | Description                                            |
 * |----------------|--------------------------------------------------------|
 * | dataInputPtr   | 32-bit aligned input buffer.                           |
 * | dataOutputPtr  | 32-bit aligned output buffer.                          |
 * | msgLen         | Payload length in bytes.                               |
 * | msgType        | Block position for chained requests.                   |
 * | hwKeySelected  | Select hardware key slot instead of software key.      |
 * | hwKeySlot      | Hardware key slot index.                               |
 * | swKeyPtr       | Pointer to a software key when @ref hwKeySelected is false. |
 * | keySize        | Software key width.                                    |
 */
typedef struct
{
    uint32_t const *dataInputPtr; /*!< 32-bit aligned input buffer. */
    uint32_t *dataOutputPtr;      /*!< 32-bit aligned output buffer. */
    uint16_t msgLen;              /*!< Payload length in bytes. */
    hcu_msg_type_t msgType;       /*!< Block position for chained traffic. */
    bool hwKeySelected;           /*!< Select hardware key storage when true. */
    uint32_t hwKeySlot;           /*!< Hardware key slot index. */
    uint32_t const *swKeyPtr;     /*!< Software key buffer when hardware keys are not used. */
    hcu_key_size_t keySize;       /*!< Width of the software key. */
} aes_algorithm_config_t;

#if FEATURE_HCU_SHA_ENGINE
/*!
 * @brief Input and output parameters for SHA generation or authorization.
 *
 * | Field         | Description                                             |
 * |---------------|---------------------------------------------------------|
 * | dataInputPtr  | 32-bit aligned message buffer.                          |
 * | dataOutputPtr | Digest buffer, or expected digest for authorize flows.  |
 * | msgLen        | Current chunk length in bytes.                          |
 * | totalLen      | Total message length in bytes for the whole sequence.   |
 * | msgType       | Block position for chained requests.                    |
 * | shaType       | SHA-256 or SHA-384 selection.                           |
 */
typedef struct
{
    uint32_t const *dataInputPtr; /*!< 32-bit aligned input buffer. */
    uint32_t *dataOutputPtr;      /*!< Digest buffer or expected digest buffer. */
    uint32_t msgLen;              /*!< Current chunk length in bytes. */
    uint32_t totalLen;            /*!< Total length of the complete message in bytes. */
    hcu_msg_type_t msgType;       /*!< Block position for chained hashing traffic. */
    hcu_sha_type_t shaType;       /*!< SHA engine selection. */
} sha_algorithm_config_t;
#endif

/*******************************************************************************
 * API
 ******************************************************************************/

#if defined(__cplusplus)
extern "C" {
#endif

/*******************************************************************************
 * Driver Lifecycle & Common Control
 ******************************************************************************/
/*!
 * @name Driver Lifecycle & Common Control
 * @brief Functions that initialize the singleton driver state and configure
 *        global runtime behavior.
 * @{
 */

/*!
 * @brief Initialize the HCU driver state and default transport settings.
 *
 * The driver stores the application-provided runtime state pointer, clears its
 * bookkeeping fields, applies the configured data-swapping mode, and creates
 * the internal semaphore object used by the backend.
 *
 * @param[in] userConfig Pointer to the user configuration structure.
 * @param[in] state      Pointer to the runtime state storage supplied by the application.
 * @return Execution status.
 * @retval STATUS_SUCCESS Driver state was initialized successfully.
 * @retval STATUS_ERROR   Semaphore creation failed.
 *
 * @pre The HCU clock and any required interrupt routing must already be enabled
 *      by the platform.
 * @post The singleton state pointer is ready for subsequent API calls.
 */
status_t HCU_DRV_Init(const hcu_user_config_t *userConfig, hcu_state_t *state);

/*!
 * @brief Reset the active driver state and release initialization resources.
 *
 * This function clears the singleton runtime state, disables the HCU interrupt,
 * resets key control registers, clears the operation-done flag, and destroys
 * the semaphore created by @ref HCU_DRV_Init.
 *
 * @param[in] state Pointer to the runtime state previously passed to
 *                  @ref HCU_DRV_Init.
 * @return Execution status returned by OSIF_SemaDestroy().
 */
status_t HCU_DRV_DeInit(hcu_state_t *state);

/*!
 * @brief Program the HCU global data-swapping mode.
 *
 * @param[in] cfg Swap mode written into the HCU control register.
 *
 * @note This setting affects subsequent commands launched by the driver.
 */
void HCU_DRV_CfgSwapping(hcu_swapping_t cfg);

/*!
 * @brief Clear the HCU operation-done flag.
 */
void HCU_DRV_ClearODFlag(void);

/*!
 * @brief Store a completion callback pointer in the runtime state.
 *
 * The current implementation records the callback pair and returns the
 * previously stored callback without invoking it directly.
 *
 * @param[in] callbackFunction Callback pointer to store.
 * @param[in] callbackParam    User data stored alongside the callback.
 * @return The callback pointer that was stored before this call.
 */
security_callback_t HCU_DRV_InstallCallback(security_callback_t callbackFunction,
                                            void *callbackParam);

/*! @} */

/*******************************************************************************
 * AES / SM4 Block Cipher Operations
 ******************************************************************************/
/*!
 * @name AES / SM4 Block Cipher Operations
 * @brief Functions that launch block-cipher encryption or decryption jobs.
 * @{
 */

/*!
 * @brief Encrypt a message with AES in ECB mode.
 *
 * @param[in] aesAlgCfg Pointer to the AES job configuration.
 * @return Execution status for command setup and completion.
 *
 * @pre @ref HCU_DRV_Init must have completed successfully.
 * @note The input and output buffers are expected to be 32-bit aligned and the
 *       message length should cover complete 16-byte blocks.
 */
status_t HCU_DRV_EncryptECB(aes_algorithm_config_t *aesAlgCfg);

/*!
 * @brief Decrypt a message with AES in ECB mode.
 *
 * @param[in] aesAlgCfg Pointer to the AES job configuration.
 * @return Execution status for command setup and completion.
 */
status_t HCU_DRV_DecryptECB(aes_algorithm_config_t *aesAlgCfg);

#if FEATURE_HCU_SM4_ENGINE
/*!
 * @brief Encrypt a message with SM4 in ECB mode.
 *
 * @param[in] plainText 32-bit aligned plaintext buffer.
 * @param[in] length    Plaintext length in bytes. The payload is expected to
 *                      cover complete 16-byte blocks.
 * @param[out] cipherText 32-bit aligned ciphertext buffer.
 * @return Execution status for command setup and completion.
 */
status_t HCU_DRV_EncryptSM4ECB(const void *plainText,
                               uint16_t length,
                               void *cipherText);

/*!
 * @brief Decrypt a message with SM4 in ECB mode.
 *
 * @param[in] cipherText 32-bit aligned ciphertext buffer.
 * @param[in] length     Ciphertext length in bytes. The payload is expected to
 *                       cover complete 16-byte blocks.
 * @param[out] plainText 32-bit aligned plaintext buffer.
 * @return Execution status for command setup and completion.
 */
status_t HCU_DRV_DecryptSM4ECB(const void *cipherText,
                               uint32_t length,
                               void *plainText);
#endif /* FEATURE_HCU_SM4_ENGINE */

/*!
 * @brief Encrypt a message with AES in CBC mode.
 *
 * @param[in] aesAlgCfg Pointer to the AES job configuration.
 * @param[in] iv        Pointer to the initialization vector for the first block
 *                      of a chained sequence. Later blocks reuse the cached IV
 *                      held in the runtime state when @ref aes_algorithm_config_t.msgType
 *                      is not MSG_START or MSG_ALL.
 * @return Execution status for command setup and completion.
 */
status_t HCU_DRV_EncryptCBC(aes_algorithm_config_t *aesAlgCfg, uint32_t *iv);

/*!
 * @brief Decrypt a message with AES in CBC mode.
 *
 * @param[in] aesAlgCfg Pointer to the AES job configuration.
 * @param[in] iv        Pointer to the initialization vector for the first block
 *                      of a chained sequence.
 * @return Execution status for command setup and completion.
 */
status_t HCU_DRV_DecryptCBC(aes_algorithm_config_t *aesAlgCfg, uint32_t *iv);

#if FEATURE_HCU_AES_CTR_ENGINE
/*!
 * @brief Decrypt a message with AES in CTR mode.
 *
 * @param[in] aesAlgCfg Pointer to the AES job configuration.
 * @param[in] cv        Pointer to the initial counter value for the first block
 *                      of a chained sequence.
 * @return Execution status for command setup and completion.
 */
status_t HCU_DRV_DecryptCTR(aes_algorithm_config_t *aesAlgCfg, uint32_t *cv);

/*!
 * @brief Encrypt a message with AES in CTR mode.
 *
 * @param[in] aesAlgCfg Pointer to the AES job configuration.
 * @param[in] cv        Pointer to the initial counter value for the first block
 *                      of a chained sequence.
 * @return Execution status for command setup and completion.
 */
status_t HCU_DRV_EncryptCTR(aes_algorithm_config_t *aesAlgCfg, uint32_t *cv);
#endif /* FEATURE_HCU_AES_CTR_ENGINE */

/*! @} */

/*******************************************************************************
 * Message Authentication & CCM Operations
 ******************************************************************************/
/*!
 * @name Message Authentication & CCM Operations
 * @brief Functions that launch CMAC or CCM formatting and authentication flows.
 * @{
 */

/*!
 * @brief Generate an AES-CMAC value for the supplied message block sequence.
 *
 * @param[in] aesAlgCfg   Pointer to the AES job configuration.
 * @param[out] cmacConfig Pointer to the CMAC output configuration.
 * @return Execution status for command setup and completion.
 *
 * @note Use @ref aes_algorithm_config_t.msgType to split a message across
 *       multiple calls while preserving intermediate IV state.
 */
status_t HCU_DRV_GenerateMAC(aes_algorithm_config_t *aesAlgCfg,
                             hcu_cmac_config_t *cmacConfig);

/*!
 * @brief Authorize an AES-CMAC value against the supplied message sequence.
 *
 * @param[in] aesAlgCfg   Pointer to the AES job configuration.
 * @param[in] cmacConfig  Pointer to the expected MAC buffer and length.
 * @return Execution status for command setup and completion.
 */
status_t HCU_DRV_AuthorizeMAC(aes_algorithm_config_t *aesAlgCfg,
                              hcu_cmac_config_t *cmacConfig);

#if FEATURE_HCU_AES_CCM_ENGINE
/*!
 * @brief Reserved hook for standalone CCM parameter staging.
 *
 * @param[in] ccm  Pointer to the CCM configuration structure.
 * @param[in] mode Select encryption or decryption formatting.
 * @return Execution status.
 *
 * @note The current HCU V2 source tree performs CCM parameter staging inside
 *       @ref HCU_DRV_EncryptCCM and @ref HCU_DRV_DecryptCCM.
 */
status_t HCU_DRV_CCMConfig(hcu_ccm_config_t *ccm, hcu_mode_sel_t mode);

/*!
 * @brief Encrypt a message with AES in CCM mode.
 *
 * @param[in] aesAlgCfg  Pointer to the AES job configuration.
 * @param[in,out] ccmConfig Pointer to CCM nonce, AAD, tag, and length metadata.
 * @return Execution status for command setup and completion.
 *
 * @warning The CCM tag length must be even and no greater than 16 bytes.
 */
status_t HCU_DRV_EncryptCCM(aes_algorithm_config_t *aesAlgCfg,
                            hcu_ccm_config_t *ccmConfig);

/*!
 * @brief Decrypt and authenticate a message with AES in CCM mode.
 *
 * @param[in] aesAlgCfg  Pointer to the AES job configuration.
 * @param[in,out] ccmConfig Pointer to CCM nonce, AAD, tag, and length metadata.
 * @return Execution status for command setup and completion.
 */
status_t HCU_DRV_DecryptCCM(aes_algorithm_config_t *aesAlgCfg,
                            hcu_ccm_config_t *ccmConfig);
#endif /* FEATURE_HCU_AES_CCM_ENGINE */

/*! @} */

/*******************************************************************************
 * SHA Operations
 ******************************************************************************/
#if FEATURE_HCU_SHA_ENGINE
/*!
 * @name SHA Operations
 * @brief Functions that launch SHA digest or authorization requests.
 * @{
 */

/*!
 * @brief Generate a SHA digest for the supplied message sequence.
 *
 * @param[in] shaAlgCfg Pointer to the SHA job configuration.
 * @return Execution status for command setup and completion.
 *
 * @note Non-final chunks in a multi-block SHA sequence must be non-zero in
 *       length and aligned to the algorithm block size (64 bytes for SHA-256,
 *       128 bytes for SHA-384).
 */
status_t HCU_DRV_GenerateSHA(sha_algorithm_config_t *shaAlgCfg);

#if FEATURE_HCU_HAS_SHA_AUTHORIZE
/*!
 * @brief Authorize a SHA digest against the supplied message sequence.
 *
 * @param[in] shaAlgCfg Pointer to the SHA job configuration.
 * @return Execution status for command setup and completion.
 */
status_t HCU_DRV_AuthorizeSHA(sha_algorithm_config_t *shaAlgCfg);
#endif /* FEATURE_HCU_HAS_SHA_AUTHORIZE */

/*! @} */
#endif /* FEATURE_HCU_SHA_ENGINE */

/*******************************************************************************
 * Compatibility Hooks & Interrupt Support
 ******************************************************************************/
/*!
 * @name Compatibility Hooks & Interrupt Support
 * @brief Declarations used for integration parity and interrupt servicing.
 * @{
 */

/*!
 * @brief Reserved hook for command cancellation support.
 *
 * @return Execution status.
 *
 * @note The public header keeps this declaration for API compatibility. The
 *       current HCU V2 source tree does not provide a companion implementation.
 */
status_t HCU_DRV_CancelCommand(void);

/*!
 * @brief Service HCU interrupt sources for the active command.
 */
void HCU_DRV_IRQHandler(void);

/*! @} */

#if defined(__cplusplus)
}
#endif

/*! @} */

#endif /* HCU_DRV_H */
