Livt packages

Livt.Math

Version 1.7.2

Reusable integer and fixed-point arithmetic, complex numbers, trigonometry, and statistics for FPGA applications written in Livt.

Published files (90)

src/arithmetic/WideArithmetic.lvt

namespace Livt.Math.Arithmetic

/**
 * Exact signed 64-bit arithmetic with symmetric output clipping.
 * Wide values use two's-complement logic[64] transport, not Livt int arithmetic.
 * Division uses 64 restoring steps; root consumes 32 pairs of bits.
 * ROUNDING_STAGES selects 3 default or 4 separately registered stages.
 * POWER_OF_TWO_FAST_PATH enables exact shift division with additional hardware.
 * PIPELINED_DISPATCH splits the six-way operand selector into registered groups.
 * Configuration changes latency, never results; callers wait for completion.
 * OPERATIONS bits enable multiply/add/divide/root/clamp (1/2/4/8/16).
 * Disabled operations return zero and set Failed; the default enables all.
 * One caller owns this scheduled component. Reset cancels pending requests.
 * Invalid division or overflowing add/multiply returns zero and sets Failed().
 */
component WideArithmetic<OUTPUT_BITS: int = 24, OPERATIONS: int = 31, ROUNDING_STAGES: int = 3, POWER_OF_TWO_FAST_PATH: bool = false, PIPELINED_DISPATCH: bool = false>
{
	static assert OUTPUT_BITS >= 2 && OUTPUT_BITS <= 31, "output bits must be 2..31"

	static assert OPERATIONS >= 0 && OPERATIONS <= 31, "operation mask must be 0..31"

	static assert ROUNDING_STAGES == 3 || ROUNDING_STAGES == 4, "rounding stages must be 3 or 4"

	// Owned arithmetic worker used by serialized operations.
	primitive: WideArithmeticPrimitive

	// Request toggle paired with the native worker acknowledgment.
	request: logic

	/**
	 * Owns one native arithmetic worker in the caller clock/reset context. Calls must be
	 * serialized; reset cancels an outstanding request.
	 */
	new()
	{
		primitive = new WideArithmeticPrimitive()
		primitive.operations = OPERATIONS
		primitive.roundingStages = ROUNDING_STAGES
		primitive.powerOfTwoFastPath = POWER_OF_TWO_FAST_PATH
	}

	/**
	 * Submits one operation with two 64-bit operands and waits for its matching
	 * acknowledgment. The operation codes follow WideArithmeticPrimitive; only one caller may
	 * use this worker at a time.
	 */
	fn Execute(op: int, a: logic[64], b: logic[64])
	{
		state {
			primitive.operation = op
			primitive.a = a
			primitive.b = b
			primitive.outputBits = OUTPUT_BITS
		}

		request = !request
		primitive.request = request

		while (primitive.acknowledge != request) {
			state {
			}
		}
	}

	/** Adds a registered binary-operation dispatch boundary when enabled. */
	fn ExecuteBinary(op: int, a: logic[64], b: logic[64])
	{
		Execute(op, a, b)
	}

	/** Keeps unary operations out of the wide binary-operand selector. */
	fn ExecuteUnary(op: int, a: logic[64])
	{
		Execute(op, a, 0)
	}

	/**
	 * Signed product, with overflow detected before narrowing.
	 */
	public fn Multiply(a: logic[64], b: logic[64]) logic[64]
	{
		static if (PIPELINED_DISPATCH) {
			ExecuteBinary(0, a, b)
		} else {
			Execute(0, a, b)
		}
		return primitive.result
	}

	/**
	 * Signed sum, with overflow detected before narrowing.
	 */
	public fn Add(a: logic[64], b: logic[64]) logic[64]
	{
		static if (PIPELINED_DISPATCH) {
			ExecuteBinary(1, a, b)
		} else {
			Execute(1, a, b)
		}
		return primitive.result
	}

	/**
	 * Signed nearest division; exact ties select the even quotient. Divisor is positive.
	 */
	public fn DivideEven(a: logic[64], b: logic[64]) logic[64]
	{
		static if (PIPELINED_DISPATCH) {
			ExecuteBinary(2, a, b)
		} else {
			Execute(2, a, b)
		}
		return primitive.result
	}

	/**
	 * Floor square root of any unsigned 64-bit input.
	 */
	public fn Sqrt(a: logic[64]) logic[64]
	{
		static if (PIPELINED_DISPATCH) {
			ExecuteUnary(3, a)
		} else {
			Execute(3, a, 0)
		}
		return primitive.result
	}

	/**
	 * Symmetric signed saturation, followed by checked narrowing to Livt int.
	 */
	public fn Clamp(a: logic[64]) int
	{
		static if (PIPELINED_DISPATCH) {
			ExecuteUnary(4, a)
		} else {
			Execute(4, a, 0)
		}
		return primitive.result as int
	}

	/**
	 * Unsigned floor division for nonnegative signed-range values.
	 */
	public fn DivideFloor(a: logic[64], b: logic[64]) logic[64]
	{
		static if (PIPELINED_DISPATCH) {
			ExecuteBinary(5, a, b)
		} else {
			Execute(5, a, b)
		}
		return primitive.result
	}

	/**
	 * Error flag belongs to the most recently completed operation.
	 */
	public fn Failed() bool
	{
		return primitive.failed
	}
}