1 /*
2  * Copyright (c) 2020-2021 Huawei Device Co., Ltd.
3  *
4  * HDF is dual licensed: you can use it either under the terms of
5  * the GPL, or the BSD license, at your option.
6  * See the LICENSE file in the root of this repository for complete details.
7  */
8 
9 /**
10  * @addtogroup SDIO
11  * @{
12  *
13  * @brief Declares standard APIs of basic secure digital input and output (SDIO) capabilities.
14  *
15  * You can use this module to access the SDIO and enable the driver to operate an SDIO-compliant device.
16  * These capabilities include reading and writing data based on SDIO, setting the block size,
17  * applying for and releasing interrupts, enabling and disabling devices, and occupying and releasing the bus.
18  *
19  * @since 1.0
20  */
21 
22  /**
23   * @file sdio_if.h
24   *
25   * @brief Declares the standard SDIO APIs.
26   *
27   * @since 1.0
28   */
29 
30 #ifndef SDIO_IF_H
31 #define SDIO_IF_H
32 
33 #include "mmc_if.h"
34 
35 #ifdef __cplusplus
36 #if __cplusplus
37 extern "C" {
38 #endif
39 #endif /* __cplusplus */
40 
41 /**
42  * @brief Enumerates SDIO common information types.
43  *
44  * When obtaining SDIO common information by calling {@link SdioGetCommonInfo} or setting the information
45  * by calling {@link SdioSetCommonInfo}, you need to pass the information type.
46  *
47  * @since 1.0
48  */
49 typedef enum {
50     SDIO_FUNC_INFO = 0,   /**< Functionality information */
51     SDIO_OTHER_INFO,      /**< Other information */
52 } SdioCommonInfoType;
53 
54 /**
55  * @brief Defines the SDIO capabilities.
56  *
57  * You can obtain and set the SDIO capabilities by calling {@link SdioGetCommonInfo} and {@link SdioSetCommonInfo}
58  * with {@link SdioCommonInfo} and {@link SdioCommonInfoType} passed.
59  *
60  * @since 1.0
61  */
62 typedef struct {
63     uint32_t maxBlockNum;    /**< Maximum number of blocks in a request */
64     uint32_t maxBlockSize;   /**< Maximum number of bytes in a block.
65                               * The value ranges from <b>1</b> to <b>2048</b>.
66                               */
67     uint32_t maxRequestSize; /**< Maximum number of bytes in a request.
68                               * The value ranges from <b>1</b> to <b>2048</b>.
69                               */
70     uint32_t enTimeout;      /**< Maximum timeout duration, in milliseconds.
71                               * The value cannot exceed <b>1</b> second.
72                               */
73     uint32_t funcNum;        /**< Functionality number, ranging from <b>1</b> to <b>7</b>. */
74     uint32_t irqCap;         /**< IRQ capabilities */
75     void *data;              /**< Private data */
76 } SdioFuncInfo;
77 
78 /**
79  * @brief Defines SDIO common information.
80  *
81  * You can obtain and set common SDIO information by calling {@link SdioGetCommonInfo} and {@link SdioSetCommonInfo}
82  * with {@link SdioCommonInfo} and {@link SdioCommonInfoType} passed.
83  *
84  * @since 1.0
85  */
86 typedef union {
87     SdioFuncInfo funcInfo;   /**< Functionality information */
88 } SdioCommonInfo;
89 
90 /**
91  * @brief Defines SDIO function config.
92  *
93  * When enabling an SDIO controller, you must specify its SDIO functionality configurations for
94  * selecting the required functionality. For details, see {@link SdioOpen}.
95  *
96  * @since 1.0
97  */
98 struct SdioFunctionConfig {
99     uint32_t funcNr;        /**< Functionality number, ranging from <b>1</b> to <b>7</b>. */
100     uint16_t vendorId;      /**< Vendor ID */
101     uint16_t deviceId;      /**< Device ID */
102 };
103 
104 /**
105  * @brief Defines the function type of an SDIO IRQ.
106  *
107  * This function is registered when you call {@link SdioClaimIrq} to request the SDIO IRQ.
108  *
109  * @param data Indicates the private data passed to this IRQ (The data is specified when the IRQ is registered).
110  *
111  * @since 1.0
112  */
113 typedef void SdioIrqHandler(void *);
114 
115 /**
116  * @brief Opens an SDIO controller with a specified bus number.
117  *
118  * Before using the SDIO interface, you can obtain the device handle of the SDIO controller
119  * by calling {@link SdioOpen}. This function is used in pair with {@link SdioClose}.
120  *
121  * @param mmcBusNum Indicates the bus number.
122  * @param config Indicates the pointer to SDIO functionality configurations.
123  *
124  * @return Returns the device handle {@link DevHandle} of the SDIO controller if the operation is successful;
125  * returns <b>NULL</b> otherwise.
126  *
127  * @since 1.0
128  */
129 DevHandle SdioOpen(int16_t mmcBusNum, struct SdioFunctionConfig *config);
130 
131 /**
132  * @brief Closes an SDIO controller.
133  *
134  * After the SDIO interface is used, you can close the SDIO controller by calling {@link SdioClose}.
135  * This function is used in pair with {@link SdioOpen}.
136  *
137  * @param handle Indicates the pointer to the device handle of the SDIO controller.
138  *
139  * @since 1.0
140  */
141 void SdioClose(DevHandle handle);
142 
143 /**
144  * @brief Incrementally reads a given length of data from the specified SDIO address.
145  *
146  * If the length of the data to read is greater than the size of a block, the data is read by block,
147  * and the remaining data that is smaller than one block is read by byte. Otherwise, data is read by byte.
148  *
149  * @param handle Indicates the pointer to the device handle of the SDIO controller obtained by {@link SdioOpen}.
150  * @param data Indicates the pointer to the data to read.
151  * @param addr Indicates the start address of the data to read.
152  * @param size Indicates the length of the data to read.
153  *
154  * @return Returns <b>0</b> if the operation is successful; returns a negative value if the operation fails.
155  *
156  * @since 1.0
157  */
158 int32_t SdioReadBytes(DevHandle handle, uint8_t *data, uint32_t addr, uint32_t size);
159 
160 /**
161  * @brief Incrementally writes a given length of data into the specified SDIO address.
162  *
163  * If the length of the data to write is greater than the size of a block, the data is written by block first,
164  * and the remaining data that is smaller than one block is written by byte. Otherwise, data is written by byte.
165  *
166  * @param handle Indicates the pointer to the device handle of the SDIO controller obtained by {@link SdioOpen}.
167  * @param data Indicates the pointer to the data to write.
168  * @param addr Indicates the start address of the data to write.
169  * @param size Indicates the length of the data to write.
170  *
171  * @return Returns <b>0</b> if the operation is successful; returns a negative value if the operation fails.
172  *
173  * @since 1.0
174  */
175 int32_t SdioWriteBytes(DevHandle handle, uint8_t *data, uint32_t addr, uint32_t size);
176 
177 /**
178  * @brief Reads a given length of data from the fixed SDIO address.
179  *
180  * If the length of the data to read is greater than the size of a block, the data is read by block,
181  * and the remaining data that is smaller than one block is read by byte. Otherwise, data is read by byte.
182  *
183  * @param handle Indicates the pointer to the device handle of the SDIO controller obtained by {@link SdioOpen}.
184  * @param data Indicates the pointer to the data to read.
185  * @param addr Indicates the fixed address of the data to read.
186  * @param size Indicates the length of the data to read.
187  * @param scatterLen Indicates the length of the scatter list. If this value is not <b>0</b>, the data is of the
188  * scatter list type.
189  *
190  * @return Returns <b>0</b> if the operation is successful; returns a negative value if the operation fails.
191  *
192  * @since 1.0
193  */
194 int32_t SdioReadBytesFromFixedAddr(DevHandle handle, uint8_t *data,
195     uint32_t addr, uint32_t size, uint32_t scatterLen);
196 
197 /**
198  * @brief Writes a given length of data into the fixed SDIO address.
199  *
200  * If the length of the data to write is greater than the size of a block, the data is written by block first,
201  * and the remaining data that is smaller than one block is written by byte. Otherwise, data is written by byte.
202  *
203  * @param handle Indicates the pointer to the device handle of the SDIO controller obtained by {@link SdioOpen}.
204  * @param data Indicates the pointer to the data to write.
205  * @param addr Indicates the fixed address of the data to write.
206  * @param size Indicates the length of the data to write.
207  * @param scatterLen Indicates the length of the scatter list. If this value is not <b>0</b>, the data is of the
208  * scatter list type.
209  *
210  * @return Returns <b>0</b> if the operation is successful; returns a negative value if the operation fails.
211  *
212  * @since 1.0
213  */
214 int32_t SdioWriteBytesToFixedAddr(DevHandle handle, uint8_t *data,
215     uint32_t addr, uint32_t size, uint32_t scatterLen);
216 
217 /**
218  * @brief Reads a given length of data from the address space of SDIO function 0.
219  *
220  * Currently, only one byte of data can be read.
221  *
222  * @param handle Indicates the pointer to the device handle of the SDIO controller obtained by {@link SdioOpen}.
223  * @param data Indicates the pointer to the data to read.
224  * @param addr Indicates the start address of the data to read.
225  * @param size Indicates the length of the data to read.
226  *
227  * @return Returns <b>0</b> if the operation is successful; returns a negative value if the operation fails.
228  *
229  * @since 1.0
230  */
231 int32_t SdioReadBytesFromFunc0(DevHandle handle, uint8_t *data, uint32_t addr, uint32_t size);
232 
233 /**
234  * @brief Writes a given length of data into the address space of SDIO function 0.
235  *
236  * Currently, only one byte of data can be written.
237  *
238  * @param handle Indicates the pointer to the device handle of the SDIO controller obtained by {@link SdioOpen}.
239  * @param data Indicates the pointer to the data to write.
240  * @param addr Indicates the start address of the data to write.
241  * @param size Indicates the length of the data to write.
242  *
243  * @return Returns <b>0</b> if the operation is successful; returns a negative value if the operation fails.
244  *
245  * @since 1.0
246  */
247 int32_t SdioWriteBytesToFunc0(DevHandle handle, uint8_t *data, uint32_t addr, uint32_t size);
248 
249 /**
250  * @brief Sets the block size.
251  *
252  * If data to read or write is performed, use this function to set the block size.
253  *
254  * @param handle Indicates the pointer to the device handle of the SDIO controller obtained by {@link SdioOpen}.
255  * @param blockSize Indicates the block size to be set. If the value is <b>0</b>, the default value is used.
256  * The value ranges from <b>1</b> to <b>2048</b> bytes.
257  *
258  * @return Returns <b>0</b> if the operation is successful; returns a negative value if the operation fails.
259  *
260  * @since 1.0
261  */
262 int32_t SdioSetBlockSize(DevHandle handle, uint32_t blockSize);
263 
264 /**
265  * @brief Obtains common information.
266  *
267  * You can call this function to obtain the capabilities and private data of the I/O function.
268  *
269  * @param handle Indicates the pointer to the device handle of the SDIO controller obtained by {@link SdioOpen}.
270  * @param info Indicates the pointer to the common information to be obtained.
271  * For details, see {@link SdioCommonInfo}.
272  * @param infoType Indicates the type of the common information to be obtained.
273  * For details, see {@link SdioCommonInfoType}.
274  *
275  * @return Returns <b>0</b> if the operation is successful; returns a negative value if the operation fails.
276  *
277  * @since 1.0
278  */
279 int32_t SdioGetCommonInfo(DevHandle handle, SdioCommonInfo *info, SdioCommonInfoType infoType);
280 
281 /**
282  * @brief Sets common information.
283  *
284  * You can call this function to set the maximum timeout duration and private data.
285  *
286  * @param handle Indicates the pointer to the device handle of the SDIO controller obtained by {@link SdioOpen}.
287  * @param info Indicates the pointer to the common information to be set.
288  * For details, see {@link SdioCommonInfo}.
289  * @param infoType Indicates the type of the common information to be set.
290  * For details, see {@link SdioCommonInfoType}.
291  *
292  * @return Returns <b>0</b> if the operation is successful; returns a negative value if the operation fails.
293  *
294  * @since 1.0
295  */
296 int32_t SdioSetCommonInfo(DevHandle handle, SdioCommonInfo *info, SdioCommonInfoType infoType);
297 
298 /**
299  * @brief Flushes data.
300  *
301  * You can call this function when an SDIO needs to be reinitialized or an unexpected error occurs.
302  *
303  * @param handle Indicates the pointer to the device handle of the SDIO controller obtained by {@link SdioOpen}.
304  *
305  * @return Returns <b>0</b> if the operation is successful; returns a negative value if the operation fails.
306  *
307  * @since 1.0
308  */
309 int32_t SdioFlushData(DevHandle handle);
310 
311 /**
312  * @brief Claims a host exclusively.
313  *
314  * You can call this function to enable the SDIO module to exclusively claim a host
315  * and then perform operations on the devices connected to the host. After performing required operations,
316  * release the host by calling {@link SdioReleaseHost}.
317  *
318  * @param handle Indicates the pointer to the device handle of the SDIO controller obtained by {@link SdioOpen}.
319  *
320  * @since 1.0
321  */
322 void SdioClaimHost(DevHandle handle);
323 
324 /**
325  * @brief Releases the exclusively claimed host.
326  *
327  * This function is used in pair with {@link SdioClaimHost}.
328  *
329  * @param handle Indicates the pointer to the device handle of the SDIO controller obtained by {@link SdioOpen}.
330  *
331  * @since 1.0
332  */
333 void SdioReleaseHost(DevHandle handle);
334 
335 /**
336  * @brief Enables the SDIO device so that its register can be accessed.
337  *
338  * @param handle Indicates the pointer to the device handle of the SDIO controller obtained by {@link SdioOpen}.
339  *
340  * @return Returns <b>0</b> if the operation is successful; returns a negative value if the operation fails.
341  *
342  * @since 1.0
343  */
344 int32_t SdioEnableFunc(DevHandle handle);
345 
346 /**
347  * @brief Disables the SDIO device.
348  *
349  * This function is used in pair with {@link SdioEnableFunc}.
350  *
351  * @param handle Indicates the pointer to the device handle of the SDIO controller obtained by {@link SdioOpen}.
352  *
353  * @return Returns <b>0</b> if the operation is successful; returns a negative value if the operation fails.
354  *
355  * @since 1.0
356  */
357 int32_t SdioDisableFunc(DevHandle handle);
358 
359 /**
360  * @brief Claims an SDIO IRQ.
361  *
362  * When there is data, commands, or events, the IRQ function is executed.
363  *
364  * @param handle Indicates the pointer to the device handle of the SDIO controller obtained by {@link SdioOpen}.
365  * @param irqHandler Indicates the pointer to the SDIO IRQ function. For details, see {@link SdioIrqHandler}.
366  *
367  * @return Returns <b>0</b> if the operation is successful; returns a negative value if the operation fails.
368  *
369  * @since 1.0
370  */
371 int32_t SdioClaimIrq(DevHandle handle, SdioIrqHandler *irqHandler);
372 
373 /**
374  * @brief Releases an SDIO IRQ.
375  *
376  * This function is used in pair with {@link SdioClaimIrq}.
377  *
378  * @param handle Indicates the pointer to the device handle of the SDIO controller obtained by {@link SdioOpen}.
379  *
380  * @return Returns <b>0</b> if the operation is successful; returns a negative value if the operation fails.
381  *
382  * @since 1.0
383  */
384 int32_t SdioReleaseIrq(DevHandle handle);
385 
386 #ifdef __cplusplus
387 #if __cplusplus
388 }
389 #endif
390 #endif /* __cplusplus */
391 
392 #endif /* SDIO_IF_H */
393 /** @} */
394