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 : * @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 1 : #define DISK_IOCTL_GET_SECTOR_COUNT 1
44 : /** Get the size of a disk SECTOR in bytes */
45 1 : #define DISK_IOCTL_GET_SECTOR_SIZE 2
46 : /** reserved. It used to be DISK_IOCTL_GET_DISK_SIZE */
47 1 : #define DISK_IOCTL_RESERVED 3
48 : /** How many sectors constitute a FLASH Erase block */
49 1 : #define DISK_IOCTL_GET_ERASE_BLOCK_SZ 4
50 : /** Commit any cached read/writes to disk */
51 1 : #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 1 : #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 1 : #define DISK_IOCTL_CTRL_DEINIT 7
70 :
71 : /**
72 : * @brief Possible return bitmasks for disk_status()
73 : */
74 :
75 : /** Disk status okay */
76 1 : #define DISK_STATUS_OK 0x00
77 : /** Disk status uninitialized */
78 1 : #define DISK_STATUS_UNINIT 0x01
79 : /** Disk status no media */
80 1 : #define DISK_STATUS_NOMEDIA 0x02
81 : /** Disk status write protected */
82 1 : #define DISK_STATUS_WR_PROTECT 0x04
83 :
84 : struct disk_operations;
85 :
86 : /**
87 : * @brief Disk info
88 : */
89 1 : struct disk_info {
90 : /** Internally used list node */
91 1 : sys_dnode_t node;
92 : /** Disk name */
93 1 : const char *name;
94 : /** Disk operations */
95 1 : const struct disk_operations *ops;
96 : /** Device associated to this disk */
97 1 : const struct device *dev;
98 : /** Internally used disk reference count */
99 1 : uint16_t refcnt;
100 : };
101 :
102 : /**
103 : * @brief Disk operations
104 : */
105 1 : struct disk_operations {
106 0 : int (*init)(struct disk_info *disk);
107 0 : int (*status)(struct disk_info *disk);
108 0 : int (*read)(struct disk_info *disk, uint8_t *data_buf,
109 : uint32_t start_sector, uint32_t num_sector);
110 0 : int (*write)(struct disk_info *disk, const uint8_t *data_buf,
111 : uint32_t start_sector, uint32_t num_sector);
112 0 : 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 1 : 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 1 : 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_ */
|
