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