rtems/cpukit/include/dev/flash/flashdev.h

/* SPDX-License-Identifier: BSD-2-Clause */

/**
 * @file
 *
 * @ingroup Flash
 *
 * @brief Generic Flash API
 */

/*
 * Copyright (C) 2023 Aaron Nyholm
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 */

#ifndef _DEV_FLASHDEV_H
#define _DEV_FLASHDEV_H

#include <rtems/thread.h>
#include <sys/types.h>

typedef struct rtems_flashdev rtems_flashdev;

/**
 * @defgroup Generic Flash API
 *
 * @ingroup RTEMSDeviceDrivers
 *
 * @brief Generic Flash API to wrap specific device drivers.
 *
 * @{
 */

/* IOCTL Calls */

/**
 * @brief Obtains the flash device.
 *
 * This command has no argument.
 */
#define RTEMS_FLASHDEV_IOCTL_OBTAIN 0
/**
 * @brief Releases the flash device.
 *
 * This command has no argument.
 */
#define RTEMS_FLASHDEV_IOCTL_RELEASE 1
/**
 * @brief Returns the JEDEC ID of the flash device. This IOCTL call
 * is informational only.
 *
 * @param[out] jedec_id Pointer to uint32_t in which the JEDEC ID is
 * returned in.
 */
#define RTEMS_FLASHDEV_IOCTL_JEDEC_ID 2
/**
 * @brief Erases flash device.
 *
 * @param[in] erase_args Pointer to rtems_flashdev_region struct
 * containing offset and size of erase to be performed.
 */
#define RTEMS_FLASHDEV_IOCTL_ERASE 3
/**
 * @brief Set a region that limits read, write and erase calls to within it.
 * Regions are file descriptor specific and limited to a single region per
 * file descriptor and 32 regions total per flash device. Regions can be
 * changed or updated by calling this IOCTL again.
 *
 * @param[in] region Pointer to rtems_flashdev_region struct containing
 * base and length of defined region.
 */
#define RTEMS_FLASHDEV_IOCTL_REGION_SET 4
/**
 * @brief Removes the set region on the file descriptor.
 *
 * This command has no argument.
 */
#define RTEMS_FLASHDEV_IOCTL_REGION_UNSET 5
/**
 * @brief Returns the type of flash device (e.g. NOR or NAND).
 *
 * @param[out] flash_type Pointer to integer which is set to the flash
 * type macro value.
 */
#define RTEMS_FLASHDEV_IOCTL_TYPE 6

/**
 * @brief Get the size and address of flash page at given offset
 *
 * The offset ignores the region limiting. To find page of region
 * limited offset add the base of the region to the desired offset.
 *
 * @param[in,out] rtems_flashdev_ioctl_page_info arg Pointer to struct
 * with offset and space for return values.
 */
#define RTEMS_FLASHDEV_IOCTL_PAGEINFO_BY_OFFSET 7

/**
 * @brief Get the size and address of nth flash page where n is index passed in.
 *
 * The index ignores the region limiting.
 *
 * @param[in,out] rtems_flashdev_ioctl_page_info arg Pointer to struct
 * with index and space for return values.
 */
#define RTEMS_FLASHDEV_IOCTL_PAGEINFO_BY_INDEX 8

/**
 * @brief Get the number of pages in flash device.
 *
 * @param[out] count Integer containing the number of pages.
 */
#define RTEMS_FLASHDEV_IOCTL_PAGE_COUNT 9

/**
 * @brief Get the minimum write size supported by the driver.
 *
 * @param[out] count Integer containing the minimum write size.
 */
#define RTEMS_FLASHDEV_IOCTL_WRITE_BLOCK_SIZE 10

/**
 * @brief The maximum number of region limited file descriptors
 * allowed to be open at once.
 */
#define RTEMS_FLASHDEV_MAX_REGIONS 32

/**
 * @brief Enum for flash type returned from IOCTL call.
 */
typedef enum rtems_flashdev_flash_type {
  /**
   * @brief The flash device is NOR flash.
   **/
  RTEMS_FLASHDEV_NOR,
  /**
   * @brief The flash device is NAND flash.
   */
  RTEMS_FLASHDEV_NAND
} rtems_flashdev_flash_type;

/**
 * @brief General definition for on flash device.
 */
typedef struct rtems_flashdev_region {
  /**
   * @brief Base of region.
   */
  off_t offset;
  /**
   * @brief Length of region.
   */
  size_t size;
} rtems_flashdev_region;

/**
 * @brief Struct holding region definitions
 */
typedef struct rtems_flashdev_region_table {
  /**
   * @brief The maximum regions that can be defined at once.
   */
  int max_regions;

  /**
   * @brief Pointer to array of rtems_flashdev_region of length
   * max_regions
   */
  rtems_flashdev_region* regions;

  /**
   * @brief Array of uint32_t acting as bit allocator
   * for regions array.
   */
  uint32_t *bit_allocator;
} rtems_flashdev_region_table;

/**
 * @brief Page information returned from IOCTL calls.
 */
typedef struct rtems_flashdev_ioctl_page_info {
  /**
   * @brief Offset or index to find page at.
   */
  off_t location;

  /**
   * @brief Information returned about the page. Including the
   * base offset and size of page.
   */
  rtems_flashdev_region page_info;
} rtems_flashdev_ioctl_page_info;

/**
 * @brief Flash device.
 */
struct rtems_flashdev {
  /**
   * @brief Call to the device driver to read the flash device.
   *
   * @param[in] flash Pointer to flash device.
   * @param[in] offset Address to read from.
   * @param[in] count Number of bytes to read.
   * @param[out] buffer Buffer for data to be read into.
   *
   * @retval 0 Successful operation.
   * @retval 1 Failed operation.
   */
  int ( *read )(
    rtems_flashdev *flash,
    uintptr_t offset,
    size_t count,
    void *buffer
  );

  /**
   * @brief Call to the device driver to write to the flash device.
   *
   * @param[in] flash Pointer to flash device.
   * @param[in] offset Address to write to.
   * @param[in] count Number of bytes to read.
   * @param[in] buffer Buffer for data to be written from.
   *
   * @retval 0 Successful operation.
   * @retval 1 Failed operation.
   */
  int ( *write )(
    rtems_flashdev *flash,
    uintptr_t offset,
    size_t count,
    const void *buffer
  );

  /**
   * @brief Call to the device driver to erase the flash device.
   *
   * @param[in] flash Pointer to flash device.
   * @param[in] offset Address to erase at.
   * @param[in] count Number of bytes to erase.
   *
   * @retval 0 Successful operation.
   * @retval 1 Failed operation.
   */
  int ( *erase )(
    rtems_flashdev *flash,
    uintptr_t offset,
    size_t count
  );

  /**
   * @brief Call to the device driver to return the JEDEC ID.
   *
   * @param[in] flash The flash device.
   *
   * @retval JEDEC ID.
   */
  uint32_t ( *jedec_id )(
    rtems_flashdev *flash
  );

  /**
   * @brief Call to the device driver to return the flash type.
   *
   * @param[in] flash The flash device.
   * @param[out] type The type of flash device.
   *
   * @retval 0 Success
   * @retbal Other Failure
   */
  int ( *flash_type )(
    rtems_flashdev *flash,
    rtems_flashdev_flash_type *type
  );

  /**
   * @brief Call to device driver to get size and offset of page at
   * given offset.
   *
   * @param[in] flash The flash device
   * @param[in] search_offset The offset of the page which info is to be
   * returned.
   * @param[out] page_offset The offset of the start of the page
   * @param[out] page_size The size of the page
   *
   * @retval 0 Success.
   * @retval non-zero Failed.
   */
  int ( *page_info_by_offset )(
    rtems_flashdev *flash,
    off_t search_offset,
    off_t *page_offset,
    size_t *page_size
  );

  /**
   * @brief Call to device driver to get size and offset of page at
   * given index.
   *
   * @param[in] flash The flash device
   * @param[in] search_index The index of the page which info is to be returned.
   * @param[out] page_offset The offset of the start of the page
   * @param[out] page_size The size of the page
   *
   * @retval 0 Success.
   * @retval non-zero Failed.
   */
  int ( *page_info_by_index )(
    rtems_flashdev *flashdev,
    off_t search_index,
    off_t *page_offset,
    size_t *page_size
  );

  /**
   * @brief Call to device driver to return the number of pages on the flash
   * device.
   *
   * @param[out] page_count The number of pages on the flash device.
   *
   * @retval 0 Success.
   * @retval non-zero Failed.
   */
  int ( *page_count )(
    rtems_flashdev *flashdev,
    int *page_count
  );

  /**
   * @brief Call to device driver to return the minimum write size of the
   * flash device.
   *
   * @param[out] write_block_size The minimum write size of the flash device.
   *
   * @retval 0 Success.
   * @retval non-zero Failed.
   */
  int ( *write_block_size )(
    rtems_flashdev *flashdev,
    size_t *write_block_size
  );

  /**
   * @brief Destroys the flash device.
   *
   * @param[in] flash Pointer to flash device.
   */
  void ( *destroy )(
    rtems_flashdev *flashdev
  );

  /**
   * @brief Pointer to device driver.
   */
  void *driver;

  /**
   * @brief Mutex to protect the flash device access.
   */
  rtems_recursive_mutex mutex;

  /**
   * @brief Region table defining size and memory for region allocations
   */
  rtems_flashdev_region_table *region_table;
};

/**
 * @brief Allocate and initialize the flash device.
 *
 * After a successful allocation and initialization of the flash device
 * it must be destroyed via rtems_flashdev_destroy_and_free().
 *
 * @param[in] size The number of bytes to allocate.
 *
 * @retval NULL Failed to set up flash device.
 * @retval non-NULL The new flash device.
 */
rtems_flashdev *rtems_flashdev_alloc_and_init(
  size_t size
);

/**
 * @brief Initialize the flash device.
 *
 * After a successful initialization of the flash device it must be
 * destroyed via rtems_flashdev_destory().
 *
 * After initialization and before registration read, write, erase, jedec_id
 * and flash_type functions need to be set in the flashdev.
 *
 * @param[in] flash The flash device to initialize.
 *
 * @retval 1 Failed to set up flash device.
 * @retval 0 Successful set up of flash device.
 */
int rtems_flashdev_init(
  rtems_flashdev *flash
);

/**
 * @brief Register the flash device.
 *
 * This function always claims ownership of the flash device.
 *
 * After initialization and before registration read, write, erase, jedec_id
 * and flash_type functions need to be set in the flashdev.
 *
 * @param[in] flash The flash device.
 * @param[in] flash_path The path to the flash device file.
 *
 * @retval 0 Successful operation.
 * @retval non-zero Failed operation.
 */
int rtems_flashdev_register(
  rtems_flashdev *flash,
  const char *flash_path
);

/**
 * @brief Destroys the flash device.
 *
 * @param[in] flash The flash device.
 */
void rtems_flashdev_destroy(
  rtems_flashdev *flash
);

/**
 * @brief Destroys the flash device and frees its memory.
 *
 * @param[in] flash The flash device.
 */
void rtems_flashdev_destroy_and_free(
  rtems_flashdev *flash
);

/** @} */

#endif /* _DEV_FLASHDEV_H */