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
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
|
/*
* Interface to SPI flash
*
* Copyright (C) 2008 Atmel Corporation
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License
* version 2 as published by the Free Software Foundation.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*/
#ifndef _SPI_FLASH_H_
#define _SPI_FLASH_H_
#include <stdint.h>
#include <stddef.h>
#include <spi-generic.h>
#include <boot/coreboot_tables.h>
/* SPI Flash opcodes */
#define SPI_OPCODE_WREN 0x06
#define SPI_OPCODE_FAST_READ 0x0b
struct spi_flash;
/*
* SPI write protection is enforced by locking the status register.
* The following modes are known. It depends on the flash chip if the
* mode is actually supported.
*
* PRESERVE : Keep the previous status register lock-down setting (noop)
* NONE : Status register isn't locked
* PIN : Status register is locked as long as the ~WP pin is active
* REBOOT : Status register is locked until power failure
* PERMANENT: Status register is permanently locked
*/
enum spi_flash_status_reg_lockdown {
SPI_WRITE_PROTECTION_PRESERVE = -1,
SPI_WRITE_PROTECTION_NONE = 0,
SPI_WRITE_PROTECTION_PIN,
SPI_WRITE_PROTECTION_REBOOT,
SPI_WRITE_PROTECTION_PERMANENT
};
/*
* Representation of SPI flash operations:
* read: Flash read operation.
* write: Flash write operation.
* erase: Flash erase operation.
* status: Read flash status register.
*/
struct spi_flash_ops {
int (*read)(const struct spi_flash *flash, u32 offset, size_t len,
void *buf);
int (*write)(const struct spi_flash *flash, u32 offset, size_t len,
const void *buf);
int (*erase)(const struct spi_flash *flash, u32 offset, size_t len);
int (*status)(const struct spi_flash *flash, u8 *reg);
};
/* Current code assumes all callbacks are supplied in this object. */
struct spi_flash_protection_ops {
/*
* Returns 1 if the whole region is software write protected.
* Hardware write protection mechanism aren't accounted.
* If the write protection could be changed, due to unlocked status
* register for example, 0 should be returned.
* Returns 0 on success.
*/
int (*get_write)(const struct spi_flash *flash,
const struct region *region);
/*
* Enable the status register write protection, if supported on the
* requested region, and optionally enable status register lock-down.
* Returns 0 if the whole region was software write protected.
* Hardware write protection mechanism aren't accounted.
* If the status register is locked and the requested configuration
* doesn't match the selected one, return an error.
* Only a single region is supported !
*
* @return 0 on success
*/
int
(*set_write)(const struct spi_flash *flash,
const struct region *region,
const bool non_volatile,
const enum spi_flash_status_reg_lockdown mode);
};
struct spi_flash_part_id;
struct spi_flash {
struct spi_slave spi;
u8 vendor;
union {
u8 raw;
struct {
u8 dual_spi : 1;
u8 _reserved : 7;
};
} flags;
u16 model;
const char *name;
u32 size;
u32 sector_size;
u32 page_size;
u8 erase_cmd;
u8 status_cmd;
u8 pp_cmd; /* Page program command. */
u8 wren_cmd; /* Write Enable command. */
const struct spi_flash_ops *ops;
/* If !NULL all protection callbacks exist. */
const struct spi_flash_protection_ops *prot_ops;
const struct spi_flash_part_id *part;
};
void lb_spi_flash(struct lb_header *header);
/* SPI Flash Driver Public API */
/*
* Probe for SPI flash chip on given SPI bus and chip select and fill info in
* spi_flash structure.
*
* Params:
* bus = SPI Bus # for the flash chip
* cs = Chip select # for the flash chip
* flash = Pointer to spi flash structure that needs to be filled
*
* Return value:
* 0 = success
* non-zero = error
*/
int spi_flash_probe(unsigned int bus, unsigned int cs, struct spi_flash *flash);
/*
* Generic probing for SPI flash chip based on the different flashes provided.
*
* Params:
* spi = Pointer to spi_slave structure
* flash = Pointer to spi_flash structure that needs to be filled.
*
* Return value:
* 0 = success
* non-zero = error
*/
int spi_flash_generic_probe(const struct spi_slave *slave,
struct spi_flash *flash);
/* All the following functions return 0 on success and non-zero on error. */
int spi_flash_read(const struct spi_flash *flash, u32 offset, size_t len,
void *buf);
int spi_flash_write(const struct spi_flash *flash, u32 offset, size_t len,
const void *buf);
int spi_flash_erase(const struct spi_flash *flash, u32 offset, size_t len);
int spi_flash_status(const struct spi_flash *flash, u8 *reg);
/*
* Return the vendor dependent SPI flash write protection state.
* @param flash : A SPI flash device
* @param region: A subregion of the device's region
*
* Returns:
* -1 on error
* 0 if the device doesn't support block protection
* 0 if the device doesn't enable block protection
* 0 if given range isn't covered by block protection
* 1 if given range is covered by block protection
*/
int spi_flash_is_write_protected(const struct spi_flash *flash,
const struct region *region);
/*
* Enable the vendor dependent SPI flash write protection. The region not
* covered by write-protection will be set to write-able state.
* Only a single write-protected region is supported.
* Some flash ICs require the region to be aligned in the block size, sector
* size or page size.
* Some flash ICs require the region to start at TOP or BOTTOM.
*
* @param flash : A SPI flash device
* @param region: A subregion of the device's region
* @param non_volatile: Write status register non-volatile
* @param mode: Optional lock-down of status register
* @return 0 on success
*/
int
spi_flash_set_write_protected(const struct spi_flash *flash,
const struct region *region,
const bool non_volatile,
const enum spi_flash_status_reg_lockdown mode);
/*
* Some SPI controllers require exclusive access to SPI flash when volatile
* operations like erase or write are being performed. In such cases,
* volatile_group_begin will gain exclusive access to SPI flash if not already
* acquired and volatile_group_end will end exclusive access if this was the
* last request in the group. spi_flash_{write,erase} operations call
* volatile_group_begin at the start of function and volatile_group_end after
* erase/write operation is performed. These functions can also be used by any
* components that wish to club multiple volatile operations into a single
* group.
*/
int spi_flash_volatile_group_begin(const struct spi_flash *flash);
int spi_flash_volatile_group_end(const struct spi_flash *flash);
/*
* These are callbacks for marking the start and end of volatile group as
* handled by the chipset. Not every chipset requires this special handling. So,
* these functions are expected to be implemented in Kconfig option for volatile
* group is enabled (SPI_FLASH_HAS_VOLATILE_GROUP).
*/
int chipset_volatile_group_begin(const struct spi_flash *flash);
int chipset_volatile_group_end(const struct spi_flash *flash);
/* Return spi_flash object reference for the boot device. This is only valid
* if CONFIG_BOOT_DEVICE_SPI_FLASH is enabled. */
const struct spi_flash *boot_device_spi_flash(void);
/* Protect a region of spi flash using its controller, if available. Returns
* < 0 on error, else 0 on success. */
int spi_flash_ctrlr_protect_region(const struct spi_flash *flash,
const struct region *region,
const enum ctrlr_prot_type type);
/*
* This function is provided to support spi flash command-response transactions.
* Only 2 vectors are supported and the 'func' is called with appropriate
* write and read buffers together. This can be used for chipsets that
* have specific spi flash controllers that don't conform to the normal
* spi xfer API because they are specialized controllers and not generic.
*
* Returns 0 on success and non-zero on failure.
*/
int spi_flash_vector_helper(const struct spi_slave *slave,
struct spi_op vectors[], size_t count,
int (*func)(const struct spi_slave *slave, const void *dout,
size_t bytesout, void *din, size_t bytesin));
#endif /* _SPI_FLASH_H_ */
|
