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