-
Notifications
You must be signed in to change notification settings - Fork 38
/
physical_drive.h
219 lines (194 loc) · 8.41 KB
/
physical_drive.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
/****************************************************************************
**
** Copyright (C) ${COPYRIGHT_YEAR} MikroElektronika d.o.o.
** Contact: https://www.mikroe.com/contact
**
** This file is part of the mikroSDK package
**
** Commercial License Usage
**
** Licensees holding valid commercial NECTO compilers AI licenses may use this
** file in accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The MikroElektronika Company.
** For licensing terms and conditions see
** https://www.mikroe.com/legal/software-license-agreement.
** For further information use the contact form at
** https://www.mikroe.com/contact.
**
**
** GNU Lesser General Public License Usage
**
** Alternatively, this file may be used for
** non-commercial projects under the terms of the GNU Lesser
** General Public License version 3 as published by the Free Software
** Foundation: https://www.gnu.org/licenses/lgpl-3.0.html.
**
** The above copyright notice and this permission notice shall be
** included in all copies or substantial portions of the Software.
**
** THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
** OF MERCHANTABILITY, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
** TO THE WARRANTIES FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
** IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
** DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT
** OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE
** OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
**
****************************************************************************/
/*!
* @file sdspi_physical_drive.h
* @brief SD SPI Physical Drive.
*/
#ifndef _PHYSICAL_DRIVE_H_
#define _PHYSICAL_DRIVE_H_
#ifdef __cplusplus
extern "C"{
#endif
#include "stdint.h"
#include "generic_pointer.h"
/**
* @defgroup physical_drive_group Physical Drive
* @ingroup middlewaregroup
* @brief Physical Drive Reference.
* @details Physical Drive Data Structures and API Reference.
*/
/**
* @defgroup physical_drive_status_group Physical Drive APIs Status
* @ingroup physical_drive_group
* @brief Physical Drive API function return values.
* @{
*/
/**
* @brief: Success.
*/
#define PDS_OK ((uint8_t)0)
/**
* @brief: Error.
*/
#define PDS_GENERAL_ERROR ((uint8_t)1)
/**
* @brief: Function is not implemented.
*/
#define PDS_NOT_IMPLEMENTED ((uint8_t)2)
typedef uint8_t pd_status_t;
/*! @} */ // physical_drive_status_group
/**
* @brief Physical Drive Type Enumerator.
*
* @details Indicate that a physical drives is initialized, what implementation the physical drive uses,
* and what it's @ref physical_drive_vector_table_t functions point to.
*/
typedef enum {
PD_TYPE_UNINITIALIZED = 0,
PD_TYPE_SDSPI,
} physical_drive_type_t;
/**
* @ingroup physical_drive_data_group
*
* @brief Physical Drive Vector Table
*
* @details A table of function pointers, used used by @ref physical_drive_t struct,
* in order to call up correct functions for the particular implementation of the physical drive.
*/
typedef struct physical_drive_vector_table physical_drive_vector_table_t;
/**
* @defgroup physical_drive_data_group Physical Drive Data
* @ingroup physical_drive_group
* @brief Physical Drive Data Structure Reference.
*/
/**
* @ingroup physical_drive_data_group
*
* @brief Physical Drive Base Data Structure Reference.
*
* @details Keeps track of the relevant data for the physical drive and manages communication with hardware memory module,
* with it's vector table that point to correct function for particular physical drive implementation.
* It's intended usage is, as a base structure of a derived structures, eg. @ref sdspi_logical_drive_t.
* It is not intended to be used independently.
*/
typedef struct {
physical_drive_vector_table_t * vtptr; /**< Physical drive vector table. See @ref physical_drive_vector_table_t structure. */
physical_drive_type_t type; /**< Type of physical drive. See @ref physical_drive_type_t enum.*/
uint32_t sector_count; /**< Number of sectors on this physical drive. */
uint16_t sector_size; /**< Sector size in unit of bytes, on this physical drive. */
uint16_t erase_block_size; /**< Erase block size on this physical drive. */
uint8_t volumes; /**< Number of logical drives mounted on this physical drive */
uint8_t error; /**< Tracks APIs statuses and errors on this physical drive */
} physical_drive_t;
/**
* @addtogroup physical_drive_group
* @brief Physical Drive Reference.
* @details Physical Drive Data Structures and API Reference.
* @{
*/
/**
* @brief Initialize a Hardware memory module.
*
* @details This API function will initialize hardware memory module, making it ready for subsequent read and write operations.
*
* @param[in] physical_drive A pointer to the physical drive base structure.
* It manages communication with, and identifies hardware memory module.
* See @ref physical_drive_t, and @ref sdspi_physical_drive_t structures for detailed explanation.
*
* @retval PDS_OK If the hardware memory module is initialized successfully.
* @retval FSS_GENERAL_ERROR If the hardware memory module failed.
*
* @pre @c physical_drive structure must be initialized before calling this function.
* See @ref sdspi_physical_drive_init functions for detailed explanation.
*
* @post Reading from and writing to hardware memory module is now possible.
* All other physical drive API function can be called.
*
* @note @c physical_drive should be used only as base of derived structures.
* Eg. @ref sdspi_physical_drive_t.
*/
pd_status_t physical_drive_init(physical_drive_t * physical_drive);
/**
* @brief Write to a Hardware Memory Module.
*
* @details This API function will write @c size number of bytes from the @c buffer
* into the hardware memory module at the location indicated by the parameter @c addr.
*
* @param[in] physical_drive A pointer to the physical drive base structure.
* It manages communication with, and identifies hardware memory module.
* See @ref physical_drive_t, and @ref sdspi_physical_drive_t structures for detailed explanation.
* @param[in] buffer A pointer to the buffer from which data will be written to the hardware memory module.
* @param[in] addr The location inside hardware memory module, in unit of bytes, where data will be written.
* @param[in] size Number of bytes data that needs to be written into the hardware memory module.
*
* @retval PDS_OK If data was written to the hardware memory module successfully.
* @retval FSS_GENERAL_ERROR If writing data failed.
*
* @pre The hardware memory module must be initialized first.
* See @ref physical_drive_init functions for detailed explanation.
*
* @note @c physical_drive should be used only as base of derived structures.
* Eg. @ref sdspi_physical_drive_t.
*/
pd_status_t physical_drive_read(physical_drive_t * physical_drive, void * buffer, unsigned long long addr, unsigned long long size);
/**
* @brief Read from a Hardware Memory Module.
*
* @details This API function will read @c size number of bytes from the location indicated
* by the parameter @c addr inside hardware memory module, and store it into the @c buffer.
*
* @param[in] physical_drive A pointer to the physical drive base structure.
* It manages communication with, and identifies hardware memory module.
* See @ref physical_drive_t, and @ref sdspi_physical_drive_t structures for detailed explanation.
* @param[in] buffer A pointer to the buffer where data read form the hardware memory module will be stored.
* @param[in] addr The location inside hardware memory module, from which data will be read.
* @param[in] size Number of bytes data that needs to be read from the hardware memory module.
*
* @retval PDS_OK If data was read from the hardware memory module successfully.
* @retval FSS_GENERAL_ERROR If reading data failed.
*
* @pre The hardware memory module must be initialized first.
* See @ref physical_drive_init functions for detailed explanation.
*/
pd_status_t physical_drive_write(physical_drive_t * physical_drive, const void * __generic_ptr buffer, unsigned long long addr, unsigned long long size);
/*! @} */ // physical_drive_group
#ifdef __cplusplus
}
#endif
#endif // !_PHYSICAL_DRIVE_H_