sdk/include/platform/sunburst/platform-adc.hh - 3p/cheriot-rtos - Git at Google

 #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 = true;

 	/**
 	 * 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);
 	}
 };
	#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 = true;

	/**
	* 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);
	}
	};