qmk_firmware

QMK firmware for my keyboards (Corne, Sweep Ferris) and trackball (Ploopy Adept)
Log | Files | Refs | Submodules | LICENSE

flash.h (4350B)

      1 // Copyright 2024 Nick Brassel (@tzarc)
      2 // SPDX-License-Identifier: GPL-2.0-or-later
      3 #pragma once
      4 
      5 #ifdef __cplusplus
      6 extern "C" {
      7 #endif
      8 
      9 #include <stdint.h>
     10 #include <stdlib.h>
     11 #include <stdbool.h>
     12 
     13 /**
     14  * @brief The status of a flash operation.
     15  */
     16 enum {
     17     FLASH_STATUS_SUCCESS     = 0,  //< The operation completed successfully.
     18     FLASH_STATUS_ERROR       = -1, //< An error occurred during the operation.
     19     FLASH_STATUS_TIMEOUT     = -2, //< The operation timed out.
     20     FLASH_STATUS_BAD_ADDRESS = -3, //< The address is out of bounds.
     21     FLASH_STATUS_BUSY        = -4, //< The flash is busy.
     22 };
     23 
     24 /**
     25  * @brief The status of a flash operation.
     26  */
     27 typedef int16_t flash_status_t;
     28 
     29 /**
     30  * @brief Initializes the flash driver.
     31  *
     32  * This function initializes the flash driver and prepares it for use.
     33  * It should be called before any other flash-related functions are used.
     34  */
     35 void flash_init(void);
     36 
     37 /**
     38  * @brief Checks if the flash is busy.
     39  *
     40  * This function checks if the flash is currently busy with an operation.
     41  *
     42  * @return FLASH_STATUS_SUCCESS if the flash is not busy, FLASH_STATUS_BUSY if the flash is busy, or FLASH_STATUS_ERROR if an error occurred.
     43  */
     44 flash_status_t flash_is_busy(void);
     45 
     46 /**
     47  * @brief Initiates a chip erase operation.
     48  *
     49  * This function does not wait for the flash to become ready.
     50  *
     51  * @return FLASH_STATUS_SUCCESS if the erase command was successfully sent, FLASH_STATUS_TIMEOUT if the flash is busy, or FLASH_STATUS_ERROR if an error occurred.
     52  */
     53 flash_status_t flash_begin_erase_chip(void);
     54 
     55 /**
     56  * @brief Waits for the chip erase operation to complete.
     57  *
     58  * This function waits for the chip erase operation to complete.
     59  *
     60  * @return FLASH_STATUS_SUCCESS if the chip erase operation completed successfully, FLASH_STATUS_TIMEOUT if the flash was still busy, or FLASH_STATUS_ERROR if an error occurred.
     61  */
     62 flash_status_t flash_wait_erase_chip(void);
     63 
     64 /**
     65  * @brief Erases the entire flash memory chip.
     66  *
     67  * This function initiates an erase operation to erase the entire flash memory chip.
     68  * It waits for the operation to complete.
     69  *
     70  * @return FLASH_STATUS_SUCCESS if the erase was successfully executed, FLASH_STATUS_TIMEOUT if the flash is busy, or FLASH_STATUS_ERROR if an error occurred.
     71  */
     72 flash_status_t flash_erase_chip(void);
     73 
     74 /**
     75  * @brief Erases a block of flash memory.
     76  *
     77  * This function initiates an erase operation to erase a block of flash memory.
     78  * It waits for the operation to complete.
     79  *
     80  * @param addr The address of the block to erase.
     81  *
     82  * @return FLASH_STATUS_SUCCESS if the erase was successfully executed, FLASH_STATUS_TIMEOUT if the flash is busy, or FLASH_STATUS_ERROR if an error occurred.
     83  */
     84 flash_status_t flash_erase_block(uint32_t addr);
     85 
     86 /**
     87  * @brief Erases a sector of flash memory.
     88  *
     89  * This function initiates an erase operation to erase a sector of flash memory.
     90  * It waits for the operation to complete.
     91  *
     92  * @param addr The address of the sector to erase.
     93  *
     94  * @return FLASH_STATUS_SUCCESS if the erase was successfully executed, FLASH_STATUS_TIMEOUT if the flash is busy, or FLASH_STATUS_ERROR if an error occurred.
     95  */
     96 flash_status_t flash_erase_sector(uint32_t addr);
     97 
     98 /**
     99  * @brief Reads a range of flash memory.
    100  *
    101  * This function reads a range of flash memory into a buffer.
    102  *
    103  * @param addr The address of the range to read.
    104  * @param buf A pointer to the buffer to read the range into.
    105  * @param len The length of the range to read.
    106  *
    107  * @return FLASH_STATUS_SUCCESS if the range was successfully read, FLASH_STATUS_BAD_ADDRESS if the address is out of bounds, FLASH_STATUS_TIMEOUT if the flash is busy, or FLASH_STATUS_ERROR if an error occurred.
    108  */
    109 flash_status_t flash_read_range(uint32_t addr, void *buf, size_t len);
    110 
    111 /**
    112  * @brief Writes a range of flash memory.
    113  *
    114  * This function writes a range of flash memory from a buffer.
    115  *
    116  * @param addr The address of the range to write.
    117  * @param buf A pointer to the buffer to write to the range.
    118  * @param len The length of the range to write.
    119  *
    120  * @return FLASH_STATUS_SUCCESS if the range was successfully written, FLASH_STATUS_BAD_ADDRESS if the address is out of bounds, FLASH_STATUS_TIMEOUT if the flash is busy, or FLASH_STATUS_ERROR if an error occurred.
    121  */
    122 flash_status_t flash_write_range(uint32_t addr, const void *buf, size_t len);
    123 
    124 #ifdef __cplusplus
    125 }
    126 #endif