This driver for Atmel® | SMART ARM®-based microcontrollers provides an interface for the configuration and management of the SERCOM module in its SPI mode to transfer SPI data frames.
The following driver API modes are covered by this manual:
The following peripheral is used by this module:
The following devices can use this module:
The outline of this documentation is as follows:
There are no prerequisites.
The Serial Peripheral Interface (SPI) is a high-speed synchronous data transfer interface using three or four pins. It allows fast communication between a master device and one or more peripheral devices.
A device connected to the bus must act as a master or a slave. The master initiates and controls all data transactions. The SPI master initiates a communication cycle by pulling low the Slave Select (SS) pin of the desired slave. The Slave Select pin is active low. Master and slave prepare data to be sent in their respective shift registers, and the master generates the required clock pulses on the SCK line to interchange data. Data is always shifted from master to slave on the Master Out - Slave In (MOSI) line, and from slave to master on the Master In - Slave Out (MISO) line. After each data transfer, the master can synchronize to the slave by pulling the SS line high.
| Driver feature macro | Supported devices |
|---|---|
| FEATURE_SPI_SLAVE_SELECT_LOW_DETECT | SAM D21/R21/D10/D11/L21/L22/DA1/C20/C21/R30/R34/R35 |
| FEATURE_SPI_HARDWARE_SLAVE_SELECT | SAM D21/R21/D10/D11/L21/L22/DA1/C20/C21/R30/R34/R35 |
| FEATURE_SPI_ERROR_INTERRUPT | SAM D21/R21/D10/D11/L21/L22/DA1/C20/C21/R30/R34/R35 |
| FEATURE_SPI_SYNC_SCHEME_VERSION_2 | SAM D21/R21/D10/D11/L21/L22/DA1/C20/C21/R30/R34/R35 |
In the figure below, the connection between one master and one slave is shown.
The different lines are as follows:
If the bus consists of several SPI slaves, they can be connected in parallel and the SPI master can use general I/O pins to control separate SS lines to each slave on the bus.
It is also possible to connect all slaves in series. In this configuration, a common SS is provided to N slaves, enabling them simultaneously. The MISO from the N-1 slaves is connected to the MOSI on the next slave. The Nth slave connects its MISO back to the master. For a complete transaction, the master must shift N+1 characters.
The SPI character size is configurable to eight or nine bits.
When configured as a master, the SS pin will be configured as an output.
Writing a character will start the SPI clock generator, and the character is transferred to the shift register when the shift register is empty. Once this is done, a new character can be written. As each character is shifted out from the master, a character is shifted in from the slave. If the receiver is enabled, the data is moved to the receive buffer at the completion of the frame and can be read.
When configured as a slave, the SPI interface will remain inactive with MISO tri-stated as long as the SS pin is driven high.
The data register can be updated at any time. As the SPI slave shift register is clocked by SCK, a minimum of three SCK cycles are needed from the time new data is written, until the character is ready to be shifted out. If the shift register has not been loaded with data, the current contents will be transmitted.
If constant transmission of data is needed in SPI slave mode, the system clock should be faster than SCK. If the receiver is enabled, the received character can be read from the receive buffer. When SS line is driven high, the slave will not receive any additional data.
When the SPI slave is configured with address recognition, the first character in a transaction is checked for an address match. If there is a match, the MISO output is enabled and the transaction is processed. If the address does not match, the complete transaction is ignored.
If the device is asleep, it can be woken up by an address match in order to process the transaction.
There are four combinations of SCK phase and polarity with respect to serial data. The table below shows the clock polarity (CPOL) and clock phase (CPHA) in the different modes. Leading edge is the first clock edge in a clock cycle and trailing edge is the last clock edge in a clock cycle.
| Mode | CPOL | CPHA | Leading Edge | Trailing Edge |
|---|---|---|---|---|
| 0 | 0 | 0 | Rising, Sample | Falling, Setup |
| 1 | 0 | 1 | Rising, Setup | Falling, Sample |
| 2 | 1 | 0 | Falling, Sample | Rising, Setup |
| 3 | 1 | 1 | Falling, Setup | Rising, Sample |
The SERCOM pads are automatically configured as seen in the table below. If the receiver is disabled, the data input (MISO for master, MOSI for slave) can be used for other purposes.
In master mode, the SS pin(s) must be configured using the spi_slave_inst struct.
| Pin | Master SPI | Slave SPI |
|---|---|---|
| MOSI | Output | Input |
| MISO | Input | Output |
| SCK | Output | Input |
| SS | User defined output enable | Input |
The SPI module can operate in all sleep modes by setting the run_in_standby option in the spi_config struct. The operation in slave and master mode is shown in the table below.
| run_in_standby | Slave | Master |
|---|---|---|
| false | Disabled, all reception is dropped | GCLK is disabled when master is idle, wake on transmit complete |
| true | Wake on reception | GCLK is enabled while in sleep modes, wake on all interrupts |
In SPI master mode, the clock (SCK) is generated internally using the SERCOM baudrate generator. In SPI slave mode, the clock is provided by an external master on the SCK pin. This clock is used to directly clock the SPI shift register.
The pin MUX settings must be configured properly, as not all settings can be used in different modes of operation.
For extra information, see Extra Information for SERCOM SPI Driver. This includes:
For a list of examples related to this driver, see Examples for SERCOM SPI Driver.
Modules | |
| Related Project(s) | |
| In this section you can find all the projects related to the SAM Serial Peripheral Interface (SERCOM SPI) Driver. | |
| Quick Start Guide(s) | |
| In this section you can find a list of all Quick Start guides related to the SAM Serial Peripheral Interface (SERCOM SPI) Driver. | |
Data Structures | |
| struct | spi_config |
| SPI configuration structure. More... | |
| struct | spi_master_config |
| SPI Master configuration structure. More... | |
| struct | spi_module |
| SERCOM SPI driver software device instance structure. More... | |
| struct | spi_slave_config |
| SPI slave configuration structure. More... | |
| struct | spi_slave_inst |
| SPI peripheral slave instance structure. More... | |
| struct | spi_slave_inst_config |
| SPI peripheral slave configuration structure. More... | |
Macros | |
| #define | PINMUX_DEFAULT 0 |
| Default pinmux. More... | |
| #define | PINMUX_UNUSED 0xFFFFFFFF |
| Unused pinmux. More... | |
| #define | SPI_TIMEOUT 10000 |
| SPI timeout value. More... | |
Typedefs | |
| typedef void(* | spi_callback_t )(struct spi_module *const module) |
| Type of the callback functions. More... | |
Functions | |
| static bool | spi_is_syncing (struct spi_module *const module) |
| Determines if the SPI module is currently synchronizing to the bus. More... | |
| enum status_code | spi_set_baudrate (struct spi_module *const module, uint32_t baudrate) |
| Set the baudrate of the SPI module. More... | |
Driver Feature Definition | |
Define SERCOM SPI features set according to different device family. | |
| #define | FEATURE_SPI_SLAVE_SELECT_LOW_DETECT |
| SPI slave select low detection. More... | |
| #define | FEATURE_SPI_HARDWARE_SLAVE_SELECT |
| Slave select can be controlled by hardware. More... | |
| #define | FEATURE_SPI_ERROR_INTERRUPT |
| SPI with error detect feature. More... | |
| #define | FEATURE_SPI_SYNC_SCHEME_VERSION_2 |
| SPI sync scheme version 2. More... | |
Driver Initialization and Configuration | |
| static void | spi_get_config_defaults (struct spi_config *const config) |
| Initializes an SPI configuration structure to default values. More... | |
| static void | spi_slave_inst_get_config_defaults (struct spi_slave_inst_config *const config) |
| Initializes an SPI peripheral slave device configuration structure to default values. More... | |
| static void | spi_attach_slave (struct spi_slave_inst *const slave, const struct spi_slave_inst_config *const config) |
| Attaches an SPI peripheral slave. More... | |
| enum status_code | spi_init (struct spi_module *const module, Sercom *const hw, const struct spi_config *const config) |
| Initializes the SERCOM SPI module. More... | |
Enable/Disable | |
| static void | spi_enable (struct spi_module *const module) |
| Enables the SERCOM SPI module. More... | |
| static void | spi_disable (struct spi_module *const module) |
| Disables the SERCOM SPI module. More... | |
| void | spi_reset (struct spi_module *const module) |
| Resets the SPI module. More... | |
Lock/Unlock | |
| static enum status_code | spi_lock (struct spi_module *const module) |
| Attempt to get lock on driver instance. More... | |
| static void | spi_unlock (struct spi_module *const module) |
| Unlock driver instance. More... | |
Ready to Write/Read | |
| static bool | spi_is_write_complete (struct spi_module *const module) |
| Checks if the SPI in master mode has shifted out last data, or if the master has ended the transfer in slave mode. More... | |
| static bool | spi_is_ready_to_write (struct spi_module *const module) |
| Checks if the SPI module is ready to write data. More... | |
| static bool | spi_is_ready_to_read (struct spi_module *const module) |
| Checks if the SPI module is ready to read data. More... | |
Read/Write | |
| static enum status_code | spi_write (struct spi_module *module, uint16_t tx_data) |
| Transfers a single SPI character. More... | |
| enum status_code | spi_write_buffer_wait (struct spi_module *const module, const uint8_t *tx_data, uint16_t length) |
Sends a buffer of length SPI characters. More... | |
| static enum status_code | spi_read (struct spi_module *const module, uint16_t *rx_data) |
| Reads last received SPI character. More... | |
| enum status_code | spi_read_buffer_wait (struct spi_module *const module, uint8_t *rx_data, uint16_t length, uint16_t dummy) |
Reads buffer of length SPI characters. More... | |
| enum status_code | spi_transceive_wait (struct spi_module *const module, uint16_t tx_data, uint16_t *rx_data) |
| Sends and reads a single SPI character. More... | |
| enum status_code | spi_transceive_buffer_wait (struct spi_module *const module, uint8_t *tx_data, uint8_t *rx_data, uint16_t length) |
Sends and receives a buffer of length SPI characters. More... | |
| enum status_code | spi_select_slave (struct spi_module *const module, struct spi_slave_inst *const slave, bool select) |
| Selects slave device. More... | |
Callback Management | |
| void | spi_register_callback (struct spi_module *const module, spi_callback_t callback_func, enum spi_callback callback_type) |
| Registers a SPI callback function. More... | |
| void | spi_unregister_callback (struct spi_module *module, enum spi_callback callback_type) |
| Unregisters a SPI callback function. More... | |
| static void | spi_enable_callback (struct spi_module *const module, enum spi_callback callback_type) |
| Enables an SPI callback of a given type. More... | |
| static void | spi_disable_callback (struct spi_module *const module, enum spi_callback callback_type) |
| Disables callback. More... | |
Writing and Reading | |
| enum status_code | spi_write_buffer_job (struct spi_module *const module, uint8_t *tx_data, uint16_t length) |
| Asynchronous buffer write. More... | |
| enum status_code | spi_read_buffer_job (struct spi_module *const module, uint8_t *rx_data, uint16_t length, uint16_t dummy) |
| Asynchronous buffer read. More... | |
| enum status_code | spi_transceive_buffer_job (struct spi_module *const module, uint8_t *tx_data, uint8_t *rx_data, uint16_t length) |
| Asynchronous buffer write and read. More... | |
| void | spi_abort_job (struct spi_module *const module) |
| Aborts an ongoing job. More... | |
| static enum status_code | spi_get_job_status (const struct spi_module *const module) |
| Retrieves the current status of a job. More... | |
| static enum status_code | spi_get_job_status_wait (const struct spi_module *const module) |
| Retrieves the status of job once it ends. More... | |
| #define FEATURE_SPI_ERROR_INTERRUPT |
SPI with error detect feature.
| #define FEATURE_SPI_HARDWARE_SLAVE_SELECT |
Slave select can be controlled by hardware.
| #define FEATURE_SPI_SLAVE_SELECT_LOW_DETECT |
SPI slave select low detection.
| #define FEATURE_SPI_SYNC_SCHEME_VERSION_2 |
SPI sync scheme version 2.
| #define PINMUX_DEFAULT 0 |
Default pinmux.
Referenced by spi_get_config_defaults().
| #define PINMUX_UNUSED 0xFFFFFFFF |
Unused pinmux.
| #define SPI_TIMEOUT 10000 |
SPI timeout value.
Referenced by spi_read_buffer_wait(), spi_transceive_buffer_wait(), spi_transceive_wait(), and spi_write_buffer_wait().
| typedef void(* spi_callback_t)(struct spi_module *const module) |
Type of the callback functions.
| enum spi_addr_mode |
SPI address modes enum.
For slave mode when using the SPI frame with address format.
| Enumerator | |
|---|---|
| SPI_ADDR_MODE_MASK |
|
| SPI_ADDR_MODE_UNIQUE |
The slave responds to the two unique addresses in |
| SPI_ADDR_MODE_RANGE |
The slave responds to the range of addresses between and including |
| enum spi_callback |
SPI Callback enum.
Callbacks for SPI callback driver.
| enum spi_character_size |
| enum spi_data_order |
| enum spi_frame_format |
| enum spi_interrupt_flag |
SPI Interrupt Flags.
Interrupt flags for the SPI module.
| enum spi_mode |
SPI signal MUX settings.
Set the functionality of the SERCOM pins. As not all combinations can be used in different modes of operation, proper combinations must be chosen according to the rest of the configuration.
See MUX Settings for a description of the various MUX setting options.
| enum spi_transfer_mode |
SPI transfer modes enum.
SPI transfer mode.
| void spi_abort_job | ( | struct spi_module *const | module | ) |
Aborts an ongoing job.
This function will abort the specified job type.
| [in] | module | Pointer to SPI software instance struct |
References SPI_INTERRUPT_FLAG_DATA_REGISTER_EMPTY, SPI_INTERRUPT_FLAG_RX_COMPLETE, SPI_INTERRUPT_FLAG_TX_COMPLETE, and STATUS_ABORTED.
|
inlinestatic |
Attaches an SPI peripheral slave.
This function will initialize the software SPI peripheral slave, based on the values of the config struct. The slave can then be selected and optionally addressed by the spi_select_slave function.
| [out] | slave | Pointer to the software slave instance struct |
| [in] | config | Pointer to the config struct |
References spi_slave_inst::address, spi_slave_inst_config::address, spi_slave_inst::address_enabled, spi_slave_inst_config::address_enabled, Assert, port_config::direction, port_get_config_defaults(), PORT_PIN_DIR_OUTPUT, port_pin_set_config(), port_pin_set_output_level(), spi_slave_inst::ss_pin, and spi_slave_inst_config::ss_pin.
Referenced by adp_interface_init(), configure_spi_master(), HAL_RadioSpiInit(), ksz8851snl_interface_init(), nm_bus_init(), run_spi_init_test(), and ssd1306_interface_init().
|
inlinestatic |
Disables the SERCOM SPI module.
This function will disable the SERCOM SPI module.
| [in,out] | module | Pointer to the software instance struct |
References _sercom_get_interrupt_vector(), Assert, spi_is_syncing(), and system_interrupt_disable().
Referenced by HAL_RadioDeInit(), nm_bus_deinit(), run_baud_test(), setup_transfer_9bit_test(), spi_reset(), and spi_set_baudrate().
|
inlinestatic |
Disables callback.
Disables the callback function registered by the spi_register_callback, and the callback will not be called from the interrupt routine.
| [in] | module | Pointer to SPI software instance struct |
| [in] | callback_type | Callback type given by an enum |
References Assert.
Referenced by cleanup_buffer_polled_write_interrupt_read_test().
|
inlinestatic |
Enables the SERCOM SPI module.
This function will enable the SERCOM SPI module.
| [in,out] | module | Pointer to the software instance struct |
References _sercom_get_interrupt_vector(), Assert, spi_is_syncing(), and system_interrupt_enable().
Referenced by adp_interface_init(), configure_spi_master(), configure_spi_slave(), HAL_Radio_resources_init(), HAL_RadioSpiInit(), ksz8851snl_interface_init(), nm_bus_init(), run_baud_test(), run_spi_init_test(), setup_transfer_9bit_test(), spi_set_baudrate(), and ssd1306_interface_init().
|
inlinestatic |
Enables an SPI callback of a given type.
Enables the callback function registered by the spi_register_callback. The callback function will be called from the interrupt handler when the conditions for the callback type are met.
| [in] | module | Pointer to SPI software instance struct |
| [in] | callback_type | Callback type given by an enum |
References Assert.
Referenced by configure_spi_master_callbacks(), configure_spi_slave_callbacks(), and setup_buffer_polled_write_interrupt_read_test().
|
inlinestatic |
Initializes an SPI configuration structure to default values.
This function will initialize a given SPI configuration structure to a set of known default values. This function should be called on any new instance of the configuration structures before being modified by the user application.
The default configuration is as follows:
| [out] | config | Configuration structure to initialize to default values |
References Assert, spi_master_config::baudrate, spi_config::character_size, spi_config::data_order, GCLK_GENERATOR_0, spi_config::generator_source, spi_config::master, spi_config::master_slave_select_enable, spi_config::mode, spi_config::mode_specific, spi_config::mux_setting, PINMUX_DEFAULT, spi_config::pinmux_pad0, spi_config::pinmux_pad1, spi_config::pinmux_pad2, spi_config::pinmux_pad3, spi_config::receiver_enable, spi_config::run_in_standby, spi_config::select_slave_low_detect_enable, SPI_CHARACTER_SIZE_8BIT, SPI_DATA_ORDER_MSB, SPI_MODE_MASTER, SPI_SIGNAL_MUX_SETTING_D, SPI_TRANSFER_MODE_0, and spi_config::transfer_mode.
Referenced by adp_interface_init(), configure_spi_master(), configure_spi_slave(), HAL_RadioSpiInit(), ksz8851snl_interface_init(), nm_bus_init(), run_baud_test(), run_spi_init_test(), setup_transfer_9bit_test(), and ssd1306_interface_init().
|
inlinestatic |
Retrieves the current status of a job.
Retrieves the current status of a job that was previously issued.
| [in] | module | Pointer to SPI software instance struct |
Referenced by spi_get_job_status_wait().
|
inlinestatic |
Retrieves the status of job once it ends.
Waits for current job status to become non-busy, then returns its value.
| [in] | module | Pointer to SPI software instance struct |
References spi_get_job_status(), and STATUS_BUSY.
| enum status_code spi_init | ( | struct spi_module *const | module, |
| Sercom *const | hw, | ||
| const struct spi_config *const | config | ||
| ) |
Initializes the SERCOM SPI module.
This function will initialize the SERCOM SPI module, based on the values of the config struct.
| [out] | module | Pointer to the software instance struct |
| [in] | hw | Pointer to hardware instance |
| [in] | config | Pointer to the config struct |
| STATUS_OK | Module initiated correctly |
| STATUS_ERR_DENIED | If module is enabled |
| STATUS_BUSY | If module is busy resetting |
| STATUS_ERR_INVALID_ARG | If invalid argument(s) were provided |
References _sercom_get_sercom_inst_index(), _sercom_instances, _sercom_set_handler(), _spi_check_config(), _spi_interrupt_handler(), _spi_set_config(), Assert, spi_config::generator_source, i, spi_config::mode, NULL, sercom_set_gclk_generator(), system_gclk_chan_config::source_generator, SPI_MODE_MASTER, SPI_MODE_SLAVE, STATUS_BUSY, STATUS_ERR_DENIED, STATUS_ERR_INVALID_ARG, STATUS_OK, system_apb_clock_set_mask(), SYSTEM_CLOCK_APB_APBC, SYSTEM_CLOCK_APB_APBD, system_gclk_chan_enable(), system_gclk_chan_get_config_defaults(), and system_gclk_chan_set_config().
Referenced by adp_interface_init(), configure_spi_master(), configure_spi_slave(), HAL_RadioSpiInit(), ksz8851snl_interface_init(), nm_bus_init(), run_baud_test(), run_spi_init_test(), setup_transfer_9bit_test(), and ssd1306_interface_init().
|
inlinestatic |
Checks if the SPI module is ready to read data.
This function will check if the SPI module is ready to read data.
| [in] | module | Pointer to the software instance struct |
| true | If the SPI module is ready to read data |
| false | If the SPI module is not ready to read data |
References Assert.
Referenced by HAL_SPISend(), run_single_byte_polled_test(), run_transfer_9bit_test(), spi_read(), spi_read_buffer_wait(), spi_select_slave(), spi_transceive_buffer_wait(), spi_transceive_wait(), and spi_write_buffer_wait().
|
inlinestatic |
Checks if the SPI module is ready to write data.
This function will check if the SPI module is ready to write data.
| [in] | module | Pointer to the software instance struct |
| true | If the SPI module is ready to write data |
| false | If the SPI module is not ready to write data |
References Assert.
Referenced by HAL_SPISend(), run_single_byte_polled_test(), run_transfer_9bit_test(), spi_read_buffer_wait(), spi_select_slave(), spi_transceive_buffer_wait(), spi_transceive_wait(), spi_write(), and spi_write_buffer_wait().
|
inlinestatic |
Determines if the SPI module is currently synchronizing to the bus.
This function will check if the underlying hardware peripheral module is currently synchronizing across multiple clock domains to the hardware bus. This function can be used to delay further operations on the module until it is ready.
| [in] | module | SPI hardware module |
| true | Module synchronization is ongoing |
| false | Module synchronization is not ongoing |
References Assert.
Referenced by HAL_Radio_resources_init(), spi_disable(), spi_enable(), spi_reset(), and spi_set_baudrate().
|
inlinestatic |
Checks if the SPI in master mode has shifted out last data, or if the master has ended the transfer in slave mode.
This function will check if the SPI master module has shifted out last data, or if the slave select pin has been drawn high by the master for the SPI slave module.
| [in] | module | Pointer to the software instance struct |
| true | If the SPI master module has shifted out data, or slave select has been drawn high for SPI slave |
| false | If the SPI master module has not shifted out data |
References Assert.
Referenced by HAL_SPISend(), run_single_byte_polled_test(), run_transfer_9bit_test(), spi_read_buffer_wait(), spi_transceive_buffer_wait(), and spi_write_buffer_wait().
|
inlinestatic |
Attempt to get lock on driver instance.
This function checks the instance's lock, which indicates whether or not it is currently in use, and sets the lock if it was not already set.
The purpose of this is to enable exclusive access to driver instances, so that, e.g., transactions by different services will not interfere with each other.
| [in,out] | module | Pointer to the driver instance to lock |
| STATUS_OK | If the module was locked |
| STATUS_BUSY | If the module was already locked |
References STATUS_BUSY, STATUS_OK, system_interrupt_enter_critical_section(), and system_interrupt_leave_critical_section().
|
inlinestatic |
Reads last received SPI character.
This function will return the last SPI character shifted into the receive register by the spi_write function.
| [in] | module | Pointer to the software instance struct |
| [out] | rx_data | Pointer to store the received data |
| STATUS_OK | If data was read |
| STATUS_ERR_IO | If no data is available |
| STATUS_ERR_OVERFLOW | If the data is overflown |
References Assert, SPI_CHARACTER_SIZE_9BIT, spi_is_ready_to_read(), STATUS_ERR_IO, STATUS_ERR_OVERFLOW, and STATUS_OK.
Referenced by HAL_SPISend(), run_single_byte_polled_test(), run_transfer_9bit_test(), spi_read_buffer_wait(), spi_select_slave(), spi_transceive_buffer_wait(), spi_transceive_wait(), and spi_write_buffer_wait().
| enum status_code spi_read_buffer_job | ( | struct spi_module *const | module, |
| uint8_t * | rx_data, | ||
| uint16_t | length, | ||
| uint16_t | dummy | ||
| ) |
Asynchronous buffer read.
Sets up the driver to read from the SPI to a given buffer. If registered and enabled, a callback function will be called when the read is finished.
| [in] | module | Pointer to SPI software instance struct |
| [out] | rx_data | Pointer to data buffer to receive |
| [in] | length | Data buffer length |
| [in] | dummy | Dummy character to send when reading in master mode |
| STATUS_OK | If the operation completed successfully |
| STATUS_ERR_BUSY | If the SPI was already busy with a read operation |
| STATUS_ERR_DENIED | If the receiver is not enabled |
| STATUS_ERR_INVALID_ARG | If requested read length was zero |
References _spi_read_buffer(), Assert, dummy_write, STATUS_BUSY, STATUS_ERR_DENIED, STATUS_ERR_INVALID_ARG, and STATUS_OK.
Referenced by main(), and run_buffer_polled_write_interrupt_read_test().
| enum status_code spi_read_buffer_wait | ( | struct spi_module *const | module, |
| uint8_t * | rx_data, | ||
| uint16_t | length, | ||
| uint16_t | dummy | ||
| ) |
Reads buffer of length SPI characters.
This function will read a buffer of data from an SPI peripheral by sending dummy SPI character if in master mode, or by waiting for data in slave mode.
| [in] | module | Pointer to the software instance struct |
| [out] | rx_data | Data buffer for received data |
| [in] | length | Length of data to receive |
| [in] | dummy | 8- or 9-bit dummy byte to shift out in master mode |
| STATUS_OK | If the read was completed |
| STATUS_ABORTED | If transaction was ended by master before the entire buffer was transferred |
| STATUS_ERR_INVALID_ARG | If invalid argument(s) were provided |
| STATUS_ERR_TIMEOUT | If the operation was not completed within the timeout in slave mode |
| STATUS_ERR_DENIED | If the receiver is not enabled |
| STATUS_ERR_OVERFLOW | If the data is overflown |
References _spi_clear_tx_complete_flag(), Assert, i, SPI_CHARACTER_SIZE_9BIT, spi_is_ready_to_read(), spi_is_ready_to_write(), spi_is_write_complete(), SPI_MODE_MASTER, SPI_MODE_SLAVE, spi_read(), SPI_TIMEOUT, spi_write(), STATUS_ABORTED, STATUS_BUSY, STATUS_ERR_DENIED, STATUS_ERR_INVALID_ARG, STATUS_ERR_TIMEOUT, and STATUS_OK.
Referenced by adp_interface_read_response(), ksz8851_fifo_read(), main(), and run_baud_test().
| void spi_register_callback | ( | struct spi_module *const | module, |
| spi_callback_t | callback_func, | ||
| enum spi_callback | callback_type | ||
| ) |
Registers a SPI callback function.
Registers a callback function which is implemented by the user.
| [in] | module | Pointer to USART software instance struct |
| [in] | callback_func | Pointer to callback function |
| [in] | callback_type | Callback type given by an enum |
References Assert.
Referenced by configure_spi_master_callbacks(), configure_spi_slave_callbacks(), and setup_buffer_polled_write_interrupt_read_test().
| void spi_reset | ( | struct spi_module *const | module | ) |
Resets the SPI module.
This function will reset the SPI module to its power on default values and disable it.
| [in,out] | module | Pointer to the software instance struct |
References Assert, spi_disable(), and spi_is_syncing().
| enum status_code spi_select_slave | ( | struct spi_module *const | module, |
| struct spi_slave_inst *const | slave, | ||
| const bool | select | ||
| ) |
Selects slave device.
This function will drive the slave select pin of the selected device low or high depending on the select Boolean. If slave address recognition is enabled, the address will be sent to the slave when selecting it.
| [in] | module | Pointer to the software module struct |
| [in] | slave | Pointer to the attached slave |
| [in] | select | Boolean stating if the slave should be selected or deselected |
| STATUS_OK | If the slave device was selected |
| STATUS_ERR_UNSUPPORTED_DEV | If the SPI module is operating in slave mode |
| STATUS_BUSY | If the SPI module is not ready to write the slave address |
References spi_slave_inst::address, spi_slave_inst::address_enabled, Assert, port_pin_set_output_level(), spi_is_ready_to_read(), spi_is_ready_to_write(), SPI_MODE_MASTER, spi_read(), spi_write(), spi_slave_inst::ss_pin, STATUS_BUSY, STATUS_ERR_UNSUPPORTED_DEV, and STATUS_OK.
Referenced by adp_interface_send_start(), adp_interface_send_stop(), HAL_SPICSAssert(), HAL_SPICSDeassert(), ksz8851_fifo_read(), ksz8851_fifo_write_begin(), ksz8851_fifo_write_end(), ksz8851_reg_read(), ksz8851_reg_write(), main(), run_baud_test(), run_buffer_polled_write_interrupt_read_test(), run_single_byte_polled_test(), run_transceive_buffer_test(), run_transfer_9bit_test(), ssd1306_write_command(), and ssd1306_write_data().
| enum status_code spi_set_baudrate | ( | struct spi_module *const | module, |
| uint32_t | baudrate | ||
| ) |
Set the baudrate of the SPI module.
This function will set the baudrate of the SPI module.
| [in] | module | Pointer to the software instance struct |
| [in] | baudrate | The baudrate wanted |
| STATUS_ERR_INVALID_ARG | If invalid argument(s) were provided |
| STATUS_OK | If the configuration was written |
References _sercom_get_sercom_inst_index(), _sercom_get_sync_baud_val(), Assert, spi_disable(), spi_enable(), spi_is_syncing(), STATUS_ERR_INVALID_ARG, STATUS_OK, and system_gclk_chan_get_hz().
|
inlinestatic |
Initializes an SPI peripheral slave device configuration structure to default values.
This function will initialize a given SPI slave device configuration structure to a set of known default values. This function should be called on any new instance of the configuration structures before being modified by the user application.
The default configuration is as follows:
| [out] | config | Configuration structure to initialize to default values |
References spi_slave_inst_config::address, spi_slave_inst_config::address_enabled, Assert, and spi_slave_inst_config::ss_pin.
Referenced by adp_interface_init(), configure_spi_master(), HAL_RadioSpiInit(), ksz8851snl_interface_init(), nm_bus_init(), run_spi_init_test(), and ssd1306_interface_init().
| enum status_code spi_transceive_buffer_job | ( | struct spi_module *const | module, |
| uint8_t * | tx_data, | ||
| uint8_t * | rx_data, | ||
| uint16_t | length | ||
| ) |
Asynchronous buffer write and read.
Sets up the driver to write and read to and from given buffers. If registered and enabled, a callback function will be called when the transfer is finished.
| [in] | module | Pointer to SPI software instance struct |
| [in] | tx_data | Pointer to data buffer to send |
| [out] | rx_data | Pointer to data buffer to receive |
| [in] | length | Data buffer length |
| STATUS_OK | If the operation completed successfully |
| STATUS_ERR_BUSY | If the SPI was already busy with a read operation |
| STATUS_ERR_DENIED | If the receiver is not enabled |
| STATUS_ERR_INVALID_ARG | If requested read length was zero |
References _spi_transceive_buffer(), Assert, STATUS_BUSY, STATUS_ERR_DENIED, STATUS_ERR_INVALID_ARG, and STATUS_OK.
Referenced by main(), and run_transceive_buffer_test().
| enum status_code spi_transceive_buffer_wait | ( | struct spi_module *const | module, |
| uint8_t * | tx_data, | ||
| uint8_t * | rx_data, | ||
| uint16_t | length | ||
| ) |
Sends and receives a buffer of length SPI characters.
This function will send and receive a buffer of data via the SPI.
In master mode the SPI characters will be sent immediately and the received SPI character will be read as soon as the shifting of the SPI character is complete.
In slave mode this function will place the data to be sent into the transmit buffer. It will then block until an SPI master has shifted the complete buffer and the received data is available.
| [in] | module | Pointer to the software instance struct |
| [in] | tx_data | Pointer to the buffer to transmit |
| [out] | rx_data | Pointer to the buffer where received data will be stored |
| [in] | length | Number of SPI characters to transfer |
| STATUS_OK | If the operation was completed |
| STATUS_ERR_INVALID_ARG | If invalid argument(s) were provided |
| STATUS_ERR_TIMEOUT | If the operation was not completed within the timeout in slave mode |
| STATUS_ERR_DENIED | If the receiver is not enabled |
| STATUS_ERR_OVERFLOW | If the data is overflown |
References _spi_clear_tx_complete_flag(), Assert, i, length, SPI_CHARACTER_SIZE_9BIT, spi_is_ready_to_read(), spi_is_ready_to_write(), spi_is_write_complete(), SPI_MODE_MASTER, SPI_MODE_SLAVE, spi_read(), SPI_TIMEOUT, spi_write(), STATUS_ABORTED, STATUS_BUSY, STATUS_ERR_DENIED, STATUS_ERR_INVALID_ARG, STATUS_ERR_TIMEOUT, and STATUS_OK.
Referenced by adp_interface_transceive(), ksz8851_fifo_read(), ksz8851_reg_read(), ksz8851_reg_write(), and run_transceive_buffer_test().
| enum status_code spi_transceive_wait | ( | struct spi_module *const | module, |
| uint16_t | tx_data, | ||
| uint16_t * | rx_data | ||
| ) |
Sends and reads a single SPI character.
This function will transfer a single SPI character via SPI and return the SPI character that is shifted into the shift register.
In master mode the SPI character will be sent immediately and the received SPI character will be read as soon as the shifting of the data is complete.
In slave mode this function will place the data to be sent into the transmit buffer. It will then block until an SPI master has shifted a complete SPI character, and the received data is available.
| [in] | module | Pointer to the software instance struct |
| [in] | tx_data | SPI character to transmit |
| [out] | rx_data | Pointer to store the received SPI character |
| STATUS_OK | If the operation was completed |
| STATUS_ERR_TIMEOUT | If the operation was not completed within the timeout in slave mode |
| STATUS_ERR_DENIED | If the receiver is not enabled |
| STATUS_ERR_OVERFLOW | If the incoming data is overflown |
References Assert, j, spi_is_ready_to_read(), spi_is_ready_to_write(), SPI_MODE_SLAVE, spi_read(), SPI_TIMEOUT, spi_write(), STATUS_BUSY, STATUS_ERR_DENIED, STATUS_ERR_TIMEOUT, and STATUS_OK.
|
inlinestatic |
Unlock driver instance.
This function clears the instance lock, indicating that it is available for use.
| [in,out] | module | Pointer to the driver instance to lock |
| STATUS_OK | If the module was locked |
| STATUS_BUSY | If the module was already locked |
| void spi_unregister_callback | ( | struct spi_module *const | module, |
| enum spi_callback | callback_type | ||
| ) |
Unregisters a SPI callback function.
Unregisters a callback function which is implemented by the user.
| [in] | module | Pointer to SPI software instance struct |
| [in] | callback_type | Callback type given by an enum |
Referenced by cleanup_buffer_polled_write_interrupt_read_test().
|
inlinestatic |
Transfers a single SPI character.
This function will send a single SPI character via SPI and ignore any data shifted in by the connected device. To both send and receive data, use the spi_transceive_wait function or use the spi_read function after writing a character. The spi_is_ready_to_write function should be called before calling this function.
Note that this function does not handle the SS (Slave Select) pin(s) in master mode; this must be handled from the user application.
| [in] | module | Pointer to the software instance struct |
| [in] | tx_data | Data to transmit |
| STATUS_OK | If the data was written |
| STATUS_BUSY | If the last write was not completed |
References Assert, spi_is_ready_to_write(), STATUS_BUSY, and STATUS_OK.
Referenced by HAL_SPISend(), run_single_byte_polled_test(), run_transfer_9bit_test(), spi_read_buffer_wait(), spi_select_slave(), spi_transceive_buffer_wait(), spi_transceive_wait(), and spi_write_buffer_wait().
| enum status_code spi_write_buffer_job | ( | struct spi_module *const | module, |
| uint8_t * | tx_data, | ||
| uint16_t | length | ||
| ) |
Asynchronous buffer write.
Sets up the driver to write to the SPI from a given buffer. If registered and enabled, a callback function will be called when the write is finished.
| [in] | module | Pointer to SPI software instance struct |
| [out] | tx_data | Pointer to data buffer to receive |
| [in] | length | Data buffer length |
| STATUS_OK | If the operation completed successfully |
| STATUS_ERR_BUSY | If the SPI was already busy with a write operation |
| STATUS_ERR_INVALID_ARG | If requested write length was zero |
References _spi_write_buffer(), Assert, STATUS_BUSY, STATUS_ERR_INVALID_ARG, and STATUS_OK.
| enum status_code spi_write_buffer_wait | ( | struct spi_module *const | module, |
| const uint8_t * | tx_data, | ||
| uint16_t | length | ||
| ) |
Sends a buffer of length SPI characters.
This function will send a buffer of SPI characters via the SPI and discard any data that is received. To both send and receive a buffer of data, use the spi_transceive_buffer_wait function.
Note that this function does not handle the _SS (slave select) pin(s) in master mode; this must be handled by the user application.
| [in] | module | Pointer to the software instance struct |
| [in] | tx_data | Pointer to the buffer to transmit |
| [in] | length | Number of SPI characters to transfer |
| STATUS_OK | If the write was completed |
| STATUS_ABORTED | If transaction was ended by master before entire buffer was transferred |
| STATUS_ERR_INVALID_ARG | If invalid argument(s) were provided |
| STATUS_ERR_TIMEOUT | If the operation was not completed within the timeout in slave mode |
References _spi_clear_tx_complete_flag(), Assert, i, length, SPI_CHARACTER_SIZE_9BIT, spi_is_ready_to_read(), spi_is_ready_to_write(), spi_is_write_complete(), SPI_MODE_MASTER, SPI_MODE_SLAVE, spi_read(), SPI_TIMEOUT, spi_write(), STATUS_ABORTED, STATUS_BUSY, STATUS_ERR_INVALID_ARG, STATUS_ERR_TIMEOUT, and STATUS_OK.
Referenced by ksz8851_fifo_write(), ksz8851_fifo_write_begin(), ksz8851_fifo_write_end(), main(), run_baud_test(), run_buffer_polled_write_interrupt_read_test(), ssd1306_write_command(), and ssd1306_write_data().
1.8.5