ra8_bkup.h

Go to the documentation of this file.

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

typedef enum : uint8_t {
  k_ra8_bkup_vdet_2p80v = 0U, 
  k_ra8_bkup_vdet_2p53v = 1U, 
  k_ra8_bkup_vdet_2p10v = 2U, 
  k_ra8_bkup_vdet_1p95v = 3U, 
  k_ra8_bkup_vdet_1p85v = 4U, 
  k_ra8_bkup_vdet_1p75v = 5U, 
} ra8_bkup_vdet_level_t;

typedef enum : uint8_t {
  k_ra8_bkup_source_vbatt = 0U, 
  k_ra8_bkup_source_vcc   = 1U, 
} ra8_bkup_source_t;

typedef enum : uint8_t {
  k_ra8_bkup_chan_rtcic0 = 0U, 
  k_ra8_bkup_chan_rtcic1 = 1U, 
  k_ra8_bkup_chan_rtcic2 = 2U, 
} ra8_bkup_channel_t;

typedef enum : uint8_t {
  k_ra8_bkup_edge_falling = 0U, 
  k_ra8_bkup_edge_rising  = 1U, 
} ra8_bkup_edge_t;

typedef enum : uint8_t {
  k_ra8_bkup_nc_width_32768hz = 0U, 
  k_ra8_bkup_nc_width_64hz    = 1U, 
  k_ra8_bkup_nc_width_32hz    = 2U, 
  k_ra8_bkup_nc_width_16hz    = 3U, 
  k_ra8_bkup_nc_width_8hz     = 4U, 
  k_ra8_bkup_nc_width_4hz     = 5U, 
  k_ra8_bkup_nc_width_2hz     = 6U, 
  k_ra8_bkup_nc_width_1hz     = 7U, 
} ra8_bkup_nc_width_t;

typedef enum : uint8_t {
  k_ra8_bkup_capture_src_pin    = 0U, 
  k_ra8_bkup_capture_src_vbtadf = 1U, 
} ra8_bkup_capture_src_t;
 
/* =============================================================================
 * Configuration / status structures
 * =============================================================================
 */

typedef struct {
  ra8_bkup_vdet_level_t vdet_level;    
  bool                  enable_switch; 
  bool                  enable_backup; 
} ra8_bkup_config_t;

typedef struct {
  ra8_bkup_source_t source;       
  bool              vbatt_r_ok;   
  bool              por_detected; 
  uint8_t           tamper_flags; 
  uint8_t           raw_vbtbpsr;  
} ra8_bkup_status_t;

typedef struct {
  bool                   input_enable;       
  bool                   noise_canceller_en; 
  ra8_bkup_edge_t        edge;               
  bool                   irq_enable;         
  bool                   clear_backup;       
  bool                   zeroize_huk;        
  ra8_bkup_capture_src_t capture_src;        
} ra8_bkup_tamper_chan_cfg_t;

typedef struct {
  ra8_bkup_nc_width_t nc_width; 
  ra8_bkup_tamper_chan_cfg_t channels[(uint8_t)k_ra8_bkup_chan_count];
} ra8_bkup_tamper_config_t;

typedef struct {
  uint32_t bbfsar; 
  uint16_t saba;   
  uint16_t pabas;  
  uint16_t pabans; 
} ra8_bkup_security_config_t;

typedef void (*ra8_bkup_event_fn_t)(void* ctx, uint8_t tamper_flags);
 
/* =============================================================================
 * Lifecycle
 * =============================================================================
 */

[[nodiscard]] ra8_err_t ra8_bkup_init(const ra8_bkup_config_t* cfg);

[[nodiscard]] ra8_err_t ra8_bkup_deinit(void);

[[nodiscard]] ra8_err_t ra8_bkup_cold_start_init(ra8_bkup_vdet_level_t level,
                                                 uint32_t              timeout_iters);

[[nodiscard]] ra8_err_t ra8_bkup_warm_start_check(bool* needs_reinit, uint32_t timeout_iters);

[[nodiscard]] ra8_err_t ra8_bkup_no_switch_init(uint32_t timeout_iters);
 
/* =============================================================================
 * Status
 * =============================================================================
 */

[[nodiscard]] ra8_err_t ra8_bkup_get_status(ra8_bkup_status_t* out);

[[nodiscard]] ra8_err_t ra8_bkup_clear_status(uint8_t mask);
 
/* =============================================================================
 * VBTBKRn 32-bit word access
 * =============================================================================
 */

[[nodiscard]] ra8_err_t ra8_bkup_read_word(uint8_t word_index, uint32_t* out);

[[nodiscard]] ra8_err_t ra8_bkup_write_word(uint8_t word_index, uint32_t value);

[[nodiscard]] ra8_err_t ra8_bkup_read_byte(uint16_t index, uint8_t* out);

[[nodiscard]] ra8_err_t ra8_bkup_write_byte(uint16_t index, uint8_t value);

[[nodiscard]] ra8_err_t ra8_bkup_zero_all(void);
 
/* =============================================================================
 * Tamper-detection / RTCIC pad wiring
 * =============================================================================
 */

[[nodiscard]] ra8_err_t ra8_bkup_tamper_init(const ra8_bkup_tamper_config_t* cfg);

[[nodiscard]] ra8_err_t ra8_bkup_tamper_disable(void);

[[nodiscard]] ra8_err_t ra8_bkup_read_input(ra8_bkup_channel_t channel, bool* high_out);

[[nodiscard]] ra8_err_t ra8_bkup_set_input_enable(ra8_bkup_channel_t channel, bool enable);
 
/* =============================================================================
 * VBATT analog voltage monitor (VBATTMNSELR)
 * =============================================================================
 */

[[nodiscard]] ra8_err_t ra8_bkup_set_voltage_monitor(bool enable);

[[nodiscard]] ra8_err_t ra8_bkup_get_voltage_monitor_enabled(bool* enabled_out);
 
/* =============================================================================
 * TrustZone partitioning
 * =============================================================================
 */

[[nodiscard]] ra8_err_t ra8_bkup_security_apply(const ra8_bkup_security_config_t* cfg);

[[nodiscard]] ra8_err_t ra8_bkup_security_get(ra8_bkup_security_config_t* cfg);
 
/* =============================================================================
 * Interrupt path
 * =============================================================================
 */

[[nodiscard]] ra8_err_t ra8_bkup_attach_handler(ra8_bkup_event_fn_t fn, void* ctx);

[[nodiscard]] ra8_err_t ra8_bkup_isr_handle(void);

void ra8_bkup_dispatch(uint8_t tamper_flags);
 
#ifdef __cplusplus
}
#endif