MEGARF SPI master service.

This is the API for SPI master service on MEGARF.

Quick Start Guide

See Quick Start Guide for the SPI Master Driver

Data Structures
struct	spi_device

Variables
port_pin_t	spi_device::id

Spi Master Management Configuration
typedef uint8_t	spi_flags_t
typedef uint32_t	board_spi_select_id_t
void	spi_master_init (volatile void *spi)
	Initializes the SPI in master mode. More...
void	spi_master_setup_device (volatile void *spi, struct spi_device *device, spi_flags_t flags, unsigned long baud_rate, board_spi_select_id_t sel_id)
	Setup a SPI device. More...
void	spi_select_device (volatile void *spi, struct spi_device *device)
	Select given device on the SPI bus. More...
void	spi_deselect_device (volatile void *spi, struct spi_device *device)
	Deselect given device on the SPI bus. More...
status_code_t	spi_write_packet (volatile void *spi, const uint8_t *data, size_t len)
	Send a sequence of bytes to a SPI device. More...
status_code_t	spi_read_packet (volatile void *spi, uint8_t *data, size_t len)
	Receive a sequence of bytes from a SPI device. More...
static void	spi_read_single (volatile void *spi, uint8_t *data)
	Receive one byte from a SPI device. More...
static __always_inline void	spi_write_single (volatile void *spi, uint8_t data)
	Write one byte to a SPI device. More...
static bool	spi_is_tx_empty (volatile void *spi)
	Checks if all transmissions are complete. More...
static bool	spi_is_tx_ready (volatile void *spi)
	Checks if all transmissions is ready. More...
static bool	spi_is_rx_full (volatile void *spi)
	Tests if the SPI contains a received character. More...
static bool	spi_is_rx_ready (volatile void *spi)
	Checks if all reception is ready. More...
#define	CONFIG_SPI_MASTER_DUMMY   0xFF
#define	SPI_CPHA   (1 << 0)
	Clock phase. More...
#define	SPI_CPOL   (1 << 1)
	Clock polarity. More...
#define	SPI_MODE_0   0
	SPI mode 0. More...
#define	SPI_MODE_1   (SPI_CPHA)
	SPI mode 1. More...
#define	SPI_MODE_2   (SPI_CPOL)
	SPI mode 2. More...
#define	SPI_MODE_3   (SPI_CPOL | SPI_CPHA)
	SPI mode 3. More...

Quick start guide for SPI master on MEGARF devices

Basic setup for MEGARF devices

The SPI module will be set up as master:

• SPI on PORTB
• FOSC/16 as SPI clock speed
• Slave Chip Select connected on PORTB pin 0
• SPI mode 0 (data on rising clock edge)

Workflow

Example code

Add to application C-file (e.g. main.c):

#define SPI_SCK       IOPORT_CREATE_PIN(PORTB, 1)
#define SPI_MOSI      IOPORT_CREATE_PIN(PORTB, 2)
#define SPI_MISO      IOPORT_CREATE_PIN(PORTB, 3)
#define SPI_SS        IOPORT_CREATE_PIN(PORTB, 0)

 void spi_init_pins(void)
 {
     gpio_configure_pin(SPI_SCK, IOPORT_INIT_HIGH | IOPORT_DIR_OUTPUT);
     gpio_configure_pin(SPI_MOSI, IOPORT_INIT_HIGH | IOPORT_DIR_OUTPUT);
     gpio_configure_pin(SPI_MISO, IOPORT_DIR_INPUT);
     gpio_configure_pin(SPI_SS, IOPORT_INIT_HIGH | IOPORT_DIR_OUTPUT);
 }

 void spi_init_module(void)
 {
    struct spi_device spi_device_conf = {
        .id = IOPORT_CREATE_PIN(PORTB, 0)
    };

    spi_master_init(&SPCR);
    spi_master_setup_device(&SPCR, &spi_device_conf, SPI_MODE_0,
      1000000,0);
    spi_enable(&SPCR);
 }

Workflow

1. Ensure that conf_spi_master.h is present for the driver.

   • Note

     This file is only for the driver and should not be included by the user. In this example the file can be left empty.

2. Initialize the pins used by the SPI interface (this initialization is for the ATmega128rfa1 device).
3. Define the pins used by the SPI interface

   • #define SPI_SCK       IOPORT_CREATE_PIN(PORTB, 1)
     #define SPI_MOSI      IOPORT_CREATE_PIN(PORTB, 2)
     #define SPI_MISO      IOPORT_CREATE_PIN(PORTB, 3)
     #define SPI_SS        IOPORT_CREATE_PIN(PORTB, 0)

   1. Set the pin used for slave select as output high:

      ioport_configure_port_pin(SPI_SS, IOPORT_INIT_HIGH | IOPORT_DIR_OUTPUT);

   2. Set MOSI and SCL as output high, and set MISO as input:

      ioport_configure_port_pin(SPI_SCK, IOPORT_INIT_HIGH | IOPORT_DIR_OUTPUT);
      ioport_configure_port_pin(SPI_MOSI, IOPORT_INIT_HIGH | IOPORT_DIR_OUTPUT);
      ioport_configure_port_pin(SPI_MISO, IOPORT_DIR_INPUT);

4. Define the SPI device configuration struct to describe which pin the slave select (slave chip select) is connected to, in this case the slave select pin has been connected to PORTB pin 0 (PB0):

   • struct spi_device spi_device_conf = {
         .id = IOPORT_CREATE_PIN(PORTB, 0)
     };

5. Initialize the SPI module:

   • spi_master_init(&SPCR);

6. Setup the SPI master module for a specific device:

   • spi_master_setup_device(&SPCR, &spi_device_conf, SPI_MODE_0, 1000000, 0);

   • Note

     The last argument, which is zero in this case, can be ignored and is only included for compatibility purposes.

7. Then enable the SPI:

   • spi_enable(&SPCR);

Usage steps

Example code

Add to, e.g., the main loop in the application C-file:

uint8_t data_buffer[1] = {0xD7};

struct spi_device spi_device_conf = {
    .id = IOPORT_CREATE_PIN(PORTB, 0)
};

spi_select_device(&SPCR, &spi_device_conf);

spi_write_packet(&SPCR, data_buffer, 1);
spi_read_packet(&SPCR, data_buffer, 1);

spi_deselect_device(&SPCR, &spi_device_conf);

Workflow

1. Create a buffer for data to be sent/received on the SPI bus, in this case a single byte buffer is used. The buffer can be of arbitrary size as long as there is space left in SRAM:

   • uint8_t data_buffer[1] = {0xD7};

2. Define the SPI device configuration struct to describe which pin the slave select (slave chip select) is connected to, in this case the slave select pin has been connected to PORTB pin01 (PB0):

   • struct spi_device spi_device_conf = {
         .id = IOPORT_CREATE_PIN(PORTB, 0)
     };

   • Note

     As this struct is the same for both the initializing part and the usage part it could be a good idea to make the struct global, and hence accessible for both the initializing part and usage part. Another solution could be to create the struct in the main function and pass the address of the struct to the spi_init_module() function, e.g.:

     void spi_init_module(struct spi_device *spi_device_conf)
     {
         ...
     
         spi_master_setup_device(&SPCR, spi_device_conf, SPI_MODE_0, 
         1000000, 0);
     
         ...
     }

3. Write data to the SPI slave device, in this case write one byte from the data_buffer:

   • spi_write_packet(&SPCR, data_buffer, 1);

4. Read data from the SPI slave device, in this case read one byte and put it into the data_buffer:

   • spi_read_packet(&SPCR, data_buffer, 1);

   • Attention

     As the SPI works as a shift register so that data is shifted in at the same time as data is shifted out a read operation will mean that a dummy byte CONFIG_SPI_MASTER_DUMMY is written to the SPI bus. CONFIG_SPI_MASTER_DUMMY defaults to 0xFF, but can be changed by defining it inside the conf_spi_master.h file.

5. When read and write operations is done de-select the slave:

   • spi_deselect_device(&SPCR, &spi_device_conf);

#define CONFIG_SPI_MASTER_DUMMY   0xFF

Referenced by spi_read_packet().

#define SPI_CPHA   (1 << 0)

Clock phase.

#define SPI_CPOL   (1 << 1)

Clock polarity.

#define SPI_MODE_0   0

SPI mode 0.

#define SPI_MODE_1   (SPI_CPHA)

SPI mode 1.

#define SPI_MODE_2   (SPI_CPOL)

SPI mode 2.

#define SPI_MODE_3   (SPI_CPOL | SPI_CPHA)

SPI mode 3.

typedef uint32_t board_spi_select_id_t

typedef uint8_t spi_flags_t

void spi_deselect_device	(	volatile void *	spi,
		struct spi_device *	device
	)

Deselect given device on the SPI bus.

Calls board chip deselect.

Parameters

spi	Base address of the SPI instance.
device	SPI device

References spi_device::id, and ioport_set_pin_high().

static bool spi_is_rx_full ( volatile void *  spi )

inlinestatic

Tests if the SPI contains a received character.

Parameters

spi	Base address of the SPI instance.

Returns

1 if the SPI Receive Holding Register is full, otherwise 0.

References spi_is_tx_ok().

Referenced by epd_spi_read(), and spi_read_packet().

static bool spi_is_rx_ready ( volatile void *  spi )

inlinestatic

Checks if all reception is ready.

Parameters

spi	Base address of the SPI instance.

Returns

1 if the SPI Receiver is ready, otherwise 0.

References spi_is_tx_ok().

static bool spi_is_tx_empty ( volatile void *  spi )

inlinestatic

Checks if all transmissions are complete.

Parameters

spi	Base address of the SPI instance.

Returns

Status.

Return values

1	All transmissions complete.
0	Transmissions not complete.

References spi_is_tx_ok().

Referenced by epd_spi_write(), and spi_write_packet().

static bool spi_is_tx_ready ( volatile void *  spi )

inlinestatic

Checks if all transmissions is ready.

Parameters

spi	Base address of the SPI instance.

Returns

Status.

Return values

1	All transmissions complete.
0	Transmissions not complete.

References spi_is_tx_ok().

void spi_master_init

(

volatile void *

spi

)

Initializes the SPI in master mode.

Parameters

spi	Base address of the SPI instance.

References PRSPI_bm, spi_enable_master_mode(), and sysclk_enable_module().

Referenced by at45dbx_spi_init(), epd_spi_init(), and main().

void spi_master_setup_device	(	volatile void *	spi,
		struct spi_device *	device,
		spi_flags_t	flags,
		unsigned long	baud_rate,
		board_spi_select_id_t	sel_id
	)

Setup a SPI device.

The returned device descriptor structure must be passed to the driver whenever that device should be used as current slave device.

Parameters

spi	Base address of the SPI instance.
device	Pointer to SPI device struct that should be initialized.
flags	SPI configuration flags. Common flags for all implementations are the SPI modes SPI_MODE_0 ... SPI_MODE_3.
baud_rate	Divider for Baud rate setting.
sel_id	Board specific select id

status_code_t spi_read_packet	(	volatile void *	spi,
		uint8_t *	data,
		size_t	len
	)

Receive a sequence of bytes from a SPI device.

All bytes sent out on SPI bus are sent as value 0.

Parameters

spi	Base address of the SPI instance.
data	data buffer to read
len	Length of data

Precondition

SPI device must be selected with spi_select_device() first

References CONFIG_SPI_MASTER_DUMMY, spi_is_rx_full(), spi_write_single(), and STATUS_OK.

Referenced by spi_at45dbx_mem_check().

static void spi_read_single ( volatile void *  spi, uint8_t *  data  )

inlinestatic

Receive one byte from a SPI device.

Parameters

spi	Base address of the SPI instance.
data	Pointer to the data byte where to store the received data.

References spi_get().

void spi_select_device	(	volatile void *	spi,
		struct spi_device *	device
	)

Select given device on the SPI bus.

Set device specific setting and calls board chip select.

Parameters

spi	Base address of the SPI instance.
device	SPI device

References spi_device::id, and ioport_set_pin_low().

status_code_t spi_write_packet	(	volatile void *	spi,
		const uint8_t *	data,
		size_t	len
	)

Send a sequence of bytes to a SPI device.

Received bytes on the SPI bus are discarded.

Parameters

spi	Base address of the SPI instance.
data	data buffer to write
len	Length of data

Precondition

SPI device must be selected with spi_select_device() first

References spi_is_tx_empty(), spi_write_single(), and STATUS_OK.

Referenced by spi_at45dbx_mem_check().

static __always_inline void spi_write_single ( volatile void *  spi, uint8_t  data  )

static

Write one byte to a SPI device.

Parameters

spi	Base address of the SPI instance.
data	The data byte to be loaded

References spi_put().

Referenced by epd_spi_read(), epd_spi_write(), spi_read_packet(), and spi_write_packet().

port_pin_t spi_device::id

Referenced by spi_deselect_device(), and spi_select_device().