1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
|
/*****************************************************************************
* @file ee.h
* @author MCD Application Team
* @brief This file contains the interface of the EEPROM emulator
* for Dory platform.
*****************************************************************************
* @attention
*
* <h2><center>© Copyright (c) 2020 STMicroelectronics.
* All rights reserved.</center></h2>
*
* This software component is licensed by ST under Ultimate Liberty license
* SLA0044, the "License"; You may not use this file except in compliance with
* the License. You may obtain a copy of the License at:
* www.st.com/SLA0044
*
*****************************************************************************
*/
#ifndef EE_H__
#define EE_H__
/*
* Description
* -----------
* the EE module implements an EEPROM emulator in one C file ("ee.c").
* Its interface is defined below in this file ("ee.h").
* Up to two independent banks can be configured.
* Data granularity for store and read is one 32-bit word.
*
* Configuration and dependencies
* ------------------------------
* the EE module includes a generic configuration header file "ee_cfg.h":
* this file has to be defined by the user and must provide the following:
*
* - Hardware flash driver definitions:
*
* * HW_FLASH_PAGE_SIZE (in bytes)
*
* * HW_FLASH_WIDTH (in bytes)
*
* * int HW_FLASH_Write( uint32_t address,
* uint64_t data );
*
* * int HW_FLASH_Erase( uint32_t page,
* uint16_t n,
* int interrupt );
*
* - Optional configuration definitions:
*
* * CFG_EE_BANK0_SIZE
* Size of the first bank in bytes (must be greater than 0).
* It must be a multiple of twice the page size.
* If not defined, it is set to twice the page size.
*
* * CFG_EE_BANK0_MAX_NB
* Maximum number of (32-bit) data that can be stored in the first bank.
* This definition is only used during preprocessing for check.
*
* * CFG_EE_BANK1_SIZE
* Size of the second bank in bytes (can be 0 if the bank is not used).
* It must be a multiple of twice the page size.
* If not defined, it is set to 0.
*
* * CFG_EE_BANK1_MAX_NB
* Maximum number of (32-bit) data that can be stored in the second bank.
* This definition is only used during preprocessing for check.
*
* * CFG_EE_AUTO_CLEAN
* When set to 1, this setting forces EE_Clean to be called at end of
* EE_Write when needed.
*
*
* Notes
* -----
* - a corrupted word in FLASH detected by the user software shall be set to 0.
* The EEPROM emulation software will then handle it properly.
*/
#include <stdint.h>
/* Definition of the functions return value */
enum
{
EE_OK = 0,
EE_NOT_FOUND, /* read data is not found in flash */
EE_CLEAN_NEEDED, /* data is written but a "clean" is needed */
EE_ERASE_ERROR, /* an error occurs during flash erase */
EE_WRITE_ERROR, /* an error occurs during flash write */
EE_STATE_ERROR /* state of flash is incoherent (needs clean or format) */
};
/*
* EE_Init
*
* Initialization of EEPROM emulation module. It must be called once at reset.
*
* format: 0 -> recover EE state from flash and restore the pages
* to a known good state in case of power loss.
* 1 -> erase all the pages: starts from scratch.
* This format mode can be activated the very first time EEPROM
* emulation is used, to prepare flash pages for EEPROM emulation
* with empty EEPROM
*
* base_address: absolute start address of flash area used for EEPROM
* emulation. It must be a multiple of flash page size.
*
* return: EE_OK in case of success
* EE..._ERROR in case of error
*/
extern int EE_Init( int format,
uint32_t base_address );
/*
* EE_Read
*
* Returns the last stored variable data, if found, which corresponds to
* the passed virtual address
*
* bank: index of the bank (0 or 1)
*
* addr: variable virtual address
*
* data: pointer to a 32-bit word (allocated by the caller) containing the
* variable value in case of success.
*
* return: EE_OK in case of success
* EE_NOT_FOUND in case this virtual address has never been written to
* EE..._ERROR in case of error
*/
extern int EE_Read( int bank, uint16_t addr, uint32_t* data );
/*
* EE_Write
*
* Writes/updates variable data in EEPROM emulator.
* Triggers internal pages transfer if flash pool is full.
*
* bank: index of the bank (0 or 1)
*
* addr: variable virtual address
*
* data: 32-bit data word to be written
*
* return: EE_OK in case of success
* EE_CLEAN_NEEDED if success but user must trigger flash cleanup
* by calling EE_Clean()
* EE..._ERROR in case of error
*/
extern int EE_Write( int bank, uint16_t addr, uint32_t data );
/*
* EE_Clean
*
* Erase obsolete pool of pages in polling or interrupt mode.
* This function should be called when EE_Write() has returned EE_CLEAN_NEEDED
* (and only in that case)
* If interrupt mode is used, the user must declare a function with the
* following prototype (see hw.h):
* void HWCB_FLASH_EndOfCleanup( void );
* this function is called under FLASH IRQ handler at end of cleanup.
*
* bank: index of the bank (0 or 1)
*
* interrupt: 0 -> polling mode
* 1 -> interrupt mode
*
* return: EE_OK in case of success
* EE..._ERROR in case of error
*/
extern int EE_Clean( int bank, int interrupt );
/*
* EE_Dump
*
* Dumps part of the EEPROM emulation content.
* For the purpose of dumping the full content of the EEPROM, this function is
* faster than calling several times the EE_Read() function.
* Note 1: for speed purpose, CRC is not checked. If you need CRC to be
* checked, you must use EE_Read() instead.
* Note 2: Some part of the output buffer can be not written if the
* corresponding variables have not been stored in the EEPROM.
*
* bank: index of the bank (0 or 1)
*
* addr: virtual address of the first variable to dump
*
* data: pointer to a 32-bit buffer (allocated by the caller) where the
* variables from the EEPROM emulation are written.
* Variable from virtual address addr is stored in data[0],
* variable from virtual address (addr+1) is stored in data[1],
* ...
* variable from virtual address (addr+size-1) is stored in
* data[size-1].
*
* size: number of consecutive variables to dump
*
* return: none
*/
extern void EE_Dump( int bank, uint16_t addr, uint32_t* data, uint16_t size );
#endif /* EE_H__ */
|
