platform-adc.hh

#pragma once
#include <debug.hh>
#include <stdint.h>
#include <utils.hh>
 
/**
 * A simple driver for Sonata's XADC (Xilinx Analogue to Digital Converter).
 *
 * Documentation source can be found at:
 * https://github.com/lowRISC/sonata-system/blob/97a525c48f7bf051b999d0178dba04859819bc5e/doc/ip/adc.md
 *
 * Rendered documentation is served from:
 * https://lowrisc.github.io/sonata-system/doc/ip/adc.html
 */
class SonataAnalogueDigitalConverter : private utils::NoCopyNoMove
{
    /**
     * Flag to set when debugging the driver for UART log messages.
     */
    static constexpr bool DebugDriver = false;
 
    /**
     * Helper for conditional debug logs and assertions.
     */
    using Debug = ConditionalDebug<DebugDriver, "ADC">;
 
    /**
     * Results of measurements / analogue conversions are stored in Dynamic
     * Reconfiguration Port (DRP) status registers as most-significant-bit
     * justified 12 bit values, represented by this mask.
     */
    static constexpr uint16_t MeasurementMask = 0xFFF0;
 
    /**
     * The location (offset) of the Xilinx Analogue-to-Digital Converter's
     * Dynamic Reconfiguration Port (DRP) registers, which are 16-bit registers
     * that are sequentially mapped to memory in 4-byte (word) intervals, in the
     * lower 2 bytes of each word. This includes both status (read-only) and
     * control (read/write) registers.
     *
     * https://docs.amd.com/r/en-US/ug480_7Series_XADC/XADC-Register-Interface
     */
    enum class RegisterOffset : uint8_t
    {
        Temperature                      = 0x00,
        VoltageInternalSupply            = 0x01,
        VoltageAuxiliarySupply           = 0x02,
        VoltageDedicated                 = 0x03,
        VoltageInternalPositiveReference = 0x04,
        VoltageInternalNegativeReference = 0x05,
        VoltageBlockRamSupply            = 0x06,
 
        /* Offset 0x07 is undefined. */
 
        /* ADC A's calibration coefficient status registers omitted. */
 
        /* Offsets 0x0B and 0x0C are undefined. */
 
        /* Zynq-700 SoC-specific voltage status registers omitted. */
 
        VoltageAuxiliary0  = 0x10,
        VoltageAuxiliary1  = 0x11,
        VoltageAuxiliary2  = 0x12,
        VoltageAuxiliary3  = 0x13,
        VoltageAuxiliary4  = 0x14,
        VoltageAuxiliary5  = 0x15,
        VoltageAuxiliary6  = 0x16,
        VoltageAuxiliary7  = 0x17,
        VoltageAuxiliary8  = 0x18,
        VoltageAuxiliary9  = 0x19,
        VoltageAuxiliary10 = 0x1A,
        VoltageAuxiliary11 = 0x1B,
        VoltageAuxiliary12 = 0x1C,
        VoltageAuxiliary13 = 0x1D,
        VoltageAuxiliary14 = 0x1E,
        VoltageAuxiliary15 = 0x1F,
 
        /* Maximum & minimum sensor measurement status registers omitted. */
 
        /* Offsets 0x2B and 0x2F are undefined. */
 
        /* ADC B's calibration coefficient status registers omitted. */
 
        /* Offsets 0x33 to 0x3E are undefined. */
 
        FlagRegister    = 0x3F,
        ConfigRegister0 = 0x40,
        ConfigRegister1 = 0x41,
        ConfigRegister2 = 0x42,
 
        /* 0x43 to 0x47 are factory test registers and so are omitted. */
 
        /* Sequence and Alarm control registers are emitted. */
    };
 
    /**
     * Definitions of fields (and their locations) within the Xilinx
     * Analogue-to-digital Converter's Config Register 2 (offset 0x42).
     *
     * https://docs.amd.com/r/en-US/ug480_7Series_XADC/Control-Registers?section=XREF_53021_Configuration
     */
    enum ConfigRegister2Field : uint16_t
    {
        /* Bits 0-3 are invalid and should not be interacted with. */
 
        /**
         * Power-down bits for the Analogue-to-Digital Converter.
         */
        PowerDownMask = 0x3 << 4,
 
        /* Bits 6-7 are invalid and should not be interacted with. */
 
        /**
         * Bits used to select the division ratio between the Dynamic
         * Reconfiguration Port clock (DCLK) and the lower frequency
         * Analogue-to- Digital Converter Clock (ADCCLK). Values of 0 and 1 are
         * mapped to a divider of 2 by the DCLK divider selection specification.
         * All other values are mapped identically; the minimum division ratio
         * is 2.
         */
        ClockDividerMask = 0xFF << 8,
    };
 
    /**
     * A helper that returns a pointer to the Analogue-to-Digital Converter
     * (ADC)'s memory, which is mapped to the Dynamic Reconfiguration Port (DRP)
     * registers used by the ADC.
     */
    [[nodiscard, gnu::always_inline]] volatile uint32_t *registers() const
    {
        return MMIO_CAPABILITY(uint32_t, adc);
    }
 
    /**
     * Read the contents of a Dynamic Reconfiguration Port (DRP) register from
     * memory. DRP registers are 16 bits wide but are mapped sequentially in
     * memory, using 4 bytes per register, with the relevant data written in the
     * lower 16 bits.
     *
     * The single argument is the register to read the value of.
     */
    [[nodiscard]] uint16_t register_read(RegisterOffset reg) const
    {
        uint8_t registerOffset = static_cast<uint8_t>(reg);
        return static_cast<uint16_t>(registers()[registerOffset]);
    }
 
    /**
     * Write to the contents of a Dynamic Reconfiguration Port (DRP) register in
     * memory. DRP Registers are 16 bits wide but are mapped sequentially in
     * memory, using 4 bytes per register, with the relevant data written to the
     * lower 16 bits.
     *
     * The first argument is the register to write to.
     * The second argument is the value to write to the register.
     */
    void register_write(RegisterOffset reg, uint16_t value) const
    {
        uint8_t registerOffset      = static_cast<uint8_t>(reg);
        registers()[registerOffset] = static_cast<uint32_t>(value);
    }
 
    /**
     * Sets the relevant bits of a Dynamic Reconfiguration Port (DRP) register
     * in memory. This acts like `register_write`, but additionally takes a
     * mask so that it only overwrites specified bits of the register, and
     * retains the value of all unselected bits.
     *
     * The first argument is the register to write to.
     * The second argument is the mask of bits in the register to write to.
     * The third argument is the values that will be written to the register
     * according to the mask.
     */
    void register_set_bits(RegisterOffset reg,
                           uint16_t       bitMask,
                           uint16_t       bitValues) const
    {
        uint16_t registerBits = register_read(reg);
        registerBits &= ~bitMask;            /* Clear bits in the mask. */
        registerBits |= bitMask & bitValues; /* Set values of masked bits. */
        return register_write(reg, registerBits);
    }
 
    public:
    /**
     * Represents the offsets of the Xilinx Analogue-to-Digital Converter's
     * (XADC) Dynamic Reconfiguration Port (DRP) status registers that are used
     * to store values that are measured/sampled by the XADC, forming a mapping
     * that provides a more comprehensible interface.
     *
     * https://lowrisc.github.io/sonata-system/doc/ip/adc.html
     */
    enum class MeasurementRegister : uint8_t
    {
        ArduinoA0   = static_cast<uint8_t>(RegisterOffset::VoltageAuxiliary4),
        ArduinoA1   = static_cast<uint8_t>(RegisterOffset::VoltageAuxiliary12),
        ArduinoA2   = static_cast<uint8_t>(RegisterOffset::VoltageAuxiliary5),
        ArduinoA3   = static_cast<uint8_t>(RegisterOffset::VoltageAuxiliary13),
        ArduinoA4   = static_cast<uint8_t>(RegisterOffset::VoltageAuxiliary6),
        ArduinoA5   = static_cast<uint8_t>(RegisterOffset::VoltageAuxiliary14),
        Temperature = static_cast<uint8_t>(RegisterOffset::Temperature),
        VoltageInternalSupply =
          static_cast<uint8_t>(RegisterOffset::VoltageInternalSupply),
        VoltageAuxiliarySupply =
          static_cast<uint8_t>(RegisterOffset::VoltageAuxiliarySupply),
        VoltageInternalReferencePositive = static_cast<uint8_t>(
          RegisterOffset::VoltageInternalPositiveReference),
        VoltageInternalReferenceNegative = static_cast<uint8_t>(
          RegisterOffset::VoltageInternalNegativeReference),
        VoltageBlockRamSupply =
          static_cast<uint8_t>(RegisterOffset::VoltageBlockRamSupply),
    };
 
    /**
     * Possible power down modes that can be set in Config Register 2.
     *
     * https://docs.amd.com/r/en-US/ug480_7Series_XADC/Control-Registers?section=XREF_93518_Power_Down
     */
    enum class PowerDownMode : uint8_t
    {
        None = 0b00, /* Default */
        /* 0b01 is not valid, and should not be selected. */
        ConverterB     = 0b10,
        BothConverters = 0b11,
    };
 
    /**
     * The Xilinx Analogue-to-Digtal Converter can sample at a maximum rate of 1
     * Megasample per second. It uses 16 bit Dynamic Reconfiguration Port (DRP)
     * registers, and stores 12-bit measurements, which are stored most-
     * significant-bit justified.
     *
     * https://docs.amd.com/r/en-US/ug480_7Series_XADC/XADC-Overview
     */
    static constexpr size_t MaxSamples          = 1 * 1000 * 1000;
    static constexpr size_t RegisterSize        = 16;
    static constexpr size_t MeasurementBitWidth = 12;
 
    /**
     * The minimum permissible Analogue-to-Digital Clock speed is 1 MHz, and the
     * maximum is 26 MHz, as per the data sheet.
     *
     * See table 65 on page 57:
     * https://docs.amd.com/v/u/en-US/ds181_Artix_7_Data_Sheet
     */
    static constexpr size_t MinClockFrequencyHz = 1 * 1000 * 1000;
    static constexpr size_t MaxClockFrequencyHz = 26 * 1000 * 1000;
 
    /**
     * A clock divider value to be used by the Xilinx Analogue-to-Digital
     * Converter (XADC), which divides its input clock (the system clock)
     * by this divider to determine the clock of the XADC. This clock
     * must fall between specified maximum and minimum frequency, and the
     * divider must be an 8-bit integer, greater than 2.
     */
    typedef uint8_t ClockDivider;
 
    /**
     * Constructor - initialises the MMIO capability for the Analogue-to-
     * Digital converter, and then sets its clock divider and power down
     * mode.
     *
     * Takes the clock divider and power down modes to initialise. The
     * clock divider should divide the system clock to create a signal
     * between 1 and 26 MHz, and should be at least 2.
     */
    SonataAnalogueDigitalConverter(ClockDivider  divider,
                                   PowerDownMode powerDown)
    {
        set_clock_divider(divider);
        set_power_down(powerDown);
        /* The analogue-to-digital converter starts up in independent ADC mode
        by default, monitoring all channels, and so no further initialisation
        logic is needed. */
    }
 
    /**
     * Constructor, without any manual setting of the clock divider. Initialises
     * the MMIO capability for the Analogue-to-Digtal converter, and then sets
     * its power down mode.
     *
     * Takes the power down mode to initialise.
     */
    SonataAnalogueDigitalConverter(PowerDownMode powerDown)
    {
        set_power_down(powerDown);
        /* The Analogue-to-digital converter starts up in independent ADC mode
        by default, monitoring all channels, and so no further initialisation
        logic is needed. */
    }
 
    /**
     * Sets the clock divider for the Sonata Analogue-to-Digital Converter
     * (ADC), which is used to divide the system clock to create the ADC clock.
     *
     * The clock divider to use is provided as the single argument. It must be
     * such that it creates a signal between 1 and 26 MHz, and should be at
     * least 2.
     */
    void set_clock_divider(ClockDivider divider)
    {
        Debug::Assert((divider >= 2), "The ADC divider must be at least 2");
        Debug::Assert(
          (CPU_TIMER_HZ / divider >= MinClockFrequencyHz),
          "The given divider causes the ADC clock to underclock its minimum.");
        Debug::Assert(
          (CPU_TIMER_HZ / divider <= MaxClockFrequencyHz),
          "The given divider causes the ADC clock to overclock its maximum.");
        register_set_bits(
          RegisterOffset::ConfigRegister2, ClockDividerMask, (divider << 8));
    }
 
    /**
     * Sets the power down configuration for the Sonata Analogue-to-Digital
     * Converter (ADC). Calling this function allows either ADC B or the entire
     * XADC to be **permanently** powered down.
     *
     * The power down mode to set is provided as an argument.
     */
    void set_power_down(PowerDownMode powerdown)
    {
        register_set_bits(RegisterOffset::ConfigRegister2,
                          PowerDownMask,
                          (static_cast<uint16_t>(powerdown) << 4));
    }
 
    /**
     * Reads the most recent output of the analogue-to-digital converter's
     * measurements from a specified status register, corresponding to
     * measurement of some channel. This currently assumes unipolar operation,
     * which means all values are positive.
     *
     * The status register to read the last measurement of is given as the
     * single argument.
     *
     * The output values can be translated to the relevant units being measured
     * by using the transfer functions defined in documentation:
     * https://docs.amd.com/r/en-US/ug480_7Series_XADC/ADC-Transfer-Functions
     */
    [[nodiscard]] int16_t read_last_measurement(MeasurementRegister reg) const
    {
        uint16_t measurement = register_read(static_cast<RegisterOffset>(reg));
        measurement &= MeasurementMask;
        measurement >>= (RegisterSize - MeasurementBitWidth);
 
        /* Currently just simple logic that assumes a unipolar analogue
        measurement: to extend support to bipolar measurement, a mechanism for
        tracking whether a measurement is bipolar or not must be introduced, and
        if so, then the negative 12-bit two's complement values must be sign
        extended first. */
        return static_cast<int16_t>(measurement);
    }
};