ExtendedRanges < P1076

P1076 Web>Vhdl2019CollectedRequirements>ExtendedRanges (2020-02-17, JimLewis) (raw view)EditAttach
---+!! Extended Ranges
---++ Proposal Editing Information
   * *Who Updates:* [[Main.PatrickLehmann][Patrick Lehmann]], [[Main.LievenLemiengre][Lieven Lemiengre]], &lt;Add YourName &gt;, ...
   * *Date Proposed:* 2016-07-19
   * *Date Last Updated:* 2017-02-22
   * *Priority:*
   * *Complexity:*
   * *Focus:* Testbench and Synthesis
   * *Depends on:* 
   * *Is needed by:* &lt;Add YourProposal &gt;, ...
   * *Improved:* [[P1076.ReflectionAPI][ReflectionAPI]]
   * *Can be improved by:* ![[generic instantiation while calling a sub program]]
   * *Related:*
      * *Subsumes:* [[P1076.RangeOperations][RangeOperations]]
      * *Old proposal page:* [[P1076.ExtendedRanges_old][ExtendedRanges (old)]]
      * &lt;Add YourProposal &gt;, ...

---++!! Table of Content
%TOC%

---++ Summary
VHDL has a concept of _ranges_ for either defining ranges on ordered sets (integer ranges, floating point number ranges, ranges on enumerated types) or defining slices to get a
sub-set of a composite type (array).

These ranges cannot be:
   * manipulated (moved/shifted by an offset, expanded, shrinked, combined/concatenated),
   * reversed, normalized,
   * compared (equal, inequal, left-of, right-of, smaller, bigger, ...),
   * queried for range properties (e.g. is_ascending, direction, length),
   * passed as an argument to a subprogram (procedure, function, operator), or
   * returned as a result from a function or ([[P1076.ExtendedUserDefinedAttributes][extended]]) user defined attribute.
This proposal addresses all these missing features, by
   * splitting ranges from subtype constraints,
   * introducing ranges as an immutable "object", which can be passed round,
   * defining operators on ranges to create a _range arithmetic_, and
   * defining attributes to ease the handling of ranges.

While developing a first solution, which could be summarized as <sticky><b>"ranges as a new VHDL <a href="../P1076/BNFVHDL2008#entity_class">entity class</a></sticky>"
(Idea 1)</b></sticky>, I found some limitations in VHDL, which might imply too heavy LRM changes to fulfill all requirements. So I had a talk with [[Main.LievenLemiengre][Lieven Lemiengre]],
who offered another view to the topic, which could be summarized as <sticky><b>"Ranges as an LRM pre-defined record" (Idea 2)</b></sticky>. This view solved many of my
issues, but has some drawbacks, too. So this proposal will show *two ideas*, presenting advantages and disadvantages for both ideas and giving a starting point for a discussion in
an upcoming IEEE meeting.

Finally, if my initial *Idea 1* seems to be too pioneering, then there might be a *hybrid solution*...
---++ Related and/or Competing Proposals:
---+++ [[P1076.RangeOperations][RangeOperations]] - Allow static operations on "ranges".
   * *Author:* Stewart Cobb
   * *VHDL Version:* VHDL-93
   * *Issue Number:* IR-2072
   * *Status:* Forwarded
   * *VASG-ISAC Analysis & Rationale:* Some of the problems that the author mentions can be solved by using aliases to normalize ranges and directions of array objects. However,
      this proposal goes farther and permits some form of arithmetic on ranges.

---+++ Aliases and Subtypes as Ranges
Many discussions begin at or end up in a sentence like:
   * *"Ranges can be emulated with subtypes."*, or
   * *"Many presented use cases can be worked around with aliases."*
I agree that aliases and/or subtypes are a -- in my eyes -- dirty workaround to emulate ranges, because each constrained subtype of a scalar type has a range. Furthermore a
subtype can be used as a =discrete_subtype_indication=. But a _range_ is not a type.
A range is an (implementation specific) data structure defining at least the following three members:
   * a direction,
   * a lower, and
   * an upper bound.
   * _reference to an ordered set_ <sup>1</sup>
A (sub-)type is more than a range. It defines:
   * a range (if constrained),
   * attributes for itself,
   * attributes for its instances, and
   * (default) operators for its instances.

<sup>1</sup>As [[Main.AndyJones][Andy Jones]] pointed out in an [[http://grouper.ieee.org/groups/1076/email/msg00082.html][IEEE reflector discussion]], VHDL ranges need
to be linked to an ordered set, otherwise a compiler can not know if for example =red to blue= is a valid range, a null range, etc. This might be trivial for integer and floating point
literals, because these literals are of type _universal_integer_ or _universal_real_ and are compatible to each other. The problem comes from enumeration, which create new
ordered sets, each with own position numbers. I'll deepen this point in a later paragraph.

---++ General Requirements
Starting from an ideal world, this is a list of requirements, which shall be solved.
   * Mandatory:
      * ranges are created by the existing =H downto L= or =L to H= syntax
      * ranges are returned by the ='range= and ='reverse_range= attributes
      * ranges can be used in subtype declarations to constrain types
      * ranges can be used in slices
      * ranges can be used in choices
      * ranges can be passed into subprograms
         * as generic parameters
         * as formal parameters
      * ranges are immutable "objects" (they behave like constants)
      * ranges can be manipulated (the "manipulated" object is a new instance, because a range is immutable)
      * new shift/move operators =<<= and =>>= for ranges
      * ranges can be reversed and normalized
      * ranges can be compared to each other
         * equality
      * properties of ranges can be queried
      * ranges can be aliased
   * Optional:
      * ranges can be returned from functions and attributes
      * ranges can be elements in composite types (e.g. to define multi-slices)
      * ranges are mutable (change the mandatory property of immutable ranges to mutable)
---++ Current Situation - Ranges and Slices in VHDL
The =range= keyword is already reserved in VHDL and used in:
   * type declaration:
      * =<b>type</b> short <b>is range</b> -32768 <b>to</b> 32767;=
      * =<b>type</b> ratio <b>is range</b> 0.0 <b>to</b> 1.0;=
      * =<b>type</b> string <b>is array</b>(positive <b>range</b> &lt;&gt;) <b>of</b> character;=
   * subtype declarations:
      * =<b>subtype</b> positive <b>is</b> integer <b>range</b> 1 <b>to</b> integer'high;=
   * type marks (e.g. in a record declaration):
      * =digit0 : integer <b>range</b> 0 <b>to</b> 9;=
Additionally, ='range= and ='reverse_range= are pre-defined attribute names, containing the string "range".

Currently, VHDL's EBNF knows "ranges" as:
   * =range :: = <font color="LimeGreen"><i>range_</i></font><a href="../P1076/BNFVHDL2008#attribute_name">attribute_name</a>=, e.g. =mySignal'range(2)=
   * =<a href="../P1076/BNFVHDL2008#simple_expression">simple_expression</a> <a href="../P1076/BNFVHDL2008#direction">direction</a> <a href="../P1076/BNFVHDL2008#simple_expression">simple_expression</a>=, e.g. =7 <b>downto</b> 0=
   * =<a href="../P1076/BNFVHDL2008#index_subtype_definition">index_subtype_definition</a>=, e.g. =natural <b>range</b> <>=
   * =<font color="LimeGreen"><i>discrete_</i></font><a href="../P1076/BNFVHDL2008#subtype_indication">subtype_indication</a>=, e.g. =std_logic_vector(RegisterIndex)=
These ranges can be used in:
   * slices,
   * range constraints,
   * choices, or
   * for loops (including generate loops)

---++ Definitions
---+++++!! VHDL Type System
|   | *Scalar Type* | *Ordered Type<sup>1</sup>* | *Discrete Type* | *Numeric Types* | *Has Position Number* |
| *integer type* | yes | yes | yes | yes | yes |
| *enumeration type* | yes | yes | yes | no | yes |
| *floating type* | yes | yes | no | yes | no |
| *physical type* | yes | yes | no | yes | yes |

<sup>1</sup>All relational operators are predefined.

---+++++!! Direction
A _direction_ is an enumeration (enumerated type in VHDL) of 2 values: =to= and =downto=.
<sticky><pre>
<b>type</b> direction <b>is</b> (to, downto);
</pre></sticky>
---+++++!! Range
A _range_ is an implementation specific data structure defining 3 members: 1) a lower bound, 2) an upper bound, and 3) a direction. The bounds are not limited to integer
or floating point literals. Every scalar values is allowed. It can be expressed in (VHDL) pseudo code as a record:
<sticky><pre>
<b>type</b> &lt;name&gt; <b>is record</b>
  Left : &lt;scalar_type&gt;;
  Right : &lt;scalar_type&gt;;
  direction  : direction;
<b>end record</b>;
</pre></sticky>

---++ Proposal - Idea 1
A _range_ should be a member in VHDL's <sticky><a href="../P1076/BNFVHDL2008#entity_class"><b>entity class</b></a></sticky> list and it should be a VHDL "object"
with its own =range_declaration= rule. So a _range_ becomes an named "object" like a VHDL constant or type. When a _range_ becomes an object, its no longer an
language internal intermediate data structure, which can now be (re)used e.g. in slices or constraints, be passed around, be returned, or define operators and have attributes.

So to warm-up with ranges, let's play with _ranges_ and their _range arithmetic_. The range declartion syntax is inspired by the type declaration syntax.
---+++ Examples
---+++++!! EX01 - Simple Example 01
The following example declares two ranges: One in ascending (to) and one in descending (downto) order. This simple example uses a =simple_range_expression= as already
known from VHDL-200x.

<sticky><pre>
<b>architecture</b> a <b>of</b> e <b>is</b>
  <b>range</b> r_lower <b>is</b> 15 <b>downto</b> 0;
  -- range R_lower is range 15 downto 0;     -- too many range keywords in one VHDL line
  <b>range</b> r_upper <b>is</b> 16 <b>to</b> 31;
  <b>range</b> empty1  <b>is</b> null;                     -- creates a null range    (for arithmetic completeness)
  <b>range</b> empty2  <b>is</b> 0 <b>downto</b> 1;               -- results in a null range (current behavior)
<b>begin</b>
<b>  -- ...</b>;
</pre></sticky>

---+++++!! EX02 - Simple Example 02
The following lines show arithmetic on ranges. Some ranges are created from attribute return values.

<sticky><pre><b>architecture</b> a <b>of</b> e <b>is</b>
  <b>subtype</b> t_int3  <b>is</b> integer <b>range</b> 0 <b>to</b> 7;
  <b>subtype</b> t_slv_8 <b>is</b> std_logic_vector(7 <b>downto</b> 0);

  <b>range</b> LowerByteRange    <b>is</b> t_slv_8'range;                   -- store a subtype's range constraint in a range
  <b>range</b> UpperByteRange    <b>is</b> LowerByteRange << 8;             -- move (both) range bounds by +8 => 15 downto 8
  <b>range</b> WordRange         <b>is</b> LowerByteRange * 4;              -- expand range by 4, lower bound is not modified => 31 downto 0
  <b>range</b> HalfWordRange     <b>is</b> WordRange / 2;                   -- split the range in equal sized parts => 15 downto 0
  <b>range</b> DoubleWordRange1  <b>is</b> WordRange & WordRange;           -- combine two ranges => 63 downto 0
  <b>range</b> DoubleWordRange2  <b>is</b> UpperByteRange & WordRange;      -- combine two ranges => 39 downto 0
  <b>range</b> NormalizedRange   <b>is</b> UpperByteRange'normalized;       -- the range is moved so the lower bound is zero => 7 downto 0
  <b>range</b> ReverseRange      <b>is</b> UpperByteRange'reversed;         -- reverse direction => 8 to 15

  <b>constant</b> Bytes     : integer := WordRange / t_int3'range;   -- divide two range lengths => 4
  <b>signal</b>   MySignal  : std_logic_vector(WordRange);           -- constrain a array with a range
  <b>subtype</b>  MySubType <b>is</b> integer <b>range</b> WordRange;              -- constrain a type to a subtype
<b>begin</b>
  lowerByte <= MySignal(LowerByteRange);                      -- use a range in a slice
<b>end architecture</b>;</pre></sticky>

---+++++!! EX03 - Simple Example 03
This example shows a range in a generic list as well as in a formal parameter list.

<sticky><pre>
<b>function</b> func
  <b>generic</b>   (<b>range</b> LHS);
  <b>parameter</b> (input : std_logic_vector(LHS); <b>range</b> RHS) <b>return</b> std_logic_vector <b>is</b>
<b>begin</b>
  <b>return</b> input(RHS);
<b>end architecture</b>;

-- example usage:
<b>signal</b> Registers : std_logic_vector(15 <b>downto</b> 0);
<b>signal</b> output    : std_logic_vector(3 downto 0);
<b>function</b> foo <b>is new</b> func <b>generic map</b> (LHS => Registers'range);
ouput <= foo(Registers, output'range);
</pre></sticky>

---+++++!! EX04 - Complex Example 04
This complex example combines many aspects from the previous examples into one big example.

<sticky><pre>
<b>architecture</b> a <b>of</b> e <b>is</b>
  -- 16-bit registers filled with four 3-bit status fields (S) and one error bit (E)
  <b>signal</b> Registers : std_logic_vector(15 <b>downto</b> 0);    -- Format: SSSE SSSE SSSE SSSE

  -- a generic extract function to demonstrate many capabilities of range objects
  <b>function</b> Extract
    <b>generic</b>   (<b>type</b> T; <b>range</b> R_MAX);
    <b>parameter</b> (input : T(R_MAX); <b>range</b> Slice)
  <b>return</b> std_logic_vector <b>is</b>
    <b>variable</b> result : T(Slice);
  <b>begin</b>
    result := input(Slice);
    <b>return</b> result;
  <b>end function</b>;

  <b>range</b> AllBitsRange    <b>is</b> 3 <b>downto</b> 0;
  <b>range</b> StatusRange     <b>is</b> 0 <b>to</b> 3;
  <b>range</b> StatusBitsRange <b>is</b> 3 <b>downto</b> 1;

  -- a normalized ranged is a to/downto range beginning at index 0
  <b>signal</b> Status : <b>array</b>(natural StatusRange'reverse) <b>of</b> std_logic_vector(StatusBitsRange'normalized);   -- (3 downto 0) of (2 downto 0)

  <b>function</b> GetStatus <b>is new</b> Extract
    <b>generic map</b> (T => Registers'type, R_Max => Registers'range);

<b>begin</b>
  genLoop: <b>for</b> i <b>in</b> StatusRange <b>generate</b>
    <b>range</b> CurrentStatusRange <b>is</b> StatusBitsRange'range << (i * AllBitsRange'length);
  <b>begin</b>
    Status(i) <= GetStatus(Registers, CurrentStatusRange);
  <b>end generate</b>;
<b>end architecture</b>;
</pre></sticky>

_This is an example to demonstrate what's possible with ranges and range arithmetic. It's not an example of short and compact VHDL code!_

---+++ Detailed Requirements
   a. Ranges can be declared in any declarative region:
      * entity declarative region
      * architecture declarative region
      * package and package body
      * process statement
      * block statement
      * generate statement
      * protected type body
      * subprogram declarative region
   a. The existing syntax =&lt;expr&gt; (*to* | *downto*) &lt;expr&gt;= becomes a simple range expression and will _construct_ a range.
   a. Ranges can be used as:
      * constraints,
      * slices
      * choices, or
      * loop-ranges as in the current usage.
   a. Ranges define attributes to query range properties:
      * ='low= -&gt; returns the lower bound
      * ='high= -&gt; returns the upper bound
      * ='left= -&gt; returns the left bound
      * ='right= -&gt; returns the right bound
      * ='length= -&gt; returns the length
      * ='direction= -&gt; returns the direction
      * ='is_ascending= -&gt; returns true if range is ascending
      * ='is_descending= -&gt; returns true if range is descending
      * ='is_nullrange= -&gt; returns true if range is a null range / empty
      * ='ascending= -&gt; returns a range with =to= direction
      * ='descending= -&gt; returns a range with =downto= direction
      * ='reverse= -&gt; reverses the direction
      * ='normalize= -&gt; creates a zero-based range (lower bound is zero)
      * ='image= -&gt; returns a string representation ="<bound> to|downto <bound>"=
   a. Ranges can be manipulated in complex range expressions by range arithmetic:
      * ="<<"= -&gt; move bounds up
      * =">>"= -&gt; move bounds down
      * ="+"= -&gt; extend upper bound
      * ="-"= -&gt; shrink upper bound
      * ="*"= -&gt; expand range
      * ="/"= -&gt; split range
      * ="/"= -&gt; range ratio
      * ="&"= -&gt; combine ranges
   a. Ranges can implement set arithmetic:
      * ="and"= -&gt; Intersection of two ranges
      * ="or"= -&gt; Union of two ranges
      * ="xor"= -&gt; Consecutive ranges
   a. Ranges can be compared for (in-)equality:
      * ="="= -&gt; Strict equality
      * ="/="= -&gt; Strict inequality
      * ="?="= -&gt; Matching equality
      * ="?/="= -&gt; Matching inequality
   a. The existing ='range= and ='reverse_range= attribute return ranges.
   a. Ranges can be passed in generic lists:
      * package generic lists
      * entity / component generic lists:
      * subprogram generic lists
   a. Ranges can be passed in formal lists to subprograms:
      * functions
      * procedures
      * operators
   a. <strike>Ranges can be returned by functions and attributes.</strike>

---++ Proposal - Idea 2
The internal range data structure of a subtype should be accessible to the VHDL user through two new pre-defined attributes for any scalar type.
   * ='range_type= returns an implicitly declared record type for the corresponding scalar type:
   * ='range_value= returns a range instance of this implicit record type.
Ranges are expressed as subtypes and can be "converted" to the corresponding record with ='range_value=. A ranged can be stored in a constant or variable, by defining the
constant/variable of type =subtype'range_type=. As a range is stored in a normal VHDL object, it can be passed around. Further it's a normal -- but LRM-defined -- record and
operators can be applied to it.

The LRM needs further changes to allow these pre-defined implicit records in slices, constraints and loops as an equivalent to the currently used =discrete_range=.

---+++ State-of-the-Art
Ranges can be expressed as (new) scalar types like:
<sticky><pre>
<b>type</b> IntRange  <b>is range</b> 0 <b>to</b> 15;
<b>type</b> Realrange <b>is range</b> 0.0 <b>downto</b> 1.0;
<b>type</b> Enum <b>is</b> (Item0, Item1, Item2, Item3);
</pre></sticky>

Every scalar type can be constrained by a range in a subtype declaration:
<sticky><pre>
<b>subtype</b> SmallInt <b>is</b> integer <b>range</b> -32768 <b>to</b> 32767;
<b>subtype</b> Enum02   <b>is</b> Enum    <b>range</b> Item0  <b>to</b> Item2;
</pre></sticky>

(Sub-)Types can be passed as type generics in _generic_=_interface_list=.

---+++ Implicit range Record:
Scalar types declare an implicit record (_range_record_), which represents a range as a triple: from, to, dir.
The VHDL record prototype looks as follows:
<sticky><pre>
type direction is (ascending, descending);    -- to and downto cannot be used, because these are keywords

type &lt;unnamed&gt; is record                -- the record is unnamed / anonymous
  Left : &lt;scalar_type&gt;;           -- the bounds are not restricted to integers
  Right : &lt;scalar_type&gt;;
  direction  : direction;
end record;
</pre></sticky>

The implicit record type of every scalar type can be accessed by an attribute called ='range_type=. If a handle to the record type is required, it can be created with an =alias=
declaration. A record instance can be created by the attribute called ='range_value=.

<sticky><pre>
subtype  R  is integer range 0 to 7;
alias integer_range is integer'range_type;
alias R_range       is R'range_type;                   -- LIEVEN: is this a different but closely related (record) type?
constant RLHS : integer_range      := R'range_value;    -- get R's range => 0 to 7
constant RRHS : R'base'range_type  := R'range_value;    -- equivalent declaration  LIEVEN: is this correct?
</pre></sticky>


---+++ Detailed Requirements
   a. Ranges can be declared in any declarative region:
      * same as in idea 1
   a. <strike>The existing syntax =&lt;expr&gt; (==to== | ==downto==) &lt;expr&gt;= becomes a simple range expression and will construct a range.</strike>
   a. Ranges can be used as:
      * <strike>constraints,</strike>
      * <strike>slices, or</strike>
      * <strike>loop-ranges</strike> as in the current usage.
   a. Ranges can be manipulated in complex range expressions by range arithmetic:
      * same as in idea 1
   a. Ranges can be compared:
      * same as in idea 1
   a. Ranges define attributes to query range properties:
      * <strike>='low= -&gt; returns the lower bound</strike>
      * <strike>='high= -&gt; returns the upper bound</strike>
      * <strike>='left= -&gt; returns the left bound</strike>
      * <strike>='right= -&gt; returns the right bound</strike>
      * <strike>='length= -&gt; returns length</strike>
      * <strike>='direction= -&gt; returns the direction</strike>
      * <strike>='is_ascending= -&gt; returns true if range is ascending</strike>
      * <strike>='is_descending= -&gt; returns true if range is descending</strike>
      * <strike>='is_nullrange= -&gt; returns true if range is a null range (empty)</strike>
      * <strike>='ascending= -&gt; returns a range with to direction</strike>
      * <strike>='descending= -&gt; returns a range with downto direction</strike>
      * <strike>='reverse= -&gt; reverse the direction</strike>
      * <strike>='normalize= -&gt; create a zero-based range (lower bound is zero)</strike>
      * <strike>='image= -&gt; returns a string representation</strike>
   a. <strike>The existing ='range= and ='reverse_range= attribute will return ranges.</strike>
   a. Ranges can be passed in generic lists:
      * same as in idea 1
   a. Ranges can be passed in formal lists to subprograms:
      * same as in idea 1
   a. Ranges can be returned by functions and attributes.

_LIEVEN: Filling the next sections with content might enable stroked lines._

---+++ Additions to STANDARD:
---++++!! New Enumerated Type: =direction=
<sticky><pre>
type direction is (ascending, descending);    -- to and <b>downto</b> cannot be used, because these are keywords
</pre></sticky>

---++++!! One implicit declared =range_record= per scalar type:
<sticky><pre>
type &lt;unnamed&gt; is record
  Left : &lt;scalar_type&gt;;
  Right : &lt;scalar_type&gt;;
  direction  : direction;
end record;
</pre></sticky>

Useful extensions if a user works with ='range_type=.
<sticky><pre>
alias integer_range <b>is</b> integer'range_type;
alias index_range   is integer_range;    -- alternative name, because most indices are integers
</pre></sticky>

---+++ Attributes on Ranges
Currently, no attributes are proposed to query range properties. Some are accessible through the record itself, but most should be implemented in normal functions.
([[P1076.ExtendedUserDefinedAttributes][Extended user-defined attributes]]) might be a solution to map these functions to the range records.

---+++ Functions for Ranges
---++++!! Lower Boundary
<sticky><pre>
<b>function</b> low(R : RANGE_RECORD) <b>return</b> RANGE_TYPE <b>is</b>
<b>begin</b>
  <b>return</b> R.Left;
<b>end function</b>;
</pre></sticky>
---++++!! Upper Boundary
<sticky><pre>
<b>function</b> high(R : RANGE_RECORD) <b>return</b> RANGE_TYPE <b>is</b>
<b>begin</b>
  <b>return</b> R.Right;
<b>end function</b>;
</pre></sticky>
---++++!! Left Boundary
<sticky><pre>
<b>function</b> left(R : RANGE_RECORD) <b>return</b> RANGE_TYPE <b>is</b>
<b>begin</b>
  <b>if</b> is_ascending(R) <b>then</b>
    <b>return</b> R.Left;
  <b>else</b>
    <b>return</b> R.Right;
  <b>end if</b>;
<b>end function</b>;
</pre></sticky>
---++++!! Right Boundary
<sticky><pre>
<b>function</b> right(R : RANGE_RECORD) <b>return</b> RANGE_TYPE <b>is</b>
<b>begin</b>
  <b>if</b> is_ascending(R) <b>then</b>
    <b>return</b> R.Right;
  <b>else</b>
    <b>return</b> R.Left;
  <b>end if</b>;
<b>end function</b>;
</pre></sticky>
---++++!! Length
<sticky><pre>
<b>function</b> length(R : RANGE_RECORD) <b>return</b> INTEGER <b>is</b>
<b>begin</b>
  <b>return</b> R.Right - R.Left + 1;
<b>end function</b>;
</pre></sticky>
---++++!! Direction
<sticky><pre>
<b>function</b> direction(R : RANGE_RECORD) <b>return</b> RANGE_DIRECTION <b>is</b>
<b>begin</b>
  <b>return</b> R.Direction;
<b>end function</b>;
</pre></sticky>
---++++!! Range is ascending
<sticky><pre>
<b>function</b> is_ascending(R : RANGE_RECORD) <b>return</b> BOOLEAN  <b>is</b>
<b>begin</b>
  <b>return</b> (R.Direction = ASCENDING);
<b>end function</b>;
</pre></sticky>
---++++!! Range is descending
<sticky><pre>
<b>function</b> is_descending(R : RANGE_RECORD) <b>return</b> BOOLEAN  <b>is</b>
<b>begin</b>
  <b>return</b> (R.Direction = DESCENDING);
<b>end function</b>;
</pre></sticky>
---++++!! Range is a null range
<sticky><pre>
<b>function</b> is_nullrange(R : RANGE_RECORD) <b>return</b> BOOLEAN  <b>is</b>
<b>begin</b>
  <b>return</b> (length(R) <= 0);
<b>end function</b>;
</pre></sticky>
---++++!! Returns an ascending range
<sticky><pre>
<b>function</b> ascending(R : RANGE_RECORD) <b>return</b> RANGE_RECORD is
<b>begin</b>
  <b>return</b> (
    Left =>  R.Left,
    Right =>  R.Right,
    Direction =>  ASCENDING
  );
<b>end function</b>;
</pre></sticky>
---++++!! Returns a descending range
<sticky><pre>
<b>function</b> descending(R : RANGE_RECORD) <b>return</b> RANGE_RECORD is
<b>begin</b>
  <b>return</b> (
    Left =>  R.Left,
    Right =>  R.Right,
    Direction =>  DESCENDING
  );
<b>end function</b>;
</pre></sticky>
---++++!! Returns a reversed range
<sticky><pre>
<b>function</b> reverse(R : RANGE_RECORD) <b>return</b> RANGE_RECORD is
<b>begin</b>
  <b>if</b> is_ascending(R) <b>then</b>
    <b>return</b> descending(R);
  <b>else</b>
    <b>return</b> ascending(R);
  <b>end if</b>;
<b>end function</b>;
</pre></sticky>
---++++!! Returns a normalized range
<sticky><pre>
<b>function</b> normalize(R : RANGE_RECORD) <b>return</b> RANGE_RECORD is
<b>begin</b>
  <b>return</b> R srl length(R);
<b>end function</b>;
</pre></sticky>
---++++!! Returns a string representation
<sticky><pre>
<b>function</b> image(R : RANGE_RECORD) <b>return</b> STRING is
<b>begin</b>
  <b>if</b> is_ascending(R) <b>then</b>
    <b>return</b> INTEGER'image(R.Left) & " to "     & INTEGER'image(R.Right);
  <b>else</b>
    <b>return</b> INTEGER'image(R.Right) & " downto " & INTEGER'image(R.Left);
  <b>end if</b>;
<b>end function</b>;
</pre></sticky>

---+++ Operators on Ranges
---++++!! "<<" - Move a range up
<sticky><pre>
<b>function</b> range_move_up
  <b>generic</b>   (<b>type</b> T <b>is</b> scalar_type);
  <b>parameter</b> (R : T'range_type; offset : T) <b>return</b> T'range_type <b>is</b>
<b>begin</b>
  <b>return</b> (
    Left => R.Left + offset,
    Right => R.Right + offset,
    direction =>  R.direction
  );
<b>end function</b>;

-- example for an implicit operator creation for integer
<b>function</b> "<<" <b>is new</b> range_move_up <b>generic map</b>(T => integer);
</pre></sticky>
---++++!! ">>" - Move a range down
<sticky><pre>
<b>function</b> range_move_down
  <b>generic</b>   (<b>type</b> T <b>is</b> scalar_type);
  <b>parameter</b> (R : T'range_type; offset : T) <b>return</b> T'range_type <b>is</b>
<b>begin</b>
  <b>return</b> (
    Left => R.Left - offset,
    Right => R.Right - offset,
    direction =>  R.direction
  );
  -- return R << (-offset);                                         -- alternative implementation
<b>end function</b>;

-- example for an implicit operator creation for integer
<b>function</b> ">>" <b>is new</b> range_move_down <b>generic map</b>(T => integer);
</pre></sticky>
---++++!! "+" - Increase the upper bound
<sticky><pre>
<b>function</b> range_increase
  <b>generic</b>   (<b>type</b> T <b>is</b> scalar_type);
  <b>parameter</b> (R : T'range_type; offset : T) <b>return</b> T'range_type <b>is</b>
<b>begin</b>
  <b>return</b> (
    Left => R.Left,
    Right => R.Right + offset,
    direction =>  R.direction
  );
<b>end function</b>;

-- example for an implicit operator creation for integer
<b>function</b> "+" <b>is new</b> range_increase <b>generic map</b>(T => integer);
</pre></sticky>
---++++!! "-" - Decrease the upper bound
<sticky><pre>
<b>function</b> range_decrease
  <b>generic</b>   (<b>type</b> T <b>is</b> scalar_type);
  <b>parameter</b> (R : T'range_type; offset : T) <b>return</b> T'range_type <b>is</b>
<b>begin</b>
  <b>return</b> (
    Left => R.Left,
    Right => R.Right - offset,
    direction =>  R.direction
  );
  -- return R + (-offset);                                          -- alternative implementation
<b>end function</b>;

-- example for an implicit operator creation for integer
<b>function</b> "-" <b>is new</b> range_decrease <b>generic map</b>(T => integer);
</pre></sticky>
---++++!! "*" - Expand a range
<sticky><pre>
<b>function</b> range_expand
  <b>generic</b>   (<b>type</b> T <b>is</b> scalar_type);
  <b>parameter</b> (R : T'range_type; mult : natural) <b>return</b> T'range_type <b>is</b>
  <b>constant</b> offset : integer := (R.Right - R.Left + 1) * (mult - 1);
<b>begin</b>
  <b>return</b> (
    Left => R.Left,
    Right => R.Right + offset,
    direction =>  R.direction
  );
  -- return R + offset;                                             -- alternative implementation
<b>end function</b>;

-- example for an implicit operator creation for integer
<b>function</b> "*" <b>is new</b> range_expand <b>generic map</b>(T => integer);
</pre></sticky>
---++++!! "/" - Split a range
<sticky><pre>
<b>function</b> range_split
  <b>generic</b>   (<b>type</b> T <b>is</b> scalar_type);
  <b>parameter</b> (R : T'range_type; div : positive) <b>return</b> T'range_type <b>is</b>
<b>begin</b>
  <b>constant</b> length : natural := (R.Right - R.Left + 1) / div;
<b>begin</b>
  <b>return</b> (
    Left => R.Left,
    Right => R.Left + length - 1,
    direction =>  R.direction
  );
<b>end function</b>;

-- example for an implicit operator creation for integer
<b>function</b> "/" <b>is new</b> range_split <b>generic map</b>(T => integer);
</pre></sticky>
---++++!! "/" - Divide ranges to get the multiple of each other
<sticky><pre>
<b>function</b> range_div
  <b>generic</b>   (<b>type</b> T <b>is</b> scalar_type);
  <b>parameter</b> (LHS : T'range_type; RHS : T'range_type) <b>return</b> T'range_type <b>is</b>
<b>begin</b>
  <b>return</b> (LHS.Right - LHS.Left + 1) / (RHS.Right - RHS.Left + 1);
<b>end function</b>;

-- example for an implicit operator creation for integer
<b>function</b> "/" <b>is new</b> range_div <b>generic map</b>(T => integer);
</pre></sticky>
---++++!! "&" - Combine two ranges
<sticky><pre>
<b>function</b> range_concat
  <b>generic</b>   (<b>type</b> T <b>is</b> scalar_type);
  <b>parameter</b> (LHS : T'range_type; RHS : T'range_type) <b>return</b> T'range_type <b>is</b>
  <b>constant</b> length : natural := (LHS.Right - LHS.Left + 1);
<b>begin</b>
  <b>return</b> (
    Left => RHS.Left,
    Right => RHS.Right + length,
    direction =>  RHS.direction
  );
  -- return RHS + length;                                            -- alternative implementation
<b>end function</b>;

-- example for an implicit operator creation for integer
<b>function</b> "&" <b>is new</b> range_concat <b>generic map</b>(T => integer);
</pre></sticky>

_This operator is *not commutative*, because only one range's direction can be preserved._
---+++ Relational Operations on Ranges
---++++!! "=" - Strict equality
TODO: needs upgrade
<sticky><pre>
<b>function</b> "="(LHS : integer'range_type; RHS : integer'range_type) <b>return</b> boolean <b>is</b>
<b>begin</b>
  <b>return</b> LHS.direction  = RHS.direction <b>and</b>
         LHS.Left = RHS.Left <b>and</b>
         LHS.Right = RHS.Right;
<b>end function</b>;
</pre></sticky>
---++++!! "/=" - Strict inequality
TODO: needs upgrade
<sticky><pre>
<b>function</b> "/="(LHS : integer'range_type; RHS : integer'range_type) <b>return</b> boolean <b>is</b>
<b>begin</b>
  <b>return not</b> (LHS = RHS);
<b>end function</b>;
</pre></sticky>
---++++!! "?=" - Matching equality
TODO: needs upgrade
<sticky><pre>
<b>function</b> "?="(LHS : integer'range_type; RHS : integer'range_type) <b>return</b> boolean <b>is</b>
<b>begin</b>
  <b>return</b> LHS.direction  = RHS.direction <b>and</b>
         (LHS.Right - LHS.Left) = (RHS.Right - RHS.Left);
<b>end function</b>;
</pre></sticky>
---++++!! "?/=" - Matching inequality
TODO: needs upgrade
<sticky><pre>
<b>function</b> "?/="(LHS : integer'range_type; RHS : integer'range_type) <b>return</b> boolean <b>is</b>
<b>begin</b>
  <b>return not</b> (LHS ?= RHS);
<b>end function</b>;
</pre></sticky>

---+++ Set Operations on Ranges
---+++++!! "and" - Intersection
<sticky><pre>
<b>function</b> "and"(LHS : RANGE_RECORD; RHS : RANGE_RECORD) <b>return</b> RANGE_RECORD  <b>is</b>
<b>begin</b>
  <b>if</b> (LHS ?= RHS) <b>then</b>
    <b>return</b> LHS;
  <b>elsif</b> ((LHS.Left <= RHS.Right) <b>and</b> (LHS.Right >= RHS.Right) <b>and</b> (LHS.Left >= RHS.Left)) <b>then</b>
    <b>return</b> (LHS.Left, RHS.Right, LHS.Direction);
  <b>elsif</b> ((RHS.Left <= LHS.Right) <b>and</b> (RHS.Right >= LHS.Right) <b>and</b> (RHS.Left >= LHS.Left)) <b>then</b>
    <b>return</b> (RHS.Left, LHS.Right, LHS.Direction);
  <b>else</b>
    <b>return</b> (
      Left => 0,
      Right => 0,
      Direction  => NULL_RANGE
    );
  <b>end if</b>;
<b>end function</b>;
</pre></sticky>

_This operator is *not commutative*, because only range's direction can be preserved._
---+++++!! "and" - Is one range a subrange of the other?
<sticky><pre>
<b>function</b> "and"(LHS : RANGE_RECORD; RHS : RANGE_RECORD) <b>return</b> BOOLEAN  <b>is</b>
<b>begin</b>
  <b>return</b> <b>not</b>  is_nullrange(LHS or RHS);
<b>end function</b>;
</pre></sticky>

_This operator is *not commutative*, because only range's direction can be preserved._
---+++++!! "or" - Union
<sticky><pre>
<b>function</b> "or"(LHS : RANGE_RECORD; RHS : RANGE_RECORD) <b>return</b> RANGE_RECORD  <b>is</b>
<b>begin</b>
  <b>if</b> (LHS ?= RHS) <b>then</b>
    <b>return</b> LHS;
  <b>elsif</b> ((LHS.Left <= RHS.Right) <b>and</b> (LHS.Right >= RHS.Right) <b>and</b> (LHS.Left >= RHS.Left)) <b>then</b>
    <b>return</b> (RHS.Left, LHS.Right, LHS.Direction);
  <b>elsif</b> ((RHS.Left <= LHS.Right) <b>and</b> (RHS.Right >= LHS.Right) <b>and</b> (RHS.Left >= LHS.Left)) <b>then</b>
    <b>return</b> (LHS.Left, RHS.Right, LHS.Direction);
  <b>else</b>
    <b>return</b> (
      Left => 0,
      Right => 0,
      Direction  => NULL_RANGE
    );
  <b>end if</b>;
<b>end function</b>;
</pre></sticky>

_This operator is *not commutative*, because only range's direction can be preserved._
---+++++!! "or" - Are both ranges overlapping?
<sticky><pre>
<b>function</b> "or"(LHS : RANGE_RECORD; RHS : RANGE_RECORD) <b>return</b> BOOLEAN  <b>is</b>
<b>begin</b>
  <b>return</b> <b>not</b>  is_nullrange(LHS or RHS);
<b>end function</b>;
</pre></sticky>

_This operator is *not commutative*, because only range's direction can be preserved._
---+++++!! "xor" - Consecutive Ranges
<sticky><pre>
<b>function</b> "xor"(LHS : RANGE_RECORD; RHS : RANGE_RECORD) <b>return</b> RANGE_RECORD  <b>is</b>
<b>begin</b>
  <b>if</b> ((LHS.Left < RHS.Left) <b>and</b> (LHS.Right < RHS.Left) <b>and</b> ((LHS.Right + 1) = RHS.Left)) <b>then</b>
    <b>return</b> (LHS.Left, RHS.Right, LHS.Direction);
  <b>elsif</b> ((RHS.Left < LHS.Left) <b>and</b> (RHS.Right < LHS.Left) <b>and</b> ((RHS.Right + 1) = LHS.Left)) <b>then</b>
    <b>return</b> (RHS.Left, LHS.Right, LHS.Direction);
  <b>else</b>
    <b>return</b> (
      Left => 0,
      Right => 0,
      Direction  => NULL_RANGE
    );
  <b>end if</b>;
<b>end function</b>;
</pre></sticky>


_This operator is *not commutative*, because only range's direction can be preserved._
---+++++!! "xor" - Are both ranges consecutive?
<sticky><pre>
<b>function</b> "xor"(LHS : RANGE_RECORD; RHS : RANGE_RECORD) <b>return</b> BOOLEAN  <b>is</b>
<b>begin</b>
  <b>return</b> <b>not</b>  is_nullrange(LHS xor RHS);
<b>end function</b>;
</pre></sticky>

_This operator is *not commutative*, because only range's direction can be preserved._

---+++ Open Questions (unsolved or for discussion)
---++++!! Q51 - Can ='range_value= by replaced with ='range=?
This proposal requests a special LRM rule, which allows a =range_record= in slices. So if every slice excepts a =range_record=, then ='range= could always return a =range_record=
instance (=range_value=). This in turn allows us to replace ='range_value= with ='range=.
---++++!! Q52 - Is it possible to define attributes on ranges?


---++ Additional Examples
---+++ Composites of Ranges
Imagine a communication controller for a user-defined protocol in a System-on-a-Chip, which offers a register interface. After several redesign cycles
over the past 5 years, the configuration values are scattered over multiple register addresses. This happens if a designer didn't implement enough reserved bits or the projected design lifetime
was exceeded. However, the configuration values as a sequence of config bits can be described as a array or record of ranges, which need to be accessed to gather the
complete configuration value.

<sticky><pre>
<b>signal</b> reg_interface : <b>array</b>(natural <b>range</b> 255 <b>downto</b> 0) <b>of</b> std_logic_vector(31 <b>downto</b> 0);

<b>type</b> Myrange <b>is record</b>
  RegID : natural;
  Rng   : range;
<b>end record</b>;
<b>type</b> MyRange_Vector <b>is array</b>(natural <b>range</b> <>) <b>of</b> MyRange;

<b>function</b> overall_range(RV : MyRange_Vector) <b>return</b> range <b>is</b>
  <b>variable</b> length : natural := 0;
<b>begin</b>
  <b>for</b> i <b>in</b> RV'range <b>loop</b>
    length = length + RV(i).Rng'length;
  <b>end loop</b>;
  <b>return</b> length - 1 <b>downto</b> 0;
<b>end function</b>;

<b>constant</b> capability_flags : MyRange_Vector := (
  0 => (0,  17 <b>downto</b> 4),
  1 => (25,  8 <b>downto</b> 0),
  2 => (97, 31 <b>downto</b> 8)
);

<b>function</b> extract(regs : std_logic_vector <b>of</b> std_logic_vector; positions : MyRange_Vector) <b>return</b> std_logic_vector <b>is</b>
  <b>variable</b> capabilities : std_logic_vector(overall_range(positions));
  <b>variable</b> offset       : natural := 0;
<b>begin</b>
  <b>for</b> i <b>in</b> positions'range <b>loop</b>
    capabilities(RV(i).Rng'normalized + offset) := regs(RV(i).RegID)(RV(i).Rng);
  <b>end loop</b>;
  <b>return</b> capabilities;
<b>end function</b>;

<b>signal</b> capabilities : std_logic_vector(overall_range(positions));

capabilities <= extract(reg_interface, capability_flags)
</pre></sticky>

---+++ Constrained ports without generic parameters.
This example requires [[P1076.OrderingAllInterfaceLists][All Interface Lists Can Be Ordered]]. In 8b/10b encoding, every byte has an additional CharIsK bit, to distinguish data characters from K character and
commas. Such encoders can be described for 1, 2, 4, or 8 bytes.
<sticky><pre>
<b>entity</b> enc_8b10b <b>is</b>
  <b>port</b> (
    DataIn    : <b>in</b>  std_logic_vector;                                   -- must be a multiple of 8, otherwise the next line fails
    CharIsK   : <b>in</b>  std_logic_vector(DataIn'range / 8);                 -- require one K bit per input byte
    DataOut   : <b>out</b> std_logic_vector((DataIn'range / 4) & DataIn'range) -- emit 2 additional bits per byte (10 bits per 8 bit byte)
  );
<b>end entity</b>;
</pre></sticky>

---++ General Comments

---++ Arguments FOR

---++ Arguments AGAINST

---++ Supporters

-- [[Main.PatrickLehmann][Patrick Lehmann]] - 2016-07-19

-- [[Main.BrentHahoe][Brent Hayhoe]] - 2016-07-21

_Add your signature here to indicate your support for the proposal_
Attachments
I	Attachment	Action	Size	Date	Who	Comment
vhdl	char_range.pkg.vhdl	manage	0.2 K	2016-08-15 - 11:36	PatrickLehmann	Package to define a scalar type (enum) for the Ranges package.
ps1	compile.ps1	manage	1.9 K	2016-08-15 - 11:38	PatrickLehmann	Compile script for Windows (PowerShell)
vhdl	ghdl_char.vhdl	manage	8.8 K	2016-08-15 - 11:37	PatrickLehmann	GHDL Testbench for enum ranges.
vhdl	ghdl_integer.vhdl	manage	58.0 K	2016-08-15 - 11:37	PatrickLehmann	GHDL Testbench for integer ranges.
vhdl	integer_range.pkg.vhdl	manage	0.1 K	2016-08-15 - 11:36	PatrickLehmann	Package to define a scalar type (integer) for the Ranges package.
vhdl	ranges.pkg.vhdl	manage	18.5 K	2016-08-15 - 11:32	PatrickLehmann	Implements an (integer) range as a record. Defines property functions and operators on ranges.
Topic revision: r16 - 2020-02-17 - 15:34:30 - JimLewis
P1076