Kenji Arai / mbed-os_TYBLE16

Dependents:   TYBLE16_simple_data_logger TYBLE16_MP3_Air

Embed: (wiki syntax)

« Back to documentation index

SPI Configuration Functions

SPI Configuration Functions
[Hal]

# Defined behavior * spi_init initializes the spi_t control structure * spi_init configures the pins used by SPI * spi_get_capabilities() fills the given `spi_capabilities_t` instance * spi_get_capabilities() should consider the `ssel` pin when evaluation the `support_slave_mode` and `hw_cs_handle` capability * spi_get_capabilities(): if the given `ssel` pin cannot be managed by hardware, `support_slave_mode` and `hw_cs_handle` should be false * At least a symbol width of 8bit must be supported * The supported frequency range must include the range [0.2..2] MHz * spi_free returns the pins owned by the SPI object to their reset state * spi_format sets the number of bits per frame * spi_format configures clock polarity and phase * spi_format configures master/slave mode * spi_frequency sets the SPI baud rate * spi_master_write writes a symbol out in master mode and receives a symbol * spi_master_block_write writes `tx_length` words to the bus * spi_master_block_write reads `rx_length` words from the bus * spi_master_block_write returns the maximum of tx_length and rx_length * spi_master_block_write specifies the write_fill which is default data transmitted while performing a read * spi_get_module returns non-zero if a value is available to read from SPI channel, 0 otherwise * spi_slave_read returns a received value out of the SPI receive buffer in slave mode * spi_slave_read blocks until a value is available * spi_slave_write writes a value to the SPI peripheral in slave mode * spi_slave_write blocks until the SPI peripheral can be written to * spi_busy returns non-zero if the peripheral is currently transmitting, 0 otherwise * spi_master_transfer starts the SPI asynchronous transfer * spi_master_transfer writes `tx_len` words to the bus * spi_master_transfer reads `rx_len` words from the bus * spi_master_transfer specifies the bit width of buffer words * The callback given to spi_master_transfer is invoked when the transfer completes (with a success or an error) * spi_master_transfer specifies the logical OR of events to be registered * The spi_master_transfer function may use the `DMAUsage` hint to select the appropriate async algorithm * spi_irq_handler_asynch reads the received values out of the RX FIFO * spi_irq_handler_asynch writes values into the TX FIFO * spi_irq_handler_asynch checks for transfer termination conditions, such as buffer overflows or transfer complete * spi_irq_handler_asynch returns event flags if a transfer termination condition was met, otherwise 0 * spi_abort_asynch aborts an on-going async transfer * spi_active returns non-zero if the SPI port is active or zero if it is not More...

Modules

 SPI hal tests
 

The SPI HAL tests ensure driver conformance to defined behaviour.


Functions

SPIName spi_get_peripheral_name (PinName mosi, PinName miso, PinName mclk)
 Returns a variant of the SPIName enum uniquely identifying a SPI peripheral of the device.
void spi_get_capabilities (PinName ssel, bool slave, spi_capabilities_t *cap)
 Fills the given spi_capabilities_t structure with the capabilities of the given peripheral.
void spi_init_direct (spi_t *obj, const spi_pinmap_t *pinmap)
 Initialize the SPI peripheral.
void spi_init (spi_t *obj, PinName mosi, PinName miso, PinName sclk, PinName ssel)
 Initialize the SPI peripheral.
void spi_free (spi_t *obj)
 Release a SPI object.
void spi_format (spi_t *obj, int bits, int mode, int slave)
 Configure the SPI format.
void spi_frequency (spi_t *obj, int hz)
 Set the SPI baud rate.

Detailed Description

# Defined behavior * spi_init initializes the spi_t control structure * spi_init configures the pins used by SPI * spi_get_capabilities() fills the given `spi_capabilities_t` instance * spi_get_capabilities() should consider the `ssel` pin when evaluation the `support_slave_mode` and `hw_cs_handle` capability * spi_get_capabilities(): if the given `ssel` pin cannot be managed by hardware, `support_slave_mode` and `hw_cs_handle` should be false * At least a symbol width of 8bit must be supported * The supported frequency range must include the range [0.2..2] MHz * spi_free returns the pins owned by the SPI object to their reset state * spi_format sets the number of bits per frame * spi_format configures clock polarity and phase * spi_format configures master/slave mode * spi_frequency sets the SPI baud rate * spi_master_write writes a symbol out in master mode and receives a symbol * spi_master_block_write writes `tx_length` words to the bus * spi_master_block_write reads `rx_length` words from the bus * spi_master_block_write returns the maximum of tx_length and rx_length * spi_master_block_write specifies the write_fill which is default data transmitted while performing a read * spi_get_module returns non-zero if a value is available to read from SPI channel, 0 otherwise * spi_slave_read returns a received value out of the SPI receive buffer in slave mode * spi_slave_read blocks until a value is available * spi_slave_write writes a value to the SPI peripheral in slave mode * spi_slave_write blocks until the SPI peripheral can be written to * spi_busy returns non-zero if the peripheral is currently transmitting, 0 otherwise * spi_master_transfer starts the SPI asynchronous transfer * spi_master_transfer writes `tx_len` words to the bus * spi_master_transfer reads `rx_len` words from the bus * spi_master_transfer specifies the bit width of buffer words * The callback given to spi_master_transfer is invoked when the transfer completes (with a success or an error) * spi_master_transfer specifies the logical OR of events to be registered * The spi_master_transfer function may use the `DMAUsage` hint to select the appropriate async algorithm * spi_irq_handler_asynch reads the received values out of the RX FIFO * spi_irq_handler_asynch writes values into the TX FIFO * spi_irq_handler_asynch checks for transfer termination conditions, such as buffer overflows or transfer complete * spi_irq_handler_asynch returns event flags if a transfer termination condition was met, otherwise 0 * spi_abort_asynch aborts an on-going async transfer * spi_active returns non-zero if the SPI port is active or zero if it is not

# Undefined behavior * Calling spi_init multiple times on the same `spi_t` without spi_free * Calling any function other than spi_init on a non-initialized or freed `spi_t` * Passing pins that cannot be on the same peripheral * Passing an invalid pointer as `obj` to any function * Passing an invalid pointer as `handler` to spi_master_transfer * Calling spi_abort while no async transfer is being processed (no transfer or a synchronous transfer)


Function Documentation

void spi_format ( spi_t obj,
int  bits,
int  mode,
int  slave 
)

Configure the SPI format.

Set the number of bits per frame, configure clock polarity and phase, shift order and master/slave mode. The default bit order is MSB.

Parameters:
[in,out]objThe SPI object to configure
[in]bitsThe number of bits per frame
[in]modeThe SPI mode (clock polarity, phase, and shift direction)
[in]slaveZero for master mode or non-zero for slave mode
void spi_free ( spi_t obj )

Release a SPI object.

TODO: spi_free is currently unimplemented This will require reference counting at the C++ level to be safe

Return the pins owned by the SPI object to their reset state Disable the SPI peripheral Disable the SPI clock

Parameters:
[in]objThe SPI object to deinitialize
void spi_frequency ( spi_t obj,
int  hz 
)

Set the SPI baud rate.

Actual frequency may differ from the desired frequency due to available dividers and bus clock Configures the SPI peripheral's baud rate

Parameters:
[in,out]objThe SPI object to configure
[in]hzThe baud rate in Hz
void spi_get_capabilities ( PinName  ssel,
bool  slave,
spi_capabilities_t cap 
)

Fills the given spi_capabilities_t structure with the capabilities of the given peripheral.

Definition at line 48 of file mbed_compat.c.

SPIName spi_get_peripheral_name ( PinName  mosi,
PinName  miso,
PinName  mclk 
)

Returns a variant of the SPIName enum uniquely identifying a SPI peripheral of the device.

Parameters:
[in]mosiThe pin to use for MOSI
[in]misoThe pin to use for MISO
[in]sclkThe pin to use for SCLK
Returns:
An SPI peripheral identifier
void spi_init ( spi_t obj,
PinName  mosi,
PinName  miso,
PinName  sclk,
PinName  ssel 
)

Initialize the SPI peripheral.

Configures the pins used by SPI, sets a default format and frequency, and enables the peripheral

Parameters:
[out]objThe SPI object to initialize
[in]mosiThe pin to use for MOSI
[in]misoThe pin to use for MISO
[in]sclkThe pin to use for SCLK
[in]sselThe pin to use for SSEL
void spi_init_direct ( spi_t obj,
const spi_pinmap_t *  pinmap 
)

Initialize the SPI peripheral.

Configures the pins used by SPI, sets a default format and frequency, and enables the peripheral

Parameters:
[out]objThe SPI object to initialize
[in]pinmappointer to structure which holds static pinmap

Definition at line 29 of file static_pinmap.cpp.