1 /*
2  * Copyright (c) 2015, Freescale Semiconductor, Inc.
3  * Copyright 2016-2017 NXP
4  *
5  * Redistribution and use in source and binary forms, with or without modification,
6  * are permitted provided that the following conditions are met:
7  *
8  * o Redistributions of source code must retain the above copyright notice, this list
9  *   of conditions and the following disclaimer.
10  *
11  * o Redistributions in binary form must reproduce the above copyright notice, this
12  *   list of conditions and the following disclaimer in the documentation and/or
13  *   other materials provided with the distribution.
14  *
15  * o Neither the name of the copyright holder nor the names of its
16  *   contributors may be used to endorse or promote products derived from this
17  *   software without specific prior written permission.
18  *
19  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
20  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
21  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
22  * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
23  * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
24  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
25  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
26  * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
28  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29  */
30 #ifndef _FSL_SDHC_H_
31 #define _FSL_SDHC_H_
32 
33 #include "fsl_common.h"
34 
35 /*!
36  * @addtogroup sdhc
37  * @{
38  */
39 
40 /******************************************************************************
41  * Definitions.
42  *****************************************************************************/
43 
44 /*! @name Driver version */
45 /*@{*/
46 /*! @brief Driver version 2.1.5. */
47 #define FSL_SDHC_DRIVER_VERSION (MAKE_VERSION(2U, 1U, 5U))
48 /*@}*/
49 
50 /*! @brief Maximum block count can be set one time */
51 #define SDHC_MAX_BLOCK_COUNT (SDHC_BLKATTR_BLKCNT_MASK >> SDHC_BLKATTR_BLKCNT_SHIFT)
52 
53 /*! @brief SDHC status */
54 enum _sdhc_status
55 {
56     kStatus_SDHC_BusyTransferring = MAKE_STATUS(kStatusGroup_SDHC, 0U),            /*!< Transfer is on-going */
57     kStatus_SDHC_PrepareAdmaDescriptorFailed = MAKE_STATUS(kStatusGroup_SDHC, 1U), /*!< Set DMA descriptor failed */
58     kStatus_SDHC_SendCommandFailed = MAKE_STATUS(kStatusGroup_SDHC, 2U),           /*!< Send command failed */
59     kStatus_SDHC_TransferDataFailed = MAKE_STATUS(kStatusGroup_SDHC, 3U),          /*!< Transfer data failed */
60     kStatus_SDHC_DMADataBufferAddrNotAlign =
61         MAKE_STATUS(kStatusGroup_SDHC, 4U), /*!< data buffer addr not align in DMA mode */
62 };
63 
64 /*! @brief Host controller capabilities flag mask */
65 enum _sdhc_capability_flag
66 {
67     kSDHC_SupportAdmaFlag = SDHC_HTCAPBLT_ADMAS_MASK,        /*!< Support ADMA */
68     kSDHC_SupportHighSpeedFlag = SDHC_HTCAPBLT_HSS_MASK,     /*!< Support high-speed */
69     kSDHC_SupportDmaFlag = SDHC_HTCAPBLT_DMAS_MASK,          /*!< Support DMA */
70     kSDHC_SupportSuspendResumeFlag = SDHC_HTCAPBLT_SRS_MASK, /*!< Support suspend/resume */
71     kSDHC_SupportV330Flag = SDHC_HTCAPBLT_VS33_MASK,         /*!< Support voltage 3.3V */
72 #if defined FSL_FEATURE_SDHC_HAS_V300_SUPPORT && FSL_FEATURE_SDHC_HAS_V300_SUPPORT
73     kSDHC_SupportV300Flag = SDHC_HTCAPBLT_VS30_MASK, /*!< Support voltage 3.0V */
74 #endif
75 #if defined FSL_FEATURE_SDHC_HAS_V180_SUPPORT && FSL_FEATURE_SDHC_HAS_V180_SUPPORT
76     kSDHC_SupportV180Flag = SDHC_HTCAPBLT_VS18_MASK, /*!< Support voltage 1.8V */
77 #endif
78     /* Put additional two flags in HTCAPBLT_MBL's position. */
79     kSDHC_Support4BitFlag = (SDHC_HTCAPBLT_MBL_SHIFT << 0U), /*!< Support 4 bit mode */
80     kSDHC_Support8BitFlag = (SDHC_HTCAPBLT_MBL_SHIFT << 1U), /*!< Support 8 bit mode */
81 };
82 
83 /*! @brief Wakeup event mask */
84 enum _sdhc_wakeup_event
85 {
86     kSDHC_WakeupEventOnCardInt = SDHC_PROCTL_WECINT_MASK,    /*!< Wakeup on card interrupt */
87     kSDHC_WakeupEventOnCardInsert = SDHC_PROCTL_WECINS_MASK, /*!< Wakeup on card insertion */
88     kSDHC_WakeupEventOnCardRemove = SDHC_PROCTL_WECRM_MASK,  /*!< Wakeup on card removal */
89 
90     kSDHC_WakeupEventsAll = (kSDHC_WakeupEventOnCardInt | kSDHC_WakeupEventOnCardInsert |
91                              kSDHC_WakeupEventOnCardRemove), /*!< All wakeup events */
92 };
93 
94 /*! @brief Reset type mask */
95 enum _sdhc_reset
96 {
97     kSDHC_ResetAll = SDHC_SYSCTL_RSTA_MASK,     /*!< Reset all except card detection */
98     kSDHC_ResetCommand = SDHC_SYSCTL_RSTC_MASK, /*!< Reset command line */
99     kSDHC_ResetData = SDHC_SYSCTL_RSTD_MASK,    /*!< Reset data line */
100 
101     kSDHC_ResetsAll = (kSDHC_ResetAll | kSDHC_ResetCommand | kSDHC_ResetData), /*!< All reset types */
102 };
103 
104 /*! @brief Transfer flag mask */
105 enum _sdhc_transfer_flag
106 {
107     kSDHC_EnableDmaFlag = SDHC_XFERTYP_DMAEN_MASK, /*!< Enable DMA */
108 
109     kSDHC_CommandTypeSuspendFlag = (SDHC_XFERTYP_CMDTYP(1U)), /*!< Suspend command */
110     kSDHC_CommandTypeResumeFlag = (SDHC_XFERTYP_CMDTYP(2U)),  /*!< Resume command */
111     kSDHC_CommandTypeAbortFlag = (SDHC_XFERTYP_CMDTYP(3U)),   /*!< Abort command */
112 
113     kSDHC_EnableBlockCountFlag = SDHC_XFERTYP_BCEN_MASK,      /*!< Enable block count */
114     kSDHC_EnableAutoCommand12Flag = SDHC_XFERTYP_AC12EN_MASK, /*!< Enable auto CMD12 */
115     kSDHC_DataReadFlag = SDHC_XFERTYP_DTDSEL_MASK,            /*!< Enable data read */
116     kSDHC_MultipleBlockFlag = SDHC_XFERTYP_MSBSEL_MASK,       /*!< Multiple block data read/write */
117 
118     kSDHC_ResponseLength136Flag = SDHC_XFERTYP_RSPTYP(1U),    /*!< 136 bit response length */
119     kSDHC_ResponseLength48Flag = SDHC_XFERTYP_RSPTYP(2U),     /*!< 48 bit response length */
120     kSDHC_ResponseLength48BusyFlag = SDHC_XFERTYP_RSPTYP(3U), /*!< 48 bit response length with busy status */
121 
122     kSDHC_EnableCrcCheckFlag = SDHC_XFERTYP_CCCEN_MASK,   /*!< Enable CRC check */
123     kSDHC_EnableIndexCheckFlag = SDHC_XFERTYP_CICEN_MASK, /*!< Enable index check */
124     kSDHC_DataPresentFlag = SDHC_XFERTYP_DPSEL_MASK,      /*!< Data present flag */
125 };
126 
127 /*! @brief Present status flag mask */
128 enum _sdhc_present_status_flag
129 {
130     kSDHC_CommandInhibitFlag = SDHC_PRSSTAT_CIHB_MASK,     /*!< Command inhibit */
131     kSDHC_DataInhibitFlag = SDHC_PRSSTAT_CDIHB_MASK,       /*!< Data inhibit */
132     kSDHC_DataLineActiveFlag = SDHC_PRSSTAT_DLA_MASK,      /*!< Data line active */
133     kSDHC_SdClockStableFlag = SDHC_PRSSTAT_SDSTB_MASK,     /*!< SD bus clock stable */
134     kSDHC_WriteTransferActiveFlag = SDHC_PRSSTAT_WTA_MASK, /*!< Write transfer active */
135     kSDHC_ReadTransferActiveFlag = SDHC_PRSSTAT_RTA_MASK,  /*!< Read transfer active */
136     kSDHC_BufferWriteEnableFlag = SDHC_PRSSTAT_BWEN_MASK,  /*!< Buffer write enable */
137     kSDHC_BufferReadEnableFlag = SDHC_PRSSTAT_BREN_MASK,   /*!< Buffer read enable */
138     kSDHC_CardInsertedFlag = SDHC_PRSSTAT_CINS_MASK,       /*!< Card inserted */
139     kSDHC_CommandLineLevelFlag = SDHC_PRSSTAT_CLSL_MASK,   /*!< Command line signal level */
140     kSDHC_Data0LineLevelFlag = (1U << 24U),                /*!< Data0 line signal level */
141     kSDHC_Data1LineLevelFlag = (1U << 25U),                /*!< Data1 line signal level */
142     kSDHC_Data2LineLevelFlag = (1U << 26U),                /*!< Data2 line signal level */
143     kSDHC_Data3LineLevelFlag = (1U << 27U),                /*!< Data3 line signal level */
144     kSDHC_Data4LineLevelFlag = (1U << 28U),                /*!< Data4 line signal level */
145     kSDHC_Data5LineLevelFlag = (1U << 29U),                /*!< Data5 line signal level */
146     kSDHC_Data6LineLevelFlag = (1U << 30U),                /*!< Data6 line signal level */
147     kSDHC_Data7LineLevelFlag = (1U << 31U),                /*!< Data7 line signal level */
148 };
149 
150 /*! @brief Interrupt status flag mask */
151 enum _sdhc_interrupt_status_flag
152 {
153     kSDHC_CommandCompleteFlag = SDHC_IRQSTAT_CC_MASK,       /*!< Command complete */
154     kSDHC_DataCompleteFlag = SDHC_IRQSTAT_TC_MASK,          /*!< Data complete */
155     kSDHC_BlockGapEventFlag = SDHC_IRQSTAT_BGE_MASK,        /*!< Block gap event */
156     kSDHC_DmaCompleteFlag = SDHC_IRQSTAT_DINT_MASK,         /*!< DMA interrupt */
157     kSDHC_BufferWriteReadyFlag = SDHC_IRQSTAT_BWR_MASK,     /*!< Buffer write ready */
158     kSDHC_BufferReadReadyFlag = SDHC_IRQSTAT_BRR_MASK,      /*!< Buffer read ready */
159     kSDHC_CardInsertionFlag = SDHC_IRQSTAT_CINS_MASK,       /*!< Card inserted */
160     kSDHC_CardRemovalFlag = SDHC_IRQSTAT_CRM_MASK,          /*!< Card removed */
161     kSDHC_CardInterruptFlag = SDHC_IRQSTAT_CINT_MASK,       /*!< Card interrupt */
162     kSDHC_CommandTimeoutFlag = SDHC_IRQSTAT_CTOE_MASK,      /*!< Command timeout error */
163     kSDHC_CommandCrcErrorFlag = SDHC_IRQSTAT_CCE_MASK,      /*!< Command CRC error */
164     kSDHC_CommandEndBitErrorFlag = SDHC_IRQSTAT_CEBE_MASK,  /*!< Command end bit error */
165     kSDHC_CommandIndexErrorFlag = SDHC_IRQSTAT_CIE_MASK,    /*!< Command index error */
166     kSDHC_DataTimeoutFlag = SDHC_IRQSTAT_DTOE_MASK,         /*!< Data timeout error */
167     kSDHC_DataCrcErrorFlag = SDHC_IRQSTAT_DCE_MASK,         /*!< Data CRC error */
168     kSDHC_DataEndBitErrorFlag = SDHC_IRQSTAT_DEBE_MASK,     /*!< Data end bit error */
169     kSDHC_AutoCommand12ErrorFlag = SDHC_IRQSTAT_AC12E_MASK, /*!< Auto CMD12 error */
170     kSDHC_DmaErrorFlag = SDHC_IRQSTAT_DMAE_MASK,            /*!< DMA error */
171 
172     kSDHC_CommandErrorFlag = (kSDHC_CommandTimeoutFlag | kSDHC_CommandCrcErrorFlag | kSDHC_CommandEndBitErrorFlag |
173                               kSDHC_CommandIndexErrorFlag), /*!< Command error */
174     kSDHC_DataErrorFlag = (kSDHC_DataTimeoutFlag | kSDHC_DataCrcErrorFlag | kSDHC_DataEndBitErrorFlag |
175                            kSDHC_AutoCommand12ErrorFlag),                                  /*!< Data error */
176     kSDHC_ErrorFlag = (kSDHC_CommandErrorFlag | kSDHC_DataErrorFlag | kSDHC_DmaErrorFlag), /*!< All error */
177     kSDHC_DataFlag = (kSDHC_DataCompleteFlag | kSDHC_DmaCompleteFlag | kSDHC_BufferWriteReadyFlag |
178                       kSDHC_BufferReadReadyFlag | kSDHC_DataErrorFlag | kSDHC_DmaErrorFlag), /*!< Data interrupts */
179     kSDHC_CommandFlag = (kSDHC_CommandErrorFlag | kSDHC_CommandCompleteFlag),                /*!< Command interrupts */
180     kSDHC_CardDetectFlag = (kSDHC_CardInsertionFlag | kSDHC_CardRemovalFlag), /*!< Card detection interrupts */
181 
182     kSDHC_AllInterruptFlags = (kSDHC_BlockGapEventFlag | kSDHC_CardInterruptFlag | kSDHC_CommandFlag | kSDHC_DataFlag |
183                                kSDHC_ErrorFlag), /*!< All flags mask */
184 };
185 
186 /*! @brief Auto CMD12 error status flag mask */
187 enum _sdhc_auto_command12_error_status_flag
188 {
189     kSDHC_AutoCommand12NotExecutedFlag = SDHC_AC12ERR_AC12NE_MASK,  /*!< Not executed error */
190     kSDHC_AutoCommand12TimeoutFlag = SDHC_AC12ERR_AC12TOE_MASK,     /*!< Timeout error */
191     kSDHC_AutoCommand12EndBitErrorFlag = SDHC_AC12ERR_AC12EBE_MASK, /*!< End bit error */
192     kSDHC_AutoCommand12CrcErrorFlag = SDHC_AC12ERR_AC12CE_MASK,     /*!< CRC error */
193     kSDHC_AutoCommand12IndexErrorFlag = SDHC_AC12ERR_AC12IE_MASK,   /*!< Index error */
194     kSDHC_AutoCommand12NotIssuedFlag = SDHC_AC12ERR_CNIBAC12E_MASK, /*!< Not issued error */
195 };
196 
197 /*! @brief ADMA error status flag mask */
198 enum _sdhc_adma_error_status_flag
199 {
200     kSDHC_AdmaLenghMismatchFlag = SDHC_ADMAES_ADMALME_MASK,   /*!< Length mismatch error */
201     kSDHC_AdmaDescriptorErrorFlag = SDHC_ADMAES_ADMADCE_MASK, /*!< Descriptor error */
202 };
203 
204 /*!
205  * @brief ADMA error state
206  *
207  * This state is the detail state when ADMA error has occurred.
208  */
209 typedef enum _sdhc_adma_error_state
210 {
211     kSDHC_AdmaErrorStateStopDma = 0x00U,         /*!< Stop DMA */
212     kSDHC_AdmaErrorStateFetchDescriptor = 0x01U, /*!< Fetch descriptor */
213     kSDHC_AdmaErrorStateChangeAddress = 0x02U,   /*!< Change address */
214     kSDHC_AdmaErrorStateTransferData = 0x03U,    /*!< Transfer data */
215 } sdhc_adma_error_state_t;
216 
217 /*! @brief Force event mask */
218 enum _sdhc_force_event
219 {
220     kSDHC_ForceEventAutoCommand12NotExecuted = SDHC_FEVT_AC12NE_MASK,  /*!< Auto CMD12 not executed error */
221     kSDHC_ForceEventAutoCommand12Timeout = SDHC_FEVT_AC12TOE_MASK,     /*!< Auto CMD12 timeout error */
222     kSDHC_ForceEventAutoCommand12CrcError = SDHC_FEVT_AC12CE_MASK,     /*!< Auto CMD12 CRC error */
223     kSDHC_ForceEventEndBitError = SDHC_FEVT_AC12EBE_MASK,              /*!< Auto CMD12 end bit error */
224     kSDHC_ForceEventAutoCommand12IndexError = SDHC_FEVT_AC12IE_MASK,   /*!< Auto CMD12 index error */
225     kSDHC_ForceEventAutoCommand12NotIssued = SDHC_FEVT_CNIBAC12E_MASK, /*!< Auto CMD12 not issued error */
226     kSDHC_ForceEventCommandTimeout = SDHC_FEVT_CTOE_MASK,              /*!< Command timeout error */
227     kSDHC_ForceEventCommandCrcError = SDHC_FEVT_CCE_MASK,              /*!< Command CRC error */
228     kSDHC_ForceEventCommandEndBitError = SDHC_FEVT_CEBE_MASK,          /*!< Command end bit error */
229     kSDHC_ForceEventCommandIndexError = SDHC_FEVT_CIE_MASK,            /*!< Command index error */
230     kSDHC_ForceEventDataTimeout = SDHC_FEVT_DTOE_MASK,                 /*!< Data timeout error */
231     kSDHC_ForceEventDataCrcError = SDHC_FEVT_DCE_MASK,                 /*!< Data CRC error */
232     kSDHC_ForceEventDataEndBitError = SDHC_FEVT_DEBE_MASK,             /*!< Data end bit error */
233     kSDHC_ForceEventAutoCommand12Error = SDHC_FEVT_AC12E_MASK,         /*!< Auto CMD12 error */
234     kSDHC_ForceEventCardInt = SDHC_FEVT_CINT_MASK,                     /*!< Card interrupt */
235     kSDHC_ForceEventDmaError = SDHC_FEVT_DMAE_MASK,                    /*!< Dma error */
236 
237     kSDHC_ForceEventsAll =
238         (kSDHC_ForceEventAutoCommand12NotExecuted | kSDHC_ForceEventAutoCommand12Timeout |
239          kSDHC_ForceEventAutoCommand12CrcError | kSDHC_ForceEventEndBitError | kSDHC_ForceEventAutoCommand12IndexError |
240          kSDHC_ForceEventAutoCommand12NotIssued | kSDHC_ForceEventCommandTimeout | kSDHC_ForceEventCommandCrcError |
241          kSDHC_ForceEventCommandEndBitError | kSDHC_ForceEventCommandIndexError | kSDHC_ForceEventDataTimeout |
242          kSDHC_ForceEventDataCrcError | kSDHC_ForceEventDataEndBitError | kSDHC_ForceEventAutoCommand12Error |
243          kSDHC_ForceEventCardInt | kSDHC_ForceEventDmaError), /*!< All force event flags mask */
244 };
245 
246 /*! @brief Data transfer width */
247 typedef enum _sdhc_data_bus_width
248 {
249     kSDHC_DataBusWidth1Bit = 0U, /*!< 1-bit mode */
250     kSDHC_DataBusWidth4Bit = 1U, /*!< 4-bit mode */
251     kSDHC_DataBusWidth8Bit = 2U, /*!< 8-bit mode */
252 } sdhc_data_bus_width_t;
253 
254 /*! @brief Endian mode */
255 typedef enum _sdhc_endian_mode
256 {
257     kSDHC_EndianModeBig = 0U,         /*!< Big endian mode */
258     kSDHC_EndianModeHalfWordBig = 1U, /*!< Half word big endian mode */
259     kSDHC_EndianModeLittle = 2U,      /*!< Little endian mode */
260 } sdhc_endian_mode_t;
261 
262 /*! @brief DMA mode */
263 typedef enum _sdhc_dma_mode
264 {
265     kSDHC_DmaModeNo = 0U,    /*!< No DMA */
266     kSDHC_DmaModeAdma1 = 1U, /*!< ADMA1 is selected */
267     kSDHC_DmaModeAdma2 = 2U, /*!< ADMA2 is selected */
268 } sdhc_dma_mode_t;
269 
270 /*! @brief SDIO control flag mask */
271 enum _sdhc_sdio_control_flag
272 {
273     kSDHC_StopAtBlockGapFlag = 0x01,       /*!< Stop at block gap */
274     kSDHC_ReadWaitControlFlag = 0x02,      /*!< Read wait control */
275     kSDHC_InterruptAtBlockGapFlag = 0x04,  /*!< Interrupt at block gap */
276     kSDHC_ExactBlockNumberReadFlag = 0x08, /*!< Exact block number read */
277 };
278 
279 /*! @brief MMC card boot mode */
280 typedef enum _sdhc_boot_mode
281 {
282     kSDHC_BootModeNormal = 0U,      /*!< Normal boot */
283     kSDHC_BootModeAlternative = 1U, /*!< Alternative boot */
284 } sdhc_boot_mode_t;
285 
286 /*! @brief The command type */
287 typedef enum _sdhc_card_command_type
288 {
289     kCARD_CommandTypeNormal = 0U,  /*!< Normal command */
290     kCARD_CommandTypeSuspend = 1U, /*!< Suspend command */
291     kCARD_CommandTypeResume = 2U,  /*!< Resume command */
292     kCARD_CommandTypeAbort = 3U,   /*!< Abort command */
293 } sdhc_card_command_type_t;
294 
295 /*!
296  * @brief The command response type.
297  *
298  * Define the command response type from card to host controller.
299  */
300 typedef enum _sdhc_card_response_type
301 {
302     kCARD_ResponseTypeNone = 0U, /*!< Response type: none */
303     kCARD_ResponseTypeR1 = 1U,   /*!< Response type: R1 */
304     kCARD_ResponseTypeR1b = 2U,  /*!< Response type: R1b */
305     kCARD_ResponseTypeR2 = 3U,   /*!< Response type: R2 */
306     kCARD_ResponseTypeR3 = 4U,   /*!< Response type: R3 */
307     kCARD_ResponseTypeR4 = 5U,   /*!< Response type: R4 */
308     kCARD_ResponseTypeR5 = 6U,   /*!< Response type: R5 */
309     kCARD_ResponseTypeR5b = 7U,  /*!< Response type: R5b */
310     kCARD_ResponseTypeR6 = 8U,   /*!< Response type: R6 */
311     kCARD_ResponseTypeR7 = 9U,   /*!< Response type: R7 */
312 } sdhc_card_response_type_t;
313 
314 /*! @brief The alignment size for ADDRESS filed in ADMA1's descriptor */
315 #define SDHC_ADMA1_ADDRESS_ALIGN (4096U)
316 /*! @brief The alignment size for LENGTH field in ADMA1's descriptor */
317 #define SDHC_ADMA1_LENGTH_ALIGN (4096U)
318 /*! @brief The alignment size for ADDRESS field in ADMA2's descriptor */
319 #define SDHC_ADMA2_ADDRESS_ALIGN (4U)
320 /*! @brief The alignment size for LENGTH filed in ADMA2's descriptor */
321 #define SDHC_ADMA2_LENGTH_ALIGN (4U)
322 
323 /* ADMA1 descriptor table
324  * |------------------------|---------|--------------------------|
325  * | Address/page field     |Reserved |         Attribute        |
326  * |------------------------|---------|--------------------------|
327  * |31                    12|11      6|05  |04  |03|02 |01 |00   |
328  * |------------------------|---------|----|----|--|---|---|-----|
329  * | address or data length | 000000  |Act2|Act1| 0|Int|End|Valid|
330  * |------------------------|---------|----|----|--|---|---|-----|
331  *
332  *
333  * |------|------|-----------------|-------|-------------|
334  * | Act2 | Act1 |     Comment     | 31-28 | 27 - 12     |
335  * |------|------|-----------------|---------------------|
336  * |   0  |   0  | No op           | Don't care          |
337  * |------|------|-----------------|-------|-------------|
338  * |   0  |   1  | Set data length |  0000 | Data Length |
339  * |------|------|-----------------|-------|-------------|
340  * |   1  |   0  | Transfer data   | Data address        |
341  * |------|------|-----------------|---------------------|
342  * |   1  |   1  | Link descriptor | Descriptor address  |
343  * |------|------|-----------------|---------------------|
344  */
345 /*! @brief The bit shift for ADDRESS filed in ADMA1's descriptor */
346 #define SDHC_ADMA1_DESCRIPTOR_ADDRESS_SHIFT (12U)
347 /*! @brief The bit mask for ADDRESS field in ADMA1's descriptor */
348 #define SDHC_ADMA1_DESCRIPTOR_ADDRESS_MASK (0xFFFFFU)
349 /*! @brief The bit shift for LENGTH filed in ADMA1's descriptor */
350 #define SDHC_ADMA1_DESCRIPTOR_LENGTH_SHIFT (12U)
351 /*! @brief The mask for LENGTH field in ADMA1's descriptor */
352 #define SDHC_ADMA1_DESCRIPTOR_LENGTH_MASK (0xFFFFU)
353 /*! @brief The maximum value of LENGTH filed in ADMA1's descriptor */
354 #define SDHC_ADMA1_DESCRIPTOR_MAX_LENGTH_PER_ENTRY (SDHC_ADMA1_DESCRIPTOR_LENGTH_MASK + 1U)
355 
356 /*! @brief The mask for the control/status field in ADMA1 descriptor */
357 enum _sdhc_adma1_descriptor_flag
358 {
359     kSDHC_Adma1DescriptorValidFlag = (1U << 0U),                     /*!< Valid flag */
360     kSDHC_Adma1DescriptorEndFlag = (1U << 1U),                       /*!< End flag */
361     kSDHC_Adma1DescriptorInterrupFlag = (1U << 2U),                  /*!< Interrupt flag */
362     kSDHC_Adma1DescriptorActivity1Flag = (1U << 4U),                 /*!< Activity 1 flag */
363     kSDHC_Adma1DescriptorActivity2Flag = (1U << 5U),                 /*!< Activity 2 flag */
364     kSDHC_Adma1DescriptorTypeNop = (kSDHC_Adma1DescriptorValidFlag), /*!< No operation */
365     kSDHC_Adma1DescriptorTypeTransfer =
366         (kSDHC_Adma1DescriptorActivity2Flag | kSDHC_Adma1DescriptorValidFlag), /*!< Transfer data */
367     kSDHC_Adma1DescriptorTypeLink = (kSDHC_Adma1DescriptorActivity1Flag | kSDHC_Adma1DescriptorActivity2Flag |
368                                      kSDHC_Adma1DescriptorValidFlag), /*!< Link descriptor */
369     kSDHC_Adma1DescriptorTypeSetLength =
370         (kSDHC_Adma1DescriptorActivity1Flag | kSDHC_Adma1DescriptorValidFlag), /*!< Set data length */
371 };
372 
373 /* ADMA2 descriptor table
374  * |----------------|---------------|-------------|--------------------------|
375  * | Address field  |     Length    | Reserved    |         Attribute        |
376  * |----------------|---------------|-------------|--------------------------|
377  * |63            32|31           16|15         06|05  |04  |03|02 |01 |00   |
378  * |----------------|---------------|-------------|----|----|--|---|---|-----|
379  * | 32-bit address | 16-bit length | 0000000000  |Act2|Act1| 0|Int|End|Valid|
380  * |----------------|---------------|-------------|----|----|--|---|---|-----|
381  *
382  *
383  * | Act2 | Act1 |     Comment     | Operation                                                         |
384  * |------|------|-----------------|-------------------------------------------------------------------|
385  * |   0  |   0  | No op           | Don't care                                                        |
386  * |------|------|-----------------|-------------------------------------------------------------------|
387  * |   0  |   1  | Reserved        | Read this line and go to next one                                 |
388  * |------|------|-----------------|-------------------------------------------------------------------|
389  * |   1  |   0  | Transfer data   | Transfer data with address and length set in this descriptor line |
390  * |------|------|-----------------|-------------------------------------------------------------------|
391  * |   1  |   1  | Link descriptor | Link to another descriptor                                        |
392  * |------|------|-----------------|-------------------------------------------------------------------|
393  */
394 /*! @brief The bit shift for LENGTH field in ADMA2's descriptor */
395 #define SDHC_ADMA2_DESCRIPTOR_LENGTH_SHIFT (16U)
396 /*! @brief The bit mask for LENGTH field in ADMA2's descriptor */
397 #define SDHC_ADMA2_DESCRIPTOR_LENGTH_MASK (0xFFFFU)
398 /*! @brief The maximum value of LENGTH field in ADMA2's descriptor */
399 #define SDHC_ADMA2_DESCRIPTOR_MAX_LENGTH_PER_ENTRY (SDHC_ADMA2_DESCRIPTOR_LENGTH_MASK)
400 
401 /*! @brief ADMA1 descriptor control and status mask */
402 enum _sdhc_adma2_descriptor_flag
403 {
404     kSDHC_Adma2DescriptorValidFlag = (1U << 0U),     /*!< Valid flag */
405     kSDHC_Adma2DescriptorEndFlag = (1U << 1U),       /*!< End flag */
406     kSDHC_Adma2DescriptorInterruptFlag = (1U << 2U), /*!< Interrupt flag */
407     kSDHC_Adma2DescriptorActivity1Flag = (1U << 4U), /*!< Activity 1 mask */
408     kSDHC_Adma2DescriptorActivity2Flag = (1U << 5U), /*!< Activity 2 mask */
409 
410     kSDHC_Adma2DescriptorTypeNop = (kSDHC_Adma2DescriptorValidFlag), /*!< No operation */
411     kSDHC_Adma2DescriptorTypeReserved =
412         (kSDHC_Adma2DescriptorActivity1Flag | kSDHC_Adma2DescriptorValidFlag), /*!< Reserved */
413     kSDHC_Adma2DescriptorTypeTransfer =
414         (kSDHC_Adma2DescriptorActivity2Flag | kSDHC_Adma2DescriptorValidFlag), /*!< Transfer type */
415     kSDHC_Adma2DescriptorTypeLink = (kSDHC_Adma2DescriptorActivity1Flag | kSDHC_Adma2DescriptorActivity2Flag |
416                                      kSDHC_Adma2DescriptorValidFlag), /*!< Link type */
417 };
418 
419 /*! @brief Defines the adma1 descriptor structure. */
420 typedef uint32_t sdhc_adma1_descriptor_t;
421 
422 /*! @brief Defines the ADMA2 descriptor structure. */
423 typedef struct _sdhc_adma2_descriptor
424 {
425     uint32_t attribute;      /*!< The control and status field */
426     const uint32_t *address; /*!< The address field */
427 } sdhc_adma2_descriptor_t;
428 
429 /*!
430  * @brief SDHC capability information.
431  *
432  * Defines a structure to save the capability information of SDHC.
433  */
434 typedef struct _sdhc_capability
435 {
436     uint32_t specVersion;    /*!< Specification version */
437     uint32_t vendorVersion;  /*!< Vendor version */
438     uint32_t maxBlockLength; /*!< Maximum block length united as byte */
439     uint32_t maxBlockCount;  /*!< Maximum block count can be set one time */
440     uint32_t flags;          /*!< Capability flags to indicate the support information(_sdhc_capability_flag) */
441 } sdhc_capability_t;
442 
443 /*! @brief Card transfer configuration.
444  *
445  * Define structure to configure the transfer-related command index/argument/flags and data block
446  * size/data block numbers. This structure needs to be filled each time a command is sent to the card.
447  */
448 typedef struct _sdhc_transfer_config
449 {
450     size_t dataBlockSize;     /*!< Data block size */
451     uint32_t dataBlockCount;  /*!< Data block count */
452     uint32_t commandArgument; /*!< Command argument */
453     uint32_t commandIndex;    /*!< Command index */
454     uint32_t flags;           /*!< Transfer flags(_sdhc_transfer_flag) */
455 } sdhc_transfer_config_t;
456 
457 /*! @brief Data structure to configure the MMC boot feature */
458 typedef struct _sdhc_boot_config
459 {
460     uint32_t ackTimeoutCount;      /*!< Timeout value for the boot ACK. The available range is 0 ~ 15. */
461     sdhc_boot_mode_t bootMode;     /*!< Boot mode selection. */
462     uint32_t blockCount;           /*!< Stop at block gap value of automatic mode. Available range is 0 ~ 65535. */
463     bool enableBootAck;            /*!< Enable or disable boot ACK */
464     bool enableBoot;               /*!< Enable or disable fast boot */
465     bool enableAutoStopAtBlockGap; /*!< Enable or disable auto stop at block gap function in boot period */
466 } sdhc_boot_config_t;
467 
468 /*! @brief Data structure to initialize the SDHC */
469 typedef struct _sdhc_config
470 {
471     bool cardDetectDat3;           /*!< Enable DAT3 as card detection pin */
472     sdhc_endian_mode_t endianMode; /*!< Endian mode */
473     sdhc_dma_mode_t dmaMode;       /*!< DMA mode */
474     uint32_t readWatermarkLevel;   /*!< Watermark level for DMA read operation. Available range is 1 ~ 128. */
475     uint32_t writeWatermarkLevel;  /*!< Watermark level for DMA write operation. Available range is 1 ~ 128. */
476 } sdhc_config_t;
477 
478 /*!
479  * @brief Card data descriptor
480  *
481  * Defines a structure to contain data-related attribute. 'enableIgnoreError' is used for the case that upper card
482  * driver
483  * want to ignore the error event to read/write all the data not to stop read/write immediately when error event
484  * happen for example bus testing procedure for MMC card.
485  */
486 typedef struct _sdhc_data
487 {
488     bool enableAutoCommand12; /*!< Enable auto CMD12 */
489     bool enableIgnoreError;   /*!< Enable to ignore error event to read/write all the data */
490     size_t blockSize;         /*!< Block size */
491     uint32_t blockCount;      /*!< Block count */
492     uint32_t *rxData;         /*!< Buffer to save data read */
493     const uint32_t *txData;   /*!< Data buffer to write */
494 } sdhc_data_t;
495 
496 /*!
497  * @brief Card command descriptor
498  *
499  * Define card command-related attribute.
500  */
501 typedef struct _sdhc_command
502 {
503     uint32_t index;                         /*!< Command index */
504     uint32_t argument;                      /*!< Command argument */
505     sdhc_card_command_type_t type;          /*!< Command type */
506     sdhc_card_response_type_t responseType; /*!< Command response type */
507     uint32_t response[4U];                  /*!< Response for this command */
508     uint32_t responseErrorFlags;            /*!< response error flag, the flag which need to check
509                                                 the command reponse*/
510 } sdhc_command_t;
511 
512 /*! @brief Transfer state */
513 typedef struct _sdhc_transfer
514 {
515     sdhc_data_t *data;       /*!< Data to transfer */
516     sdhc_command_t *command; /*!< Command to send */
517 } sdhc_transfer_t;
518 
519 /*! @brief SDHC handle typedef */
520 typedef struct _sdhc_handle sdhc_handle_t;
521 
522 /*! @brief SDHC callback functions. */
523 typedef struct _sdhc_transfer_callback
524 {
525     void (*CardInserted)(void);  /*!< Card inserted occurs when DAT3/CD pin is for card detect */
526     void (*CardRemoved)(void);   /*!< Card removed occurs */
527     void (*SdioInterrupt)(void); /*!< SDIO card interrupt occurs */
528     void (*SdioBlockGap)(void);  /*!< SDIO card stopped at block gap occurs */
529     void (*TransferComplete)(SDHC_Type *base,
530                              sdhc_handle_t *handle,
531                              status_t status,
532                              void *userData); /*!< Transfer complete callback */
533 } sdhc_transfer_callback_t;
534 
535 /*!
536  * @brief SDHC handle
537  *
538  * Defines the structure to save the SDHC state information and callback function. The detailed interrupt status when
539  * sending a command or transfering data can be obtained from the interruptFlags field by using the mask defined in
540  * sdhc_interrupt_flag_t.
541  *
542  * @note All the fields except interruptFlags and transferredWords must be allocated by the user.
543  */
544 struct _sdhc_handle
545 {
546     /* Transfer parameter */
547     sdhc_data_t *volatile data;       /*!< Data to transfer */
548     sdhc_command_t *volatile command; /*!< Command to send */
549 
550     /* Transfer status */
551     volatile uint32_t interruptFlags;   /*!< Interrupt flags of last transaction */
552     volatile uint32_t transferredWords; /*!< Words transferred by DATAPORT way */
553 
554     /* Callback functions */
555     sdhc_transfer_callback_t callback; /*!< Callback function */
556     void *userData;                    /*!< Parameter for transfer complete callback */
557 };
558 
559 /*! @brief SDHC transfer function. */
560 typedef status_t (*sdhc_transfer_function_t)(SDHC_Type *base, sdhc_transfer_t *content);
561 
562 /*! @brief SDHC host descriptor */
563 typedef struct _sdhc_host
564 {
565     SDHC_Type *base;                   /*!< SDHC peripheral base address */
566     uint32_t sourceClock_Hz;           /*!< SDHC source clock frequency united in Hz */
567     sdhc_config_t config;              /*!< SDHC configuration */
568     sdhc_capability_t capability;      /*!< SDHC capability information */
569     sdhc_transfer_function_t transfer; /*!< SDHC transfer function */
570 } sdhc_host_t;
571 
572 /*************************************************************************************************
573  * API
574  ************************************************************************************************/
575 #if defined(__cplusplus)
576 extern "C" {
577 #endif
578 
579 /*!
580  * @name Initialization and deinitialization
581  * @{
582  */
583 
584 /*!
585  * @brief SDHC module initialization function.
586  *
587  * Configures the SDHC according to the user configuration.
588  *
589  * Example:
590    @code
591    sdhc_config_t config;
592    config.cardDetectDat3 = false;
593    config.endianMode = kSDHC_EndianModeLittle;
594    config.dmaMode = kSDHC_DmaModeAdma2;
595    config.readWatermarkLevel = 128U;
596    config.writeWatermarkLevel = 128U;
597    SDHC_Init(SDHC, &config);
598    @endcode
599  *
600  * @param base SDHC peripheral base address.
601  * @param config SDHC configuration information.
602  * @retval kStatus_Success Operate successfully.
603  */
604 void SDHC_Init(SDHC_Type *base, const sdhc_config_t *config);
605 
606 /*!
607  * @brief Deinitializes the SDHC.
608  *
609  * @param base SDHC peripheral base address.
610  */
611 void SDHC_Deinit(SDHC_Type *base);
612 
613 /*!
614  * @brief Resets the SDHC.
615  *
616  * @param base SDHC peripheral base address.
617  * @param mask The reset type mask(_sdhc_reset).
618  * @param timeout Timeout for reset.
619  * @retval true Reset successfully.
620  * @retval false Reset failed.
621  */
622 bool SDHC_Reset(SDHC_Type *base, uint32_t mask, uint32_t timeout);
623 
624 /* @} */
625 
626 /*!
627  * @name DMA Control
628  * @{
629  */
630 
631 /*!
632  * @brief Sets the ADMA descriptor table configuration.
633  *
634  * @param base SDHC peripheral base address.
635  * @param dmaMode DMA mode.
636  * @param table ADMA table address.
637  * @param tableWords ADMA table buffer length united as Words.
638  * @param data Data buffer address.
639  * @param dataBytes Data length united as bytes.
640  * @retval kStatus_OutOfRange ADMA descriptor table length isn't enough to describe data.
641  * @retval kStatus_Success Operate successfully.
642  */
643 status_t SDHC_SetAdmaTableConfig(SDHC_Type *base,
644                                  sdhc_dma_mode_t dmaMode,
645                                  uint32_t *table,
646                                  uint32_t tableWords,
647                                  const uint32_t *data,
648                                  uint32_t dataBytes);
649 
650 /* @} */
651 
652 /*!
653  * @name Interrupts
654  * @{
655  */
656 
657 /*!
658  * @brief Enables the interrupt status.
659  *
660  * @param base SDHC peripheral base address.
661  * @param mask Interrupt status flags mask(_sdhc_interrupt_status_flag).
662  */
SDHC_EnableInterruptStatus(SDHC_Type * base,uint32_t mask)663 static inline void SDHC_EnableInterruptStatus(SDHC_Type *base, uint32_t mask)
664 {
665     base->IRQSTATEN |= mask;
666 }
667 
668 /*!
669  * @brief Disables the interrupt status.
670  *
671  * @param base SDHC peripheral base address.
672  * @param mask The interrupt status flags mask(_sdhc_interrupt_status_flag).
673  */
SDHC_DisableInterruptStatus(SDHC_Type * base,uint32_t mask)674 static inline void SDHC_DisableInterruptStatus(SDHC_Type *base, uint32_t mask)
675 {
676     base->IRQSTATEN &= ~mask;
677 }
678 
679 /*!
680  * @brief Enables the interrupt signal corresponding to the interrupt status flag.
681  *
682  * @param base SDHC peripheral base address.
683  * @param mask The interrupt status flags mask(_sdhc_interrupt_status_flag).
684  */
SDHC_EnableInterruptSignal(SDHC_Type * base,uint32_t mask)685 static inline void SDHC_EnableInterruptSignal(SDHC_Type *base, uint32_t mask)
686 {
687     base->IRQSIGEN |= mask;
688 }
689 
690 /*!
691  * @brief Disables the interrupt signal corresponding to the interrupt status flag.
692  *
693  * @param base SDHC peripheral base address.
694  * @param mask The interrupt status flags mask(_sdhc_interrupt_status_flag).
695  */
SDHC_DisableInterruptSignal(SDHC_Type * base,uint32_t mask)696 static inline void SDHC_DisableInterruptSignal(SDHC_Type *base, uint32_t mask)
697 {
698     base->IRQSIGEN &= ~mask;
699 }
700 
701 /* @} */
702 
703 /*!
704  * @name Status
705  * @{
706  */
707 
708 /*!
709  * @brief Gets the current interrupt status.
710  *
711  * @param base SDHC peripheral base address.
712  * @return Current interrupt status flags mask(_sdhc_interrupt_status_flag).
713  */
SDHC_GetInterruptStatusFlags(SDHC_Type * base)714 static inline uint32_t SDHC_GetInterruptStatusFlags(SDHC_Type *base)
715 {
716     return base->IRQSTAT;
717 }
718 
719 /*!
720  * @brief Clears a specified interrupt status.
721  *
722  * @param base SDHC peripheral base address.
723  * @param mask The interrupt status flags mask(_sdhc_interrupt_status_flag).
724  */
SDHC_ClearInterruptStatusFlags(SDHC_Type * base,uint32_t mask)725 static inline void SDHC_ClearInterruptStatusFlags(SDHC_Type *base, uint32_t mask)
726 {
727     base->IRQSTAT = mask;
728 }
729 
730 /*!
731  * @brief Gets the status of auto command 12 error.
732  *
733  * @param base SDHC peripheral base address.
734  * @return Auto command 12 error status flags mask(_sdhc_auto_command12_error_status_flag).
735  */
SDHC_GetAutoCommand12ErrorStatusFlags(SDHC_Type * base)736 static inline uint32_t SDHC_GetAutoCommand12ErrorStatusFlags(SDHC_Type *base)
737 {
738     return base->AC12ERR;
739 }
740 
741 /*!
742  * @brief Gets the status of the ADMA error.
743  *
744  * @param base SDHC peripheral base address.
745  * @return ADMA error status flags mask(_sdhc_adma_error_status_flag).
746  */
SDHC_GetAdmaErrorStatusFlags(SDHC_Type * base)747 static inline uint32_t SDHC_GetAdmaErrorStatusFlags(SDHC_Type *base)
748 {
749     return base->ADMAES;
750 }
751 
752 /*!
753  * @brief Gets a present status.
754  *
755  * This function gets the present SDHC's status except for an interrupt status and an error status.
756  *
757  * @param base SDHC peripheral base address.
758  * @return Present SDHC's status flags mask(_sdhc_present_status_flag).
759  */
SDHC_GetPresentStatusFlags(SDHC_Type * base)760 static inline uint32_t SDHC_GetPresentStatusFlags(SDHC_Type *base)
761 {
762     return base->PRSSTAT;
763 }
764 
765 /* @} */
766 
767 /*!
768  * @name Bus Operations
769  * @{
770  */
771 
772 /*!
773  * @brief Gets the capability information.
774  *
775  * @param base SDHC peripheral base address.
776  * @param capability Structure to save capability information.
777  */
778 void SDHC_GetCapability(SDHC_Type *base, sdhc_capability_t *capability);
779 
780 /*!
781  * @brief Enables or disables the SD bus clock.
782  *
783  * @param base SDHC peripheral base address.
784  * @param enable True to enable, false to disable.
785  */
SDHC_EnableSdClock(SDHC_Type * base,bool enable)786 static inline void SDHC_EnableSdClock(SDHC_Type *base, bool enable)
787 {
788     if (enable)
789     {
790         base->SYSCTL |= SDHC_SYSCTL_SDCLKEN_MASK;
791     }
792     else
793     {
794         base->SYSCTL &= ~SDHC_SYSCTL_SDCLKEN_MASK;
795     }
796 }
797 
798 /*!
799  * @brief Sets the SD bus clock frequency.
800  *
801  * @param base SDHC peripheral base address.
802  * @param srcClock_Hz SDHC source clock frequency united in Hz.
803  * @param busClock_Hz SD bus clock frequency united in Hz.
804  *
805  * @return The nearest frequency of busClock_Hz configured to SD bus.
806  */
807 uint32_t SDHC_SetSdClock(SDHC_Type *base, uint32_t srcClock_Hz, uint32_t busClock_Hz);
808 
809 /*!
810  * @brief Sends 80 clocks to the card to set it to the active state.
811  *
812  * This function must be called each time the card is inserted to ensure that the card can receive the command
813  * correctly.
814  *
815  * @param base SDHC peripheral base address.
816  * @param timeout Timeout to initialize card.
817  * @retval true Set card active successfully.
818  * @retval false Set card active failed.
819  */
820 bool SDHC_SetCardActive(SDHC_Type *base, uint32_t timeout);
821 
822 /*!
823  * @brief Sets the data transfer width.
824  *
825  * @param base SDHC peripheral base address.
826  * @param width Data transfer width.
827  */
SDHC_SetDataBusWidth(SDHC_Type * base,sdhc_data_bus_width_t width)828 static inline void SDHC_SetDataBusWidth(SDHC_Type *base, sdhc_data_bus_width_t width)
829 {
830     base->PROCTL = ((base->PROCTL & ~SDHC_PROCTL_DTW_MASK) | SDHC_PROCTL_DTW(width));
831 }
832 
833 /*!
834  * @brief Sets the card transfer-related configuration.
835  *
836  * This function fills the card transfer-related command argument/transfer flag/data size. The command and data are sent
837  by
838  * SDHC after calling this function.
839  *
840  * Example:
841    @code
842    sdhc_transfer_config_t transferConfig;
843    transferConfig.dataBlockSize = 512U;
844    transferConfig.dataBlockCount = 2U;
845    transferConfig.commandArgument = 0x01AAU;
846    transferConfig.commandIndex = 8U;
847    transferConfig.flags |= (kSDHC_EnableDmaFlag | kSDHC_EnableAutoCommand12Flag | kSDHC_MultipleBlockFlag);
848    SDHC_SetTransferConfig(SDHC, &transferConfig);
849    @endcode
850  *
851  * @param base SDHC peripheral base address.
852  * @param config Command configuration structure.
853  */
854 void SDHC_SetTransferConfig(SDHC_Type *base, const sdhc_transfer_config_t *config);
855 
856 /*!
857  * @brief Gets the command response.
858  *
859  * @param base SDHC peripheral base address.
860  * @param index The index of response register, range from 0 to 3.
861  * @return Response register transfer.
862  */
SDHC_GetCommandResponse(SDHC_Type * base,uint32_t index)863 static inline uint32_t SDHC_GetCommandResponse(SDHC_Type *base, uint32_t index)
864 {
865     assert(index < 4U);
866 
867     return base->CMDRSP[index];
868 }
869 
870 /*!
871  * @brief Fills the the data port.
872  *
873  * This function is used to implement the data transfer by Data Port instead of DMA.
874  *
875  * @param base SDHC peripheral base address.
876  * @param data The data about to be sent.
877  */
SDHC_WriteData(SDHC_Type * base,uint32_t data)878 static inline void SDHC_WriteData(SDHC_Type *base, uint32_t data)
879 {
880     base->DATPORT = data;
881 }
882 
883 /*!
884  * @brief Retrieves the data from the data port.
885  *
886  * This function is used to implement the data transfer by Data Port instead of DMA.
887  *
888  * @param base SDHC peripheral base address.
889  * @return The data has been read.
890  */
SDHC_ReadData(SDHC_Type * base)891 static inline uint32_t SDHC_ReadData(SDHC_Type *base)
892 {
893     return base->DATPORT;
894 }
895 
896 /*!
897  * @brief Enables or disables a wakeup event in low-power mode.
898  *
899  * @param base SDHC peripheral base address.
900  * @param mask Wakeup events mask(_sdhc_wakeup_event).
901  * @param enable True to enable, false to disable.
902  */
SDHC_EnableWakeupEvent(SDHC_Type * base,uint32_t mask,bool enable)903 static inline void SDHC_EnableWakeupEvent(SDHC_Type *base, uint32_t mask, bool enable)
904 {
905     if (enable)
906     {
907         base->PROCTL |= mask;
908     }
909     else
910     {
911         base->PROCTL &= ~mask;
912     }
913 }
914 
915 /*!
916  * @brief Enables or disables the card detection level for testing.
917  *
918  * @param base SDHC peripheral base address.
919  * @param enable True to enable, false to disable.
920  */
SDHC_EnableCardDetectTest(SDHC_Type * base,bool enable)921 static inline void SDHC_EnableCardDetectTest(SDHC_Type *base, bool enable)
922 {
923     if (enable)
924     {
925         base->PROCTL |= SDHC_PROCTL_CDSS_MASK;
926     }
927     else
928     {
929         base->PROCTL &= ~SDHC_PROCTL_CDSS_MASK;
930     }
931 }
932 
933 /*!
934  * @brief Sets the card detection test level.
935  *
936  * This function sets the card detection test level to indicate whether the card is inserted into the SDHC when DAT[3]/
937  * CD pin is selected as a card detection pin. This function can also assert the pin logic when DAT[3]/CD pin is
938  * selected
939  * as the card detection pin.
940  *
941  * @param base SDHC peripheral base address.
942  * @param high True to set the card detect level to high.
943  */
SDHC_SetCardDetectTestLevel(SDHC_Type * base,bool high)944 static inline void SDHC_SetCardDetectTestLevel(SDHC_Type *base, bool high)
945 {
946     if (high)
947     {
948         base->PROCTL |= SDHC_PROCTL_CDTL_MASK;
949     }
950     else
951     {
952         base->PROCTL &= ~SDHC_PROCTL_CDTL_MASK;
953     }
954 }
955 
956 /*!
957  * @brief Enables or disables the SDIO card control.
958  *
959  * @param base SDHC peripheral base address.
960  * @param mask SDIO card control flags mask(_sdhc_sdio_control_flag).
961  * @param enable True to enable, false to disable.
962  */
963 void SDHC_EnableSdioControl(SDHC_Type *base, uint32_t mask, bool enable);
964 
965 /*!
966  * @brief Restarts a transaction which has stopped at the block GAP for the SDIO card.
967  *
968  * @param base SDHC peripheral base address.
969  */
SDHC_SetContinueRequest(SDHC_Type * base)970 static inline void SDHC_SetContinueRequest(SDHC_Type *base)
971 {
972     base->PROCTL |= SDHC_PROCTL_CREQ_MASK;
973 }
974 
975 /*!
976  * @brief Configures the MMC boot feature.
977  *
978  * Example:
979    @code
980    sdhc_boot_config_t config;
981    config.ackTimeoutCount = 4;
982    config.bootMode = kSDHC_BootModeNormal;
983    config.blockCount = 5;
984    config.enableBootAck = true;
985    config.enableBoot = true;
986    config.enableAutoStopAtBlockGap = true;
987    SDHC_SetMmcBootConfig(SDHC, &config);
988    @endcode
989  *
990  * @param base SDHC peripheral base address.
991  * @param config The MMC boot configuration information.
992  */
993 void SDHC_SetMmcBootConfig(SDHC_Type *base, const sdhc_boot_config_t *config);
994 
995 /*!
996  * @brief Forces generating events according to the given mask.
997  *
998  * @param base SDHC peripheral base address.
999  * @param mask The force events mask(_sdhc_force_event).
1000  */
SDHC_SetForceEvent(SDHC_Type * base,uint32_t mask)1001 static inline void SDHC_SetForceEvent(SDHC_Type *base, uint32_t mask)
1002 {
1003     base->FEVT = mask;
1004 }
1005 
1006 /* @} */
1007 
1008 /*!
1009  * @name Transactional
1010  * @{
1011  */
1012 
1013 /*!
1014  * @brief Transfers the command/data using a blocking method.
1015  *
1016  * This function waits until the command response/data is received or the SDHC encounters an error by polling the status
1017  * flag.
1018  * This function support non word align data addr transfer support, if data buffer addr is not align in DMA mode,
1019  * the API will continue finish the transfer by polling IO directly
1020  * The application must not call this API in multiple threads at the same time. Because of that this API doesn't support
1021  * the re-entry mechanism.
1022  *
1023  * @note There is no need to call the API 'SDHC_TransferCreateHandle' when calling this API.
1024  *
1025  * @param base SDHC peripheral base address.
1026  * @param admaTable ADMA table address, can't be null if transfer way is ADMA1/ADMA2.
1027  * @param admaTableWords ADMA table length united as words, can't be 0 if transfer way is ADMA1/ADMA2.
1028  * @param transfer Transfer content.
1029  * @retval kStatus_InvalidArgument Argument is invalid.
1030  * @retval kStatus_SDHC_PrepareAdmaDescriptorFailed Prepare ADMA descriptor failed.
1031  * @retval kStatus_SDHC_SendCommandFailed Send command failed.
1032  * @retval kStatus_SDHC_TransferDataFailed Transfer data failed.
1033  * @retval kStatus_Success Operate successfully.
1034  */
1035 status_t SDHC_TransferBlocking(SDHC_Type *base,
1036                                uint32_t *admaTable,
1037                                uint32_t admaTableWords,
1038                                sdhc_transfer_t *transfer);
1039 
1040 /*!
1041  * @brief Creates the SDHC handle.
1042  *
1043  * @param base SDHC peripheral base address.
1044  * @param handle SDHC handle pointer.
1045  * @param callback Structure pointer to contain all callback functions.
1046  * @param userData Callback function parameter.
1047  */
1048 void SDHC_TransferCreateHandle(SDHC_Type *base,
1049                                sdhc_handle_t *handle,
1050                                const sdhc_transfer_callback_t *callback,
1051                                void *userData);
1052 
1053 /*!
1054  * @brief Transfers the command/data using an interrupt and an asynchronous method.
1055  *
1056  * This function sends a command and data and returns immediately. It doesn't wait the transfer complete or encounter an
1057  * error.
1058  * This function support non word align data addr transfer support, if data buffer addr is not align in DMA mode,
1059  * the API will continue finish the transfer by polling IO directly
1060  * The application must not call this API in multiple threads at the same time. Because of that this API doesn't support
1061  * the re-entry mechanism.
1062  *
1063  * @note Call the API 'SDHC_TransferCreateHandle' when calling this API.
1064  *
1065  * @param base SDHC peripheral base address.
1066  * @param handle SDHC handle.
1067  * @param admaTable ADMA table address, can't be null if transfer way is ADMA1/ADMA2.
1068  * @param admaTableWords ADMA table length united as words, can't be 0 if transfer way is ADMA1/ADMA2.
1069  * @param transfer Transfer content.
1070  * @retval kStatus_InvalidArgument Argument is invalid.
1071  * @retval kStatus_SDHC_BusyTransferring Busy transferring.
1072  * @retval kStatus_SDHC_PrepareAdmaDescriptorFailed Prepare ADMA descriptor failed.
1073  * @retval kStatus_Success Operate successfully.
1074  */
1075 status_t SDHC_TransferNonBlocking(
1076     SDHC_Type *base, sdhc_handle_t *handle, uint32_t *admaTable, uint32_t admaTableWords, sdhc_transfer_t *transfer);
1077 
1078 /*!
1079  * @brief IRQ handler for the SDHC.
1080  *
1081  * This function deals with the IRQs on the given host controller.
1082  *
1083  * @param base SDHC peripheral base address.
1084  * @param handle SDHC handle.
1085  */
1086 void SDHC_TransferHandleIRQ(SDHC_Type *base, sdhc_handle_t *handle);
1087 
1088 /* @} */
1089 
1090 #if defined(__cplusplus)
1091 }
1092 #endif
1093 /*! @} */
1094 
1095 #endif /* _FSL_SDHC_H_*/
1096