#ifndef QSEE_KM_H
#define QSEE_KM_H

/**
@file qsee_km.h
@brief Provide Secure Key Manager API wrappers
*/

/*===========================================================================
   Copyright (c) 2015, 2019 by Qualcomm Technologies, Incorporated.  All Rights Reserved.
===========================================================================*/

/*===========================================================================

                            EDIT HISTORY FOR FILE

when       who      what, where, why
--------   ---      ------------------------------------
01/28/15   amen     Initial version.

===========================================================================*/

/*----------------------------------------------------------------------------
 * Include Files
 * -------------------------------------------------------------------------*/
#include <stdint.h>
/** @cond */

/*----------------------------------------------------------------------------
 * Preprocessor Definitions and Constants
 * -------------------------------------------------------------------------*/

/* Bitmask flags to give tz_km_cmd_service */
#define KM_KC_FLAG     0x1   // flag to indicate keycontroller operation
#define KM_MAX_FLAG    0x2

/*----------------------------------------------------------------------------
 * Type Declarations
 * -------------------------------------------------------------------------*/

/**
 * \ingroup cri_cm_cmn_intf
 * \brief CM command interface values
 */
typedef enum km_cm_cmdid
{
    KM_CM_READ_DEVICE_INFO           = 0,  /**< Read CM device information. */
    KM_CM_READ_STATUS_INFO           = 1,  /**< Read CM status information. */
    KM_CM_READ_ERROR_SEQ             = 2,  /**< Read CM sequence error information. */
    KM_CM_READ_ERROR_INIT            = 3,  /**< Read CM initialization error information. */
    KM_CM_READ_ERROR_OTPCMD          = 4,  /**< Read CM OTP segment tag execution error information. */
    KM_CM_READ_ERROR_TRNG            = 5,  /**< Read CM TRNG error information. */
    KM_CM_READ_FEATURE               = 6,  /**< Read a feature value from feature space. */
    KM_CM_READ_OTP                   = 7,  /**< Read an OTP value from the OTP. */
    KM_CM_WRITE_FEATURE              = 8,  /**< Write a feature value to feature space. */
    KM_CM_EXECUTE_RSB                = 9,  /**< Execute an RSB transaction request. */
    KM_CM_EXECUTE_RSB_KEY_EXCH       = 10, /**< Execute an RSB key exchange transaction request. */
    KM_CM_EXECUTE_RSB_DSB            = 11, /**< Execute an RSB/DSB transaction request. */
    KM_CM_EXECUTE_OTPCMD             = 12, /**< Execute OTP command segments at the specified tag level request. */
    KM_CM_EXECUTE_TRNG_SAMPLE        = 13, /**< Execute a sample TRNG request. */
    KM_CM_MAX_COMMANDS               = 14  /**< Maximum number of interface commands. */
} km_cm_cmdid;
/** @endcond */

/*----------------------------------------------------------------------------
 * Function Declarations and Documentation
 * -------------------------------------------------------------------------*/

/**
  @addtogroup qtee_km
  @{
*/

/**
  Initialize a key manager context.

  @param[out] hdl         Context initialized and returned in hdl.

  @return
  SUCCESS -- 0 \n
  FAILURE -- Negative
 */
int qsee_km_init(void **hdl);

/**
  An open cm session returns success only if CM is not busy.

  @param[in] hdl  hdl generated by qsee_km_init

  @return
  SUCCESS -- 0 \n
  FAILURE -- Negative
 */
int qsee_km_open_cm_session(void *hdl);

/**
  This function passes the data blob to be unwrapped by
  CM hardware. The function only works if the open CM session passed.

  @param[in] hdl         hdl generated by calling qsee_km_init.
  @param[in] cmd_hdl_id  cmd id for operation to be performed
                         by CM, km_cm_cmdid type.
  @param[in] flag        Indicates suboperation, e.g., Key Controller.
  @param[in,out] buffer  Data command to feed to CM; also reads
                         back information as required by command.
  @param[in] buff_len    Buffer length (in bytes).

  @return
  SUCCESS -- 0 \n
  FAILURE -- Negative
 */
int qsee_km_cmd_service(void         *hdl,
                        km_cm_cmdid  cmd_hdl_id,
                        uint32_t       flag,
                        uint8_t        *buffer, uint32_t  buff_len);

/**
  If the Key Controller is a sub-operation during qsee_km_cmd_service,
  then hardware has a key. This key can be requested by an initiating
  client by calling this function.

  @param[in] hdl          hdl as received by qsee_km_init
  @param[out] keyptr      User allocated buffer, key is
                          written to this
  @param[in] keysz        Length of the keyptr buffer

  @return
  SUCCESS -- 0 \n
  FAILURE -- Negative
 */
int qsee_km_getkey(void   *hdl,
                   uint32_t *keyptr, uint32_t keysz);

/**
  Once the application completes using the CryptoManager (CM) core, it can
  relieve its usage by calling this function.

  @param[in] hdl      hdl as received by qsee_km_init.

  @return
  SUCCESS -- 0 \n
  FAILURE -- Negative
 */
int qsee_km_close_cm_session(void *hdl);

/**
  Once the application no longer needs this service,
  it can free the context by calling this function.

  @param[in] hdl       hdl as received by qsee_km_init.

  @return
  SUCCESS -- 0 \n
  FAILURE -- -1
 */
int qsee_km_deinit(void *hdl);

/** @} */

#endif /*QSEE_KM_H*/

