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