1 /*
2  * Copyright (c) 2016 Intel Corporation.
3  *
4  * SPDX-License-Identifier: Apache-2.0
5  */
6 
7 /**
8  * @file
9  * @brief Disk Access layer API
10  *
11  * This file contains APIs for disk access.
12  */
13 
14 #ifndef ZEPHYR_INCLUDE_STORAGE_DISK_ACCESS_H_
15 #define ZEPHYR_INCLUDE_STORAGE_DISK_ACCESS_H_
16 
17 /**
18  * @brief Storage APIs
19  * @defgroup storage_apis Storage APIs
20  * @ingroup os_services
21  * @{
22  * @}
23  */
24 
25 /**
26  * @brief Disk Access APIs
27  * @defgroup disk_access_interface Disk Access Interface
28  * @ingroup storage_apis
29  * @{
30  */
31 
32 #include <zephyr/drivers/disk.h>
33 
34 #ifdef __cplusplus
35 extern "C" {
36 #endif
37 
38 /**
39  * @brief perform any initialization
40  *
41  * This call is made by the consumer before doing any IO calls so that the
42  * disk or the backing device can do any initialization. Although still
43  * supported for legacy compatibility, users should instead call
44  * @ref disk_access_ioctl with the IOCTL @ref DISK_IOCTL_CTRL_INIT.
45  *
46  * Disk initialization is reference counted, so only the first successful call
47  * to initialize a uninitialized (or previously de-initialized) disk will
48  * actually initialize the disk
49  *
50  * @param[in] pdrv          Disk name
51  *
52  * @return 0 on success, negative errno code on fail
53  */
54 int disk_access_init(const char *pdrv);
55 
56 /**
57  * @brief Get the status of disk
58  *
59  * This call is used to get the status of the disk
60  *
61  * @param[in] pdrv          Disk name
62  *
63  * @return DISK_STATUS_OK or other DISK_STATUS_*s
64  */
65 int disk_access_status(const char *pdrv);
66 
67 /**
68  * @brief read data from disk
69  *
70  * Function to read data from disk to a memory buffer.
71  *
72  * Note: if he disk is of NVMe type, user will need to ensure data_buf
73  *       pointer is 4-bytes aligned.
74  *
75  * @param[in] pdrv          Disk name
76  * @param[in] data_buf      Pointer to the memory buffer to put data.
77  * @param[in] start_sector  Start disk sector to read from
78  * @param[in] num_sector    Number of disk sectors to read
79  *
80  * @return 0 on success, negative errno code on fail
81  */
82 int disk_access_read(const char *pdrv, uint8_t *data_buf,
83 		     uint32_t start_sector, uint32_t num_sector);
84 
85 /**
86  * @brief write data to disk
87  *
88  * Function write data from memory buffer to disk.
89  *
90  * Note: if he disk is of NVMe type, user will need to ensure data_buf
91  *       pointer is 4-bytes aligned.
92  *
93  * @param[in] pdrv          Disk name
94  * @param[in] data_buf      Pointer to the memory buffer
95  * @param[in] start_sector  Start disk sector to write to
96  * @param[in] num_sector    Number of disk sectors to write
97  *
98  * @return 0 on success, negative errno code on fail
99  */
100 int disk_access_write(const char *pdrv, const uint8_t *data_buf,
101 		      uint32_t start_sector, uint32_t num_sector);
102 
103 /**
104  * @brief Get/Configure disk parameters
105  *
106  * Function to get disk parameters and make any special device requests.
107  *
108  * @param[in] pdrv          Disk name
109  * @param[in] cmd           DISK_IOCTL_* code describing the request
110  * @param[in] buff          Command data buffer
111  *
112  * @return 0 on success, negative errno code on fail
113  */
114 int disk_access_ioctl(const char *pdrv, uint8_t cmd, void *buff);
115 
116 #ifdef __cplusplus
117 }
118 #endif
119 
120 /**
121  * @}
122  */
123 
124 #endif /* ZEPHYR_INCLUDE_STORAGE_DISK_ACCESS_H_ */
125