Module atsamd_hal::sercom::spi

source · [−]
Expand description

Use a SERCOM peripheral for SPI transactions

Using an SPI peripheral occurs in three steps. First, you must supply gpio Pins to create a set of Pads. Next, you combine the Pads with other pieces to form a Config struct. Finally, after configuring the peripheral, you enable it to yield a functional Spi struct. Transactions are performed using traits from the embedded_hal crate, specifically those from the spi, serial, and blocking modules.

Crating a set of Pads

An SPI peripheral can use up to four Pins as Sercom pads. However, only certain Pin combinations are acceptable. All Pins must be mapped to the same Sercom, and for SAMx5x chips, they must also belong to the same IoSet. This HAL makes it impossible to use invalid Pin combinations, and the Pads struct is responsible for enforcing these constraints.

A Pads type takes five or six type parameters, depending on the chip. The first type always specifies the Sercom. On SAMx5x chips, the second type specifies the IoSet. The remaining four type parameters, DI, DO, CK and SS, represent the Data In, Data Out, Sclk and SS pads respectively. Each of these type parameters is an OptionalPad and defaults to NoneT. A Pad is just a Pin configured in the correct PinMode that implements IsPad. The bsp_pins! macro can be used to define convenient type aliases for Pad types.

use atsamd_hal::gpio::{PA08, PA09, AlternateC};
use atsamd_hal::sercom::{Sercom0, spi};
use atsamd_hal::typelevel::NoneT;

// SAMx5x-specific imports
use atsamd_hal::sercom::pad::IoSet1;

type Miso = Pin<PA08, AlternateC>;
type Sclk = Pin<PA09, AlternateC>;

// SAMD11/SAMD21 version
type Pads = spi::Pads<Sercom0, Miso, NoneT, Sclk>;
// SAMx5x version
type Pads = spi::Pads<Sercom0, IoSet1, Miso, NoneT, Sclk>;

Alternatively, you can use the PadsFromIds alias to define a set of Pads in terms of PinIds instead of Pins. This is useful when you don’t have Pin aliases pre-defined.

use atsamd_hal::gpio::{PA08, PA09};
use atsamd_hal::sercom::{Sercom0, spi};
use atsamd_hal::typelevel::NoneT;

// SAMx5x-specific imports
use atsamd_hal::sercom::pad::IoSet1;

// SAMD21 version
type Pads = spi::PadsFromIds<Sercom0, PA08, NoneT, PA09>;
// SAMx5x version
type Pads = spi::PadsFromIds<Sercom0, IoSet1, PA08, NoneT, PA09>;

Instances of Pads are created using the builder pattern. Start by creating an empty set of Pads using Default. Then pass each respective Pin using the corresponding methods. For SAMD21 and SAMx5x chips, the builder methods automatically convert each pin to the correct PinMode. However, due to inherent ambiguities, users must manually configure PinModes for SAMD11 chips.

use atsamd_hal::target_device::Peripherals;
use atsamd_hal::gpio::Pins;
use atsamd_hal::sercom::{Sercom0, spi};

// SAMx5x-specific imports
use atsamd_hal::sercom::pad::IoSet1;

let mut peripherals = Peripherals::take().unwrap();
let pins = Pins::new(peripherals.PORT);
// SAMD21 version
let pads = spi::Pads::<Sercom0>::default()
    .sclk(pins.pa09)
    .data_in(pins.pa08)
    .data_out(pins.pa11);
// SAMx5x version
let pads = spi::Pads::<Sercom0, IoSet1>::default()
    .sclk(pins.pa09)
    .data_in(pins.pa08)
    .data_out(pins.pa11);

To be accepted by the Config struct as a set of ValidPads, the Pads must do two things:

  • Specify SomePad for CK and at least one of DI or DO
  • Use a valid combination of PadNums, so that the Pads implement DipoDopo

Configuring the peripheral

Next, create a Config struct, which represents the SPI peripheral in its disabled state. A Config is specified with three type parameters: the Pads type; an OpMode, which defaults to Master; and a Size type that varies by chip. Size essentially acts as a trait alias. On SAMD11 and SAMD21 chips, it represents the CharSize, which can either be EightBit or NineBit. While on SAMx5x chips, it represents the transaction Length in bytes, using type-level numbers provided by the typenum crate. Valid transaction lengths, from U1 to U255, are re-exported in the lengths sub-module.

use atsamd_hal::gpio::{PA08, PA09};
use atsamd_hal::sercom::{Sercom0, spi};
use atsamd_hal::sercom::spi::Master;
use atsamd_hal::typelevel::NoneT;

// SAMD11/SAMD21-specific imports
use atsamd_hal::sercom::spi::NineBit;

// SAMx5x-specific imports
use atsamd_hal::sercom::spi::lengths::U2;
use atsamd_hal::sercom::pad::IoSet1;

// SAMD11/SAMD21 version
type Pads = spi::PadsFromIds<Sercom0, PA08, NoneT, PA09>;
type Config = spi::Config<Pads, Master, NineBit>;

// SAMx5x version
type Pads = spi::PadsFromIds<Sercom0, IoSet1, PA08, NoneT, PA09>;
type Config = spi::Config<Pads, Master, U2>;

For simplicity, this module ignores character size on SAMx5x chips. Instead, the SPI peripheral is always configured to use 32-bit extension mode and the hardware LENGTH counter. Note that, due to a hardware bug, ICSPACE must be at least one when using the length counter. See the silicon errata for more details.

Upon creation, the Config takes ownership of both the Pads and the PAC Sercom struct. It takes a reference to the PM or MCLK, so that it can enable the APB clock, and it takes a frequency to indicate the GCLK configuration. Users are responsible for correctly configuring the GCLK.

use atsamd_hal::time::U32Ext;

// Not shown: configure GCLK for 10 MHz

// SAMD11/SAMD21 version
let pm = peripherals.PM;
let sercom = peripherals.SERCOM0;
let freq = 10.mhz();
let config = spi::Config::new(&pm, sercom, pads, freq);

// SAMx5x version
let mclk = peripherals.MCLK;
let sercom = peripherals.SERCOM0;
let freq = 10.mhz();
let config = spi::Config::new(&mclk, sercom, pads, freq);

The Config uses two different APIs for configuration. For most parameters, it provides get_ and set_ methods that take &self and &mut self respectively, e.g. get_bit_order and set_bit_order. However, because Config tracks the OpMode and Size at compile-time, which requires changing the corresponding type parameters, Config also provides a builder-pattern API, where methods take and return self, e.g. bit_order.

Once configured, the enable method consumes the Config and returns an enabled Spi struct that can be used for transactions. Because the enable function takes the Config as self, the builder-pattern API is usually the more ergonomic option.

use embedded_hal::spi::MODE_1;

// SAMD11/SAMD21 version
let spi = spi::Config::new(&pm, sercom, pads, freq)
    .baud(1.mhz())
    .char_size::<NineBit>()
    .bit_order(BitOrder::LsbFirst)
    .spi_mode(MODE_1)
    .enable();

// SAMx5x version
let spi = spi::Config::new(&mclk, sercom, pads, freq)
    .baud(1.mhz())
    .length::<U2>()
    .bit_order(BitOrder::LsbFirst)
    .spi_mode(MODE_1)
    .enable();

To be accepted as a ValidConfig, the Config must have a set of ValidPads that matches its OpMode. In particular, the SS pad must be NoneT for Master mode, where the user is expected to handle it manaully. But it must be SomePad in MasterHWSS and Slave modes, where it is controlled by the hardware.

Using a functional Spi peripheral

An Spi struct has two type parameters. The first is the corresponding Config, while the second represents its Capability, i.e. Rx, Tx or Duplex. The enable function determines the Capability automaically from the set of ValidPads.

use atsamd_hal::gpio::{PA08, PA09};
use atsamd_hal::sercom::{Sercom0, spi};
use atsamd_hal::sercom::spi::{Master, Rx};
use atsamd_hal::typelevel::NoneT;

// SAMD11/SAMD21-specific imports
use atsamd_hal::sercom::spi::NineBit;

// SAMx5x-specific imports
use atsamd_hal::sercom::spi::lengths::U2;
use atsamd_hal::sercom::pad::IoSet1;

// SAMD11/SAMD21 version
type Pads = spi::PadsFromIds<Sercom0, PA08, NoneT, PA09>;
type Config = spi::Config<Pads, Master, NineBit>;
type Spi = spi::Spi<Config, Rx>;

// SAMx5x version
type Pads = spi::PadsFromIds<Sercom0, IoSet1, PA08, NoneT, PA09>;
type Config = spi::Config<Pads, Master, U2>;
type Spi = spi::Spi<Config, Rx>;

Only Spi structs can actually perform transactions. To do so, use the various embedded HAL traits, like spi::FullDuplex, serial::Read or serial::Write. See the impl_ehal module documentation for more details about the specific trait implementations, which vary based on Size and Capability.

use nb::block;
use embedded_hal::spi::FullDuplex;

block!(spi.send(0xAA55));
let rcvd: u16 = block!(spi.read());

Modules

impl_ehal
Implement embedded_hal traits for Spi structs

Structs

Config
A configurable SPI peripheral in its disabled state
Duplex
Type-level variant of the Capability enum for duplex transactions
Flags
Interrupt bit flags for SPI transactions
Pads
Container for a set of SERCOM pads
Rx
Type-level variant of the Capability enum for simplex, Receive-only transactions
Spi
An enabled SPI peripheral that can perform transactions
Status
Status bit flags for SPI transactions
Tx
Type-level variant of the Capability enum for simplex, Transmit-only transactions

Enums

BitOrder
Define the bit order of transactions
EightBit
CharSize variant for 8-bit transactions
Error
Error enum for SPI transactions
Master
OpMode variant for Master mode
MasterHWSS
OpMode variant for Master mode with hardware-controlled slave select
NineBit
CharSize variant for 9-bit transactions
Phase
Clock phase
Polarity
Clock polarity
Slave
OpMode variant for Slave mode

Constants

MODE_0
Helper for CPOL = 0, CPHA = 0
MODE_1
Helper for CPOL = 0, CPHA = 1
MODE_2
Helper for CPOL = 1, CPHA = 0
MODE_3
Helper for CPOL = 1, CPHA = 1

Traits

AnyConfig
Type class for all possible Config types
AnySpi
Type class for all possible Spi types
AtomicSize
Marker trait for transaction Sizes that can be completed in a single read or write of the DATA register
Capability
Type-level enum representing the simplex or duplex transaction capability
CharSize
Type-level enum representing the SPI character size
DipoDopo
Configure the DIPO and DOPO fields based on a set of Pads
MasterMode
Marker trait for Master operating modes
OpMode
Type-level enum representing the SPI operating mode
PadSet
Type-level function to recover the OptionalPad types from a generic set of Pads
Receive
Sub-set of Capability variants that can receive data, i.e. Rx and Duplex
Size
Trait alias whose definition varies by chip
Transmit
Sub-set of Capability variants that can transmit dat, i.e. Tx and Duplex
ValidConfig
Marker trait for valid SPI Configurations
ValidPads
Marker trait for valid sets of Pads

Type Definitions

DataWidth
Type alias for the width of the DATA register
DefaultSize
Type alias for the default Size type, which varies by chip
PadsFromIds
Define a set of Pads using PinIds instead of Pins
SpecificConfig
Type alias to recover the specific Config type from an implementation of AnyConfig
SpecificSpi
Type alias to recover the specific Spi type from an implementation of AnySpi
Word
Type alias to recover the Word type from an implementation of CharSize