Skip to content

Commit 402bf0c

Browse files
Icarus113Icarus113
committed
feat(sd): sd host driver layer driver NG
1 parent f9765d0 commit 402bf0c

File tree

24 files changed

+2980
-36
lines changed

24 files changed

+2980
-36
lines changed

‎components/esp_driver_sd_intf/CMakeLists.txt‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
idf_build_get_property(target IDF_TARGET)
2+
3+
if(${target} STREQUAL "linux")
4+
return() # This component is not supported by the POSIX/Linux simulator
5+
endif()
6+
7+
set(srcs "sd_host.c")
8+
9+
set(public_include "include")
10+
11+
idf_component_register(SRCS ${srcs}
12+
INCLUDE_DIRS ${public_include}
13+
PRIV_REQUIRES sdmmc)

‎components/esp_driver_sd_intf/README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# SD Host Driver Interface Layer
2+
3+
This component provides the SD Host driver APIs.

‎components/esp_driver_sd_intf/include/driver/sd_host.h‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
/*
2+
* SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
3+
*
4+
* SPDX-License-Identifier: Apache-2.0
5+
*/
6+
7+
#pragma once
8+
9+
#include "esp_err.h"
10+
#include "soc/gpio_num.h"
11+
#include "driver/sd_types.h"
12+
#include "sd_protocol_types.h"
13+
14+
#ifdef __cplusplus
15+
extern "C" {
16+
#endif
17+
18+
/**
19+
* @brief Configure SD Host slot
20+
*
21+
* @param[in] slot SD Host slot handle
22+
* @param[in] config SD Host slot configuration
23+
*
24+
* @return
25+
* - ESP_OK: On success
26+
* - ESP_ERR_INVALID_ARG: Invalid argument
27+
*/
28+
esp_err_t sd_host_slot_configure(sd_host_slot_handle_t slot, const sd_host_slot_cfg_t *config);
29+
30+
/**
31+
* @brief Do a transaction for the slot
32+
*
33+
* @param[in] slot SD Host slot handle
34+
* @param[in] cmdinfo SD command info, see `sdmmc_command_t`
35+
*
36+
* @return
37+
* - ESP_OK: On success
38+
* - ESP_ERR_INVALID_ARG: Invalid argument
39+
*/
40+
esp_err_t sd_host_slot_do_transaction(sd_host_slot_handle_t slot, sdmmc_command_t *cmdinfo);
41+
42+
/**
43+
* @brief Register SD event callbacks
44+
*
45+
* @note User can deregister a previously registered callback by calling this function and setting the to-be-deregistered callback member in
46+
* the `cbs` structure to NULL.
47+
*
48+
* @param[in] slot SD Host slot handle
49+
* @param[in] cbs Group of callback functions
50+
* @param[in] user_data User data, which will be delivered to the callback functions directly
51+
*
52+
* @return
53+
* - ESP_OK: On success
54+
* - ESP_ERR_INVALID_ARG: Invalid arguments
55+
* - ESP_ERR_INVALID_STATE: Driver state is invalid, you shouldn't call this API at this moment
56+
*/
57+
esp_err_t sd_host_slot_register_event_callbacks(sd_host_slot_handle_t slot, const sd_host_evt_cbs_t *cbs, void *user_data);
58+
59+
/**
60+
* @brief Remove an SD Host slot
61+
*
62+
* @param[in] slot SD Host slot handle
63+
*
64+
* @return
65+
* - ESP_OK: On success
66+
* - ESP_ERR_INVALID_STATE: Invalid state, slot is not available
67+
* - ESP_ERR_INVALID_ARG: Invalid argument
68+
*/
69+
esp_err_t sd_host_remove_slot(sd_host_slot_handle_t slot);
70+
71+
/**
72+
* @brief Set an SD Host slot clock always on
73+
*
74+
* @param[in] slot SD Host slot handle
75+
* @param[in] always_on Always on or not
76+
*
77+
* @return
78+
* - ESP_OK: On success
79+
* - ESP_ERR_INVALID_ARG: Invalid argument
80+
*/
81+
esp_err_t sd_host_slot_set_cclk_always_on(sd_host_slot_handle_t slot, bool always_on);
82+
83+
/**
84+
* @brief Enable an SD Host slot IO interrupt
85+
*
86+
* @param[in] slot SD Host slot handle
87+
*
88+
* @return
89+
* - ESP_OK: On success
90+
* - ESP_ERR_INVALID_ARG: Invalid argument
91+
*/
92+
esp_err_t sd_host_slot_enable_io_int(sd_host_slot_handle_t slot);
93+
94+
/**
95+
* @brief Wait for IO interrupt event
96+
*
97+
* @param[in] slot SD Host slot handle
98+
* @param[in] timeout_ticks Timeout ticks
99+
*
100+
* @return
101+
* - ESP_OK: On success
102+
* - ESP_ERR_INVALID_ARG: Invalid argument
103+
* - ESP_ERR_TIMEOUT: Timeout
104+
*/
105+
esp_err_t sd_host_slot_wait_io_int(sd_host_slot_handle_t slot, TickType_t timeout_ticks);
106+
107+
/**
108+
* @brief Get slot info
109+
*
110+
* @param[in] slot SD Host slot handle
111+
* @param[out] info SD slot info
112+
*
113+
* @return
114+
* - ESP_OK: On success
115+
* - ESP_ERR_INVALID_ARG: Invalid argument
116+
*/
117+
esp_err_t sd_host_slot_get_info(sd_host_slot_handle_t slot, sd_host_slot_info_t *info);
118+
119+
/**
120+
* @brief Delete an SD Host controller
121+
*
122+
* @param[in] ctlr SD Host controller handle
123+
*
124+
* @return
125+
* - ESP_OK: On success
126+
* - ESP_ERR_INVALID_ARG: Invalid argument
127+
* - ESP_ERR_INVALID_STATE: Invalid state, there's still registered slot(s)
128+
*/
129+
esp_err_t sd_host_del_controller(sd_host_ctlr_handle_t ctlr);
130+
131+
#ifdef __cplusplus
132+
}
133+
#endif

‎components/esp_driver_sd_intf/include/driver/sd_types.h‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
/*
2+
* SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
3+
*
4+
* SPDX-License-Identifier: Apache-2.0
5+
*/
6+
7+
#pragma once
8+
9+
#include <stdint.h>
10+
#include <stdbool.h>
11+
#include "esp_err.h"
12+
#include "hal/sd_types.h"
13+
14+
#ifdef __cplusplus
15+
extern "C" {
16+
#endif
17+
18+
/**
19+
* @brief SD Host controller handle
20+
*/
21+
typedef struct sd_host_driver_t *sd_host_ctlr_handle_t;
22+
23+
/**
24+
* @brief SD Host slot handle
25+
*/
26+
typedef struct sd_slot_driver_t *sd_host_slot_handle_t;
27+
28+
/**
29+
* @brief SD Host slot configuration
30+
*/
31+
typedef struct {
32+
struct {
33+
int freq_hz; ///< Frequency in Hz
34+
bool override; ///< If set to true, frequency will be set to freq_hz; If set to false, frequency is unchanged. By default it's false
35+
} freq; ///< Frequency settings
36+
struct {
37+
bool override; ///< If set to true, width will be set to width configured in `sd_host_sdmmc_slot_io_cfg_t`; If set to false, width is unchanged. By default it's false
38+
} width; ///< Bus width settings
39+
struct {
40+
sd_sampling_mode_t mode; ///< Sampling mode, see `sd_sampling_mode_t`
41+
bool override; ///< If set to true, sampling mode will be set to sampling_mode; If set to false, sampling mode is unchanged. By default it's false
42+
} sampling_mode; ///< Sampling mode settings
43+
struct {
44+
sdmmc_delay_phase_t delayphase; ///< Delay phase, see `sdmmc_delay_phase_t`
45+
bool override; ///< If set to true, delay phase will be set to delay_phase; If set to false, delay phase is unchanged. By default it's false
46+
} delay_phase; ///< Delay phase settings
47+
struct {
48+
sdmmc_delay_line_t delayline; ///< Delay line, see `sdmmc_delay_line_t`
49+
bool override; ///< If set to true, delay line will be set to delay_line; If set to false, delay line is unchanged. By default it's false
50+
} delay_line; ///< Delay line settings
51+
} sd_host_slot_cfg_t;
52+
53+
/**
54+
* @brief Slot info
55+
*/
56+
typedef struct {
57+
int freq_hz; ///< Frequency in Hz
58+
uint8_t width; ///< Bus width
59+
sd_mode_t sd_mode; ///< SD mode, see `sd_mode_t`
60+
sd_sampling_mode_t sampling_mode; ///< Sampling mode, see `sd_sampling_mode_t`
61+
} sd_host_slot_info_t;
62+
63+
/*---------------------------------------------
64+
Event Callbacks
65+
----------------------------------------------*/
66+
/**
67+
* @brief SD event data structure
68+
*/
69+
typedef struct {
70+
//leave empty for future-proof
71+
} sd_host_evt_data_t;
72+
73+
/**
74+
* @brief Prototype of SD event callback
75+
*
76+
* @param[in] slot Slot handle
77+
* @param[in] edata SD event data
78+
* @param[in] user_data User registered context, registered when in `esp_isp_register_event_callbacks()`
79+
*
80+
* @return Whether a high priority task is woken up by this function
81+
*/
82+
typedef bool (*sd_host_callback_t)(sd_host_slot_handle_t slot, const sd_host_evt_data_t *edata, void *user_data);
83+
84+
/**
85+
* @brief SD event callbacks
86+
*/
87+
typedef struct {
88+
sd_host_callback_t on_trans_done; ///< Event callback, invoked when one transaction done
89+
sd_host_callback_t on_io_interrupt; ///< Event callback, invoked when IO interrupts
90+
} sd_host_evt_cbs_t;
91+
92+
#ifdef __cplusplus
93+
}
94+
#endif

‎components/esp_driver_sd_intf/include/esp_private/sd_driver_interface.h‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
/*
2+
* SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
3+
*
4+
* SPDX-License-Identifier: Apache-2.0
5+
*/
6+
#pragma once
7+
8+
#include <stdbool.h>
9+
#include "esp_err.h"
10+
#include "driver/sd_types.h"
11+
#include "sd_protocol_types.h"
12+
13+
#ifdef __cplusplus
14+
extern "C" {
15+
#endif
16+
17+
typedef struct sd_host_driver_t sd_host_driver_t; /*!< Type of SD driver host context */
18+
typedef struct sd_slot_driver_t sd_slot_driver_t; /*!< Type of SD driver slot context */
19+
20+
/**
21+
* @brief SD driver host driver context
22+
*/
23+
struct sd_host_driver_t {
24+
/**
25+
* @brief Delete an SD Host controller
26+
*
27+
* @param[in] ctlr_ctx SD driver host controller context
28+
*
29+
* @return
30+
* - ESP_OK: On success
31+
* - ESP_ERR_INVALID_ARG: Invalid argument
32+
* - ESP_ERR_INVALID_STATE: Invalid state, there's still registered slot(s)
33+
*/
34+
esp_err_t (*del_ctlr)(sd_host_driver_t *ctlr_ctx);
35+
};
36+
37+
/**
38+
* @brief SD driver API definition
39+
*/
40+
struct sd_slot_driver_t {
41+
/**
42+
* @brief Configure SD Host slot
43+
*
44+
* @param[in] slot_drv SD Host slot driver handle
45+
* @param[in] config SD Host slot configuration
46+
*
47+
* @return
48+
* - ESP_OK: On success
49+
* - ESP_ERR_INVALID_ARG: Invalid argument
50+
*/
51+
esp_err_t (*configure)(sd_slot_driver_t *slot_drv, const sd_host_slot_cfg_t *config);
52+
53+
/**
54+
* @brief Do a transaction for the slot
55+
*
56+
* @param[in] slot_drv SD Host slot driver handle
57+
* @param[in] cmdinfo SD command info, see `sdmmc_command_t`
58+
*
59+
* @return
60+
* - ESP_OK: On success
61+
* - ESP_ERR_INVALID_ARG: Invalid argument
62+
*/
63+
esp_err_t (*do_transaction)(sd_slot_driver_t *slot_drv, sdmmc_command_t *cmdinfo);
64+
65+
/**
66+
* @brief Register SD event callbacks
67+
*
68+
* @note User can deregister a previously registered callback by calling this function and setting the to-be-deregistered callback member in
69+
* the `cbs` structure to NULL.
70+
*
71+
* @param[in] slot_drv SD Host slot driver handle
72+
* @param[in] cbs Group of callback functions
73+
* @param[in] user_data User data, which will be delivered to the callback functions directly
74+
*
75+
* @return
76+
* - ESP_OK: On success
77+
* - ESP_ERR_INVALID_ARG: Invalid arguments
78+
* - ESP_ERR_INVALID_STATE: Driver state is invalid, you shouldn't call this API at this moment
79+
*/
80+
esp_err_t (*register_cbs)(sd_slot_driver_t *slot_drv, const sd_host_evt_cbs_t *cbs, void *user_data);
81+
82+
/**
83+
* @brief Remove an SD Host slot
84+
*
85+
* @param[in] slot_drv SD Host slot driver handle
86+
*
87+
* @return
88+
* - ESP_OK: On success
89+
* - ESP_ERR_INVALID_STATE: Invalid state, slot is not available
90+
* - ESP_ERR_INVALID_ARG: Invalid argument
91+
*/
92+
esp_err_t (*remove_slot)(sd_slot_driver_t *slot_drv);
93+
94+
/**
95+
* @brief Set an SD Host slot clock always on
96+
*
97+
* @param[in] slot_drv SD Host slot driver handle
98+
* @param[in] always_on Always on or not
99+
*
100+
* @return
101+
* - ESP_OK: On success
102+
* - ESP_ERR_INVALID_ARG: Invalid argument
103+
*/
104+
esp_err_t (*set_cclk_always_on)(sd_slot_driver_t *slot_drv, bool always_on);
105+
106+
/**
107+
* @brief Enable an SD Host slot IO interrupt
108+
*
109+
* @param[in] slot_drv SD Host slot driver handle
110+
*
111+
* @return
112+
* - ESP_OK: On success
113+
* - ESP_ERR_INVALID_ARG: Invalid argument
114+
*/
115+
esp_err_t (*enable_io_int)(sd_slot_driver_t *slot_drv);
116+
117+
/**
118+
* @brief Wait for IO interrupt event
119+
*
120+
* @param[in] slot SD Host slot handle
121+
* @param[in] timeout_ticks Timeout ticks
122+
*
123+
* @return
124+
* - ESP_OK: On success
125+
* - ESP_ERR_INVALID_ARG: Invalid argument
126+
* - ESP_ERR_TIMEOUT: Timeout
127+
*/
128+
esp_err_t (*wait_io_int)(sd_slot_driver_t *slot_drv, TickType_t timeout_ticks);
129+
130+
/**
131+
* @brief Get slot info
132+
*
133+
* @param[in] slot SD Host slot handle
134+
* @param[out] info SD slot info
135+
*/
136+
esp_err_t (*get_info)(sd_slot_driver_t *slot_drv, sd_host_slot_info_t *info);
137+
};
138+
139+
#ifdef __cplusplus
140+
}
141+
#endif

0 commit comments

Comments
 (0)