sdk/include/platform/synopsis/platform-uart.hh

#pragma once
#pragma push_macro("CHERIOT_PLATFORM_CUSTOM_UART")
#define CHERIOT_PLATFORM_CUSTOM_UART
#include_next <platform-uart.hh>
#pragma pop_macro("CHERIOT_PLATFORM_CUSTOM_UART")

/**
 * The Synopsis extended 16550 UART has two additional registers that are not
 * part of a standard 16550, one of which allows for fractional multipliers.
 *
 * This is always instantiated with 32-bit device registers.  The default baud
 * rate is set as a template parameter and can be overridden in `init`.
 */
template<unsigned DefaultBaudRate = 115'200>
struct SynopsisExtended16550 : public Uart16550<uint32_t>
{
	/**
	 * Loopback register.  Unused.
	 */
	uint32_t loopback;

	/**
	 * Divisor latch fraction.  When the divisor latch is set (for writing the
	 * divisor), this is used for the fraction.  RS-232 requires a 3% tolerance
	 * for the baud rate and an integer divisor over the clock frequency of the
	 * host may not get within this range.  This register is used to provide a
	 * 4-bit correction that allows baud rates to stay within the required
	 * range.
	 */
	uint32_t divisorLatchFraction;

	/**
	 * The divisor is calculated from 16 times the baud rate.  The baud rate is
	 * in the range of KHz to hundreds of KHz, whereas the clock frequency is
	 * typically tens to hundreds of MHz.  The divisor must fit in a 16-bit
	 * integer (written across two 8-bit device registers) and so is scaled to
	 * ensure that it fits (by a power of two, which makes it trivial to
	 * reverse the multiplication in the hardware).
	 */
	static constexpr uint32_t BaudScaleFactorShift = 4;

	/**
	 * The value in `divisorLatchFraction` is truncated to this many bits.
	 */
	static constexpr uint32_t BaudFractionBits = 4;

	/**
	 * Initialise the UART.
	 */
	void init(unsigned baudRate       = DefaultBaudRate,
	          unsigned timerFrequency = CPU_TIMER_HZ) volatile
	{
		// The multiplier that we will scale the baud rate by.
		constexpr uint32_t Multiplier = (1 << BaudScaleFactorShift);
		// The scaled baud rate is used in all of the remaining calculations.
		// See `BaudScaleFactorShift` for an explanation.
		uint32_t scaledBaudRate = baudRate * Multiplier;
		// The divisor to be programmed into the device.
		uint32_t divisor = timerFrequency / scaledBaudRate;
		// The remainder of the divisor.
		uint32_t remainder = timerFrequency % scaledBaudRate;
		// The remainder is scaled relative to the baud rate to give a
		// correction factor.
		remainder = (remainder << (BaudScaleFactorShift + 1)) / scaledBaudRate;
		// The remainder is rounded up to give the value that can be programmed
		// into the device register.
		remainder = (remainder >> 1) + (remainder & 0x1);
		// Set up the base UART
		Uart16550<uint32_t>::init(divisor,
		                          [&]() { divisorLatchFraction = remainder; });
		// Write a character with the low bit set.  Any value is fine here, but
		// if we use 0x7 (ASCII bell character) then we should get a beep if it
		// goes through to the receiver and so can tell whether this worked.
		blocking_write(0x7);
	}
};

#ifndef CHERIOT_PLATFORM_CUSTOM_UART
using Uart = SynopsisExtended16550<>;
#endif