flash.h

  1// Copyright 2024 Nick Brassel (@tzarc)
  2// SPDX-License-Identifier: GPL-2.0-or-later
  3#pragma once
  4
  5#ifdef __cplusplus
  6extern "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 */
 16enum {
 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 */
 27typedef 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 */
 35void 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 */
 44flash_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 */
 53flash_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 */
 62flash_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 */
 72flash_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 */
 84flash_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 */
 96flash_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 */
109flash_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 */
122flash_status_t flash_write_range(uint32_t addr, const void *buf, size_t len);
123
124#ifdef __cplusplus
125}
126#endif