Strategy to add parameters to subsheets on Issie

[tomcl]

Motivation

You might have a subsheet implementing a loadable up/down counter. This will have baked-in bus width output and input which can't be changed in the way that the size of a built-in register can.

Hence subsheets are not generally useful as a way to add library components.

However, in this implementation there are maybe 4 components all with a parameterised width. If all those component parameters could be set from an external sheet-level parameter then the sub-sheet would be usable as a library component.

Functionality

• Add an optional (at least 1, maybe list of?) named parameters to each sheet definition. Set up names in the otherwise empty properties window when editing a sheet and not selecting any component. All parameters are integer and have compulsory default values.
• Add optional bindings of component parameter(s) to sheet parameters, selected instead of integers in int component properties fields.
• When instantiating a subsheet provide instance values for sheet parameters (set in the instance properties window).
• When subsheet parameter instance values are changed update the corresponding bound parameters in the subsheet expansion during simulation graph and fast simulation construction.

Data Structures

• LoadedComponent - add SheetParameter option field
• CustomComponentType - add SheetParameterData option (parameter names and current values)

Design question.

Should the info on which component parameters are bound to sheet parameters be part of the component definition or part of the LoadedComponent definition?

Related Code and implementation

• The CatalogueView creates new components with a popup to select initial values of parameters
• The SelectedComponentView (RH pane) allows parameter values of a component to be chnaged.

1. Currently the code for these two views is distinct - but there is a lot of duplication. A better implementation would use common code for the popup and the properties window parameters. Refactoring for this would change a lot of code but not be very difficult.
2. Ideally - both of these views should allow int boxes to autocomplete parameters as alternative to integers - if parameters have been defined.
3. Typing initial letters in int boxes which do not match parameters can give a popup showing defined parameter names and how to create new ones - which would be from the sheet no component selected properties window.
4. This functionality could be put into int boxes (shared between both views)

Parameter Constraints

An Issie design principle is that it should not be possible to enter non-working code - or - if this is done - the errors should be easily highlighted in a way that makes correction simple.

A few component parameters have constraints on values currently enforced by the input boxes in which they are entered. For example a constant component value must be within the range allowed by its bus width.

These constraints propagate to sheet level, when parameters are bound there. Thus the sheet parameters may have a maximum and minimum value got from the intersection of all the component constraints. Worth noting that most components just enforce parameter value > 0. Some also enforce <= 64 or <= 65.

Switching off I/O ports

Additional functionality that would have value (Quartus library components allow this)

• Allow outputs to be removed (if not used) on specific instances
  • The output would stay on the design sheet but be missing from ports on an instance and not therefore need to be connected
• Allow input to be removed from ports and replaced by a constant on specific instances
  • The input would stay on the design sheet but act as a constant, and be missing from a specific instance ports
  • This is effectively binding a port to a specific value.

The info for this is essentially a tick-box for every output and input. Additionally a default value entered as part of the spec for an input.

Adding fields to types

This idea requires info added to various types. This can most easily be done in a transparent way using optional fields - on JSON save legacy saves will load correctly to new types with the options None.

Adding info to sheet (which turns into LoadedCompoenent)

Currently a sheet is saved as a tuple (component list * connection list). There is no way to add an extra per-sheet field here. compatible with legacy sheets. Probably, we need to have two load types and change to a new top-level sheet datatype which is a record. As soon as we have domne that we can easily add new option fields to the record for future upgrades in what is stored without stopping legacy load.

[tomcl]

Additional Motivation for Input Port default values

• One part of this work is giving input ports default values from their property sheets
• This would be a natural mechanism to set up non-zero values in waveform simulation - and easily implemented

[tomcl]

Implementation plan

Each point is a separate feature - although some of them have no visible effect

1. Add default values to Input component type. Make these changeable in properties, default as now on creation. Allow Inputs and outputs to be Hidden (don't appear on symbol - behave like viewer or default value constant)
   • refactor viewers as hidden outputs
2. Add SheetParam: SheetParam option field to LoadedComponent.
   • Add sheet parameter specification (with compulsory defaults) to sheet properties
   • In case there is one or more parameters add parameter chooser to sheet properties
     • lists all parametrisable components allowing parameter to be as normal, or = sheet parameter
     • Initially make widths the only such parameter
     • allow future extension to constant values
     • allow future extension to parameters defined as sheet parameter expression: plus/minus/integer/brackets using Expr type
3. Make CanvasState a record including SheetParam option, add converter from old sheet format.
4. Add to custom component properties a way to over-ride default parameters with integers or (containing sheet) parameters.
5. Write evaluator which will set all individual component parameters from sheet parameters (recursively) as needed.
   • add programmatic error returns where a parameter is out of bounds
6. Change properties so parameters are frozen if derived from sheet parameters (with nice explanation)
7. Allow constant values to be parameters
8. Using evaluator - deliver proper error messages when bad values are given to sheet parameters
9. Add parser to chooser for parameters which have expression values (with errors)
10. Allow input and output components to be disabled based on parameter condition expressions (only in libraries)
11. Implement sheets defined in a library (and fixed)

From start SheetParam must allow all possible expansions:
parameter values can be arbitrary integer expressions