Altera HWLIB  16.0
The Altera HW Manager API Reference Manual
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Groups
SD/MMC Controller Internal DMA

Description

The internal DMA controller has a control and status register interface and a single transmit or receive engine, which transfers data from system memory to the card and vice versa. The controller uses a descriptor mechanism to efficiently move data from source to destination with minimal host processor intervention. You can set up the controller to interrupt the host processor in situations such as transmit and receive data transfer completion from the card, as well as other normal or error conditions. The DMA controller and the host driver communicate through a single data structure.

The internal DMA controller transfers the data received from the card to the data buffer in the system memory, and transfers transmit data from the data buffer in the memory to the controller's FIFO buffer. Descriptors that reside in the system memory act as pointers to these buffers.

A data buffer resides in the physical memory space of the system memory and consists of complete or partial data. The buffer status is maintained in the descriptor. Data chaining refers to data that spans multiple data buffers. However, a single descriptor cannot span multiple data buffers.

A single descriptor is used for both reception and transmission. The base address of the list is written into the descriptor list base address register. A descriptor list is forward linked. The last descriptor can point back to the first entry to create a ring structure. The descriptor list resides in the physical memory address space of the host. Each descriptor can point to a maximum of two data buffers.

Data Structures

struct  ALT_SDMMC_DMA_BUF_DESC_s
 
union  ALT_SDMMC_DMA_BUF_DESC_s::DES0
 
union  ALT_SDMMC_DMA_BUF_DESC_s::DES1
 
union  ALT_SDMMC_DMA_BUF_DESC_s::DES2
 
union  ALT_SDMMC_DMA_BUF_DESC_s::DES3
 
struct  ALT_SDMMC_DMA_BUF_DESC_s::DES0.fld
 
struct  ALT_SDMMC_DMA_BUF_DESC_s::DES1.fld
 
struct  ALT_SDMMC_DMA_BUF_DESC_s::DES2.fld
 
struct  ALT_SDMMC_DMA_BUF_DESC_s::DES3.fld
 

Typedefs

typedef enum
ALT_SDMMC_DMA_INT_STATUS_e 
ALT_SDMMC_DMA_INT_STATUS_t
 
typedef struct
ALT_SDMMC_DMA_BUF_DESC_s 
ALT_SDMMC_DMA_BUF_DESC_t
 
typedef enum ALT_SDMMC_DMA_PBL_e ALT_SDMMC_DMA_PBL_t
 

ENUMS

enum  ALT_SDMMC_DMA_INT_STATUS_e {
  ALT_SDMMC_DMA_INT_STATUS_TI = (1UL << 0), ALT_SDMMC_DMA_INT_STATUS_RI = (1UL << 1), ALT_SDMMC_DMA_INT_STATUS_FBE = (1UL << 2), ALT_SDMMC_DMA_INT_STATUS_DU = (1UL << 4),
  ALT_SDMMC_DMA_INT_STATUS_CES = (1UL << 5), ALT_SDMMC_DMA_INT_STATUS_NI = (1UL << 8), ALT_SDMMC_DMA_INT_STATUS_AI = (1UL << 9)
}
 
enum  ALT_SDMMC_DMA_PBL_e {
  ALT_SDMMC_DMA_PBL_1 = 0x0, ALT_SDMMC_DMA_PBL_4 = 0x1, ALT_SDMMC_DMA_PBL_8 = 0x2, ALT_SDMMC_DMA_PBL_16 = 0x3,
  ALT_SDMMC_DMA_PBL_32 = 0x4, ALT_SDMMC_DMA_PBL_64 = 0x5, ALT_SDMMC_DMA_PBL_128 = 0x6, ALT_SDMMC_DMA_PBL_256 = 0x7
}
 

Functions

ALT_STATUS_CODE alt_sdmmc_dma_reset (void)
 
ALT_STATUS_CODE alt_sdmmc_dma_disable (void)
 
ALT_STATUS_CODE alt_sdmmc_is_dma_enabled (void)
 
ALT_STATUS_CODE alt_sdmmc_dma_enable (void)
 
ALT_STATUS_CODE alt_sdmmc_dma_start (ALT_SDMMC_DMA_BUF_DESC_t *buf_desc_list, const uint32_t desc_skip_len, const ALT_SDMMC_DMA_PBL_t burst_len, const bool use_fixed_burst)
 
ALT_STATUS_CODE alt_sdmmc_poll_demand_set (const uint32_t value)
 
uint32_t alt_sdmmc_dma_int_status_get (void)
 
uint32_t alt_sdmmc_dma_int_mask_get (void)
 
ALT_STATUS_CODE alt_sdmmc_dma_int_clear (const uint32_t mask)
 
ALT_STATUS_CODE alt_sdmmc_dma_int_disable (const uint32_t mask)
 
ALT_STATUS_CODE alt_sdmmc_dma_int_enable (const uint32_t mask)
 

Data Structure Documentation

struct ALT_SDMMC_DMA_BUF_DESC_s

This type defines the SD/MMC controller internal DMA controller descriptor structure.

The internal DMA controller uses these types of descriptor structures:

  • Dual-buffer structure - The distance between two descriptors is determined by the skip length value written to the descriptor skip length field of the bus mode register.
  • Chain structure - Each descriptor points to a unique buffer, and to the next descriptor in a linked list.
Data Fields
union DES0 des0 The DES0 field in the internal DMA controller descriptor contains control and status information.
union DES1 des1 The DES1 descriptor field contains the buffer size.
union DES2 des2 The DES2 descriptor field contains the address pointer to the data buffer.
union DES3 des3 The DES3 descriptor field contains the address pointer to the next descriptor if the present descriptor is not the last descriptor in a chained descriptor structure or the second buffer address for a dual-buffer structure.
union ALT_SDMMC_DMA_BUF_DESC_s::DES0

The DES0 field in the internal DMA controller descriptor contains control and status information.

Data Fields
struct DES0 fld Union data member access to DES0 fields.
uint32_t raw The DES0 raw register aggregate value.
union ALT_SDMMC_DMA_BUF_DESC_s::DES1

The DES1 descriptor field contains the buffer size.

Data Fields
struct DES1 fld Union data member access to DES1 fields.
uint32_t raw The DES1 raw register aggregate value.
union ALT_SDMMC_DMA_BUF_DESC_s::DES2

The DES2 descriptor field contains the address pointer to the data buffer.

Data Fields
struct DES2 fld Union data member access to DES2 fields.
uint32_t raw The DES2 raw register aggregate value.
union ALT_SDMMC_DMA_BUF_DESC_s::DES3

The DES3 descriptor field contains the address pointer to the next descriptor if the present descriptor is not the last descriptor in a chained descriptor structure or the second buffer address for a dual-buffer structure.

Data Fields
struct DES3 fld Union data member access to DES3 fields.
uint32_t raw The DES3 raw register aggregate value.
struct ALT_SDMMC_DMA_BUF_DESC_s::DES0.fld

Structure for DES0 register data fields.

Data Fields
uint32_t __pad0__: 1 Reserved
uint32_t dic: 1 Disable Interrupt on Completion (DIC). When set to 1, this bit prevents the setting of the TI/RI bit of the internal DMA controller status register (idsts) for the data that ends in the buffer pointed to by this descriptor.
uint32_t ld: 1 Last Descriptor (LD). When set to 1, this bit indicates that the buffers pointed to by this descriptor are the last buffers of the data.
uint32_t fs: 1 First Descriptor (FS). When set to 1, this bit indicates that this descriptor contains the first buffer of the data. If the size of the first buffer is 0, next descriptor contains the beginning of the data.
uint32_t ch: 1 Second Address Chained (CH). When set to 1, this bit indicates that the second address in the descriptor is the next descriptor address rather than the second buffer address. When this bit is set to 1, BS2 (DES1[25:13]) must be all zeros.
uint32_t er: 1 End of Ring (ER). When set to 1, this bit indicates that the descriptor list reached its final descriptor. The internal DMA controller returns to the base address of the list, creating a descriptor ring. ER is meaningful for only a dual-buffer descriptor structure.
uint32_t ces: 1 Card Error Summary (CES). The CES bit indicates whether a transaction error occurred. The CES bit is the logical OR of the following error bits in the rintsts register.

  • End-bit error (ebe)
  • Response timeout (rto)
  • Response CRC (rcrc)
  • Start-bit error (sbe)
  • Data read timeout (drto)
  • Data CRC for receive (dcrc)
  • Response error (re)
uint32_t __pad1__: 24 Reserved
uint32_t own: 1 When set to 1, this bit indicates that the descriptor is owned by the internal DMA controller. When this bit is set to 0, it indicates that the descriptor is owned by the host. The internal DMA controller resets this bit to 0 when it completes the data transfer.
struct ALT_SDMMC_DMA_BUF_DESC_s::DES1.fld

Structure for DES1 register data fields.

Data Fields
uint32_t bs1: 13 Buffer 1 Size (BS1). Indicates the data buffer byte size, which must be a multiple of four bytes. When the buffer size is not a multiple of four, the resulting behavior is undefined. If this field is 0, the DMA ignores the buffer and proceeds to the next descriptor for a chain structure, or to the next buffer for a dual-buffer structure. If there is only one descriptor and only one buffer to be programmed, you need to use only buffer 1 and not buffer 2.
uint32_t bs2: 13 Buffer 2 Size (BS2). These bits indicate the second data buffer byte size. The buffer size must be a multiple of four. When the buffer size is not a multiple of four, the resulting behavior is undefined. This field is not valid if DES0[4] is set to 1.
uint32_t __pad0__: 6 Reserved
struct ALT_SDMMC_DMA_BUF_DESC_s::DES2.fld

Structure for DES2 register data fields.

Data Fields
uint32_t bap1: 32 Buffer Address Pointer 1 (BAP1). These bits indicate the physical address of the first data buffer. The internal DMA controller ignores DES2 [1:0], because it only performs 32-bit-aligned accesses.
struct ALT_SDMMC_DMA_BUF_DESC_s::DES3.fld

Structure for DES3 register data fields.

Data Fields
uint32_t bap2_or_next: 32 Buffer Address Pointer 2 (BAP2) or Next Descriptor Address. These bits indicate the physical address of the second buffer when the dual-buffer structure is used. If the Second Address Chained (DES0[4]) bit is set to 1, this address contains the pointer to the physical memory where the next descriptor is present. If this is not the last descriptor, the next descriptor address pointer must be aligned to 32 bits. Bits 1 and 0 are ignored.

Typedef Documentation

This type definition enumerates the interrupt status conditions from the SD/MMC internal DMA controller that contribute to the ALT_INT_INTERRUPT_SDMMC_IRQ signal state.

NOTE: Both the general purpose interrupt status conditions for the SD/MMC controller (ALT_SDMMC_INT_STATUS_t) and the interrupt status conditions for the internal DMA controller (ALT_SDMMC_DMA_INT_STATUS_t) contribute to the overall ALT_INT_INTERRUPT_SDMMC_IRQ signal state

This type defines the SD/MMC controller internal DMA controller descriptor structure.

The internal DMA controller uses these types of descriptor structures:

  • Dual-buffer structure - The distance between two descriptors is determined by the skip length value written to the descriptor skip length field of the bus mode register.
  • Chain structure - Each descriptor points to a unique buffer, and to the next descriptor in a linked list.

This type enumerates the host bus programmable burst length options available to the SD/MMC internal DMA controller.

Enumeration Type Documentation

This type definition enumerates the interrupt status conditions from the SD/MMC internal DMA controller that contribute to the ALT_INT_INTERRUPT_SDMMC_IRQ signal state.

NOTE: Both the general purpose interrupt status conditions for the SD/MMC controller (ALT_SDMMC_INT_STATUS_t) and the interrupt status conditions for the internal DMA controller (ALT_SDMMC_DMA_INT_STATUS_t) contribute to the overall ALT_INT_INTERRUPT_SDMMC_IRQ signal state

Enumerator:
ALT_SDMMC_DMA_INT_STATUS_TI 

Transmit Interrupt Enable

ALT_SDMMC_DMA_INT_STATUS_RI 

Receive Interrupt Enable

ALT_SDMMC_DMA_INT_STATUS_FBE 

Fatal Bus Error

ALT_SDMMC_DMA_INT_STATUS_DU 

Descriptor Unavailable Interrupt

ALT_SDMMC_DMA_INT_STATUS_CES 

Card Error Summary Interrupt Enable

ALT_SDMMC_DMA_INT_STATUS_NI 

Normal Interrupt Summary Enable

ALT_SDMMC_DMA_INT_STATUS_AI 

Abnormal Interrupt Summary Enable.

This type enumerates the host bus programmable burst length options available to the SD/MMC internal DMA controller.

Enumerator:
ALT_SDMMC_DMA_PBL_1 

1 transfer unit

ALT_SDMMC_DMA_PBL_4 

4 transfer units

ALT_SDMMC_DMA_PBL_8 

8 transfer units

ALT_SDMMC_DMA_PBL_16 

16 transfer units

ALT_SDMMC_DMA_PBL_32 

32 transfer units

ALT_SDMMC_DMA_PBL_64 

64 transfer units

ALT_SDMMC_DMA_PBL_128 

128 transfer units

ALT_SDMMC_DMA_PBL_256 

256 transfer units

Function Documentation

ALT_STATUS_CODE alt_sdmmc_dma_reset ( void  )

Resets the SD/MMC internal DMA controller.

This function resets the SD/MMC controller DMA interface control logic and all internal registers of the DMA controller.

Return values
ALT_E_SUCCESSThe operation was successful.
ALT_E_ERRORThe operation failed.
ALT_STATUS_CODE alt_sdmmc_dma_disable ( void  )

Disables use of the SD/MMC controller internal DMA for data transfers.

This function disables use of the SD/MMC controller internal DMA for data transfers and requires the host to conduct data transfers through the slave interface.

Return values
ALT_E_SUCCESSThe operation was successful.
ALT_E_ERRORThe operation failed.
ALT_STATUS_CODE alt_sdmmc_is_dma_enabled ( void  )

Queries SD/MMC controller internal DMA enable.

This function returns the SD/MMC controller internal DMA enable status.

Return values
ALT_E_TRUEDMA is enabled.
ALT_E_FALSEDMA is disabled.
ALT_STATUS_CODE alt_sdmmc_dma_enable ( void  )

Enables use of the SD/MMC controller internal DMA for data transfers.

This function enables use of the SD/MMC controller internal DMA for data transfers, otherwise the host must conduct data transfers through the slave interface.

Return values
ALT_E_SUCCESSThe operation was successful.
ALT_E_ERRORThe operation failed.
ALT_STATUS_CODE alt_sdmmc_dma_start ( ALT_SDMMC_DMA_BUF_DESC_t buf_desc_list,
const uint32_t  desc_skip_len,
const ALT_SDMMC_DMA_PBL_t  burst_len,
const bool  use_fixed_burst 
)

Starts the SD/MMC internal DMA transfer with the specified descriptor an bus mode transfer configuration.

Parameters
buf_desc_listPointer to the beginning of a SD/MMC internal DMA buffer descriptor list.
desc_skip_lenDescriptor Skip Length. Specifies the number of half/full/double words (depending on 16/32/64-bit bus) to skip between two unchained descriptors. Only applicable for dual buffer structures otherwise ignored.
burst_lenProgrammable Burst Length. Specifies the maximum number of beats to be performed in one DMA transaction. The DMA will always attempt to burst as specified each time it starts a burst transfer on the host bus.
use_fixed_burstFixed Burst. Controls whether the AHB Master interface performs fixed burst transfers or not. When set, the AHB will use only SINGLE, INCR4, INCR8 or INCR16 during start of normal burst transfers. When reset, the AHB will use SINGLE and INCR burst transfer operations.
Return values
ALT_E_SUCCESSSuccessful status.
ALT_E_ERRORDetails about error status code
ALT_STATUS_CODE alt_sdmmc_poll_demand_set ( const uint32_t  value)

Sets any value for the IDMAC FSM to resume normal descriptor fetch operation.

Parameters
valueThis value will write for the IDMAC FSM.
Return values
ALT_E_SUCCESSThe operation was successful.
ALT_E_ERRORThe operation failed.
uint32_t alt_sdmmc_dma_int_status_get ( void  )

Returns the SD/MMC internal DMA controller status register value which reflects current DMA interrupt status conditions.

Returns
The value of the SD/MMC internal DMA status register which reflects the current SD/MMC internal DMA interrupt status conditions.
uint32_t alt_sdmmc_dma_int_mask_get ( void  )

Returns the SD/MMC internal DMA controller interrupt mask value which reflects the enabled internal DMA controller interrupt status conditions.

Returns
The aggregate value of the enabled SD/MMC internal DMA controller interrupt status conditions. A set (1) bit in the corresponding ALT_SDMMC_DMA_INT_STATUS_t position indicates an interrupt that is enabled. A clear (0) bit the corresponding ALT_SDMMC_DMA_INT_STATUS_t position indicates an interrupt that is masked.
ALT_STATUS_CODE alt_sdmmc_dma_int_clear ( const uint32_t  mask)

Clears the specified SD/MMC internal DMA controller interrupt status conditions identified in the mask.

This function clears one or more of the status conditions as contributors to the ALT_INT_INTERRUPT_SDMMC_IRQ interrupt signal state.

Parameters
maskSpecifies the SD/MMC internal DMA controller status conditions to clear. mask is a mask of logically OR'ed ALT_SDMMC_DMA_INT_STATUS_t values that designate the status conditions to clear.
Return values
ALT_E_SUCCESSIndicates successful completion.
ALT_E_ERRORIndicates an error occurred.
ALT_STATUS_CODE alt_sdmmc_dma_int_disable ( const uint32_t  mask)

Disable the specified SD/MMC internal DMA controller interrupt status conditions identified in the mask.

This function disables one or more of the status conditions as contributors to the ALT_INT_INTERRUPT_SDMMC_IRQ interrupt signal state.

NOTE: A cleared bit for any status condition in the mask value does not have the effect of enabling it as a contributor to the ALT_INT_INTERRUPT_SDMMC_IRQ interrupt signal state. The function alt_sdmmc_dma_int_enable() is used to enable status source conditions.

Parameters
maskSpecifies the status conditions to disable as interrupt source contributors. mask is a mask of logically OR'ed ALT_SDMMC_DMA_INT_STATUS_t values that designate the status conditions to disable.
Return values
ALT_E_SUCCESSIndicates successful completion.
ALT_E_ERRORIndicates an error occurred.
ALT_STATUS_CODE alt_sdmmc_dma_int_enable ( const uint32_t  mask)

Enable the specified SD/MMC internal DMA controller interrupt status conditions identified in the mask.

This function enables one or more of the status conditions as contributors to the ALT_INT_INTERRUPT_SDMMC_IRQ interrupt signal state.

NOTE: A cleared bit for any status condition in the mask value does not have the effect of disabling it as a contributor to the ALT_INT_INTERRUPT_SDMMC_IRQ interrupt signal state. The function alt_sdmmc_dma_int_disable() is used to disable status source conditions.

Parameters
maskSpecifies the status conditions to enable as interrupt source contributors. mask is a mask of logically OR'ed ALT_SDMMC_DMA_INT_STATUS_t values that designate the status conditions to enable.
Return values
ALT_E_SUCCESSIndicates successful completion.
ALT_E_ERRORIndicates an error occurred.