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