3.22 SPI Host Driver
Overview
The Serial Peripheral Interface (SPI) module is a synchronous serial interface useful for communicating with other peripheral or microcontroller devices. These peripheral devices can be serial EEPROMs, Shift registers, display drivers, Analog-to-Digital Converters and so on.
Features
- Allows to setup multiple Host Configurations to interact with multiple clients having different configurations. SPIx_Open and SPIx_Close are the APIs to be used for selecting/switching between different Host configurations at run time.
- Requested Speed , SPI Mode and Data Input Sample Point are configurable items for each Host Configuration table entry.
- User can provide Custom Name for each Host Configuration table entry.
- Calculated speed depends on the Bus Clock source which can be configured as part the the selected PLIB.
- Supports Enhanced Buffer mode with communication width of 8 bit only.
- Currently, only polling mode is supported.
3.22.1 Module Documentation
3.22.1.1 SPI Host Driver
Serial Peripheral Interface (SPI) HOST Driver using dsPIC MCUs.
3.22.1.1.1 Module description
Serial Peripheral Interface (SPI) HOST Driver using dsPIC MCUs.
Data structures
struct SPI_HOST_INTERFACE
Structure containing the function pointers of SPI HOST driver.
Enumerations
enum SPI1_HOST_USER_CONFIG { HOST_CONFIG, HOST_CONFIG }
Enum list is the Custom names for the SPI1 HOST multiple configuration, configured by user in MCC Melody user interface. These Host Configurations can be used to switch at runtime to interact with multiple clients.
Functions
void SPI1_Initialize (void)
Initializes SPI1 module, using the given initialization data. This function must be called before any other SPI1 function is called.
void SPI1_Deinitialize (void)
Deinitializes the SPI1 to POR values.
void SPI1_Close (void)
Disables the SPI1 module.
bool SPI1_Open (uint8_t spiConfigIndex)
Configures SPI1 module with user defined unique configuration.
uint8_t SPI1_ByteExchange (uint8_t byteData)
Exchanges one byte of data. This is a blocking function.
void SPI1_BufferExchange (void *bufferData, size_t bufferSize)
This function is used to transmit data from the buffer pointer and updates the received data in the same buffer location. This is a blocking function.
void SPI1_BufferWrite (void *bufferData, size_t bufferSize)
Writes data from a buffer. This is a blocking routine.
void SPI1_BufferRead (void *bufferData, size_t bufferSize)
Reads data from a buffer. This is a blocking routine.
void SPI1_ByteWrite (uint8_t byteData)
Writes one byte of data.
uint8_t SPI1_ByteRead (void)
Reads one byte of data from SPI1.
bool SPI1_IsRxReady (void)
Returns a boolean value if data is available to read.
bool SPI1_IsTxReady (void)
Returns a boolean value if data can be written.
Variables
const struct SPI_HOST_INTERFACE SPI1_Host
Structure object of type SPI_HOST_INTERFACE assigned with name displayed in the Melody Driver User interface. A structure pointer can be used to achieve portability across the SPI HOST having same interface structure.
3.22.1.1.2 Function Documentation
SPI1_BufferExchange()
void SPI1_BufferExchange (void * bufferData, size_t bufferSize)
This function is used to transmit data from the buffer pointer and updates the received data in the same buffer location. This is a blocking function.
The SPI1_IsTxReady function must be called before calling this function. |
in,out | bufferData |
- Address of data buffer to be excanged. |
in | bufferSize |
- Number of bytes in a buffer. |
none |
SPI1_BufferRead()
void SPI1_BufferRead (void * bufferData, size_t bufferSize)
Reads data from a buffer. This is a blocking routine.
The SPI1_IsRxReady function must be called before calling this function. |
out | bufferData |
- Address of data buffer to be read. |
in | bufferSize |
- Number of bytes in a buffer. |
none |
SPI1_BufferWrite()
void SPI1_BufferWrite (void * bufferData, size_t bufferSize)
Writes data from a buffer. This is a blocking routine.
The SPI1_IsTxReady function must be called before calling this function. |
in | bufferData |
- Address of data buffer to be written. |
in | bufferSize |
- Number of bytes in a buffer. |
none |
SPI1_ByteExchange()
uint8_t SPI1_ByteExchange (uint8_t byteData)
Exchanges one byte of data. This is a blocking function.
The SPI1_IsTxReady function must be called before calling this function. |
in | data- |
Data byte to be exchanged. |
none |
SPI1_ByteRead()
uint8_t SPI1_ByteRead (void )
Reads one byte of data from SPI1.
The SPI1_IsRxReady function must be called before calling this function. Also note that byte read must be after byte write sequence. |
none |
Data read from SPI1. |
SPI1_ByteWrite()
void SPI1_ByteWrite (uint8_t byteData)
Writes one byte of data.
The SPI1_IsTxReady function must be called before calling this function. Also note that every byte write has to be followed by a byte read. |
in | byteData |
- Data to be written. |
none |
SPI1_Close()
void SPI1_Close (void )
Disables the SPI1 module.
The SPI1_Open function must be called before calling this function. |
none |
none |
SPI1_Deinitialize()
void SPI1_Deinitialize (void )
Deinitializes the SPI1 to POR values.
none |
none |
SPI1_Initialize()
void SPI1_Initialize (void )
Initializes SPI1 module, using the given initialization data. This function must be called before any other SPI1 function is called.
none |
none |
SPI1_IsRxReady()
bool SPI1_IsRxReady (void )
Returns a boolean value if data is available to read.
The SPI1_Open function must be called before calling this function. |
none |
true - Data available to read false - Data not available to read |
SPI1_IsTxReady()
bool SPI1_IsTxReady (void )
Returns a boolean value if data can be written.
The SPI1_Open function must be called before calling this function. |
none |
true - Data can be written false - Data buffer is full |
SPI1_Open()
bool SPI1_Open (uint8_t spiConfigIndex)
Configures SPI1 module with user defined unique configuration.
in | spiConfigIndex |
- SPI1_USER_CONFIG Enum value |
bool true - SPI1 is configured successfully. bool false - SPI1 is not configured successfully. |
3.22.1.1.3 Enumeration Type Documentation
SPI1_HOST_USER_CONFIG
enum SPI1_HOST_USER_CONFIG
Enum list is the Custom names for the SPI1 HOST multiple configuration, configured by user in MCC Melody user interface. These Host Configurations can be used to switch at runtime to interact with multiple clients.
The enum list in the Help document might be just a reference to illustrate multiple configuration. Generated enum list is based on the configuration done by user in the MCC Melody user interface
HOST_CONFIG |
Custom name for configuration setting: SPI Mode : Mode 1, Sampled at : Middle, Clock Frequency : 0 kHz Custom name for configuration setting: SPI Mode : Mode 2, Sampled at : End, Clock Frequency : 0 kHz |
HOST_CONFIG |
Custom name for configuration setting: SPI Mode : Mode 1, Sampled at : Middle, Clock Frequency : 0 kHz Custom name for configuration setting: SPI Mode : Mode 2, Sampled at : End, Clock Frequency : 0 kHz |
3.22.1.1.4 Variable Documentation
SPI1_Host
const struct SPI_HOST_INTERFACE SPI1_Host
Structure object of type SPI_HOST_INTERFACE assigned with name displayed in the Melody Driver User interface. A structure pointer can be used to achieve portability across the SPI HOST having same interface structure.
3.22.2 Data Structure Documentation
3.22.2.1 SPI_HOST_INTERFACE Struct Reference
Structure containing the function pointers of SPI HOST driver.
3.22.2.1.1 Detailed Description
Structure containing the function pointers of SPI HOST driver.
#include <spi_host_interface.h>
Data Fields
void(* Initialize )(void)
Pointer to SPIx_Initialize e.g. SPI1_Initialize.
void(* Deinitialize )(void)
Pointer to SPIx_Deinitialize e.g. SPI1_Deinitialize.
void(* Close )(void)
Pointer to SPIx_Close e.g. SPI1_Close.
bool(* Open )(uint8_t spiConfigIndex)
Pointer to SPIx_Open e.g. SPI1_Open.
void(* BufferExchange )(void *bufferData, size_t bufferSize)
Pointer to SPIx_BufferExchange e.g. SPI1_BufferExchange.
void(* BufferRead )(void *bufferData, size_t bufferSize)
Pointer to SPIx_BufferRead e.g. SPI1_BufferRead.
void(* BufferWrite )(void *bufferData, size_t bufferSize)
Pointer to SPIx_BufferWrite e.g. SPI1_BufferWrite.
uint8_t(* ByteExchange )(uint8_t byteData)
Pointer to SPIx_ByteExchange e.g. SPI1_ByteExchange.
uint8_t(* ByteRead )(void)
Pointer to SPIx_ByteRead e.g. SPI1_ByteRead.
void(* ByteWrite )(uint8_t byteData)
Pointer to SPIx_ByteWrite e.g. SPI1_ByteWrite.
bool(* IsRxReady )(void)
Pointer to SPIx_IsRxReady e.g. SPI1_IsRxReady.
bool(* IsTxReady )(void)
Pointer to SPIx_IsTxReady e.g. SPI1_IsTxReady.
3.22.2.1.2 Field Documentation
The documentation for this struct was generated from the following file:
source/
BufferExchange
void(* BufferExchange) (void *bufferData, size_t bufferSize)
Pointer to SPIx_BufferExchange e.g. SPI1_BufferExchange.
BufferRead
void(* BufferRead) (void *bufferData, size_t bufferSize)
Pointer to SPIx_BufferRead e.g. SPI1_BufferRead.
BufferWrite
void(* BufferWrite) (void *bufferData, size_t bufferSize)
Pointer to SPIx_BufferWrite e.g. SPI1_BufferWrite.
ByteExchange
uint8_t(* ByteExchange) (uint8_t byteData)
Pointer to SPIx_ByteExchange e.g. SPI1_ByteExchange.
ByteRead
uint8_t(* ByteRead) (void)
Pointer to SPIx_ByteRead e.g. SPI1_ByteRead.
ByteWrite
void(* ByteWrite) (uint8_t byteData)
Pointer to SPIx_ByteWrite e.g. SPI1_ByteWrite.
Close
void(* Close) (void)
Pointer to SPIx_Close e.g. SPI1_Close.
Deinitialize
void(* Deinitialize) (void)
Pointer to SPIx_Deinitialize e.g. SPI1_Deinitialize.
Initialize
void(* Initialize) (void)
Pointer to SPIx_Initialize e.g. SPI1_Initialize.
IsRxReady
bool(* IsRxReady) (void)
Pointer to SPIx_IsRxReady e.g. SPI1_IsRxReady.
IsTxReady
bool(* IsTxReady) (void)
Pointer to SPIx_IsTxReady e.g. SPI1_IsTxReady.
Open
bool(* Open) (uint8_t spiConfigIndex)
Pointer to SPIx_Open e.g. SPI1_Open.
3.22.3 File Documentation
3.22.3.1 source/spi1.h File Reference
This is the generated driver header file for the SPI1 driver.
#include <stdint.h> #include <stdbool.h> #include <stddef.h> #include "spi_host_interface.h"
3.22.3.1.1 Functions
void SPI1_Initialize (void)
Initializes SPI1 module, using the given initialization data. This function must be called before any other SPI1 function is called.
void SPI1_Deinitialize (void)
Deinitializes the SPI1 to POR values.
void SPI1_Close (void)
Disables the SPI1 module.
bool SPI1_Open (uint8_t spiConfigIndex)
Configures SPI1 module with user defined unique configuration.
uint8_t SPI1_ByteExchange (uint8_t byteData)
Exchanges one byte of data. This is a blocking function.
void SPI1_BufferExchange (void *bufferData, size_t bufferSize)
This function is used to transmit data from the buffer pointer and updates the received data in the same buffer location. This is a blocking function.
void SPI1_BufferWrite (void *bufferData, size_t bufferSize)
Writes data from a buffer. This is a blocking routine.
void SPI1_BufferRead (void *bufferData, size_t bufferSize)
Reads data from a buffer. This is a blocking routine.
void SPI1_ByteWrite (uint8_t byteData)
Writes one byte of data.
uint8_t SPI1_ByteRead (void)
Reads one byte of data from SPI1.
bool SPI1_IsRxReady (void)
Returns a boolean value if data is available to read.
bool SPI1_IsTxReady (void)
Returns a boolean value if data can be written.
3.22.3.1.2 Macros
#define SPI1_Host_Initialize SPI1_Initialize
This macro defines the Custom Name for SPI1_Initialize API.
#define SPI1_Host_Deinitialize SPI1_Deinitialize
This macro defines the Custom Name for SPI1_Deinitialize API.
#define SPI1_Host_Close SPI1_Close
This macro defines the Custom Name for SPI1_Close API.
#define SPI1_Host_Open SPI1_Open
This macro defines the Custom Name for SPI1_Open API.
#define SPI1_Host_ByteExchange SPI1_ByteExchange
This macro defines the Custom Name for SPI1_ByteExchange API.
#define SPI1_Host_BufferExchange SPI1_BufferExchange
This macro defines the Custom Name for SPI1_BufferExchange API.
#define SPI1_Host_BufferWrite SPI1_BufferWrite
This macro defines the Custom Name for SPI1_BufferWrite API.
#define SPI1_Host_BufferRead SPI1_BufferRead
This macro defines the Custom Name for SPI1_BufferRead API.
#define SPI1_Host_ByteWrite SPI1_ByteWrite
This macro defines the Custom Name for SPI1_ByteWrite API.
#define SPI1_Host_ByteRead SPI1_ByteRead
This macro defines the Custom Name for SPI1_ByteRead API.
#define SPI1_Host_IsRxReady SPI1_IsRxReady
This macro defines the Custom Name for SPI1_IsRxReady API.
#define SPI1_Host_IsTxReady SPI1_IsTxReady
This macro defines the Custom Name for SPI1_IsTxReady API.
3.22.3.1.3 Enumerations
enum SPI1_HOST_USER_CONFIG { HOST_CONFIG, HOST_CONFIG }
Enum list is the Custom names for the SPI1 HOST multiple configuration, configured by user in MCC Melody user interface. These Host Configurations can be used to switch at runtime to interact with multiple clients.
3.22.3.1.4 Variables
const struct SPI_HOST_INTERFACE SPI1_Host
Structure object of type SPI_HOST_INTERFACE assigned with name displayed in the Melody Driver User interface. A structure pointer can be used to achieve portability across the SPI HOST having same interface structure.
3.22.3.1.5 Detailed Description
This is the generated driver header file for the SPI1 driver.
SPI1 Generated Driver Header File
3.22.3.1.6 Macro Definition Documentation
SPI1_Host_BufferExchange
#define SPI1_Host_BufferExchange SPI1_BufferExchange
This macro defines the Custom Name for SPI1_BufferExchange API.
SPI1_Host_BufferRead
#define SPI1_Host_BufferRead SPI1_BufferRead
This macro defines the Custom Name for SPI1_BufferRead API.
SPI1_Host_BufferWrite
#define SPI1_Host_BufferWrite SPI1_BufferWrite
This macro defines the Custom Name for SPI1_BufferWrite API.
SPI1_Host_ByteExchange
#define SPI1_Host_ByteExchange SPI1_ByteExchange
This macro defines the Custom Name for SPI1_ByteExchange API.
SPI1_Host_ByteRead
#define SPI1_Host_ByteRead SPI1_ByteRead
This macro defines the Custom Name for SPI1_ByteRead API.
SPI1_Host_ByteWrite
#define SPI1_Host_ByteWrite SPI1_ByteWrite
This macro defines the Custom Name for SPI1_ByteWrite API.
SPI1_Host_Close
#define SPI1_Host_Close SPI1_Close
This macro defines the Custom Name for SPI1_Close API.
SPI1_Host_Deinitialize
#define SPI1_Host_Deinitialize SPI1_Deinitialize
This macro defines the Custom Name for SPI1_Deinitialize API.
SPI1_Host_Initialize
#define SPI1_Host_Initialize SPI1_Initialize
This macro defines the Custom Name for SPI1_Initialize API.
SPI1_Host_IsRxReady
#define SPI1_Host_IsRxReady SPI1_IsRxReady
This macro defines the Custom Name for SPI1_IsRxReady API.
SPI1_Host_IsTxReady
#define SPI1_Host_IsTxReady SPI1_IsTxReady
This macro defines the Custom Name for SPI1_IsTxReady API.
SPI1_Host_Open
#define SPI1_Host_Open SPI1_Open
This macro defines the Custom Name for SPI1_Open API.
3.22.3.2 source/spi_host_interface.h File Reference
#include <stdint.h> #include <stdbool.h> #include <stddef.h>
3.22.3.2.1 Data structures
struct SPI_HOST_INTERFACE
Structure containing the function pointers of SPI HOST driver.
3.22.3.2.2 Detailed Description
SPI Generated Driver Interface Header File