1 /*
2 * SPDX-FileCopyrightText: 2015-2022 Espressif Systems (Shanghai) CO LTD
3 *
4 * SPDX-License-Identifier: Apache-2.0
5 */
6
7 /*******************************************************************************
8 * NOTICE
9 * The ll is not public api, don't use in application code.
10 * See readme.md in hal/include/hal/readme.md
11 ******************************************************************************/
12
13 // The Lowlevel layer for SPI Flash
14
15 #pragma once
16
17 #include <stdlib.h>
18 #include "soc/spi_periph.h"
19 #include "soc/spi_struct.h"
20 #include "hal/spi_types.h"
21 #include "hal/spi_flash_types.h"
22 #include <sys/param.h> // For MIN/MAX
23 #include <stdbool.h>
24 #include <string.h>
25 #include "hal/misc.h"
26
27 #ifdef __cplusplus
28 extern "C" {
29 #endif
30
31 #define SPI_FLASH_LL_CLOCK_FREQUENCY_MHZ (80)
32
33 /// Get the start address of SPI peripheral registers by the host ID
34 #define spi_flash_ll_get_hw(host_id) ( ((host_id)==SPI1_HOST) ? &SPI1 :(\
35 ((host_id)==SPI2_HOST) ? &SPI2 :(\
36 ((host_id)==SPI3_HOST) ? &SPI3 :(\
37 {abort();(spi_dev_t*)0;}\
38 ))) )
39 #define spi_flash_ll_hw_get_id(dev) ( ((dev) == &SPI1) ? SPI1_HOST :(\
40 ((dev) == &SPI2) ? SPI2_HOST :(\
41 ((dev) == &SPI3) ? SPI3_HOST :(\
42 -1\
43 ))) )
44
45 /// Empty function to be compatible with new version chips.
46 #define spi_flash_ll_set_dummy_out(dev, out_en, out_lev)
47
48 // On ESP32, we extent 4 bits to occupy `Continuous Read Mode` bits. (same to origin code.)
49 #define SPI_FLASH_LL_CONTINUOUS_MODE_BIT_NUMS (4)
50
51 /// type to store pre-calculated register value in above layers
52 typedef typeof(SPI1.clock.val) spi_flash_ll_clock_reg_t;
53
54 /*------------------------------------------------------------------------------
55 * Control
56 *----------------------------------------------------------------------------*/
57 /**
58 * Reset peripheral registers before configuration and starting control
59 *
60 * @param dev Beginning address of the peripheral registers.
61 */
spi_flash_ll_reset(spi_dev_t * dev)62 static inline void spi_flash_ll_reset(spi_dev_t *dev)
63 {
64 dev->user.val = 0;
65 dev->ctrl.val = 0;
66 }
67
68 /**
69 * Check whether the previous operation is done.
70 *
71 * @param dev Beginning address of the peripheral registers.
72 *
73 * @return true if last command is done, otherwise false.
74 */
spi_flash_ll_cmd_is_done(const spi_dev_t * dev)75 static inline bool spi_flash_ll_cmd_is_done(const spi_dev_t *dev)
76 {
77 return (dev->cmd.val == 0);
78 }
79
80 /**
81 * Erase the flash chip.
82 *
83 * @param dev Beginning address of the peripheral registers.
84 */
spi_flash_ll_erase_chip(spi_dev_t * dev)85 static inline void spi_flash_ll_erase_chip(spi_dev_t *dev)
86 {
87 dev->cmd.flash_ce = 1;
88 }
89
90 /**
91 * Erase the sector, the address should be set by spi_flash_ll_set_address.
92 *
93 * @param dev Beginning address of the peripheral registers.
94 */
spi_flash_ll_erase_sector(spi_dev_t * dev)95 static inline void spi_flash_ll_erase_sector(spi_dev_t *dev)
96 {
97 dev->ctrl.val = 0;
98 dev->cmd.flash_se = 1;
99 }
100
101 /**
102 * Erase the block, the address should be set by spi_flash_ll_set_address.
103 *
104 * @param dev Beginning address of the peripheral registers.
105 */
spi_flash_ll_erase_block(spi_dev_t * dev)106 static inline void spi_flash_ll_erase_block(spi_dev_t *dev)
107 {
108 dev->cmd.flash_be = 1;
109 }
110
111 /**
112 * Enable/disable write protection for the flash chip.
113 *
114 * @param dev Beginning address of the peripheral registers.
115 * @param wp true to enable the protection, false to disable (write enable).
116 */
spi_flash_ll_set_write_protect(spi_dev_t * dev,bool wp)117 static inline void spi_flash_ll_set_write_protect(spi_dev_t *dev, bool wp)
118 {
119 if (wp) {
120 dev->cmd.flash_wrdi = 1;
121 } else {
122 dev->cmd.flash_wren = 1;
123 }
124 }
125
126 /**
127 * Get the read data from the buffer after ``spi_flash_ll_read`` is done.
128 *
129 * @param dev Beginning address of the peripheral registers.
130 * @param buffer Buffer to hold the output data
131 * @param read_len Length to get out of the buffer
132 */
spi_flash_ll_get_buffer_data(spi_dev_t * dev,void * buffer,uint32_t read_len)133 static inline void spi_flash_ll_get_buffer_data(spi_dev_t *dev, void *buffer, uint32_t read_len)
134 {
135 if (((intptr_t)buffer % 4 == 0) && (read_len % 4 == 0)) {
136 // If everything is word-aligned, do a faster memcpy
137 memcpy(buffer, (void *)dev->data_buf, read_len);
138 } else {
139 // Otherwise, slow(er) path copies word by word
140 int copy_len = read_len;
141 for (size_t i = 0; i < (read_len + 3) / 4; i++) {
142 int word_len = MIN(sizeof(uint32_t), copy_len);
143 uint32_t word = dev->data_buf[i];
144 memcpy(buffer, &word, word_len);
145 buffer = (void *)((intptr_t)buffer + word_len);
146 copy_len -= word_len;
147 }
148 }
149 }
150
151 /**
152 * Write a word to the data buffer.
153 *
154 * @param dev Beginning address of the peripheral registers.
155 * @param word Data to write at address 0.
156 */
spi_flash_ll_write_word(spi_dev_t * dev,uint32_t word)157 static inline void spi_flash_ll_write_word(spi_dev_t *dev, uint32_t word)
158 {
159 dev->data_buf[0] = word;
160 }
161
162 /**
163 * Set the data to be written in the data buffer.
164 *
165 * @param dev Beginning address of the peripheral registers.
166 * @param buffer Buffer holding the data
167 * @param length Length of data in bytes.
168 */
spi_flash_ll_set_buffer_data(spi_dev_t * dev,const void * buffer,uint32_t length)169 static inline void spi_flash_ll_set_buffer_data(spi_dev_t *dev, const void *buffer, uint32_t length)
170 {
171 // Load data registers, word at a time
172 int num_words = (length + 3) >> 2;
173 for (int i = 0; i < num_words; i++) {
174 uint32_t word = 0;
175 uint32_t word_len = MIN(length, sizeof(word));
176 memcpy(&word, buffer, word_len);
177 dev->data_buf[i] = word;
178 length -= word_len;
179 buffer = (void *)((intptr_t)buffer + word_len);
180 }
181 }
182
183 /**
184 * Program a page of the flash chip. Call ``spi_flash_ll_set_address`` before
185 * this to set the address to program.
186 *
187 * @param dev Beginning address of the peripheral registers.
188 * @param buffer Buffer holding the data to program
189 * @param length Length to program.
190 */
spi_flash_ll_program_page(spi_dev_t * dev,const void * buffer,uint32_t length)191 static inline void spi_flash_ll_program_page(spi_dev_t *dev, const void *buffer, uint32_t length)
192 {
193 dev->user.usr_dummy = 0;
194 spi_flash_ll_set_buffer_data(dev, buffer, length);
195 dev->cmd.flash_pp = 1;
196 }
197
198 /**
199 * Trigger a user defined transaction. All phases, including command, address, dummy, and the data phases,
200 * should be configured before this is called.
201 *
202 * @param dev Beginning address of the peripheral registers.
203 */
spi_flash_ll_user_start(spi_dev_t * dev)204 static inline void spi_flash_ll_user_start(spi_dev_t *dev)
205 {
206 dev->cmd.usr = 1;
207 }
208
209 /**
210 * Check whether the host is idle to perform new commands.
211 *
212 * @param dev Beginning address of the peripheral registers.
213 *
214 * @return true if the host is idle, otherwise false
215 */
spi_flash_ll_host_idle(const spi_dev_t * dev)216 static inline bool spi_flash_ll_host_idle(const spi_dev_t *dev)
217 {
218 return dev->ext2.st == 0;
219 }
220
221 /*------------------------------------------------------------------------------
222 * Configs
223 *----------------------------------------------------------------------------*/
224 /**
225 * Select which pin to use for the flash
226 *
227 * @param dev Beginning address of the peripheral registers.
228 * @param pin Pin ID to use, 0-2. Set to other values to disable all the CS pins.
229 */
spi_flash_ll_set_cs_pin(spi_dev_t * dev,int pin)230 static inline void spi_flash_ll_set_cs_pin(spi_dev_t *dev, int pin)
231 {
232 dev->pin.cs0_dis = (pin != 0);
233 dev->pin.cs1_dis = (pin != 1);
234 dev->pin.cs2_dis = (pin != 2);
235 }
236
237 /**
238 * Set the read io mode.
239 *
240 * @param dev Beginning address of the peripheral registers.
241 * @param read_mode I/O mode to use in the following transactions.
242 */
spi_flash_ll_set_read_mode(spi_dev_t * dev,esp_flash_io_mode_t read_mode)243 static inline void spi_flash_ll_set_read_mode(spi_dev_t *dev, esp_flash_io_mode_t read_mode)
244 {
245 typeof (dev->ctrl) ctrl = dev->ctrl;
246 ctrl.val &= ~(SPI_FREAD_QIO_M | SPI_FREAD_QUAD_M | SPI_FREAD_DIO_M | SPI_FREAD_DUAL_M);
247 ctrl.val |= SPI_FASTRD_MODE_M;
248 switch (read_mode) {
249 case SPI_FLASH_FASTRD:
250 //the default option
251 break;
252 case SPI_FLASH_QIO:
253 ctrl.fread_qio = 1;
254 break;
255 case SPI_FLASH_QOUT:
256 ctrl.fread_quad = 1;
257 break;
258 case SPI_FLASH_DIO:
259 ctrl.fread_dio = 1;
260 break;
261 case SPI_FLASH_DOUT:
262 ctrl.fread_dual = 1;
263 break;
264 case SPI_FLASH_SLOWRD:
265 ctrl.fastrd_mode = 0;
266 break;
267 default:
268 abort();
269 }
270 dev->ctrl = ctrl;
271 }
272
273 /**
274 * Set clock frequency to work at.
275 *
276 * @param dev Beginning address of the peripheral registers.
277 * @param clock_val pointer to the clock value to set
278 */
spi_flash_ll_set_clock(spi_dev_t * dev,spi_flash_ll_clock_reg_t * clock_val)279 static inline void spi_flash_ll_set_clock(spi_dev_t *dev, spi_flash_ll_clock_reg_t *clock_val)
280 {
281 dev->clock.val = *clock_val;
282 }
283
284 /**
285 * Set the input length, in bits.
286 *
287 * @param dev Beginning address of the peripheral registers.
288 * @param bitlen Length of input, in bits.
289 */
spi_flash_ll_set_miso_bitlen(spi_dev_t * dev,uint32_t bitlen)290 static inline void spi_flash_ll_set_miso_bitlen(spi_dev_t *dev, uint32_t bitlen)
291 {
292 dev->user.usr_miso = bitlen > 0;
293 dev->miso_dlen.usr_miso_dbitlen = bitlen ? (bitlen - 1) : 0;
294 }
295
296 /**
297 * Set the output length, in bits (not including command, address and dummy
298 * phases)
299 *
300 * @param dev Beginning address of the peripheral registers.
301 * @param bitlen Length of output, in bits.
302 */
spi_flash_ll_set_mosi_bitlen(spi_dev_t * dev,uint32_t bitlen)303 static inline void spi_flash_ll_set_mosi_bitlen(spi_dev_t *dev, uint32_t bitlen)
304 {
305 dev->user.usr_mosi = bitlen > 0;
306 dev->mosi_dlen.usr_mosi_dbitlen = bitlen ? (bitlen - 1) : 0;
307 }
308
309 /**
310 * Set the command.
311 *
312 * @param dev Beginning address of the peripheral registers.
313 * @param command Command to send
314 * @param bitlen Length of the command
315 */
spi_flash_ll_set_command(spi_dev_t * dev,uint8_t command,uint32_t bitlen)316 static inline void spi_flash_ll_set_command(spi_dev_t *dev, uint8_t command, uint32_t bitlen)
317 {
318 dev->user.usr_command = 1;
319 typeof(dev->user2) user2 = {
320 .usr_command_value = command,
321 .usr_command_bitlen = (bitlen - 1),
322 };
323 dev->user2 = user2;
324 }
325
326 /**
327 * Get the address length that is set in register, in bits.
328 *
329 * @param dev Beginning address of the peripheral registers.
330 *
331 */
spi_flash_ll_get_addr_bitlen(spi_dev_t * dev)332 static inline int spi_flash_ll_get_addr_bitlen(spi_dev_t *dev)
333 {
334 return dev->user.usr_addr ? dev->user1.usr_addr_bitlen + 1 : 0;
335 }
336
337 /**
338 * Set the address length to send, in bits. Should be called before commands that requires the address e.g. erase sector, read, write...
339 *
340 * @param dev Beginning address of the peripheral registers.
341 * @param bitlen Length of the address, in bits
342 */
spi_flash_ll_set_addr_bitlen(spi_dev_t * dev,uint32_t bitlen)343 static inline void spi_flash_ll_set_addr_bitlen(spi_dev_t *dev, uint32_t bitlen)
344 {
345 dev->user1.usr_addr_bitlen = (bitlen - 1);
346 dev->user.usr_addr = bitlen ? 1 : 0;
347 }
348
349 /**
350 * Set the address to send in user command mode. Should be called before commands that requires the address e.g. erase sector, read, write...
351 *
352 * @param dev Beginning address of the peripheral registers.
353 * @param addr Address to send
354 */
spi_flash_ll_set_usr_address(spi_dev_t * dev,uint32_t addr,int bit_len)355 static inline void spi_flash_ll_set_usr_address(spi_dev_t *dev, uint32_t addr, int bit_len)
356 {
357 // The blank region should be all ones
358 if (bit_len >= 32) {
359 dev->addr = addr;
360 dev->slv_wr_status = UINT32_MAX;
361 } else {
362 uint32_t padding_ones = UINT32_MAX >> bit_len;
363 dev->addr = (addr << (32 - bit_len)) | padding_ones;
364 }
365 }
366
367 /**
368 * Set the address to send. Should be called before commands that requires the address e.g. erase sector, read, write...
369 *
370 * @param dev Beginning address of the peripheral registers.
371 * @param addr Address to send
372 */
spi_flash_ll_set_address(spi_dev_t * dev,uint32_t addr)373 static inline void spi_flash_ll_set_address(spi_dev_t *dev, uint32_t addr)
374 {
375 dev->addr = addr;
376 }
377
378 /**
379 * Set the length of dummy cycles.
380 *
381 * @param dev Beginning address of the peripheral registers.
382 * @param dummy_n Cycles of dummy phases
383 */
spi_flash_ll_set_dummy(spi_dev_t * dev,uint32_t dummy_n)384 static inline void spi_flash_ll_set_dummy(spi_dev_t *dev, uint32_t dummy_n)
385 {
386 dev->user.usr_dummy = dummy_n ? 1 : 0;
387 HAL_FORCE_MODIFY_U32_REG_FIELD(dev->user1, usr_dummy_cyclelen, dummy_n - 1);
388 }
389
spi_flash_ll_set_hold(spi_dev_t * dev,uint32_t hold_n)390 static inline void spi_flash_ll_set_hold(spi_dev_t *dev, uint32_t hold_n)
391 {
392 dev->ctrl2.hold_time = hold_n;
393 dev->user.cs_hold = (hold_n > 0? 1: 0);
394 }
395
spi_flash_ll_set_cs_setup(spi_dev_t * dev,uint32_t cs_setup_time)396 static inline void spi_flash_ll_set_cs_setup(spi_dev_t *dev, uint32_t cs_setup_time)
397 {
398 dev->user.cs_setup = (cs_setup_time > 0 ? 1 : 0);
399 dev->ctrl2.setup_time = cs_setup_time - 1;
400 }
401
402 /**
403 * Get the spi flash source clock frequency. Used for calculating
404 * the divider parameters.
405 *
406 * @param host_id SPI host id. Not used in this function, but to keep
407 * compatibility with other targets.
408 *
409 * @return the frequency of spi flash clock source.(MHz)
410 */
spi_flash_ll_get_source_clock_freq_mhz(uint8_t host_id)411 static inline uint32_t spi_flash_ll_get_source_clock_freq_mhz(uint8_t host_id)
412 {
413 return SPI_FLASH_LL_CLOCK_FREQUENCY_MHZ;
414 }
415
416 /**
417 * Calculate spi_flash clock frequency division parameters for register.
418 *
419 * @param host_id SPI host id. Not used in this function, but to keep
420 * compatibility with other targets.
421 * @param clkdiv frequency division factor
422 *
423 * @return Register setting for the given clock division factor.
424 */
spi_flash_ll_calculate_clock_reg(uint8_t host_id,uint8_t clkdiv)425 static inline uint32_t spi_flash_ll_calculate_clock_reg(uint8_t host_id, uint8_t clkdiv)
426 {
427 uint32_t div_parameter;
428 // See comments of `clock` in `spi_struct.h`
429 if (clkdiv == 1) {
430 div_parameter = (1 << 31);
431 } else {
432 div_parameter = ((clkdiv - 1) | (((clkdiv/2 - 1) & 0xff) << 6 ) | (((clkdiv - 1) & 0xff) << 12));
433 }
434 return div_parameter;
435 }
436
437 /**
438 * Set extra address for bits M0-M7 in DIO/QIO mode.
439 *
440 * @param dev Beginning address of the peripheral registers.
441 * @param extra_addr extra address(M0-M7) to send.
442 */
spi_flash_ll_set_extra_address(spi_dev_t * dev,uint32_t extra_addr)443 static inline void spi_flash_ll_set_extra_address(spi_dev_t *dev, uint32_t extra_addr)
444 {
445 // Not supported on ESP32.
446 }
447
448 #ifdef __cplusplus
449 }
450 #endif
451