Intel® Quark™ Microcontroller Software Interface  1.4.0
Intel® Quark™ Microcontroller BSP
qm_fpr.h
1 /*
2  * {% copyright %}
3  */
4 
5 #ifndef __QM_FPR_H__
6 #define __QM_FPR_H__
7 
8 #include "qm_common.h"
9 #include "qm_soc_regs.h"
10 
11 /**
12  * Flash Protection Region control.
13  *
14  * @defgroup groupFPR FPR
15  * @{
16  */
17 typedef void (*qm_fpr_callback_t)(void *data);
18 
19 /**
20  * FPR enable type.
21  */
22 typedef enum {
23  QM_FPR_DISABLE, /**< Disable FPR. */
24  QM_FPR_ENABLE, /**< Enable FPR. */
25  QM_FPR_LOCK_DISABLE, /**< Disable FPR lock. */
26  QM_FPR_LOCK_ENABLE /**< Enable FPR lock. */
27 } qm_fpr_en_t;
28 
29 /**
30  * FPR violation mode type.
31  */
32 typedef enum {
33  FPR_VIOL_MODE_INTERRUPT = 0, /**< Generate interrupt on violation. */
34  FPR_VIOL_MODE_RESET, /**< Reset SoC on violation. */
35  FPR_VIOL_MODE_PROBE /**< Enter probe mode on violation. */
37 
38 /**
39  * FPR region type.
40  */
41 typedef enum {
42  QM_MAIN_FLASH_SYSTEM = 0, /**< System flash region. */
43 #if (QUARK_D2000)
44  QM_MAIN_FLASH_DATA, /**< Data flash region. */
45 #endif
46  QM_MAIN_FLASH_NUM, /**< Number of flash regions. */
48 
49 /**
50  * FPR read allow type.
51  */
52 typedef enum {
54  BIT(0), /**< Allow host processor to access flash region. */
55 #if (QUARK_SE)
57  BIT(1), /**< Allow sensor subsystem to access flash region. */
58 #endif
59  QM_FPR_DMA = BIT(2), /**< Allow DMA to access flash region. */
60 #if (QUARK_SE)
62  BIT(3) /**< Allow other agents to access flash region. */
63 #endif
65 
66 /**
67  * Flash Protection Region configuration structure.
68  */
69 typedef struct {
70  qm_fpr_en_t en_mask; /**< Enable/lock bitmask. */
71  qm_fpr_read_allow_t allow_agents; /**< Per-agent read enable bitmask. */
72  uint8_t up_bound; /**< 1KB-aligned upper Flash phys addr. */
73  uint8_t low_bound; /**< 1KB-aligned lower Flash phys addr. */
75 
76 #define QM_FPR_FPR0_REG_OFFSET (7)
77 
78 #define QM_FPR_WRITE_LOCK_OFFSET (31)
79 #define QM_FPR_ENABLE_OFFSET (30)
80 #define QM_FPR_ENABLE_MASK BIT(QM_FPR_ENABLE_OFFSET)
81 #define QM_FPR_RD_ALLOW_OFFSET (20)
82 #define QM_FPR_RD_ALLOW_MASK (0xF00000)
83 #define QM_FPR_UPPER_BOUND_OFFSET (10)
84 #define QM_FPR_UPPER_BOUND_MASK (0x3FC00)
85 #define QM_FPR_LOW_BOUND_MASK (0xFF)
86 #define QM_FPR_MPR_VSTS_VALID BIT(31)
87 
88 #define QM_FPR_LOCK BIT(31)
89 
90 #define QM_FPR_EN_MASK_ENABLE BIT(0)
91 #define QM_FPR_EN_MASK_LOCK BIT(1)
92 #define QM_FPR_AGENT_MASK_HOST BIT(0)
93 #define QM_FPR_AGENT_MASK_SS BIT(1)
94 #define QM_FPR_AGENT_MASK_DMA BIT(2)
95 #define QM_FPR_AGENT_MASK_OTHER BIT(3)
96 
97 /**
98  * Configure a Flash controller's Flash Protection Region.
99  *
100  * @param[in] flash Which Flash controller to configure.
101  * @param[in] id FPR identifier.
102  * @param[in] cfg FPR configuration.
103  * @param[in] region The region of Flash to be configured.
104  *
105  * @return Standard errno return type for QMSI.
106  * @retval 0 on success.
107  * @retval Negative @ref errno for possible error codes.
108  */
109 int qm_fpr_set_config(const qm_flash_t flash, const qm_fpr_id_t id,
110  const qm_fpr_config_t *const cfg,
111  const qm_flash_region_type_t region);
112 
113 /**
114  * Configure FPR violation behaviour.
115  *
116  * @param[in] mode (generate interrupt, warm reset, enter probe mode).
117  * @param[in] flash controller.
118  * @param[in] fpr_cb for interrupt mode (only).
119  * @param[in] data user callback data for interrupt mode (only).
120  *
121  * @return Standard errno return type for QMSI.
122  * @retval 0 on success.
123  * @retval Negative @ref errno for possible error codes.
124  */
126  const qm_flash_t flash,
127  qm_fpr_callback_t fpr_cb, void *data);
128 
129 /**
130  * Save FPR context.
131  *
132  * Save the configuration of the specified FPR peripheral
133  * before entering sleep.
134  * The Flash peripheral linked to the FPR saved needs
135  * to be saved as well by calling qm_flash_save_context().
136  *
137  * FPR configuration is lost after sleep and can therefore
138  * be modified even if this configuration was locked before sleep.
139  * To support persistent configuration, the configuration must be
140  * restored when resuming as part of the bootloader.
141  *
142  * @param[in] flash Flash index.
143  * @param[out] ctx FPR context structure. This must not be NULL.
144  *
145  * @return Standard errno return type for QMSI.
146  * @retval 0 on success.
147  * @retval Negative @ref errno for possible error codes.
148  */
149 int qm_fpr_save_context(const qm_flash_t flash, qm_fpr_context_t *const ctx);
150 
151 /**
152  * Restore FPR context.
153  *
154  * Restore the configuration of the specified FPR peripheral
155  * after exiting sleep.
156  * The Flash peripheral linked to the FPR restored needs
157  * to be restored as well by calling qm_flash_restore_context().
158  *
159  * FPR configuration is lost after sleep and can therefore
160  * be modified even if this configuration was locked before sleep.
161  * To support persistent configuration, the configuration must be
162  * restored when resuming as part of the bootloader.
163  *
164  * @param[in] flash Flash index.
165  * @param[in] ctx FPR context structure. This must not be NULL.
166  *
167  * @return Standard errno return type for QMSI.
168  * @retval 0 on success.
169  * @retval Negative @ref errno for possible error codes.
170  */
171 int qm_fpr_restore_context(const qm_flash_t flash,
172  const qm_fpr_context_t *const ctx);
173 
174 /**
175  * @}
176  */
177 
178 #endif /* __QM_FPR_H__ */
Allow DMA to access flash region.
Definition: qm_fpr.h:59
System flash region.
Definition: qm_fpr.h:42
int qm_fpr_set_violation_policy(const qm_fpr_viol_mode_t mode, const qm_flash_t flash, qm_fpr_callback_t fpr_cb, void *data)
Configure FPR violation behaviour.
Definition: qm_fpr.c:70
uint8_t low_bound
1KB-aligned lower Flash phys addr.
Definition: qm_fpr.h:73
Flash Protection Region configuration structure.
Definition: qm_fpr.h:69
Allow other agents to access flash region.
Definition: qm_fpr.h:61
int qm_fpr_restore_context(const qm_flash_t flash, const qm_fpr_context_t *const ctx)
Restore FPR context.
Definition: qm_fpr.c:197
qm_fpr_read_allow_t allow_agents
Per-agent read enable bitmask.
Definition: qm_fpr.h:71
Allow host processor to access flash region.
Definition: qm_fpr.h:53
Enter probe mode on violation.
Definition: qm_fpr.h:35
qm_flash_t
Number of Flash controllers.
Definition: qm_soc_regs.h:1141
uint8_t up_bound
1KB-aligned upper Flash phys addr.
Definition: qm_fpr.h:72
qm_fpr_en_t
FPR enable type.
Definition: qm_fpr.h:22
int qm_fpr_set_config(const qm_flash_t flash, const qm_fpr_id_t id, const qm_fpr_config_t *const cfg, const qm_flash_region_type_t region)
Configure a Flash controller's Flash Protection Region.
Definition: qm_fpr.c:34
FPR context type.
Definition: qm_soc_regs.h:1591
Disable FPR.
Definition: qm_fpr.h:23
qm_fpr_en_t en_mask
Enable/lock bitmask.
Definition: qm_fpr.h:70
Generate interrupt on violation.
Definition: qm_fpr.h:33
Number of flash regions.
Definition: qm_fpr.h:46
Data flash region.
Definition: qm_fpr.h:44
int qm_fpr_save_context(const qm_flash_t flash, qm_fpr_context_t *const ctx)
Save FPR context.
Definition: qm_fpr.c:182
qm_fpr_read_allow_t
FPR read allow type.
Definition: qm_fpr.h:52
Disable FPR lock.
Definition: qm_fpr.h:25
Reset SoC on violation.
Definition: qm_fpr.h:34
qm_fpr_id_t
FPR register map.
Definition: qm_soc_regs.h:1265
qm_fpr_viol_mode_t
FPR violation mode type.
Definition: qm_fpr.h:32
Enable FPR lock.
Definition: qm_fpr.h:26
Allow sensor subsystem to access flash region.
Definition: qm_fpr.h:56
qm_flash_region_type_t
FPR region type.
Definition: qm_fpr.h:41
Enable FPR.
Definition: qm_fpr.h:24