// Copyright (c) 2023 Qualcomm Technologies, Inc.  
// All Rights Reserved.  
// Qualcomm Technologies Proprietary and Confidential.

/** @cond */
struct IStorRd_PartitionInfo
{
  uint64   total_lba_count;    /**< Total number of sectors for the partition */
  uint64   bytes_per_lba;      /**< Number of bytes of each sector */
};

struct IStorRd_Guid 
{
  uint32     data1; 
  uint16     data2; 
  uint16     data3; 
  uint8[8]   data4; 
}; 

struct IStorRd_GptEntry 
{
  IStorRd_Guid   type_guid;
  IStorRd_Guid   unique_guid;
  uint64         start_lba; 
  uint64         end_lba; 
  uint64         attributes; 
  uint8[72]      partition_name;
}; 

/** @endcond */

/** @cond */
interface IStorRd {
/** @endcond */

  /**
   * @addtogroup IStorRd
   * @{
   */

  /** @cond */

  const uint32 SPINOR = 0;

  /** Errors */
  error ERROR_INVALID_PARAM;         /** Returned when an invalid parameter is encountered */
  error ERROR_NOT_SUPPORTED;         /** Returned when an operation is not supported */
  error ERROR_DEVICE_ERROR;          /** Returned for any device errors */ 
  error ERROR_MAC_MISMATCH;          /** Returned when a MAC mismatch is seen */
  error ERROR_MAC_GENERATION;        /** Returned when HMAC calculation fails */
  error ERROR_KEY_GENERATION;        /** Returned when the KDF fails */
  error ERROR_KEY_CLEAR;             /** Returned when clearing the key fails */
  error ERROR_KEY_WRAP;              /** Returned when wrapping the key fails */
  error ERROR_OUT_OF_RESOURCES;      /** Returned when resources are not available */
  error ERROR_ALREADY_RUNNING;       /** Returned when an operation is already in progress */
  error ERROR_NOT_IN_MFG_MODE;       /** Returned for APIs that can only be called in manufacturing mode */
  error ERROR_IN_MFG_MODE;           /** Returned for APIs that can only be called out of manufacturing mode */
  error ERROR_READONLY;              /** Returned when writing to a write-protected partition */
  error ERROR_PARTITION_NOT_FOUND;   /** Returned when no partition is found */
  error ERROR_HASH_GENERATION;       /** Returned when hash calculation fails */  
  error ERROR_HASH_MISMATCH;         /** Returned when a hash mismatch is seen */

  /** @endcond */

  /**
    Opens a partition 
    
    @param[in]   guid              GUID of the partition to open
    @param[out]  IStorRdPartition  IStorRdPartition object

    @return
    Object_OK on success.
  */
  method OpenPartition (in IStorRd_Guid guid, out interface IStorRdPartition); 

  /**
    Enables/disables manufacturing mode for resiliency driver
    
    @param[in]   mode_val          1 to enable, 0 to disable manufacturing mode

    @return
    Object_OK on success.
  */
  method SetManufacturingMode (in uint8 mode_val);

  /**
  * Enables resiliency backup and applies write protect for all
  * the partitions that require it based on the devcfg / device tree settings. 

    @return
    Object_OK on success.
  */
  method EnableBackupAndWriteProtect ();

  /**
    Starts a partition iterator session to iterate all the code partitions
    
    @param[in]    dev_type              Device type
    @param[in]    slot                  Device slot
    @param[in]    lun                   Device logical unit number 
    @param[out]   expected_num_entries  Holds value of the expected number of partitions 
    @param[out]   IStorRdIterator       IStorRdIterator object

    @return
    Object_OK on success.
  */
  method StartCodePartitionIterator (in uint32 dev_type, in uint32 slot, in uint32 lun,  
                                     out uint32 expected_num_entries, out interface IStorRdIterator); 

  /* @} */ /* end_addtogroup IStorRd */
};

/** @cond */
interface IStorRdPartition {
/** @endcond */

  /**
   * @addtogroup IStorRdPartition
   * @{
   */

  /** Errors */
  error ERROR_INVALID_PARAM;         /** Returned when an invalid parameter is encountered */
  error ERROR_NOT_SUPPORTED;         /** Returned when an operation is not supported */
  error ERROR_DEVICE_ERROR;          /** Returned for any device errors */ 
  error ERROR_MAC_MISMATCH;          /** Returned when a MAC mismatch is seen */
  error ERROR_MAC_GENERATION;        /** Returned when HMAC calculation fails */
  error ERROR_KEY_GENERATION;        /** Returned when the KDF fails */
  error ERROR_KEY_CLEAR;             /** Returned when clearing the key fails */
  error ERROR_KEY_WRAP;              /** Returned when wrapping the key fails */
  error ERROR_OUT_OF_RESOURCES;      /** Returned when resources are not available */
  error ERROR_ALREADY_RUNNING;       /** Returned when an operation is already in progress */
  error ERROR_NOT_IN_MFG_MODE;       /** Returned for APIs that can only be called in manufacturing mode */
  error ERROR_IN_MFG_MODE;           /** Returned for APIs that can only be called out of manufacturing mode */
  error ERROR_READONLY;              /** Returned when writing to a write-protected partition */
  error ERROR_PARTITION_NOT_FOUND;   /** Returned when no partition is found */
  error ERROR_HASH_GENERATION;       /** Returned when hash calculation fails */  
  error ERROR_HASH_MISMATCH;         /** Returned when a hash mismatch is seen */

  /**
    Gets partition information

    @param[out] partition_info    Pointer to information about the partition

    @return
    Object_OK on success.
  */
  method GetPartitionInfo (out IStorRd_PartitionInfo partition_info);

  /**
    Reads data from a partition
    
    @param[in]   lba               Starting sector to read
    @param[in]   lba_count         Number of sectors to read
    @param[out]  data_buffer       Pointer to a buffer for the data 

    @return
    Object_OK on success.
  */
  method ReadLba (in uint64 lba, in uint64 lba_count, out buffer data_buffer); 

  /**
    Writes data to a partition
    
    @param[in]   lba               Starting sector to write
    @param[in]   lba_count         Number of sectors to write
    @param[out]  data_buffer       Pointer to a buffer for the data 

    @return
    Object_OK on success.
  */
  method WriteLba (in uint64 lba, in uint64 lba_count, in buffer data_buffer); 

  /* @} */ /* end_addtogroup IStorRdPartition */
};

/** @cond */
interface IStorRdIterator {
/** @endcond */

  /**
   * @addtogroup IStorRdIterator
   * @{
   */

  /** Partition iterator status values */
  const uint32 STATUS_NOT_STARTED = 1; 
  const uint32 STATUS_RUNNING     = 2;
  const uint32 STATUS_COMPLETE    = 3;

  /** Errors */
  error ERROR_INVALID_PARAM;         /** Returned when an invalid parameter is encountered */
  error ERROR_NOT_SUPPORTED;         /** Returned when an operation is not supported */
  error ERROR_DEVICE_ERROR;          /** Returned for any device errors */ 
  error ERROR_OUT_OF_RESOURCES;      /** Returned when resources are not available */
  error ERROR_ALREADY_RUNNING;       /** Returned when an operation is already in progress */

  /** @endcond */

  /**
    Gets the next code partition GPT entry
    
    @param[out]  entry   Pointer to the next GPT partition entry
    @param[out]  result  Indication of the job status (running or not, complete)

    @return
    Object_OK on success.
  */
  method GetNextCodePartitionEntry (out IStorRd_GptEntry gpt_entry, out uint32 result); 

  /* @} */ /* end_addtogroup IStorRdIterator */
};
