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 gpspi_flash_ll_get_hw(host_id)  (((host_id)==SPI2_HOST ? &GPSPI2 \
32                                                 : ((host_id)==SPI3_HOST ? &GPSPI3 \
33                                                 : ({abort();(spi_dev_t*)0;}))))
34 
35 #define gpspi_flash_ll_hw_get_id(dev)   ( ((dev) == (void*)&GPSPI2) ? SPI2_HOST : (\
36                                           ((dev) == (void*)&GPSPI3) ? SPI3_HOST : (\
37                                           -1 \
38                                         )) )
39 
40 typedef typeof(GPSPI2.clock.val) gpspi_flash_ll_clock_reg_t;
41 #define GPSPI_FLASH_LL_PERIPHERAL_FREQUENCY_MHZ 80
42 
43 /*------------------------------------------------------------------------------
44  * Control
45  *----------------------------------------------------------------------------*/
46 /**
47  * Reset peripheral registers before configuration and starting control.
48  *
49  * @param dev Beginning address of the peripheral registers.
50  */
gpspi_flash_ll_reset(spi_dev_t * dev)51 static inline void gpspi_flash_ll_reset(spi_dev_t *dev)
52 {
53     dev->user.val = 0;
54     dev->ctrl.val = 0;
55 
56     dev->clk_gate.clk_en = 1;
57     dev->clk_gate.mst_clk_active = 1;
58     dev->clk_gate.mst_clk_sel = 1;
59 
60     dev->dma_conf.val = 0;
61     dev->dma_conf.tx_seg_trans_clr_en = 1;
62     dev->dma_conf.rx_seg_trans_clr_en = 1;
63     dev->dma_conf.dma_seg_trans_en = 0;
64 }
65 
66 /**
67  * Check whether the previous operation is done.
68  *
69  * @param dev Beginning address of the peripheral registers.
70  *
71  * @return true if last command is done, otherwise false.
72  */
gpspi_flash_ll_cmd_is_done(const spi_dev_t * dev)73 static inline bool gpspi_flash_ll_cmd_is_done(const spi_dev_t *dev)
74 {
75     return (dev->cmd.usr == 0);
76 }
77 
78 /**
79  * Get the read data from the buffer after ``gpspi_flash_ll_read`` is done.
80  *
81  * @param dev Beginning address of the peripheral registers.
82  * @param buffer Buffer to hold the output data
83  * @param read_len Length to get out of the buffer
84  */
gpspi_flash_ll_get_buffer_data(spi_dev_t * dev,void * buffer,uint32_t read_len)85 static inline void gpspi_flash_ll_get_buffer_data(spi_dev_t *dev, void *buffer, uint32_t read_len)
86 {
87     if (((intptr_t)buffer % 4 == 0) && (read_len % 4 == 0)) {
88         // If everything is word-aligned, do a faster memcpy
89         memcpy(buffer, (void *)dev->data_buf, read_len);
90     } else {
91         // Otherwise, slow(er) path copies word by word
92         int copy_len = read_len;
93         for (uint32_t i = 0; i < (read_len + 3) / 4; i++) {
94             int word_len = MIN(sizeof(uint32_t), copy_len);
95             uint32_t word = dev->data_buf[i];
96             memcpy(buffer, &word, word_len);
97             buffer = (void *)((intptr_t)buffer + word_len);
98             copy_len -= word_len;
99         }
100     }
101 }
102 
103 /**
104  * Write a word to the data buffer.
105  *
106  * @param dev Beginning address of the peripheral registers.
107  * @param word Data to write at address 0.
108  */
gpspi_flash_ll_write_word(spi_dev_t * dev,uint32_t word)109 static inline void gpspi_flash_ll_write_word(spi_dev_t *dev, uint32_t word)
110 {
111     dev->data_buf[0] = word;
112 }
113 
114 /**
115  * Set the data to be written in the data buffer.
116  *
117  * @param dev Beginning address of the peripheral registers.
118  * @param buffer Buffer holding the data
119  * @param length Length of data in bytes.
120  */
gpspi_flash_ll_set_buffer_data(spi_dev_t * dev,const void * buffer,uint32_t length)121 static inline void gpspi_flash_ll_set_buffer_data(spi_dev_t *dev, const void *buffer, uint32_t length)
122 {
123     // Load data registers, word at a time
124     int num_words = (length + 3) / 4;
125     for (int i = 0; i < num_words; i++) {
126         uint32_t word = 0;
127         uint32_t word_len = MIN(length, sizeof(word));
128         memcpy(&word, buffer, word_len);
129         dev->data_buf[i] = word;
130         length -= word_len;
131         buffer = (void *)((intptr_t)buffer + word_len);
132     }
133 }
134 
135 /**
136  * Trigger a user defined transaction. All phases, including command, address, dummy, and the data phases,
137  * should be configured before this is called.
138  *
139  * @param dev Beginning address of the peripheral registers.
140  */
gpspi_flash_ll_user_start(spi_dev_t * dev)141 static inline void gpspi_flash_ll_user_start(spi_dev_t *dev)
142 {
143     dev->cmd.update = 1;
144     while (dev->cmd.update);
145     dev->cmd.usr = 1;
146 }
147 
148 /**
149  * Set HD pin high when flash work at spi mode.
150  *
151  * @param dev Beginning address of the peripheral registers.
152  */
gpspi_flash_ll_set_hold_pol(spi_dev_t * dev,uint32_t pol_val)153 static inline void gpspi_flash_ll_set_hold_pol(spi_dev_t *dev, uint32_t pol_val)
154 {
155     dev->ctrl.hold_pol = pol_val;
156 }
157 
158 /**
159  * Check whether the host is idle to perform new commands.
160  *
161  * @param dev Beginning address of the peripheral registers.
162  *
163  * @return true if the host is idle, otherwise false
164  */
gpspi_flash_ll_host_idle(const spi_dev_t * dev)165 static inline bool gpspi_flash_ll_host_idle(const spi_dev_t *dev)
166 {
167     return dev->cmd.usr == 0;
168 }
169 
170 /**
171  * Set phases for user-defined transaction to read
172  *
173  * @param dev Beginning address of the peripheral registers.
174  */
gpspi_flash_ll_read_phase(spi_dev_t * dev)175 static inline void gpspi_flash_ll_read_phase(spi_dev_t *dev)
176 {
177     typeof (dev->user) user = {
178         .usr_command = 1,
179         .usr_mosi = 0,
180         .usr_miso = 1,
181         .usr_addr = 1,
182     };
183     dev->user = user;
184 }
185 /*------------------------------------------------------------------------------
186  * Configs
187  *----------------------------------------------------------------------------*/
188 /**
189  * Select which pin to use for the flash
190  *
191  * @param dev Beginning address of the peripheral registers.
192  * @param pin Pin ID to use, 0-2. Set to other values to disable all the CS pins.
193  */
gpspi_flash_ll_set_cs_pin(spi_dev_t * dev,int pin)194 static inline void gpspi_flash_ll_set_cs_pin(spi_dev_t *dev, int pin)
195 {
196     dev->misc.cs0_dis = (pin == 0) ? 0 : 1;
197     dev->misc.cs1_dis = (pin == 1) ? 0 : 1;
198 }
199 
200 /**
201  * Set the read io mode.
202  *
203  * @param dev Beginning address of the peripheral registers.
204  * @param read_mode I/O mode to use in the following transactions.
205  */
gpspi_flash_ll_set_read_mode(spi_dev_t * dev,esp_flash_io_mode_t read_mode)206 static inline void gpspi_flash_ll_set_read_mode(spi_dev_t *dev, esp_flash_io_mode_t read_mode)
207 {
208     typeof (dev->ctrl) ctrl = dev->ctrl;
209     typeof (dev->user) user = dev->user;
210 
211     ctrl.val &= ~(SPI_FCMD_QUAD_M | SPI_FADDR_QUAD_M | SPI_FREAD_QUAD_M | SPI_FCMD_DUAL_M | SPI_FADDR_DUAL_M | SPI_FREAD_DUAL_M);
212     user.val &= ~(SPI_FWRITE_QUAD_M | SPI_FWRITE_DUAL_M);
213 
214     switch (read_mode) {
215     case SPI_FLASH_FASTRD:
216         //the default option
217     case SPI_FLASH_SLOWRD:
218         break;
219     case SPI_FLASH_QIO:
220         ctrl.fread_quad = 1;
221         ctrl.faddr_quad = 1;
222         user.fwrite_quad = 1;
223         break;
224     case SPI_FLASH_QOUT:
225         ctrl.fread_quad = 1;
226         user.fwrite_quad = 1;
227         break;
228     case SPI_FLASH_DIO:
229         ctrl.fread_dual = 1;
230         ctrl.faddr_dual = 1;
231         user.fwrite_dual = 1;
232         break;
233     case SPI_FLASH_DOUT:
234         ctrl.fread_dual = 1;
235         user.fwrite_dual = 1;
236         break;
237     default:
238         abort();
239     }
240 
241     dev->ctrl = ctrl;
242     dev->user = user;
243 }
244 
245 /**
246  * Set clock frequency to work at.
247  *
248  * @param dev Beginning address of the peripheral registers.
249  * @param clock_val pointer to the clock value to set
250  */
gpspi_flash_ll_set_clock(spi_dev_t * dev,gpspi_flash_ll_clock_reg_t * clock_val)251 static inline void gpspi_flash_ll_set_clock(spi_dev_t *dev, gpspi_flash_ll_clock_reg_t *clock_val)
252 {
253     dev->clock.val = *clock_val;
254 }
255 
256 /**
257  * Set the input length, in bits.
258  *
259  * @param dev Beginning address of the peripheral registers.
260  * @param bitlen Length of input, in bits.
261  */
gpspi_flash_ll_set_miso_bitlen(spi_dev_t * dev,uint32_t bitlen)262 static inline void gpspi_flash_ll_set_miso_bitlen(spi_dev_t *dev, uint32_t bitlen)
263 {
264     dev->user.usr_miso = bitlen > 0;
265     if (bitlen) {
266         dev->ms_dlen.ms_data_bitlen = bitlen - 1;
267     }
268 }
269 
270 /**
271  * Set the output length, in bits (not including command, address and dummy
272  * phases)
273  *
274  * @param dev Beginning address of the peripheral registers.
275  * @param bitlen Length of output, in bits.
276  */
gpspi_flash_ll_set_mosi_bitlen(spi_dev_t * dev,uint32_t bitlen)277 static inline void gpspi_flash_ll_set_mosi_bitlen(spi_dev_t *dev, uint32_t bitlen)
278 {
279     dev->user.usr_mosi = bitlen > 0;
280     if (bitlen) {
281         dev->ms_dlen.ms_data_bitlen = bitlen - 1;
282     }
283 }
284 
285 /**
286  * Set the command.
287  *
288  * @param dev Beginning address of the peripheral registers.
289  * @param command Command to send
290  * @param bitlen Length of the command
291  */
gpspi_flash_ll_set_command(spi_dev_t * dev,uint8_t command,uint32_t bitlen)292 static inline void gpspi_flash_ll_set_command(spi_dev_t *dev, uint8_t command, uint32_t bitlen)
293 {
294     dev->user.usr_command = 1;
295     typeof(dev->user2) user2 = {
296         .usr_command_value = command,
297         .usr_command_bitlen = (bitlen - 1),
298     };
299     dev->user2 = user2;
300 }
301 
302 /**
303  * Get the address length that is set in register, in bits.
304  *
305  * @param dev Beginning address of the peripheral registers.
306  *
307  */
gpspi_flash_ll_get_addr_bitlen(spi_dev_t * dev)308 static inline int gpspi_flash_ll_get_addr_bitlen(spi_dev_t *dev)
309 {
310     return dev->user.usr_addr ? dev->user1.usr_addr_bitlen + 1 : 0;
311 }
312 
313 /**
314  * Set the address length to send, in bits. Should be called before commands that requires the address e.g. erase sector, read, write...
315  *
316  * @param dev Beginning address of the peripheral registers.
317  * @param bitlen Length of the address, in bits
318  */
gpspi_flash_ll_set_addr_bitlen(spi_dev_t * dev,uint32_t bitlen)319 static inline void gpspi_flash_ll_set_addr_bitlen(spi_dev_t *dev, uint32_t bitlen)
320 {
321     dev->user1.usr_addr_bitlen = (bitlen - 1);
322     dev->user.usr_addr = bitlen ? 1 : 0;
323 }
324 
325 /**
326  * Set the address to send in user mode. Should be called before commands that requires the address e.g. erase sector, read, write...
327  *
328  * @param dev Beginning address of the peripheral registers.
329  * @param addr Address to send
330  */
gpspi_flash_ll_set_usr_address(spi_dev_t * dev,uint32_t addr,uint32_t bitlen)331 static inline void gpspi_flash_ll_set_usr_address(spi_dev_t *dev, uint32_t addr, uint32_t bitlen)
332 {
333     // The blank region should be all ones
334     uint32_t padding_ones = (bitlen == 32? 0 : UINT32_MAX >> bitlen);
335     dev->addr = (addr << (32 - bitlen)) | padding_ones;
336 }
337 
338 
339 /**
340  * Set the address to send. Should be called before commands that requires the address e.g. erase sector, read, write...
341  *
342  * @param dev Beginning address of the peripheral registers.
343  * @param addr Address to send
344  */
gpspi_flash_ll_set_address(spi_dev_t * dev,uint32_t addr)345 static inline void gpspi_flash_ll_set_address(spi_dev_t *dev, uint32_t addr)
346 {
347     dev->addr = addr;
348 }
349 
350 /**
351  * Set the length of dummy cycles.
352  *
353  * @param dev Beginning address of the peripheral registers.
354  * @param dummy_n Cycles of dummy phases
355  */
gpspi_flash_ll_set_dummy(spi_dev_t * dev,uint32_t dummy_n)356 static inline void gpspi_flash_ll_set_dummy(spi_dev_t *dev, uint32_t dummy_n)
357 {
358     dev->user.usr_dummy = dummy_n ? 1 : 0;
359     HAL_FORCE_MODIFY_U32_REG_FIELD(dev->user1, usr_dummy_cyclelen, dummy_n - 1)
360 }
361 
362 /**
363  * Set D/Q output level during dummy phase
364  *
365  * @param dev Beginning address of the peripheral registers.
366  * @param out_en whether to enable IO output for dummy phase
367  * @param out_level dummy output level
368  */
gpspi_flash_ll_set_dummy_out(spi_dev_t * dev,uint32_t out_en,uint32_t out_lev)369 static inline void gpspi_flash_ll_set_dummy_out(spi_dev_t *dev, uint32_t out_en, uint32_t out_lev)
370 {
371     dev->ctrl.dummy_out = out_en;
372     dev->ctrl.q_pol = out_lev;
373     dev->ctrl.d_pol = out_lev;
374 }
375 
376 /**
377  * Set extra hold time of CS after the clocks.
378  *
379  * @param dev Beginning address of the peripheral registers.
380  * @param hold_n Cycles of clocks before CS is inactive
381  */
gpspi_flash_ll_set_hold(spi_dev_t * dev,uint32_t hold_n)382 static inline void gpspi_flash_ll_set_hold(spi_dev_t *dev, uint32_t hold_n)
383 {
384     dev->user1.cs_hold_time = hold_n - 1;
385     dev->user.cs_hold = (hold_n > 0? 1: 0);
386 }
387 
gpspi_flash_ll_set_cs_setup(spi_dev_t * dev,uint32_t cs_setup_time)388 static inline void gpspi_flash_ll_set_cs_setup(spi_dev_t *dev, uint32_t cs_setup_time)
389 {
390     dev->user.cs_setup = (cs_setup_time > 0 ? 1 : 0);
391     dev->user1.cs_setup_time = cs_setup_time - 1;
392 }
393 
394 /**
395  * Calculate spi_flash clock frequency division parameters for register.
396  *
397  * @param clkdiv frequency division factor
398  *
399  * @return Register setting for the given clock division factor.
400  */
gpspi_flash_ll_calculate_clock_reg(uint8_t clkdiv)401 static inline uint32_t gpspi_flash_ll_calculate_clock_reg(uint8_t clkdiv)
402 {
403     uint32_t div_parameter;
404     // See comments of `clock` in `spi_struct.h`
405     if (clkdiv == 1) {
406         div_parameter = (1 << 31);
407     } else {
408         div_parameter = ((clkdiv - 1) | (((clkdiv/2 - 1) & 0xff) << 6 ) | (((clkdiv - 1) & 0xff) << 12));
409     }
410     return div_parameter;
411 }
412 
413 #ifdef __cplusplus
414 }
415 #endif
416