Variables, auto-routing and links
15. Geo-Variables
Geo-variables allow position-dependent parameter values across a region.
let a = tile(0 0)
a : geovar('example 1)
let b = tile(1 0)
b : geovar('example 2)
let all = rect(0 0 2 1)
all : code('kernel [id:@example])
all : union(a b)
The @ prefix in code() references a geo-variable. The geo-variable
must cover every PE where the corresponding code is applied.
Apply code() to a separate region beside the geo-variable regions, as
above, or apply the geo-variable after code(), as arrayplace does with
copies that already carry code. A geo-variable set on part of a region before
code() is applied to the whole is ignored without a message, and every PE
compiles with one value: with the geo-variables above on a and b,
let all = union(a b) followed by all : code('kernel [id:@example])
compiles both PEs with id=1.
16. Arc Variables
Arc variables are sent along a routing path from source to destination.
region : arcvar('port.varname value)
The name is <terminal>.<var>: this defines varname on the region's
terminal port. A region at the other end of a transport from port
references it with the ^ prefix and the name of its own terminal on that
transport: ^rx.varname, where rx is that terminal. The reference can appear
in link() and other note parameters; a code() parameter rejects it.
17. Symbol Variables
Symbol variables reference entries in a kernel's symbol table:
$symbol_name
Used primarily with link() to reference memory locations for
post-processing fix-ups.
18. Auto-Routing: Terminals and Transports
For complex layouts where manual routing is impractical, paint provides an automatic routing system.
Terminals
region : terminal('port_name 'tag SIDE color [shape] [split] chunk)
region : terminal('port_name 'tag SIDE color [shape] [split] chunk revpin)
| Parameter | Description |
|---|---|
'port_name | Terminal name (used in transport references) |
'tag | Tag for matching source and destination terminals |
SIDE | RIGHT, LEFT, UP, DOWN, or CENTER |
color | Routing color for this terminal |
[shape] | Array describing the terminal shape (e.g. [4 2]) |
[split] | Array describing how the shape is split across PEs; same length as shape, and its product is the number of pins |
chunk | Number of chunks; recorded with the terminal (in regiondump), not used by the router |
revpin | Optional: 1 to reverse pin order |
A pin is a PE that a transport's route connects to. Paint finds the pins from
the region's own paint() rule for the terminal's color: a pin is a PE on side
SIDE whose rule routes that color through that side, such as [C>R] for a
RIGHT terminal and [L>C] for a CENTER one. Without such a rule, Paint
stops with has no pins defined. [1 1] [1 1] is one pin on one PE.
Connected terminals should advertise the same shape and split; Paint does
not check this.
Paint gives both terminals of a transport the same physical color, so give
them the same symbolic color. Given two, Paint numbers them alike, and drops a
color(N) pin on one of them without a message.
SIDE behavior:
- Cardinal directions (
RIGHT,LEFT,UP,DOWN): routing begins/ends on the adjacent PE. CENTER: routing begins/ends on the PE itself. More flexible but overwrites existing routing on the pin PEs.
Transports
let arc = transport('src_region.port 'dst_region.port 'arc_name)
Connects two terminals. The transport creates a new region that must be unioned with the regions containing the terminals:
let all = union(sender receiver arc)
Each terminal is named by its path of region names from the union, such as
'sender.tx or 'outer.inner.rx.
If Paint cannot connect a transport, it prints
port(s) of arc sender.tx -> receiver.rx not found, drops the transport and
still writes the image. This happens with a misspelt name, with name()
applied before terminal(), and with two different tags. A transport left out
of the final union gives no message at all. In each case the image has no
route for it, and the receiving kernel waits forever, so check the paint log
for that line.
Aliases
region : alias('new_name 'child.terminal_name)
Creates a terminal alias at a higher level of the hierarchy, mapping to
a child region's terminal, so that a transport can name 'region.new_name
without knowing the inside of region.
Routing algorithm
The built-in router is a heuristic-based bus router supporting straight-line and orthogonal routes. It does not support multicast.
19. Link
region : link($symbol "order" "program" [param:value ...])
region : link($symbol "order" "program" [param:value ...] disable)
Post-processing fix-up that writes computed values into the machine image after initial compilation.
| Parameter | Description |
|---|---|
$symbol | Symbol table reference to target memory, looked up from the region link is applied to: on region grid, $aa.cell names grid.aa.cell |
"order" | Dimension traversal order (e.g., "y n") |
"program" | An executable on PATH that generates the values |
[params] | Parameters to pass to the program |
disable | Optional: 1 to skip this link |
Paint only records the link in the .note file. milink runs the program
when it links the image, as program key=value ... out=/dev/fd/N: one
argument per parameter, with numbers and colors in hex (color=0x5). The
program writes raw little-endian 16-bit words to the out= file, one word
per element of the dimensions named in the order, with the rightmost
dimension changing fastest. Dimensions not in the order receive the same
words. milink warns supplied data is too short or too long when the
count differs, and fails when the program exits with a nonzero status.