KM3NeT CLB  2.0
KM3NeT CLB v2 Embedded Software
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
sflash.h
Go to the documentation of this file.
1 /*
2  * KM3NeT CLB v2 Firmware
3  * ----------------------
4  *
5  * Copyright 2013 KM3NeT Collaboration
6  *
7  * All Rights Reserved.
8  *
9  *
10  * File : sflash.h
11  * Created : 29 jan. 2014
12  * Author : Vincent van Beveren
13  */
14 
15 #ifndef SFLASH_H_
16 #define SFLASH_H_
17 
18 #include <stdbool.h>
19 #include <stdint.h>
20 #include <errorcode.h>
21 
22 
23 /**
24  * @file
25  *
26  * @ingroup spidrivers
27  *
28  * This driver implements access to the Serial Flash.
29  *
30  * Note that this interface is probably a standard, but I could not find it.
31  */
32 
33 #define SF_MF_SPANSION 0x01 //!< Manufacturer Spansion
34 #define SF_MF_MICRON 0x20 //!< Manufacturer Micron
35 
36 #define SF_DEV_MICRON_N25QA 0xBA
37 #define SF_DEV_SPANSION_S25FL 0x02
38 
39 #define E_SF_DEVNOTFOUND ( E_SFLASH + 1 )
40 #define E_SF_DEVNOTFOUND_DESCR "Device not supported or no device found"
41 
42 #define E_SF_WRITEERASE ( E_SFLASH + 2 )
43 #define E_SF_WRITEERASE_DESCR "Flash write or erase error"
44 
45 #define E_SF_PASSWORD ( E_SFLASH + 3 )
46 #define E_SF_PASSWORD_DESCR "Password failed"
47 
48 
49 #define SF_INFO_CAP_PASSWORD 0x1 //!< Device supports password protection.
50 #define SF_INFO_CAP_SECTOR_PROTECT 0x2 //!< Device support per sector protection
51 
52 #define SF_INFO_STS_PASSWORD_PROTECT 0x1 //!< Whether (part of) the flash is password
53  //!< protected.
54 #define SF_INFO_STS_LOCKED 0x2 //!< Whether part of the flash is locked.
55 
56 //! Serial Flash password
57 typedef uint8_t SfPassword[8];
58 
59 
60 
61 typedef struct {
62  uint32_t sectorSize; //!< Sector size in bytes
63  uint32_t flashSize; //!< flash size in bytes
64  uint16_t pageSize; //!< Page size in bytes
65  uint8_t mfId; //!< Manufacturer ID
66  uint8_t devId; //!< Device ID
67  uint8_t devCap; //!< Device capacity ID
68  uint8_t cap; //!< Device capabilities, see SF_INF_CAP_*
69  uint8_t sts; //!< Device status, see SF_INFO_STS_*
70  uint8_t _status; //!< Hardware status register value. For debugging. Device specific.
71 } SfInfo;
72 
73 //! Flash info, only valid after successful initialization.
74 extern SfInfo sfInfo;
75 
76 /**
77  * Initializes the Serial Flash.
78  *
79  * @retval true Flash detected and initialized
80  * @retval false Some error occurred. Check error module for error.
81  */
82 bool sfInit();
83 
84 /**
85  * Resets the flash.
86  *
87  * @retval true Flash detected and initialized
88  * @retval false Some error occurred. Check error module for error.
89  */
90 bool sfReset();
91 
92 /**
93  * Read from a specific address in flash.
94  *
95  * @param address Offset address
96  * @param data Data array to fill up to 'count' bytes.
97  * @param count No. of bytes to read.
98  *
99  * @retval true Flash read successfully.
100  * @retval false Some error occurred. Check error module for error.
101  */
102 bool sfRead(uint32_t address, uint8_t * data, uint32_t count);
103 
104 /**
105  * Program an page in flash.
106  *
107  * Note that a maximum of 'sfInfo.pageSize' bytes can be programmed at once, and only per page. If
108  * programming continues over the page boundary it will continue at the beginning of the same page.
109  *
110  * @param address Offset address
111  * @param data Data array to read up to 'count' bytes.
112  * @param count No. of bytes to write.
113  *
114  * @retval true Flash read successfully.
115  * @retval false Some error occurred. Check error module for error.
116  */
117 bool sfProg(uint32_t address, uint8_t * data, uint32_t count);
118 
119 /**
120  * Program cross pages.
121  *
122  * Unlike sfProg this function can write over page boundaries and multiple pages, e.g. it does
123  * not really matter where you start or end. There is a small performance penalty.
124  *
125  * @param address Offset address
126  * @param data Data array to read up to 'count' bytes.
127  * @param count No. of bytes to write.
128  *
129  * @retval true Flash read successfully.
130  * @retval false Some error occurred. Check error module for error.
131  */
132 bool sfProgXPage(uint32_t address, uint8_t * data, uint32_t count);
133 
134 
135 /**
136  * Erase a sector in flash.
137  *
138  * Erases a 'sfInfo.sectorSize'-sized sector in flash. Note that though a full 32 bit address is
139  * accepted, only the most significant bits will be used.
140  *
141  * @param address Offset address
142  *
143  * @retval true Flash read successfully.
144  * @retval false Some error occurred. Check error module for error.
145  */
146 bool sfErase(uint32_t address);
147 
148 /**
149  * Quad enable,
150  *
151  * @param enable Enables the quad mode
152  *
153  * @retval true Command successful
154  * @retval false Command failed, check error module for error.
155  */
156 bool sfQuadEnable(bool enable);
157 
158 
159 /**
160  * Password protects specific sectors from being modified. Before setting the password you can
161  * select wich sectors need to be protected.
162  *
163  * @note sfProtect can only be used before issuing this command, or after unlocking the flash
164  * using sfLockUnlock().
165  *
166  * @param password A poiner to the password.
167  *
168  * @retval true Command successful
169  * @retval false Command failed, check error module for error.
170  */
171 bool sfSetPasswordOTP(SfPassword * password);
172 
173 /**
174  * Unlocks or locks the flash with the specified password.
175  *
176  * @param password A pointer to the password, or NULL to lock.
177  *
178  * @retval true Command successful
179  * @retval false Command failed, check error module for error.
180  */
181 bool sfLockUnlock(SfPassword * password);
182 
183 
184 
185 /**
186  * Protects a specific sector from being erased or programmed.
187  *
188  * @param address First location of the sector to be protected.
189  *
190  * @note This command can only be issued before SetPasswordOTP, or after issuing the right password
191  * using sfLockUnlock().
192  *
193  * @note Though a full 32 bit address is accepted, only the first byte on the first page of each
194  * sector should be addressed.
195  *
196  * @retval true Command successful
197  * @retval false Command failed, check error module for error.
198  */
199 bool sfProtect(uint32_t address);
200 
201 /**
202  * Unprotects the entire flash array.
203  *
204  * @note This command can only be issued before SetPasswordOTP, or after issuing the right password
205  * using sfLockUnlock().
206  *
207  * @retval true Command successful
208  * @retval false Command failed, check error module for error.
209  */
210 bool sfUnProtect();
211 
212 /**
213  * Shows diagnostic state of Spansion Flash.
214  */
215 void sfSpDiag();
216 
217 #endif /* SFLASH_H_ */
bool sfQuadEnable(bool enable)
Quad enable,.
Definition: sflash.c:442
bool sfLockUnlock(SfPassword *password)
Unlocks or locks the flash with the specified password.
Definition: sflash.c:645
uint8_t SfPassword[8]
Serial Flash password.
Definition: sflash.h:57
bool sfInit()
Initializes the Serial Flash.
Definition: sflash.c:435
Definition: sflash.h:61
uint32_t flashSize
flash size in bytes
Definition: sflash.h:63
uint8_t mfId
Manufacturer ID.
Definition: sflash.h:65
uint8_t _status
Hardware status register value.
Definition: sflash.h:70
uint8_t cap
Device capabilities, see SF_INF_CAP_*.
Definition: sflash.h:68
SfInfo sfInfo
Flash info, only valid after successful initialization.
Definition: sflash.c:161
uint16_t pageSize
Page size in bytes.
Definition: sflash.h:64
uint32_t sectorSize
Sector size in bytes.
Definition: sflash.h:62
bool sfReset()
Resets the flash.
Definition: sflash.c:320
bool sfErase(uint32_t address)
Erase a sector in flash.
Definition: sflash.c:564
uint8_t sts
Device status, see SF_INFO_STS_*.
Definition: sflash.h:69
bool sfSetPasswordOTP(SfPassword *password)
Password protects specific sectors from being modified.
Definition: sflash.c:589
uint8_t devId
Device ID.
Definition: sflash.h:66
bool sfProtect(uint32_t address)
Protects a specific sector from being erased or programmed.
Definition: sflash.c:672
bool sfProgXPage(uint32_t address, uint8_t *data, uint32_t count)
Program cross pages.
Definition: sflash.c:547
This module is responsible for distributing error codes.
uint8_t devCap
Device capacity ID.
Definition: sflash.h:67
bool sfRead(uint32_t address, uint8_t *data, uint32_t count)
Read from a specific address in flash.
Definition: sflash.c:491
bool sfProg(uint32_t address, uint8_t *data, uint32_t count)
Program an page in flash.
Definition: sflash.c:519
void sfSpDiag()
Shows diagnostic state of Spansion Flash.
Definition: sflash.c:627
bool sfUnProtect()
Unprotects the entire flash array.
Definition: sflash.c:690