Azure Sphere MT3620 M4 API Reference Manual
 All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Functions
Function
SPIM

This section provides Fixed APIs(defined as Common Interface) to fully control the MediaTek SPIM HW. More...

Overview

This section provides Fixed APIs(defined as Common Interface) to fully control the MediaTek SPIM HW.

Functions

int mtk_mhal_spim_dump_reg (struct mtk_spi_controller *ctlr)
 This function is used to dump spi register for debugging. More...
 
int mtk_mhal_spim_clear_irq_status (struct mtk_spi_controller *ctlr)
 This function is used to clear SPIM HW status. More...
 
int mtk_mhal_spim_fifo_handle_rx (struct mtk_spi_controller *ctlr, struct mtk_spi_transfer *xfer)
 This function is used to read FIFO data from SPIM HW. More...
 
int mtk_mhal_spim_prepare_hw (struct mtk_spi_controller *ctlr, struct mtk_spi_config *config)
 This function is used to initialize SPIM HW based on *config settings. More...
 
int mtk_mhal_spim_prepare_transfer (struct mtk_spi_controller *ctlr, struct mtk_spi_transfer *xfer)
 This function is used to initialize SPIM based on mtk_spi_transfer setting. More...
 
int mtk_mhal_spim_fifo_transfer_one (struct mtk_spi_controller *ctlr, struct mtk_spi_transfer *xfer)
 This function is used to perform a single mtk_spi_transfer by FIFO mode. More...
 
int mtk_mhal_spim_dma_done_callback_register (struct mtk_spi_controller *ctlr, spi_dma_done_callback callback, void *user_data)
 This function is used to register user's DMA callback to M-HAL. More...
 
int mtk_mhal_spim_dma_transfer_one (struct mtk_spi_controller *ctlr, struct mtk_spi_transfer *xfer)
 This function is used to perform a single mtk_spi_transfer by DMA mode. More...
 
int mtk_mhal_spim_allocate_dma_chan (struct mtk_spi_controller *ctlr)
 This function is used to allocate SPIM DMA channel. More...
 
int mtk_mhal_spim_release_dma_chan (struct mtk_spi_controller *ctlr)
 This function is used to release SPIM DMA channel. More...
 
int mtk_mhal_spim_enable_clk (struct mtk_spi_controller *ctlr)
 This function is used to enable SPIM clock before transfer. More...
 
int mtk_mhal_spim_disable_clk (struct mtk_spi_controller *ctlr)
 This function is used to disable SPIM clock before transfer. More...
 

Function Documentation

int mtk_mhal_spim_dump_reg ( struct mtk_spi_controller *  ctlr)

This function is used to dump spi register for debugging.

Usage:Used for OS-HAL to dump SPIM register.

Parameters
[in]ctlr: SPI controller used with the device.
Returns
Return "0" if dump register successfully.
Return -SPIM_EPTR if ctlr is NULL.
int mtk_mhal_spim_clear_irq_status ( struct mtk_spi_controller *  ctlr)

This function is used to clear SPIM HW status.

Usage: It's called in irq function to clear SPIM HW irq status.

Parameters
[in]ctlr: SPI controller used with the device.
Returns
Return "0" if clear irq status successfully.
Return -SPIM_EPTR if ctlr is NULL.
int mtk_mhal_spim_fifo_handle_rx ( struct mtk_spi_controller *  ctlr,
struct mtk_spi_transfer *  xfer 
)

This function is used to read FIFO data from SPIM HW.

Usage: it must be called in irq function with FIFO mode. while using FIFO mode, read rx FIFO register and copy data to xfer->rx_buffer.

Parameters
[in]ctlr: SPI controller used with the device.
[in]xfer: the read/write buffer pair user should transfer.
Example
spim_irq_handler()
{
mtk_mhal_spim_clear_irq_status(ctlr);
if (use FIFO mode)
mtk_mhal_spim_fifo_handle_rx(ctlr, xfer);
}
Returns
Return "0" if read FIFO data successfully.
Return -SPIM_EPTR if ctlr or xfer is NULL.
int mtk_mhal_spim_prepare_hw ( struct mtk_spi_controller *  ctlr,
struct mtk_spi_config *  config 
)

This function is used to initialize SPIM HW based on *config settings.

Usage: Use *config setting to init HW. It must be called before transferring.

Parameters
[in]ctlr: SPI controller used with the device.
[in]config: HW setting
Example
struct mtk_spi_config spi_default_config = {
.cpol = SPI_CPOL_0,
.cpha = SPI_CPHA_0,
.rx_mlsb = SPI_MSB,
.tx_mlsb = SPI_MSB,
.slave_sel = SPI_SELECT_DEVICE_0,
.cs_polar = SPI_CS_POLARITY_LOW,
};
mtk_mhal_spim_prepare_hw(ctlr, &spi_default_config);
Returns
Return "0" if configure SPIM HW successfully.
Return -SPIM_EPTR if ctlr or config is NULL.
int mtk_mhal_spim_prepare_transfer ( struct mtk_spi_controller *  ctlr,
struct mtk_spi_transfer *  xfer 
)

This function is used to initialize SPIM based on mtk_spi_transfer setting.

Usage: Initialize HW according to *xfer arg(such as speed). It must be called before transferring.

Parameters
[in]ctlr: SPI controller used with the device.
[in]xfer: The read/write buffer pair user should transfer.
Example
struct mtk_spi_transfer xfer;
memset(&xfer, 0, sizeof(struct mtk_spi_transfer));
xfer.use_dma = 0;
xfer.tx_buf = tx_buf;
xfer.rx_buf = rx_buf;
xfer.len = len;
mtk_mhal_spim_prepare_transfer(ctlr, &xfer);
Returns
Return "0" if configure SPIM HW successfully.
Return -SPIM_EPTR if ctlr or xfer is NULL.
int mtk_mhal_spim_fifo_transfer_one ( struct mtk_spi_controller *  ctlr,
struct mtk_spi_transfer *  xfer 
)

This function is used to perform a single mtk_spi_transfer by FIFO mode.

Usage: this function triggers SPIM HW to perform a single mtk_spi_transfer.
while the function returns, the transfer may not be completed.
So OS-HAL should wait for SPIM HW irq to be finished (maybe use semaphore).

Parameters
[in]ctlr: SPI controller used with the device.
[in]xfer: The read/write buffer pair user should transfer.
Returns
Return "0" if the transfer is in progress.
Return -SPIM_EPTR if ctlr or xfer is NULL.
Return -SPIM_ELENGTH if xfer opcode_len/len is not supported. see Note in Supported Features for details.
int mtk_mhal_spim_dma_done_callback_register ( struct mtk_spi_controller *  ctlr,
spi_dma_done_callback  callback,
void *  user_data 
)

This function is used to register user's DMA callback to M-HAL.

It's used for DMA mode transaction. In DMA mode, mtk_mhal_spim_dma_transfer_one() returns a value once the SPI hardware register is assigned and the DMA is configured.
During this process the transaction is usually not completed, once it is completed, a DMA interrupt is triggered and a related user callback is called in the DMA interrupt service routine.

Parameters
[in]ctlr: SPI controller used with the device.
[in]callback: The callback function given by OS-HAL which will be called at SPI master's DMA interrupt service routine.
[in]user_data: A parameter given by OS-HAL and will be passed to user when the callback function is called.
Returns
Return "0" if callback register successfully.
Return -SPIM_EPTR if ctlr or callback or user_data is NULL.
int mtk_mhal_spim_dma_transfer_one ( struct mtk_spi_controller *  ctlr,
struct mtk_spi_transfer *  xfer 
)

This function is used to perform a single mtk_spi_transfer by DMA mode.

Usage: This function triggers SPIM HW to perform a single mtk_spi_transfer. When the function returns, the transfer may not be completed. So OS-HAL should wait for SPIM HW irq to be finished (maybe use semaphore).

Parameters
[in]ctlr: SPI controller used with the device.
[in]xfer: The read/write buffer pair user should transfer.
Returns
Return "0" if the transfer is in progress.
Return -SPIM_EPTR if ctlr or xfer is NULL.
Return -SPIM_ELENGTH if xfer opcode_len/len is not supported. Return -SPIM_ENOMEM if allocate temp buffer fail.
int mtk_mhal_spim_allocate_dma_chan ( struct mtk_spi_controller *  ctlr)

This function is used to allocate SPIM DMA channel.

Usage: User should call it to allocate DMA channel after call #mtk_mhal_spim_alloc_controller and set dma_chan in initial flow.

Parameters
[in]ctlr: SPI controller used with the device.
Returns
Return 0 if users allocate DMA channel successfully.
Return -SPIM_EPTR if ctlr or xfer is NULL.
Return -SPIM_EBUSY if dma chan is busy.
int mtk_mhal_spim_release_dma_chan ( struct mtk_spi_controller *  ctlr)

This function is used to release SPIM DMA channel.

Usage: user should call it to release DMA channel before call #mtk_mhal_spim_release_controller in de-initial flow.

Parameters
[in]ctlr: SPI controller used with the device.
Returns
Return 0 if users allocate DMA channel successfully.
Return -SPIM_EPTR if ctlr or xfer is NULL.
Return -SPIM_EBUSY if dma chan is already released.
int mtk_mhal_spim_enable_clk ( struct mtk_spi_controller *  ctlr)

This function is used to enable SPIM clock before transfer.

Usage: It must be called to enable clock before transferring, otherwise the access to SPIM register will fail .

Parameters
[in]ctlr: SPI controller used with the device.
Returns
Return "0" if enable SPIM clock successfully.
Return -SPIM_EPTR if ctlr is NULL.
int mtk_mhal_spim_disable_clk ( struct mtk_spi_controller *  ctlr)

This function is used to disable SPIM clock before transfer.

Usage: It needs to be called after transfer to disable clock.

Parameters
[in]ctlr: SPIM controller used with the device.
Returns
Return "0" if disable SPIM clock successfully.
Return -SPIM_EPTR if ctlr is NULL.