1 /* 2 * Copyright (c) 2016 Intel Corporation. 3 * Copyright (c) 2021 Nordic Semiconductor ASA 4 * 5 * SPDX-License-Identifier: Apache-2.0 6 */ 7 8 /** 9 * @file 10 * @ingroup disk_driver_interface 11 * @brief Main header file for disk driver API. 12 * 13 * This file contains interface for disk access. Apart from disks, various 14 * other storage media like Flash and RAM disks may implement this interface to 15 * be used by various higher layers(consumers) like USB Mass storage 16 * and Filesystems. 17 */ 18 19 #ifndef ZEPHYR_INCLUDE_DRIVERS_DISK_H_ 20 #define ZEPHYR_INCLUDE_DRIVERS_DISK_H_ 21 22 /** 23 * @brief Interfaces for disks. 24 * @defgroup disk_driver_interface Disk Access 25 * @since 1.6 26 * @version 1.1.0 27 * @ingroup io_interfaces 28 * @{ 29 * 30 * @defgroup disk_driver_interface_ext Device-specific Disk Access API extensions 31 * 32 * @{ 33 * @} 34 */ 35 36 #include <zephyr/kernel.h> 37 #include <zephyr/types.h> 38 #include <zephyr/sys/dlist.h> 39 40 #ifdef __cplusplus 41 extern "C" { 42 #endif 43 44 /** 45 * @brief Possible Cmd Codes for disk_ioctl() 46 */ 47 48 /** Get the number of sectors in the disk */ 49 #define DISK_IOCTL_GET_SECTOR_COUNT 1 50 /** Get the size of a disk SECTOR in bytes */ 51 #define DISK_IOCTL_GET_SECTOR_SIZE 2 52 /** reserved. It used to be DISK_IOCTL_GET_DISK_SIZE */ 53 #define DISK_IOCTL_RESERVED 3 54 /** How many sectors constitute a FLASH Erase block */ 55 #define DISK_IOCTL_GET_ERASE_BLOCK_SZ 4 56 /** Commit any cached read/writes to disk */ 57 #define DISK_IOCTL_CTRL_SYNC 5 58 /** Initialize the disk. This IOCTL must be issued before the disk can be 59 * used for I/O. It is reference counted, so only the first successful 60 * invocation of this macro on an uninitialized disk will initialize the IO 61 * device 62 */ 63 #define DISK_IOCTL_CTRL_INIT 6 64 /** Deinitialize the disk. This IOCTL can be used to de-initialize the disk, 65 * enabling it to be removed from the system if the disk is hot-pluggable. 66 * Disk usage is reference counted, so for a given disk the 67 * `DISK_IOCTL_CTRL_DEINIT` IOCTL must be issued as many times as the 68 * `DISK_IOCTL_CTRL_INIT` IOCTL was issued in order to de-initialize it. 69 * 70 * This macro optionally accepts a pointer to a boolean as the `buf` parameter, 71 * which if true indicates the disk should be forcibly stopped, ignoring all 72 * reference counts. The disk driver must report success if a forced stop is 73 * requested, but this operation is inherently unsafe. 74 */ 75 #define DISK_IOCTL_CTRL_DEINIT 7 76 77 /** 78 * @brief Possible return bitmasks for disk_status() 79 */ 80 81 /** Disk status okay */ 82 #define DISK_STATUS_OK 0x00 83 /** Disk status uninitialized */ 84 #define DISK_STATUS_UNINIT 0x01 85 /** Disk status no media */ 86 #define DISK_STATUS_NOMEDIA 0x02 87 /** Disk status write protected */ 88 #define DISK_STATUS_WR_PROTECT 0x04 89 90 struct disk_operations; 91 92 /** 93 * @brief Disk info 94 */ 95 struct disk_info { 96 /** Internally used list node */ 97 sys_dnode_t node; 98 /** Disk name */ 99 const char *name; 100 /** Disk operations */ 101 const struct disk_operations *ops; 102 /** Device associated to this disk */ 103 const struct device *dev; 104 /** Internally used disk reference count */ 105 uint16_t refcnt; 106 }; 107 108 /** 109 * @brief Disk operations 110 */ 111 struct disk_operations { 112 int (*init)(struct disk_info *disk); 113 int (*status)(struct disk_info *disk); 114 int (*read)(struct disk_info *disk, uint8_t *data_buf, 115 uint32_t start_sector, uint32_t num_sector); 116 int (*write)(struct disk_info *disk, const uint8_t *data_buf, 117 uint32_t start_sector, uint32_t num_sector); 118 int (*erase)(struct disk_info *disk, uint32_t start_sector, uint32_t num_sector); 119 int (*ioctl)(struct disk_info *disk, uint8_t cmd, void *buff); 120 }; 121 122 /** 123 * @brief Register disk 124 * 125 * @param[in] disk Pointer to the disk info structure 126 * 127 * @return 0 on success, negative errno code on fail 128 */ 129 int disk_access_register(struct disk_info *disk); 130 131 /** 132 * @brief Unregister disk 133 * 134 * @param[in] disk Pointer to the disk info structure 135 * 136 * @return 0 on success, negative errno code on fail 137 */ 138 int disk_access_unregister(struct disk_info *disk); 139 140 #ifdef __cplusplus 141 } 142 #endif 143 144 /** 145 * @} 146 */ 147 148 #endif /* ZEPHYR_INCLUDE_DRIVERS_DISK_H_ */ 149
