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

Overview

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

Functions
int	mtk_mhal_spis_dump_reg (struct mtk_spis_controller *ctlr)
	This function is used to dump spis register for debugging. More...

int	mtk_mhal_spis_get_irq_status (struct mtk_spis_controller *ctlr)
	This function is used to get SPIS HW status. More...

int	mtk_mhal_spis_clear_irq_status (struct mtk_spis_controller *ctlr)
	This function is used to clear SPIS HW status. More...

int	mtk_mhal_spis_handle_h2dmb (struct mtk_spis_controller *ctlr)
	This function is used to handle H2DMB which is sent from spi master. More...

int	mtk_mhal_spis_send_d2hmb (struct mtk_spis_controller *ctlr)
	This function is used to update spis transmisson status. More...

int	mtk_mhal_spis_handle_rx (struct mtk_spis_controller *ctlr)
	This function is used to update spis RX transmisson status to d2hmb_state(defined in mtk_spis_private) and read FIFO data from SPIS HW. More...

int	mtk_mhal_spis_handle_tx (struct mtk_spis_controller *ctlr)
	This function is used to update spis TX transmisson status to d2hmb_state(defined in mtk_spis_private) More...

int	mtk_mhal_spis_setup_hw (struct mtk_spis_controller ctlr, struct mtk_spis_config config)
	This function is used to initialize SPIS HW based on *config settings. More...

int	mtk_mhal_spis_enable_irq (struct mtk_spis_controller *ctlr)
	This function is used to enable SPIS HW interrupt. More...

int	mtk_mhal_spis_fifo_transfer_one (struct mtk_spis_controller ctlr, struct mtk_spis_transfer xfer)
	This function is used to perform a single mtk_spi_transfer by FIFO mode. More...

int	mtk_mhal_spis_dma_done_callback_register (struct mtk_spis_controller *ctlr, spis_dma_done_callback callback)
	This function is used to register user's DMA callback to M-HAL. More...

int	mtk_mhal_spis_dma_transfer_one (struct mtk_spis_controller ctlr, struct mtk_spis_transfer xfer)
	This function is used to perform a single mtk_spis_transfer by DMA mode. More...

int	mtk_mhal_spis_allocate_dma_chan (struct mtk_spis_controller *ctlr)
	This function is used to allocate SPIS DMA channel. More...

int	mtk_mhal_spis_release_dma_chan (struct mtk_spis_controller *ctlr)
	This function is used to release SPIS DMA channel. More...

int	mtk_mhal_spis_enable_clk (struct mtk_spis_controller *ctlr)
	This function is used to enable SPIS clock before transfer. More...

int	mtk_mhal_spis_disable_clk (struct mtk_spis_controller *ctlr)
	This function is used to disable SPIS clock before transfer. More...

Function Documentation

int mtk_mhal_spis_dump_reg ( struct mtk_spis_controller * ctlr )

This function is used to dump spis register for debugging.

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

Parameters

[in] ctlr : SPI controller used with the device.

Returns: Return "0" if dumping register successfully.
Return -SPIS_EPTR if ctlr is NULL.

int mtk_mhal_spis_get_irq_status ( struct mtk_spis_controller * ctlr )

This function is used to get SPIS HW status.

Usage: Used to get SPIS HW irq status.

Parameters

[in] ctlr : SPI controller used with the device.

Returns: Return irq status if getting irq status successfully.
Return -SPIS_EPTR if ctlr is NULL.

int mtk_mhal_spis_clear_irq_status ( struct mtk_spis_controller * ctlr )

This function is used to clear SPIS HW status.

Usage: Used to clear SPIS HW irq status.

Parameters

[in] ctlr : SPI controller used with the device.

Returns: Return "0" if clear irq status successfully.
Return -SPIS_EPTR if ctlr is NULL.

int mtk_mhal_spis_handle_h2dmb ( struct mtk_spis_controller * ctlr )

This function is used to handle H2DMB which is sent from spi master.

Usage: Used to to parse the H2DMB cmd to fill struct mtk_spis_transfer, and then clear H2DMB status.

Parameters

[in] ctlr : SPI controller used with the device.

Example: spis_irq_handler()

{

irq_status = mtk_mhal_spis_get_irq_status(ctlr);

mtk_mhal_spis_clear_irq_status(ctlr);

switch (irq_status) {

case SPIM_WRITE_IRQ_MB_TO_SPIS:

mtk_mhal_spis_handle_h2dmb(ctlr);

mtk_mhal_spis_fifo_transfer_one(ctlr, xfer);

break;

}

mtk_mhal_spis_send_d2hmb(ctrl);

mtk_mhal_spis_clear_irq_status(ctrl);

}

Returns: Return "0" if handling H2DMB successfully.
Return -SPIS_EPTR if ctlr or xfer is NULL. Return -SPIS_EH2DMB if H2DMB is illegal. Return -SPIS_ELENGTH if xfer len is not supported,

int mtk_mhal_spis_send_d2hmb ( struct mtk_spis_controller * ctlr )

This function is used to update spis transmisson status.

Usage: Used to update spis transmisson status(defined in spis_d2hmb_state) from d2hmb_state(defined in mtk_spis_private)to regiset SPIS_STATUS(0x60). spim can get this status by read this register.

Parameters

[in] ctlr : SPI controller used with the device.

Example: spis_irq_handler()

{

irq_status = mtk_mhal_spis_get_irq_status(ctlr);

mtk_mhal_spis_clear_irq_status(ctlr);

switch (irq_status) {

case SPIM_WRITE_DATA_TO_SPIS:

mtk_mhal_spis_handle_rx(ctlr);

break;

}

mtk_mhal_spis_send_d2hmb(ctrl);

mtk_mhal_spis_clear_irq_status(ctrl);

}

Returns: Return "0" if update D2HMB status successfully.
Return -SPIS_EPTR if ctlr is NULL.

int mtk_mhal_spis_handle_rx ( struct mtk_spis_controller * ctlr )

This function is used to update spis RX transmisson status to d2hmb_state(defined in mtk_spis_private) and read FIFO data from SPIS HW.

Usage: Used to update spis transmisson status, and while using FIFO mode, copy data from rx FIFO register to xfer->rx_buffer.

Parameters

[in] ctlr : SPI controller used with the device.

Example: spis_irq_handler()

{

irq_status = mtk_mhal_spis_get_irq_status(ctlr);

mtk_mhal_spis_clear_irq_status(ctlr);

switch (irq_status) {

case SPIM_WRITE_DATA_TO_SPIS:

mtk_mhal_spis_handle_rx(ctlr);

break;

}

mtk_mhal_spis_send_d2hmb(ctrl);

mtk_mhal_spis_clear_irq_status(ctrl);

}

Returns: Return "0" if handle rx successfully.
Return -SPIS_EPTR if ctlr or xfer is NULL. Return -SPIS_ELENGTH if ctlr or xfer is NULL.

int mtk_mhal_spis_handle_tx ( struct mtk_spis_controller * ctlr )

This function is used to update spis TX transmisson status to d2hmb_state(defined in mtk_spis_private)

Usage: Used to update spis transmisson status.

Parameters

[in] ctlr : SPI controller used with the device.

Example: spis_irq_handler()

{

irq_status = mtk_mhal_spis_get_irq_status(ctlr);

mtk_mhal_spis_clear_irq_status(ctlr);

switch (irq_status) {

case SPIM_READ_DATA_FROM_SPIS:

mtk_mhal_spis_handle_tx(ctlr);

break;

}

mtk_mhal_spis_send_d2hmb(ctrl);

mtk_mhal_spis_clear_irq_status(ctrl);

}

Returns: Return "0" if handle tx successfully.
Return -SPIS_EPTR if ctlr or xfer is NULL.

int mtk_mhal_spis_setup_hw	(	struct mtk_spis_controller *	ctlr,
		struct mtk_spis_config *	config
	)

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

Usage: Used to *config setting to init HW. It must be called before transfer.

Parameters

[in]	ctlr	: SPI controller used with the device.
[in]	config	: HW setting

Example: struct mtk_spis_config spi_default_config = {

.cpol = SPI_CPOL_0,

.cpha = SPI_CPHA_0,

};

mtk_mhal_spis_setup_hw(ctlr, &spi_default_config);

Returns: Return "0" if setting SPIS HW successfully.
Return -SPIS_EPTR if ctlr or config is NULL.

int mtk_mhal_spis_enable_irq ( struct mtk_spis_controller * ctlr )

This function is used to enable SPIS HW interrupt.

Usage: It must be called before transfer to enable irq firstly.

Parameters

[in] ctlr : SPI controller used with the device.

Returns: Return "0" if enable irq successfully.
Return -SPIS_EPTR if ctlr is NULL.

int mtk_mhal_spis_fifo_transfer_one	(	struct mtk_spis_controller *	ctlr,
		struct mtk_spis_transfer *	xfer
	)

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

Usage: this function triggers SPIS HW to perform a single mtk_spi_transfer.
It must be called after mtk_mhal_spis_send_d2hmb(), while the function returns, representing that SPIS HW is ready to receive or send data.

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 -SPIS_EPTR if ctlr or xfer is NULL.
Return -SPIS_ELENGTH if xfer len is not supported.

int mtk_mhal_spis_dma_done_callback_register	(	struct mtk_spis_controller *	ctlr,
		spis_dma_done_callback	callback
	)

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_spis_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.

Returns: Return "0" if callback registers successfully.
Return -SPIS_EPTR if ctlr or callbackis NULL.

int mtk_mhal_spis_dma_transfer_one	(	struct mtk_spis_controller *	ctlr,
		struct mtk_spis_transfer *	xfer
	)

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

Usage: This function triggers SPIS HW to perform a single mtk_spis_transfer. It must be called after mtk_mhal_spis_send_d2hmb(), while the function returns, representing that SPIS HW is ready to receive or send data.

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 -SPIS_EPTR if ctlr or xfer is NULL.
Return -SPIS_ELENGTH if xfer len is not supported. Return -SPIS_EMEM if xfer buffer address is not 4Bytes alignment.

int mtk_mhal_spis_allocate_dma_chan ( struct mtk_spis_controller * ctlr )

This function is used to allocate SPIS DMA channel.

Usage: User should call it to allocate DMA channel after call #mtk_mhal_spis_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 -SPIS_EPTR if ctlr or xfer is NULL.
Return -SPIS_EBUSY if DMA chan is busy. Return -SPIS_EDMA if DMA processing failed.

int mtk_mhal_spis_release_dma_chan ( struct mtk_spis_controller * ctlr )

This function is used to release SPIS DMA channel.

Usage: user should call it to release DMA channel before call #mtk_mhal_spis_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 -SPIS_EPTR if ctlr or xfer is NULL.
Return -SPIS_EBUSY if DMA chan is already released.

int mtk_mhal_spis_enable_clk ( struct mtk_spis_controller * ctlr )

This function is used to enable SPIS clock before transfer.

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

Parameters

[in] ctlr : SPI controller used with the device.

Returns: Return "0" if enable SPIS clock successfully.
Return -SPIS_EPTR if ctlr is NULL.

int mtk_mhal_spis_disable_clk ( struct mtk_spis_controller * ctlr )

This function is used to disable SPIS clock before transfer.

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

Parameters

[in] ctlr : SPIS controller used with the device.

Returns: Return "0" if disable SPIS clock successfully.
Return -SPIS_EPTR if ctlr is NULL.

Overview

Functions

Function Documentation