blob: d98047c89f07cedf38b69249235abb2487839b32 [file] [log] [blame]
Damien George784e0232017-01-24 16:56:03 +11001/*
2 * This file is part of the MicroPython project, http://micropython.org/
3 *
4 * The MIT License (MIT)
5 *
Damien George4e487002018-03-02 16:01:18 +11006 * Copyright (c) 2016-2018 Damien P. George
Damien George784e0232017-01-24 16:56:03 +11007 *
8 * Permission is hereby granted, free of charge, to any person obtaining a copy
9 * of this software and associated documentation files (the "Software"), to deal
10 * in the Software without restriction, including without limitation the rights
11 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
12 * copies of the Software, and to permit persons to whom the Software is
13 * furnished to do so, subject to the following conditions:
14 *
15 * The above copyright notice and this permission notice shall be included in
16 * all copies or substantial portions of the Software.
17 *
18 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
19 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
20 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
21 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
22 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
23 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
24 * THE SOFTWARE.
25 */
Damien George784e0232017-01-24 16:56:03 +110026#ifndef MICROPY_INCLUDED_DRIVERS_MEMORY_SPIFLASH_H
27#define MICROPY_INCLUDED_DRIVERS_MEMORY_SPIFLASH_H
28
Damien Georgea739b352018-03-09 17:32:28 +110029#include "drivers/bus/spi.h"
Damien George4e487002018-03-02 16:01:18 +110030#include "drivers/bus/qspi.h"
Damien George784e0232017-01-24 16:56:03 +110031
Damien Georgee7edf072025-04-09 21:30:17 +100032// Whether to enable dynamic configuration of SPI flash through mp_spiflash_chip_params_t.
33#ifndef MICROPY_HW_SPIFLASH_CHIP_PARAMS
34#define MICROPY_HW_SPIFLASH_CHIP_PARAMS (0)
35#endif
36
Damien Georgeb0785692025-04-02 12:47:48 +110037// Whether to enable detection of SPI flash during initialisation.
38#ifndef MICROPY_HW_SPIFLASH_DETECT_DEVICE
39#define MICROPY_HW_SPIFLASH_DETECT_DEVICE (0)
40#endif
41
Damien George86fe73b2018-06-07 14:09:10 +100042#define MP_SPIFLASH_ERASE_BLOCK_SIZE (4096) // must be a power of 2
43
Damien George4e487002018-03-02 16:01:18 +110044enum {
45 MP_SPIFLASH_BUS_SPI,
46 MP_SPIFLASH_BUS_QSPI,
47};
48
Damien George86fe73b2018-06-07 14:09:10 +100049struct _mp_spiflash_t;
50
Damien Georgee43a74a2020-12-17 16:59:54 +110051#if MICROPY_HW_SPIFLASH_ENABLE_CACHE
Damien George86fe73b2018-06-07 14:09:10 +100052// A cache must be provided by the user in the config struct. The same cache
53// struct can be shared by multiple SPI flash instances.
54typedef struct _mp_spiflash_cache_t {
55 uint8_t buf[MP_SPIFLASH_ERASE_BLOCK_SIZE] __attribute__((aligned(4)));
56 struct _mp_spiflash_t *user; // current user of buf, for shared use
57 uint32_t block; // current block stored in buf; 0xffffffff if invalid
58} mp_spiflash_cache_t;
Damien Georgee43a74a2020-12-17 16:59:54 +110059#endif
Damien George86fe73b2018-06-07 14:09:10 +100060
Damien George4e487002018-03-02 16:01:18 +110061typedef struct _mp_spiflash_config_t {
62 uint32_t bus_kind;
63 union {
64 struct {
65 mp_hal_pin_obj_t cs;
66 void *data;
Damien Georgea739b352018-03-09 17:32:28 +110067 const mp_spi_proto_t *proto;
Damien George4e487002018-03-02 16:01:18 +110068 } u_spi;
69 struct {
70 void *data;
71 const mp_qspi_proto_t *proto;
72 } u_qspi;
73 } bus;
Damien Georgee43a74a2020-12-17 16:59:54 +110074 #if MICROPY_HW_SPIFLASH_ENABLE_CACHE
Damien Georgeb78ca322018-06-07 15:39:46 +100075 mp_spiflash_cache_t *cache; // can be NULL if cache functions not used
Damien Georgee43a74a2020-12-17 16:59:54 +110076 #endif
Damien George4e487002018-03-02 16:01:18 +110077} mp_spiflash_config_t;
78
Damien Georgee7edf072025-04-09 21:30:17 +100079#if MICROPY_HW_SPIFLASH_CHIP_PARAMS
80typedef struct _mp_spiflash_chip_params_t {
81 uint32_t jedec_id;
82 uint8_t memory_size_bytes_log2;
83 uint8_t qspi_prescaler;
84 uint8_t qread_num_dummy;
85} mp_spiflash_chip_params_t;
86#endif
87
Damien George784e0232017-01-24 16:56:03 +110088typedef struct _mp_spiflash_t {
Damien George4e487002018-03-02 16:01:18 +110089 const mp_spiflash_config_t *config;
Damien Georgee7edf072025-04-09 21:30:17 +100090 #if MICROPY_HW_SPIFLASH_CHIP_PARAMS
91 const mp_spiflash_chip_params_t *chip_params;
92 #endif
Damien George4e487002018-03-02 16:01:18 +110093 volatile uint32_t flags;
Damien George784e0232017-01-24 16:56:03 +110094} mp_spiflash_t;
95
96void mp_spiflash_init(mp_spiflash_t *self);
Damien George8cde5fa2019-07-03 01:03:25 +100097void mp_spiflash_deepsleep(mp_spiflash_t *self, int value);
Damien Georgecc5a9402018-06-07 15:36:27 +100098
Damien Georgeb0785692025-04-02 12:47:48 +110099#if MICROPY_HW_SPIFLASH_DETECT_DEVICE
100// A board/port should define this function to perform actions based on the JEDEC id.
101int mp_spiflash_detect(mp_spiflash_t *spiflash, int ret, uint32_t devid);
102#endif
103
Damien Georgeb78ca322018-06-07 15:39:46 +1000104// These functions go direct to the SPI flash device
105int mp_spiflash_erase_block(mp_spiflash_t *self, uint32_t addr);
Andrew Leech7ee5afe2021-03-05 10:15:29 +1100106int mp_spiflash_read(mp_spiflash_t *self, uint32_t addr, size_t len, uint8_t *dest);
Damien Georgeb78ca322018-06-07 15:39:46 +1000107int mp_spiflash_write(mp_spiflash_t *self, uint32_t addr, size_t len, const uint8_t *src);
108
Damien Georgee43a74a2020-12-17 16:59:54 +1100109#if MICROPY_HW_SPIFLASH_ENABLE_CACHE
Damien Georgecc5a9402018-06-07 15:36:27 +1000110// These functions use the cache (which must already be configured)
Damien Georgec61e8592025-03-19 15:47:35 +1100111// Note: don't use these functions in combination with memory-mapped
112// flash, because MP_QSPI_IOCTL_MEMORY_MODIFIED is not called.
Andrew Leech7ee5afe2021-03-05 10:15:29 +1100113int mp_spiflash_cache_flush(mp_spiflash_t *self);
114int mp_spiflash_cached_read(mp_spiflash_t *self, uint32_t addr, size_t len, uint8_t *dest);
Damien Georgecc5a9402018-06-07 15:36:27 +1000115int mp_spiflash_cached_write(mp_spiflash_t *self, uint32_t addr, size_t len, const uint8_t *src);
Damien Georgee43a74a2020-12-17 16:59:54 +1100116#endif
Damien George784e0232017-01-24 16:56:03 +1100117
118#endif // MICROPY_INCLUDED_DRIVERS_MEMORY_SPIFLASH_H