Support for SPI and EEPROM in amc board

[marcoaccame]

This PR adds to embot::hw the support for SPI, EEPROM and the STM chip M95512DF which is a ... spi EEPROM mounted on the amc board.

This PR also requires this one on icub-firmware-shared.

The code was tested on the amc board on a dedicated project and works fine.

IMPORTANT.

The SPI driver with the added configuration features for speed, datasize and shape of the frame is ready to use by a AEA sensor (or other absolute SPI encoder) which can be attached to the J5 connector of the amc board. The driver for the AEA is yet to be developed but can follow the guideline that I have used for embot::hw::chip::M95512DF

For this reason, in the SPI driver and for the M95512DF chip I have also added some documentation and for the M95512DF chip also a test function which describes how to use the chip.

Here are some more details.

Configuration of the embot::hw::spi driver

The driver can be configured through embot::hw::spi::Config which allows, so far, to adapt
speed, datasize and shape of the SPI dataframe.

The pinout of the clock (SCLK), master output/slave input (MOSI), master input/slave output (MISO),
and slave select (SS) are for now not managed in here. They are initted at startup by embot::hw::bsp::init().

The embot::hw::spi::Prescaler

It allows to scale the bus used by SPI to match some discrete speeds.

The embot::hw::spi::DataSize

It allows to form a dataframe of different sizes.

The embot::hw::spi::Mode

It shapes the data frame. That can happens in four different modes whiche end up in binary values of
two parameters: the clock polarity (CPOL) and the clock phase (CPHA).

A CPOL = 0 means that the clock line idles low and similarly CPOL = 1 means clock line idles high.
And if CPHA = 0 the bits are sampled on the leading clock edge, else if CPHA = 1 ar ecampled on the trailing ege.

All four possible combinations are shown in the following figure, alongside with the values of embot::shw::spi::Mode used in the embot::hw::spi driver.

                    CPHA = 0              CPHA = 1                               
              samples on leading     samples on trailing
                      |                     |  
CPOL = 0              v___               ___v      
CLK idles low       __|   |__         __|   |__
                    Mode::zero        Mode::one
    
              samples on leading     samples on trailing       
                      |                     |
CPOL = 1            __v    __         __    v__
CKL idles high        |___|             |___|
                    Mode::two        Mode::tree

Figure. Description of embot::shw::spi::Mode.

Description of the embot::hw::chip::M95512DF

This class embot::hw::chip::M95512DF implements a device driver for the chip M95512-DF which is an SPI EEPROM of size 64 KB and page size 128 B.

                Vcc
                 |
             ---------
            |         |
       D ---|         |
       C ---|         |
      nS --o| M95xxx  |--- Q
      nW --o|         |
   nHOLD --o|         |
            |         |
             --------- 
                |
               Vss

Figure 1. Logic diagram.

Signal name	Function	Direction	Description
C	Serial Clock	Input
D	Serial data input	Input
Q	Serial data output	Output
nS	Chip select	Input	When this input signal is high, the device is deselected. Driving Chip select low selects the device.
nW	Write protect	Input	The main purpose of this input signal is to freeze the size of the area of memory that is protected against Write instructions.
nHOLD	Hold	Input	Used to pause any serial communications with the device without deselecting the device
Vcc	Supply voltage	-
Vss	Ground	-

Table 1. Signals.

Basic usage

You can use the following code, as long as the settings for SPI are specified by the bsp of the board.

#include "embot_hw_chip_M95512DF.h"

bool ok = embot::hw::chip::M95512DF::testof_M95512DF();

Code listing. Usage of the class

#if defined(EMBOT_HW_CHIP_M95512DF_enable_test)    

// it tests the chip and offers an example of use
bool embot::hw::chip::testof_M95512DF()
{    
    // this configuration tells about which spi bus to use, which are the control pins
    // and their low level GPIO configuration
    // some extra info:
    // 1. this configuration is typically used by the embot::hw::eeprom and defined
    //    inside embot::hw::eeprom::thebsp located inside mbot_hw_bsp_nameofboard.cpp
    // 2. the spi bus in here specified is initted by M95512DF code w/ a 
    //    call to embot::hw::spi::init() in a way that is specified by
    //    embot::hw::spi::thebsp typically placed inside embot_hw_bsp_nameofboard.cpp
    // 3. the control pins are initialised / deinitialised inside M95512DF only if
    //    embot::hw::chip::M95512DF::Config::PinControl::config.isvalid()
    constexpr embot::hw::chip::M95512DF::Config cfg 
    {
        embot::hw::SPI::six,  // the spi bus
        //{}, // dummy spi config
        {embot::hw::spi::Prescaler::eight, embot::hw::spi::DataSize::eight, embot::hw::spi::Mode::zero},
        {   // the control pins
            {embot::hw::GPIO::PORT::G, embot::hw::GPIO::PIN::eight},    // nS
            {embot::hw::GPIO::PORT::F, embot::hw::GPIO::PIN::twelve},   // nW
            {embot::hw::GPIO::PORT::F, embot::hw::GPIO::PIN::thirteen}, // nHOLD   
            {   // GPIO configuration of the control pins
                embot::hw::gpio::Mode::OUTPUTpushpull,
                embot::hw::gpio::Pull::nopull,
                embot::hw::gpio::Speed::veryhigh
            }        
        }    
    };
    
    // address in EEPROM, data to write, destination for data to read
    constexpr embot::hw::chip::M95512DF::ADR adr {64};
    static constexpr uint8_t bytes2write[8] {1, 2, 3, 4, 5, 6, 7, 8};
    constexpr embot::core::Data data2write {bytes2write, sizeof(bytes2write)};
    uint8_t bytes2read[4] {0};
    embot::core::Data data2read {bytes2read, sizeof(bytes2read)}; 
        
    // step 01: create the object
    embot::hw::chip::M95512DF *chipM95512DF = new embot::hw::chip::M95512DF;
    
    bool ok {false};
    
    // step 02: initialise it (for extra check i also deinit and init it again)   
    chipM95512DF->init(cfg);
    chipM95512DF->deinit();
    if(true == chipM95512DF->init(cfg))
    {  
        // step 03: write some data to EEPROM
        if(true == chipM95512DF->write(adr, data2write))
        {
            // step 04: read data back
            if(true == chipM95512DF->read(adr+1, data2read))
            {
                // step 05: compare them
                ok = (bytes2read[0] == bytes2write[1]) ? true : false;
            }
        }                   
    }

    // step 06: print result
    embot::core::print(ok ? "test chipM95512DF: OK" : "test chipM95512DF: KO");   
    
    // step 07: delete the object: the destructor also deinits
    delete chipM95512DF;
    
    return ok;
}


#endif

Code listing. Usage of the class, part 2.

Caveat Emptor

The interface of the device driver is kept intentionally simple and some features are left (for now) inside the private implementation.

References

[1] Datasheet of M95512-W M95512-R M95512-DF, DS4192 - Rev 24 - September 2021