Notation for user defined property for fixed point and arbitrary length integers

[jeras]

I would like to define a user defined property for defining the next two bit vector types.

• arbitrary length integer,
• fixed point.
  The question is what notation to use, I will list a few options, the provided examples are for the same type.

The property would be used in VHDL/Verilog and software header code generators.

Wikipedia provides a few notations, one of them looks a good fit.
I used the Q notation before (ARM version):

SQ16.8
UQ168

VHDL provides a standardized syntax for fixed point values:

sfixed (16-1 downto -8)
ufixed (16-1 downto -8)

And for arbitrary length integers there is:

signed   (24-1 downto 0)
unsigned (24-1 downto 0)

Verilog/SystemVerilog does not provide a standardized syntax for fixed point values, but is is common to use this:

logic   signed [16-1:-8]
logic unsigned [16-1:-8]

Arbitrary length integers are defined with the common vector notation and the signed/unsigned specifier (added in Verilog 2001):

logic   signed [24-1:0]
logic unsigned [24-1:0]

Xilinx also provides type definitions for the C++ language based HLS:

ap_fixed<24, 16>
ap_ufixed<24, 16>

I did not go in deep enough to find out whether there is a clear distinction between fixed point and arbitrary length integer.

The default choice for SystemRDL would be the Verilog notation, since a lot of the syntax is already based on Verilog.
The problem I see is, Verilog lacks a clear distinction between fixed point and arbitrary length integer.
VHDL provides the strongest standardization and the cleares distinction between types.

One option for Verilog syntax would be to just provide the signed/unsigned specifier without a range for arbitrary length integer, withe the length of the vector extracted from the field width. And for fixed point use the full type with the range.

[darsor]

I'm very interested in this and willing to try implementing it for the PeakRDL exporters. Here are some thoughts about possible fixedpoint property implementations.

Single Property

The available type options I see are

• string: use the direct Q-format.
• struct: a struct with fields for number of integer/fractional bits, and signedness. This looks way too verbose for frequent usage.
• array of unsigned for fractional width/signedness. Unclear at best.

The Q-format string wins on conciseness and readability.

property fixedpoint {
    type = string;
    component = field | signal;
};

This would be used like

field {
     fixedpoint = "Q15";
} my_number[16];

The width can always be inferred from the field itself, but it would be nice to support the various forms:

• Qn: signed number with n fractional bits
• Qm.n: signed number with m integer bits and n fractional bits (I'd lean towards the TI version of the Q-notation, but could be convinced otherwise).
• UQn: same as above but unsigned
• UQm.n: same as above but unsigned
• SQn: alias for Qn
• SQm.n: alias for Qm.n

Either m or n can be negative, but the width (if derivable from the Q-format) must match the field width.

Multiple Properties

Instead of a single property, we could define one for signedness, one for fractional width, and one for the integer width. In this case it might look something like

// "signed" is a reserved word
property signed_num {
    type = bool;
    component = field | signal;
    // default false to match behavior of built-in boolean properties
    default = false;
};

// number of fractional bits
property fracwidth {
    type = longint unsigned;
    component = field | signal;
};

// number of integer bits
property intwidth {
    type = longint unsigned;
    component = field | signal;
};

I actually like this quite a bit. It feels like more idiomatic SystemRDL and reduces the confusion from multiple interpretations of the Q-format. One limitation is that SystemRDL doesn't support signed integer types (!). But that can be worked around by requiring only one of the width properties to be defined (intwidth can be larger than the field width).

Its usage would look like this:

field {
    signed_num;
    fracwidth = 15;
} my_number[16]

@jeras, what did you end up using?
@amykyta3, as the resident expert on actually implementing properties like these, do you have any comments?

[amykyta3]

Alternatively if we want to avoid the Q notation TI vs ARM debacle, your second proposal looks good. I would just remove the intwidth property entirely since it is implicitly known based on the field/signal width already (unless I'm missing something)

[darsor]

@amykyta3 You're right, the default "signed" property should be true in this case.

The intwidth property is required because otherwise there's no way to express a negative number of fractional bits. The relationship is

bitwidth = intwidth + fracwidth + 1

for signed numbers, sans the +1 for unsigned numbers. You can't derive one without knowing the other two.

One factor that might help decide between the two options is in the implementation details. Does the SystemRDL compiler allow a UDP to be parsed into arbitrary component attributes? Specifically, could the compiler parse the Q notation into fracwidth and intwidth so that it doesn't have to be done individually by the exporters?

[darsor]

After looking closer, it looks like the compiler does not implement any UDPs directly, but just provides a mechanism for registering and exposing their values. So each exporter would have to independently handle Q notation parsing. Not the end of the world, but it makes me think the second option would be easier from an implementation perspective since it only requires validation, not parsing.

As for the Q notation option, we could expose a command line flag for exporters supporting it to switch between TI and ARM notation, allowing users to use the notation they prefer. It's hard enough to keep track of fixedpoint representations without having to mentally translate to a different notation. Though that might hurt cross-compatibility and make the semantics of the UDP a little fuzzy.

[darsor]

Could also use another UDP to set the fixedpoint standard:

enum qformat {
    TI;
    ARM;
};

property qformat_spec {
    type = qformat;
    component = field | signal;
}

//...

default qformat_spec = qformat::ARM;

Then the semantics can be concretely defined and the RDL files can be more portable.

[amykyta3]

Catching up to the discussion a bit..

After looking closer, it looks like the compiler does not implement any UDPs directly, but just provides a mechanism for registering and exposing their values. So each exporter would have to independently handle Q notation parsing. Not the end of the world, but it makes me think the second option would be easier from an implementation perspective since it only requires validation, not parsing.

Yes agree. In the current form, the exporter would have to have an additional utility to parse the Q notation string. Either way, the UDPDefinition is something that lives alongside the exporter so having an additional parsing mechanism co-located with that is not a big deal. If we start seeing cases where a UDP is common to multiple different exporters, then it may make sense to absorb the UDPDefinition class to some common area if appropriate.

As for the Q notation option, we could expose a command line flag for exporters supporting it to switch between TI and ARM notation, allowing users to use the notation they prefer. It's hard enough to keep track of fixedpoint representations without having to mentally translate to a different notation. Though that might hurt cross-compatibility and make the semantics of the UDP a little fuzzy.

I would recommend picking one notation and sticking with it. Giving the user control via a command-line arg to change interpretation feels dangerous and probably not necessary. If the notation used is clearly stated, then users will adapt.

[jeras]

I did not implement this yet, but my latest approach would be to not use UDPs and just have a parameterized sfixed/ufixed register. A custom generator (it already has to be custom, since there is no standard approach) would detect this instances and generate sfixed/ufixed code.

https://github.com/jeras/PeakRDL-jinja/blob/devel_jinja_with_SystemRDL/example/vhdl_fixed.rdl

https://github.com/jeras/PeakRDL-jinja/blob/devel_jinja_with_SystemRDL/example/vhdl_numeric.rdl

[darsor]

Thanks for the feedback, it's valuable.

In my use case it's useful to have more than one field in a register. An example that comes to mind is a control register for an AGC (automatic gain control) circuit, where I have enables/selects as well as a 16-bit reference value in fixedpoint format. I think it would be unnecessarily restrictive to enforce a single number per register.

I was envisioning "Q32.-8" being a valid Q-format. That's pretty typical from the usage that I've seen. I'm not a big fan of using unsigned underflow for negative numbers, but it would probably work.

If I'm interpreting your MSB/LSB format correctly, LSB is essentially the number of fractional bits, and MSB is the number of integer bits (+ sign)? What are your thoughts about my second proposed approach (sign/fracwidth/intwidth properties)? It seems like they align a little better.

[jeras]

Unfortunately the fixed point code from my most recent experience was entirely custom and not based on any common approach. There was little consideration for minimizing the number of bits while keeping the desired range and minimizing the quantization noise to a level compared to the noise in the data. The most annoying part was how confusing was properly translating mathematical equations with physical units into HDL and back. This can cause bugs and maybe even serious consequences. I would like something where this translation made sense every time I look at it, so I can easily recheck the code without first relearning the custom conventions (which are usually not documented). This was not meant as a rant, it was intended as my motivation.

So I started this issue in an attempt to propose a flexible solution which would be a good fit for HDL and SW. I prefer standard solutions, so instead of documenting it at length (and making oversights and errors in the process), I can point to a standard written by a committee with experienced members. The best standard I have seen so far is from VHDL. It defines well saturation/truncation, bit widths for addition/multiplication/division/modulo, overloaded operators, literals and print formatting, ...

https://github.com/ghdl/ghdl/blob/master/libraries/ieee2008/fixed_generic_pkg.vhdl

As for use cases I had in mind, it was mostly DSP. Things like FIR filter coefficients, data paths, registers containing average/min/max values for a stream, accumulated results. A data stream after a low pass filter would contain less noise, so it should have more fractional bits to avoid the quantization noise from rising above the noise in the signal. An accumulator would need extra int bits to extend the range. For a FIR coefficient table it makes sense that the coefficients are aligned to byte/half/word/double/long boundaries, so that SW can move them between memory and HW registers without conversion, preferably it should be able to use memcopy.

I would prefer, if the sign UDP (or HDL parameter/generic) would mean signedness and not presence or absence of an additional sign bit, which would affect the bit width of the fixed point number. This would be consistent with most type definition in HDL and SW (int signed and int unsigned are of the same width, the same goes for other standard types) and would also be consistent with the VHDL fixed point standard.

• MSB (or 'left or 'high signal vector attributes in VHDL, see standard) would match intwidth,
• LSB (or 'right or 'low in VHDL) would match fracwidth.

[darsor]

Thank you. Your suggestions make more sense given the context. I agree the VHDL fixed_pkg is the best implementation I've seen and should be emulated where possible. I've been going back and forth between the Q-format notation and specifically specifying the integer/fractional widths, but now I'm leaning towards the latter.

I would argue that property names like intwidth and fracwidth are more clear to the average user than MSB and LSB, which have their own definitions and semantics in SystemRDL. If you can think of better names for the properties, I'm all ears.

You're saying you'd prefer if changing the signedness doesn't change the number of bits in the representation? So more like the ARM-style Q-format where the sign bit is implicitly included in the intwidth. Then changing the signedness changes the range of representable numbers, but not the number of bits. That makes sense, especially given your example of signed vs unsigned integers in programming languages.

I think I'll plan on implementing PeakRDL support for something like the following:

enum sign {
    SIGNED;
    UNSIGNED;
};

property signedness {
    type = sign;
    component = field | signal;
};

// number of fractional bits
property fracwidth {
    type = longint unsigned;
    component = field | signal;
};

// number of integer bits (including sign bit)
property intwidth {
    type = longint unsigned;
    component = field | signal;
};

I'm open to suggestions for names of these properties. I'm on the fence about using an enum type or not. signedness = sign::SIGNED; seems a little verbose, but it may be clearer than using a boolean type. Especially since sign = true;, sign = false;, and an undefined sign property all have different meanings.

[jeras]

Good to see we are getting to the same page. The current proposal seems OK to me. I agree that MSB/LSB while making a lot of sense in a HDL language do not make as much sense in the SW context.

I was looking whether the VHDL standard has any text describing the fixed library, but there is not much, just a few usage patterns related to generalization. So we will have to find something else to link to when we write a document.

A related data type mentioned when I started this issue, are arbitrary length integers. They are a common type in VHDL, and in Verilog this would match signed/unsigned vectors or even more generally integral types. One feature I thought about was zero/sign extension. For example in a 32-bit register space a 24-bit signed integer could have its sign (bit [23]) extended (copied) to [31:24], so a load word from SW would not have to sign extend it in SW. The same might be applied to fixed point numbers.

[darsor]

Would it make more sense to have the HDL developer handle the sign extension? In SystemRDL you could define a field like

field {
    sw = r;
    hw = w;
    signedness = sign::SIGNED;
} my_integer[32];

Which would create a port of type input logic signed [31:0]. Then in the HDL you could use a sign extension function (from fixed_pkg if using VHDL) or manually sign extend the value when assigning the ports. The only disadvantage I see is the need to handle overflow in the reverse case (when SW writes and HW reads).

[darsor]

The following is the likely property declaration based on previous discussions:

// signedness of a component
property is_signed {
    type = bool;
    component = field | signal;
    default = true;
};

// number of fractional bits
property fracwidth {
    type = longint unsigned;
    component = field | signal;
};

// number of integer bits (including sign bit)
property intwidth {
    type = longint unsigned;
    component = field | signal;
};

As a first pass on the semantics for fracwidth and intwidth I propose:

1. A component is interpreted as a fixedpoint number if either fracwidth or intwidth is defined for the component.
2. The fracwidth property defines the number of fractional bits in the fixedpoint representation.
   a. The weight of the least significant bit of the component is 2^-fracwidth.
3. The intwidth property defines the number of integer bits in the fixedpoint representation (including the sign bit, if present).
4. The bit width of the component shall be equal to fracwidth + intwidth.
   a. If both widths are defined, it is an error if their sum does not equal the bit width of the component.
5. Only one of fracwidth or intwidth need be defined. The other is inferred from the component bit width.
6. Either fracwidth or intwidth can be a negative integer.
   a. Because SystemRDL does not have a signed integer type, the only way to achieve this is to define one of the widths as larger than the bit width of the component so that the other width is inferred as a negative number.
7. If fracwidth or intwidth is defined for a component and is_signed is not, the is_signed property is inferred to be false.
8. If is_signed is true the fixedpoint representation has a range from -2^(intwidth-1) to 2^(intwidth-1) - 2^-fracwidth.
9. If is_signed is false the fixedpoint representation has a range from 0 to 2^intwidth - 2^-fracwidth.

For is_signed:

1. When is_signed is true the component is interpreted as a signed number.
2. When is_signed is false the component is interpreted as an unsigned number.

[darsor]

Open questions:

1. How to handle counters? Can they be signed? Should incrvalue/decrvalue have the same signedness and same LSB?
2. Can fields in external registers be fixedpoint values?
3. Fixedpoint enums?

[darsor]

I don't see any compelling use-cases for fixedpointer counters/enums, so these new properties will be mutually exclusive with counter and encode for now. External fields can be fixedpoint. The HDL exporter may not care, but the c-header and documentation exporters can use the information.

I've decided to drop the ability to define these properties for signal components as well. It opens a can of worms since signals can be used in all sorts of places, meaning lots of potential edge cases.

[amykyta3]

Agree on all comments.
In the spirit of "YAGNI", no need to proactively add the feature for counters or signals if nobody's asking for it.
I'd also not include it for enums as that opens up more cans of worms, and also hardly see that as being useful.