ra8_dotf.h

Go to the documentation of this file.

 
#pragma once
 
#ifdef __cplusplus
extern "C" {
#endif
 
#include <stdint.h>
 
#include "ra8_dotf_regs.h"
#include "ra8_err.h"
 
/* =============================================================================
 * Configuration enums
 * =============================================================================
 */

typedef enum : uint32_t {
  k_ra8_dotf_key_size_128 = k_ra8_dotf_reg00_key_size_128, 
  k_ra8_dotf_key_size_192 = k_ra8_dotf_reg00_key_size_192, 
  k_ra8_dotf_key_size_256 = k_ra8_dotf_reg00_key_size_256, 
} ra8_dotf_key_size_t;

typedef enum : uint8_t {
  k_ra8_dotf_sca_off      = 0U, 
  k_ra8_dotf_sca_standard = 1U, 
  k_ra8_dotf_sca_max      = 2U, 
} ra8_dotf_sca_level_t;
 
/* =============================================================================
 * Region descriptor
 * =============================================================================
 */

typedef struct {
  uint32_t start_addr; 
  uint32_t end_addr;   
  uint8_t  key_index;  
  uint8_t  region_id;  
} ra8_dotf_region_t;
 
/* =============================================================================
 * Key handle (opaque to ra8_rsip)
 * =============================================================================
 */

typedef struct {
  ra8_dotf_key_size_t size;      
  uint8_t             key_index; 
  uint8_t             valid;     
  uint32_t            words[8];  
} ra8_dotf_key_handle_t;

typedef void (*ra8_dotf_event_fn_t)(void* ctx, uint8_t channel);
 
/* =============================================================================
 * Lifecycle
 * =============================================================================
 */

[[nodiscard]] ra8_err_t ra8_dotf_init(void);

[[nodiscard]] ra8_err_t ra8_dotf_deinit(void);
 
/* =============================================================================
 * Per-region configuration (multi-region staging)
 * =============================================================================
 */

[[nodiscard]] ra8_err_t ra8_dotf_set_region(uint8_t channel, const ra8_dotf_region_t* region);

[[nodiscard]] ra8_err_t ra8_dotf_select_region(uint8_t channel, uint8_t region_id);

[[nodiscard]] ra8_err_t ra8_dotf_get_active_region(uint8_t channel, ra8_dotf_region_t* region);
 
/* =============================================================================
 * RSIP key + IV staging
 * =============================================================================
 */

[[nodiscard]] ra8_err_t ra8_dotf_install_key(uint8_t channel, const ra8_dotf_key_handle_t* handle);

[[nodiscard]] ra8_err_t ra8_dotf_rotate_key(uint8_t                      channel,
                                            const ra8_dotf_key_handle_t* new_handle,
                                            const uint32_t*              iv_words);

[[nodiscard]] ra8_err_t ra8_dotf_set_iv(uint8_t channel, const uint32_t* iv_words);
 
/* =============================================================================
 * Per-channel enable / disable
 * =============================================================================
 */

[[nodiscard]] ra8_err_t ra8_dotf_enable(uint8_t channel);

[[nodiscard]] ra8_err_t ra8_dotf_disable(uint8_t channel);
 
/* =============================================================================
 * REG00 sub-field tuning
 * =============================================================================
 */

[[nodiscard]] ra8_err_t ra8_dotf_set_sca_level(uint8_t channel, ra8_dotf_sca_level_t level);

[[nodiscard]] ra8_err_t ra8_dotf_set_key_size(uint8_t channel, ra8_dotf_key_size_t size);

[[nodiscard]] ra8_err_t ra8_dotf_run_self_test(uint8_t channel, uint32_t* out_status);
 
/* =============================================================================
 * Status accessors
 * =============================================================================
 */

[[nodiscard]] ra8_err_t ra8_dotf_get_status(uint8_t channel, uint32_t* out_mask);

[[nodiscard]] ra8_err_t ra8_dotf_clear_status(uint8_t channel);
 
/* =============================================================================
 * IRQ attach / dispatch
 * =============================================================================
 */

[[nodiscard]] ra8_err_t ra8_dotf_attach_handler(ra8_dotf_event_fn_t fn, void* ctx);

void ra8_dotf_dispatch(uint8_t channel);
 
/* =============================================================================
 * Power transition
 * =============================================================================
 */

typedef struct {
  uint8_t               channel;      
  ra8_dotf_key_handle_t key;          
  uint32_t              iv_words[4];  
  ra8_dotf_region_t     region;       
  ra8_dotf_sca_level_t  sca_level;    
  bool                  enable_after; 
} ra8_dotf_open_cfg_t;

[[nodiscard]] ra8_err_t ra8_dotf_open(const ra8_dotf_open_cfg_t* cfg);

[[nodiscard]] ra8_err_t ra8_dotf_close(void);

[[nodiscard]] ra8_err_t ra8_dotf_set_region_window(uint8_t channel, uint32_t start, uint32_t len);

[[nodiscard]] ra8_err_t ra8_dotf_enter_stop(void);

[[nodiscard]] ra8_err_t ra8_dotf_exit_stop(void);
 
#ifdef __cplusplus
}
#endif