PROTOCOLS

Cqhci

Defined in fuchsia.hardware.sdmmc/sdmmc.fidl

DisableCqhci

Disables the Command Queueing Engine. EnableCqhci must have previously been called. From this point onwards, regular requests can be submitted (until EnableCqhci is called again).

Request

<EMPTY>

Response

Name	Type
payload	Cqhci_DisableCqhci_Result

EnableCqhci

Enables the Command Queueing Engine. The CQHCI driver is expected to already have called InitializeCommandQueueing to handle interrupts. While CQHCI is enabled, it is the caller's responsibility to only submit regular requests (via Request) via DCMD, or after disabling CQHCI.

Request

<EMPTY>

Response

Name	Type
payload	Cqhci_EnableCqhci_Result

InitializeCommandQueueing

Initializes the CQHCI driver, providing it with all necessary resources.

This call is expected to be made once. The server should reject any additional calls until the peer end of virtual_interrupt_lifeline closes.

Interrupt Delegation

While the CQHCI driver is running, it takes over the physical IRQ object from its underlying driver, and directly handles any CQHCI-specific interrupts. Interrupts which it cannot service (e.g. SDHCI interrupts) are forwarded to the underlying driver via virtual_interrupt. The server should service interrupts exactly as it normally would. The CQHCI driver will wait for the virtual IRQ to be acked before acking the physical IRQ.

Arguments

• virtual_interrupt - A virtual interrupt to monitor instead of the physical IRQ. The CQHCI driver will use this to forward interrupts which it cannot directly service.
• virtual_interrupt_lifeline - A lifeline for the virtual interrupt. The CQHCI driver will destroy the peer end upon shutdown, which should be handled by the server as a signal to stop monitoring the virtual interrupt and return to monitoring the physical interrupt.

Returns

• cqhci_mmio and cqhci_mmio_offset - An MMIO for the CQHCI register block. MMIO size minus offset must be at least 512 bytes as per the CQHCI specification.
• sdhci_mmio and sdhci_mmio_offset - An MMIO for the SDHCI register block. MMIO size minus offset must be at least 512 bytes as per the SDHCI specification.
• bti - The BTI to use for pinning pages for DMA.
• interrupt - The physical interrupt to monitor.

Request

Name	Type
virtual_interrupt	handle<interrupt>
virtual_interrupt_lifeline	handle<eventpair>

Response

Name	Type
payload	Cqhci_InitializeCommandQueueing_Result

InBandInterrupt

Defined in fuchsia.hardware.sdmmc/sdmmc.fidl

Callback

Request

<EMPTY>

Response

<EMPTY>

Sdmmc

Defined in fuchsia.hardware.sdmmc/sdmmc.fidl

AckInBandInterrupt

Request

<EMPTY>

DisableCqhci

Disables the Command Queueing Engine. EnableCqhci must have previously been called. From this point onwards, regular requests can be submitted (until EnableCqhci is called again).

Request

<EMPTY>

Response

Name	Type
payload	Cqhci_DisableCqhci_Result

EnableCqhci

Enables the Command Queueing Engine. The CQHCI driver is expected to already have called InitializeCommandQueueing to handle interrupts. While CQHCI is enabled, it is the caller's responsibility to only submit regular requests (via Request) via DCMD, or after disabling CQHCI.

Request

<EMPTY>

Response

Name	Type
payload	Cqhci_EnableCqhci_Result

HostInfo

Get host info.

Request

<EMPTY>

Response

Name	Type
payload	Sdmmc_HostInfo_Result

HwReset

Issue a hw reset.

Request

<EMPTY>

Response

Name	Type
payload	Sdmmc_HwReset_Result

InitializeCommandQueueing

Initializes the CQHCI driver, providing it with all necessary resources.

This call is expected to be made once. The server should reject any additional calls until the peer end of virtual_interrupt_lifeline closes.

Interrupt Delegation

While the CQHCI driver is running, it takes over the physical IRQ object from its underlying driver, and directly handles any CQHCI-specific interrupts. Interrupts which it cannot service (e.g. SDHCI interrupts) are forwarded to the underlying driver via virtual_interrupt. The server should service interrupts exactly as it normally would. The CQHCI driver will wait for the virtual IRQ to be acked before acking the physical IRQ.

Arguments

• virtual_interrupt - A virtual interrupt to monitor instead of the physical IRQ. The CQHCI driver will use this to forward interrupts which it cannot directly service.
• virtual_interrupt_lifeline - A lifeline for the virtual interrupt. The CQHCI driver will destroy the peer end upon shutdown, which should be handled by the server as a signal to stop monitoring the virtual interrupt and return to monitoring the physical interrupt.

Returns

• cqhci_mmio and cqhci_mmio_offset - An MMIO for the CQHCI register block. MMIO size minus offset must be at least 512 bytes as per the CQHCI specification.
• sdhci_mmio and sdhci_mmio_offset - An MMIO for the SDHCI register block. MMIO size minus offset must be at least 512 bytes as per the SDHCI specification.
• bti - The BTI to use for pinning pages for DMA.
• interrupt - The physical interrupt to monitor.

Request

Name	Type
virtual_interrupt	handle<interrupt>
virtual_interrupt_lifeline	handle<eventpair>

Response

Name	Type
payload	Cqhci_InitializeCommandQueueing_Result

PerformTuning

Perform tuning.

Request

Name	Type
cmd_idx	uint32

Response

Name	Type
payload	Sdmmc_PerformTuning_Result

RegisterInBandInterrupt

Register the given callback to be called when an in-band interrupt is received from the card. Before calling the callback the protocol implementation will disable the in-band interrupt in the controller. In-band interrupts can be re-enabled by calling AckInBandInterrupt() once the previous interrupt has been handled by the client.

Request

Name	Type
interrupt_cb	client_end:InBandInterrupt

Response

Name	Type
payload	Sdmmc_RegisterInBandInterrupt_Result

RegisterVmo

In the methods below, vmo_id is used to uniquely identify a VMO that will be passed to Request in an SdmmcBufferRegion. VMO IDs are chosen by the caller, and may be any uint32 value. Registers a VMO and transfers ownership to the protocol implementation. vmo_rights is a bit field containing SdmmcVmoRight values, and determines the read/write permissions used by the implementation when pinning or mapping the VMO. The implementation may pin vmo during this call or any time it is used in a request, and may keep it pinned until the VMO is unregistered. client_id may be in [0, SDMMC_MAX_CLIENT_ID] and identifies the ID space for this VMO to be registered in (that is, two different VMOs may use the same ID if they are registered for different clients).

Request

Name	Type
vmo_id	uint32
client_id	uint8
vmo	handle<vmo>
offset	uint64
size	uint64
vmo_rights	SdmmcVmoRight

Response

Name	Type
payload	Sdmmc_RegisterVmo_Result

Request

Perform the requests in order, atomically (i.e., no intervening requests). Furthermore, calls are replied to in the order they are received. If an error occurs, abort any remaining requests. Else, return the response of the last request.

The protocol implementation chooses whether or not to use DMA depending on the properties of the request and the capabilities of the controller.

Clients are responsible for performing the following cache operations:

After read requests:

• Call zx_cache_flush with ZX_CACHE_FLUSH_DATA | ZX_CACHE_FLUSH_INVALIDATE on buffers that have been mapped by the client.
• Call zx_vmo_op_range with ZX_VMO_OP_CACHE_CLEAN_INVALIDATE on all other buffers.

Note that writing to any portion of a buffer before Request has returned can corrupt the received data.

Before write requests:

• Call zx_cache_flush with ZX_CACHE_FLUSH_DATA on buffers that have been mapped by the client.
• Call zx_vmo_op_range with ZX_VMO_OP_CACHE_CLEAN on all other buffers.

Request

Name	Type
reqs	vector<SdmmcReq>

Response

Name	Type
payload	Sdmmc_Request_Result

SetBusFreq

Set bus frequency, zero means disable the clock to the card.

Request

Name	Type
bus_freq	uint32

Response

Name	Type
payload	Sdmmc_SetBusFreq_Result

SetBusWidth

Set bus width.

Request

Name	Type
bus_width	SdmmcBusWidth

Response

Name	Type
payload	Sdmmc_SetBusWidth_Result

SetSignalVoltage

Set signal voltage.

Request

Name	Type
voltage	SdmmcVoltage

Response

Name	Type
payload	Sdmmc_SetSignalVoltage_Result

SetTiming

Set mmc timing.

Request

Name	Type
timing	SdmmcTiming

Response

Name	Type
payload	Sdmmc_SetTiming_Result

UnregisterVmo

The callee unmaps/unpins the VMO and returns ownership to the caller.

Request

Name	Type
vmo_id	uint32
client_id	uint8

Response

Name	Type
payload	Sdmmc_UnregisterVmo_Result

STRUCTS

Cqhci_DisableCqhci_Response

Defined in fuchsia.hardware.sdmmc/sdmmc.fidl

<EMPTY>

Cqhci_EnableCqhci_Response

Defined in fuchsia.hardware.sdmmc/sdmmc.fidl

<EMPTY>

Cqhci_InitializeCommandQueueing_Response resource

Defined in fuchsia.hardware.sdmmc/sdmmc.fidl

Field	Type	Description	Default
cqhci_mmio	handle<vmo>		No default
cqhci_mmio_offset	zx/Off		No default
sdhci_mmio	handle<vmo>		No default
sdhci_mmio_offset	zx/Off		No default
bti	handle<bti>		No default
interrupt	handle<interrupt>		No default

SdmmcBufferRegion resource

Defined in fuchsia.hardware.sdmmc/sdmmc.fidl

Field	Type	Description	Default
buffer	SdmmcBuffer		No default
offset	uint64	Offset into the VMO to start reading or writing. This is relative to the offset passed to RegisterVmo if type is VMO_ID.	No default
size	uint64	Number of bytes to read from or write to this buffer region.	No default

SdmmcHostInfo

Defined in fuchsia.hardware.sdmmc/sdmmc.fidl

Field	Type	Description	Default
caps	SdmmcHostCap	Controller capabilities	No default
max_transfer_size	uint32	Maximum data request size, in bytes. Set to MAX_TRANSFER_UNBOUNDED if no such maximum exists.	No default
max_buffer_regions	uint64	The number of buffer regions that may be used in a single request.	No default

SdmmcReq resource

Defined in fuchsia.hardware.sdmmc/sdmmc.fidl

Field	Type	Description	Default
cmd_idx	uint32		No default
cmd_flags	uint32		No default
arg	uint32		No default
blocksize	uint32		No default
suppress_error_messages	bool	If true, the SDMMC driver should reduce the log level of any error messages that this request produces. This will be set on requests for which errors are expected or not fatal.	No default
client_id	uint8	The client ID for this request. Only VMOs registered with this client may be present in buffers below.	No default
use_inline_crypto	bool	If true, the slot and dun will be used to encrypt/decrypt this request.	No default
slot	uint8	The key slot used to encrypt/decrypt the bytes in this request.	No default
dun	uint32	The data unit number used as an initialization vector for this encrypted IO request.	No default
buffers	vector<SdmmcBufferRegion>		No default

Sdmmc_HostInfo_Response

Defined in fuchsia.hardware.sdmmc/sdmmc.fidl

Field	Type	Description	Default
info	SdmmcHostInfo		No default

Sdmmc_HwReset_Response

Defined in fuchsia.hardware.sdmmc/sdmmc.fidl

<EMPTY>

Sdmmc_PerformTuning_Response

Defined in fuchsia.hardware.sdmmc/sdmmc.fidl

<EMPTY>

Sdmmc_RegisterInBandInterrupt_Response

Defined in fuchsia.hardware.sdmmc/sdmmc.fidl

<EMPTY>

Sdmmc_RegisterVmo_Response

Defined in fuchsia.hardware.sdmmc/sdmmc.fidl

<EMPTY>

Sdmmc_Request_Response

Defined in fuchsia.hardware.sdmmc/sdmmc.fidl

Field	Type	Description	Default
response	array<uint32, 4>		No default

Sdmmc_SetBusFreq_Response

Defined in fuchsia.hardware.sdmmc/sdmmc.fidl

<EMPTY>

Sdmmc_SetBusWidth_Response

Defined in fuchsia.hardware.sdmmc/sdmmc.fidl

<EMPTY>

Sdmmc_SetSignalVoltage_Response

Defined in fuchsia.hardware.sdmmc/sdmmc.fidl

<EMPTY>

Sdmmc_SetTiming_Response

Defined in fuchsia.hardware.sdmmc/sdmmc.fidl

<EMPTY>

Sdmmc_UnregisterVmo_Response resource

Defined in fuchsia.hardware.sdmmc/sdmmc.fidl

Field	Type	Description	Default
vmo	handle<vmo>		No default

ENUMS

SdmmcBusWidth strict

Type: uint8

Defined in fuchsia.hardware.sdmmc/sdmmc.fidl

Name	Value	Description
ONE	0
FOUR	1
EIGHT	2
MAX	3

SdmmcTiming strict

Type: uint8

Defined in fuchsia.hardware.sdmmc/sdmmc.fidl

Name	Value	Description
LEGACY	0
HS	1
HSDDR	2
HS200	3
HS400	4
SDR12	5
SDR25	6
SDR50	7
SDR104	8
DDR50	9
HS400_ENHANCED_STROBE	10
MAX	11

SdmmcVoltage strict

Type: uint8

Defined in fuchsia.hardware.sdmmc/sdmmc.fidl

Name	Value	Description
V330	0
V180	1
MAX	2

TABLES

SdmmcMetadata

Defined in fuchsia.hardware.sdmmc/metadata.fidl

Ordinal	Field	Type	Description
1	max_frequency	uint32	Maximum bus operating frequency. The SDMMC core driver will cap the bus frequency to this level. The default value is UINT32_MAX if no metadata is specified.
2	speed_capabilities	SdmmcHostPrefs	Host-specific speed capabilities. The default value is 0 (no flags) if no metadata is specified.
3	enable_cache	bool	If true, utilize the on-device volatile cache. The default value is true if no metadata is specified. Ignored if the attached device or inserted card does not have storage.
4	removable	bool	If true, this SDMMC controller corresponds to a removable card slot that may have an MMC/SD/SDIO card inserted or removed at any time. In this case, failure to probe during driver initialization is not considered fatal. The default value is false if no metadata is specified.
5	max_command_packing	uint32	Use command packing (batching) up to this many commands. If zero, command packing is disabled. The default value is 16 if no metadata is specified. Ignored if the attached device or inserted card does not support command packing.
6	use_fidl	bool	complete. If true, use the FIDL SDMMC protocol. If false, use the Banjo SDMMC protocol. The default value is true if no metadata is specified.
7	instance_identifier	string:64	instead. String identifier for the port instance. The default value is an empty string if no metadata is specified.
8	vccq_off_with_controller_off	bool	If true, the controller driver turns off VCC and VCCQ when in the OFF state. In this case the card must be re-initialized after leaving the OFF state. If not set (or if no metadata is provided), the default value is false.

UNIONS

Cqhci_DisableCqhci_Result strict

Defined in fuchsia.hardware.sdmmc/sdmmc.fidl

Ordinal	Variant	Type	Description
1	response	Cqhci_DisableCqhci_Response
2	err	zx/Status

Cqhci_EnableCqhci_Result strict

Defined in fuchsia.hardware.sdmmc/sdmmc.fidl

Ordinal	Variant	Type	Description
1	response	Cqhci_EnableCqhci_Response
2	err	zx/Status

Cqhci_InitializeCommandQueueing_Result strict resource

Defined in fuchsia.hardware.sdmmc/sdmmc.fidl

Ordinal	Variant	Type	Description
1	response	Cqhci_InitializeCommandQueueing_Response
2	err	zx/Status

SdmmcBuffer strict resource

Defined in fuchsia.hardware.sdmmc/sdmmc.fidl

Ordinal	Variant	Type	Description
1	vmo_id	uint32	The ID of a VMO that was previously registered.
2	vmo	handle<vmo>	An unregistered VMO of which the protocol implementation does not take ownership. The VMO is pinned upon entering Request and is unpinned before returning.

Sdmmc_HostInfo_Result strict

Defined in fuchsia.hardware.sdmmc/sdmmc.fidl

Ordinal	Variant	Type	Description
1	response	Sdmmc_HostInfo_Response
2	err	zx/Status

Sdmmc_HwReset_Result strict

Defined in fuchsia.hardware.sdmmc/sdmmc.fidl

Ordinal	Variant	Type	Description
1	response	Sdmmc_HwReset_Response
2	err	zx/Status

Sdmmc_PerformTuning_Result strict

Defined in fuchsia.hardware.sdmmc/sdmmc.fidl

Ordinal	Variant	Type	Description
1	response	Sdmmc_PerformTuning_Response
2	err	zx/Status

Sdmmc_RegisterInBandInterrupt_Result strict

Defined in fuchsia.hardware.sdmmc/sdmmc.fidl

Ordinal	Variant	Type	Description
1	response	Sdmmc_RegisterInBandInterrupt_Response
2	err	zx/Status

Sdmmc_RegisterVmo_Result strict

Defined in fuchsia.hardware.sdmmc/sdmmc.fidl

Ordinal	Variant	Type	Description
1	response	Sdmmc_RegisterVmo_Response
2	err	zx/Status

Sdmmc_Request_Result strict

Defined in fuchsia.hardware.sdmmc/sdmmc.fidl

Ordinal	Variant	Type	Description
1	response	Sdmmc_Request_Response
2	err	zx/Status

Sdmmc_SetBusFreq_Result strict

Defined in fuchsia.hardware.sdmmc/sdmmc.fidl

Ordinal	Variant	Type	Description
1	response	Sdmmc_SetBusFreq_Response
2	err	zx/Status

Sdmmc_SetBusWidth_Result strict

Defined in fuchsia.hardware.sdmmc/sdmmc.fidl

Ordinal	Variant	Type	Description
1	response	Sdmmc_SetBusWidth_Response
2	err	zx/Status

Sdmmc_SetSignalVoltage_Result strict

Defined in fuchsia.hardware.sdmmc/sdmmc.fidl

Ordinal	Variant	Type	Description
1	response	Sdmmc_SetSignalVoltage_Response
2	err	zx/Status

Sdmmc_SetTiming_Result strict

Defined in fuchsia.hardware.sdmmc/sdmmc.fidl

Ordinal	Variant	Type	Description
1	response	Sdmmc_SetTiming_Response
2	err	zx/Status

Sdmmc_UnregisterVmo_Result strict resource

Defined in fuchsia.hardware.sdmmc/sdmmc.fidl

Ordinal	Variant	Type	Description
1	response	Sdmmc_UnregisterVmo_Response
2	err	zx/Status

BITS

SdmmcHostCap strict

Type: uint64

Defined in fuchsia.hardware.sdmmc/sdmmc.fidl

Name	Value	Description
BUS_WIDTH_8	1
DMA	2
VOLTAGE_330	4
AUTO_CMD12	8
SDR104	16
SDR50	32
DDR50	64
NO_TUNING_SDR50	128	The host does not require tuning for SDR50.
HS400_ENHANCED_STROBE	256
COMMAND_QUEUEING	512

SdmmcHostPrefs strict

Type: uint64

Defined in fuchsia.hardware.sdmmc/sdmmc.fidl

Name	Value	Description
DISABLE_HS400	1
DISABLE_HS200	2
DISABLE_HSDDR	4

SdmmcVmoRight strict

Type: uint32

Defined in fuchsia.hardware.sdmmc/sdmmc.fidl

Name	Value	Description
READ	1
WRITE	2

CONSTANTS

Name	Value	Type	Description
MAX_NAME_LENGTH	64	uint8
MAX_TRANSFER_UNBOUNDED	4294967295	uint32	The maximum value for a transfer size, identifying that there effectively exists no maximum for a single operation.
SDMMC_MAX_CLIENT_ID	7	uint8	The max value of client_id fields below. There is no known need for more than eight clients at the moment, however if that changes later this value will be increased.
SDMMC_PAGES_COUNT	512	uint64	number of pages per request - 2M per request matches DMA_DESC_COUNT in dev/block/sdhci (PAGE_SIZE / sizeof(zx_paddr_t))

SERVICES

SdmmcService

Defined in fuchsia.hardware.sdmmc/sdmmc.fidl

Name	Type	Transport
sdmmc	fuchsia.hardware.sdmmc/Sdmmc	Driver
inline_crypto	fuchsia.hardware.inlineencryption/DriverDevice	Driver