blib/lib/Silicon/Chip.pm

filter: Statementstmt 88.2% 15 / 17 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 6 / 6 Podpod n/a totaltotal 91.3% 21 / 23 CC 1 SCAR 0.5
CC
1
Cov
88%
BEGIN
1.3
BEGIN
1.0
BEGIN
1.0
CRAP 1.0
↑ Summary
1 #!/usr/bin/perl -I/home/phil/perl/cpan/SvgSimple/lib/
2 #-------------------------------------------------------------------------------
3 # Design a silicon chip by combining gates and sub chips.
4 # Philip R Brenan at appaapps dot com, Appa Apps Ltd Inc., 2023
5 #-------------------------------------------------------------------------------
6 # Update sizes from sub chips
7 # Forward propogation of constants from bits()
8 # Speed up left/down collapse by tracking the positions of corners we wish to collapse
9 1 ▶use v5.34;
Subroutine BEGIN: called CC=1 SCAR=0.0
10 package Silicon::Chip;
11 our $VERSION = 20231118; # Version
12 1 ▶use warnings FATAL => qw(all);
Subroutine BEGIN: called CC=1 SCAR=0.0
13 1 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
14 1 ▶use Carp qw(confess carp);
Subroutine BEGIN: called CC=1 SCAR=0.0
15 1 ▶use Data::Dump qw(dump);
Subroutine BEGIN: called CC=1 SCAR=0.0
16 0 ▶use Data::Table::Text qw(:all);
Subroutine BEGIN: called CC=1 SCAR=2.6
17 use Digest::MD5 qw(md5_hex);
18 use Svg::Simple;
19  
20 makeDieConfess;
21  
22 my sub maxSimulationSteps {100} # Maximum simulation steps
23 my sub gateNotIO {0} # Not an input or output gate
24 my sub gateInternalInput {1} # Input gate on an internal chip
25 my sub gateInternalOutput {2} # Output gate on an internal chip
26 my sub gateExternalInput {3} # Input gate on the external chip
27 my sub gateExternalOutput {4} # Output gate on the external chip
28 my sub gateOuterInput {5} # Input gate on the external chip connecting to the outer world
29 my sub gateOuterOutput {6} # Output gate on the external chip connecting to the outer world
30  
31 my $possibleTypes = q(and|continue|gt|input|lt|nand|nor|not|nxor|one|or|output|xor|zero);#Substitute: possible gate types
32  
33 sub debugMask {0} # Adds a grid and fiber names to a mask to help debug fibers if true.
34  
35 #D1 Construct # Construct a L<silicon> L<chip> using standard L<lgs>, components and sub chips combined via buses.
36  
37 sub newChip(%) # Create a new L<chip>.
38 {my (%options) = @_; # Options
39 !@_ or !ref($_[0]) or confess "Call as a sub not as a method";
40 genHash(__PACKAGE__, # Chip description
41 name => $options{name} // $options{title} // "Unnamed chip: ".timeStamp, # Name of chip
42 gates => $options{gates} // {}, # Gates in chip
43 installs => $options{installs} // [], # Chips installed within the chip
44 title => $options{title}, # Title if known
45 gateSeq => 0, # Gate sequence number - this allows us to display the gates in the order they were defined ti simplify the understanding of drawn layouts
46 sizeBits => {}, # Sizes of buses
47 sizeWords => {}, # Sizes of buses
48 );
49 }
50  
51 my sub newGate($$$$) # Make a L<lg>.
52 {my ($chip, $type, $output, $inputs) = @_; # Chip, gate type, output name, input names to output from another gate
53  
54 my $g = genHash(__PACKAGE__."::Gate", # Gate
55 type => $type, # Gate type
56 output => $output, # Output name which is used as the name of the gate as well
57 inputs => $inputs, # Input names to driving outputs
58 io => gateNotIO, # Whether an input/output gate or not
59 seq => ++$chip->gateSeq, # Sequence number for this gate
60 );
61 }
62  
63 my sub validateName($$%) # Confirm that a component name looks like a variable name and has not already been used
64 {my ($chip, $output, %options) = @_; # Chip, name, options
65  
66 my $gates = $chip->gates; # Gates implementing the chip
67  
68 $output =~ m(\A[a-z][a-z0-9_.:]*\Z)i or confess <<"END";
69 Invalid gate name: '$output'
70 END
71  
72 $$gates{$output} and confess <<"END";
73 Gate: '$output' has already been specified
74 END
75 1
76 }
77  
78 sub gate($$$;$$) # A L<lg> chosen from B<possibleTypes>. The gate type can be used as a method name, so B<-E<gt>gate("and",> can be reduced to B<-E<gt>and(>.
79 {my ($chip, $type, $output, $input1, $input2) = @_; # Chip, gate type, output name, input from another gate, input from another gate
80 @_ >= 3 or confess "Three or more parameters";
81 my $gates = $chip->gates; # Gates implementing the chip
82  
83 my $inputs; # Input hash mapping used to accept outputs from other gates as inputs for this gate
84  
85 validateName $chip, $output; # Validate the name of the gate
86  
87 if ($type =~ m(\A(input)\Z)i) # Input gates input to themselves unless they have been connected to an output gate during sub chip expansion
88 {@_> 3 and confess <<"END";
89 No input hash allowed for input gate: '$output'
90 END
91 $inputs = {$output=>$output}; # Convert convenient scalar name to hash for consistency with gates in general
92 }
93 elsif ($type =~ m(\A(one|zero)\Z)i) # Input gates input to themselves unless they have been connected to an output gate during sub chip expansion
94 {@_> 3 and confess <<"END";
95 No input hash allowed for '$type' gate: '$output'
96 END
97 $inputs = {}; # Convert convenient scalar name to hash for consistency with gates in general
98 }
99 elsif ($type =~ m(\A(output)\Z)i) # Output has one optional scalar value naming its input if known at this point
100 {if (defined($input1))
101 {ref($input1) and confess <<"END";
102 Scalar input name required for input on output gate: '$output'
103 END
104 $inputs = {$output=>$input1}; # Convert convenient scalar name to hash for consistency with gates in general
105 }
106 }
107 elsif ($type =~ m(\A(continue|not)\Z)i) # These gates have one input expressed as a name rather than a hash
108 {!defined($input1) and confess "Input name required for gate: '$output'\n";
109 $type =~ m(\Anot\Z)i and ref($input1) =~ m(hash)i and confess <<"END";
110 Scalar input name required for: '$output'
111 END
112 $inputs = {$output=>$input1}; # Convert convenient scalar name to hash for consistency with gates in general
113 }
114 elsif ($type =~ m(\A(nxor|xor|gt|ngt|lt|nlt)\Z)i) # These gates must have exactly two inputs expressed as a hash mapping input pin name to connection to a named gate. These operations are associative.
115 {!defined($input1) and confess <<"END" =~ s/\n/ /gsr;
116 Input one required for gate: '$output'
117 END
118 !defined($input2) and confess <<"END" =~ s/\n/ /gsr;
119 Input two required for gate: '$output'
120 END
121 ref($input1) and confess <<"END" =~ s/\n/ /gsr;
122 Input one must be the name of the connecting gate.
123 END
124 ref($input2) and confess <<"END" =~ s/\n/ /gsr;
125 Input two must be the name of the connecting gate.
126 END
127 $inputs = {1=>$input1, 2=>$input2}; # Construct the inputs hash expected in general for these two input gates
128 }
129 elsif ($type =~ m(\A(and|nand|nor|or)\Z)i) # These gates must have two or more inputs expressed as a hash mapping input pin name to connection to a named gate. These operations are associative.
130 {!defined($input1) and confess <<"END" =~ s/\n/ /gsr;
131 Input hash required for gate: '$output'
132 END
133 if (ref($input1) =~ m(hash)i)
134 {$inputs = $input1;
135 }
136 elsif (ref($input1) =~ m(array)i)
137 {$inputs = {map {$_=>$$input1[$_]} keys @$input1};
138 }
139 else
140 {confess <<"END" =~ s/\n/ /gsr;
141 Inputs must be either a hash of input gate
142 names to output gate names or an array of input gate name for gate: '$output'
143 END
144 }
145 }
146 else # Unknown gate type
147 {confess <<"END" =~ s/\n/ /gsr;
148 Unknown gate type: '$type' for gate: '$output',
149 possible types are: '$possibleTypes
150 END
151 }
152  
153 $chip->gates->{$output} = newGate($chip, $type, $output, $inputs); # Construct gate, save it and return it
154 }
155  
156 our $AUTOLOAD; # The method to be autoloaded appears here. This allows us to have gate names like 'or' and 'and' without overwriting the existing Perl operators with these names.
157  
158 sub AUTOLOAD($@) #P Autoload by L<lg> name to provide a more readable way to specify the L<lgs> on a L<chip>.
159 {my ($chip, @options) = @_; # Chip, options
160 my $type = $AUTOLOAD =~ s(\A.*::) ()r;
161 if ($type !~ m(\A($possibleTypes|DESTROY)\Z)) # Select autoload requests we can process as gate names
162 {confess <<"END" =~ s/\n/ /gsr;
163 Unknown method: '$type'
164 END
165 }
166 &gate($chip, $type, @options) if $type =~ m(\A($possibleTypes)\Z);
167 }
168  
169 my sub cloneGate($$) # Clone a L<lg> on a L<chip>.
170 {my ($chip, $gate) = @_; # Chip, gate
171 my %i = $gate->inputs ? $gate->inputs->%* : (); # Copy inputs
172 newGate($chip, $gate->type, $gate->output, {%i})
173 }
174  
175 my sub getGate($$) # Details of a named gate or confess if no such gate
176 {my ($chip, $name) = @_; # Chip, gate name
177 my $g = $chip->gates->{$name}; # Gate details
178 $g or confess "No such gate as $name\n";
179 $g
180 }
181  
182 my sub renameGateInputs($$$) # Rename the inputs of a L<lg> on a L<chip>.
183 {my ($chip, $gate, $name) = @_; # Chip, gate, prefix name
184 for my $p(qw(inputs))
185 {my %i;
186 my $i = $gate->inputs;
187 for my $n(sort keys %$i)
188 {$i{$n} = sprintf "(%s %s)", $name, $$i{$n};
189 }
190 $gate->inputs = \%i;
191 }
192 $gate
193 }
194  
195 my sub renameGate($$$) # Rename a L<lg> on a L<chip> by adding a prefix.
196 {my ($chip, $gate, $name) = @_; # Chip, gate, prefix name
197 $gate->output = sprintf "(%s %s)", $name, $gate->output;
198 $gate
199 }
200  
201 #D2 Buses # A bus is an array of bits or an array of arrays of bits
202  
203 #D3 Bits # An array of bits that can be manipulated via one name.
204  
205 my sub sizeBits($$%) # Size of a bits bus.
206 {my ($chip, $name, %options) = @_; # Chip, bits bus name, options
207 return $options{bits} if defined($options{bits});
208 my $s = $chip->sizeBits->{$name};
209 defined($s) or confess "No bit bus named ".dump($name)."\n";
210 $s
211 }
212  
213 sub setSizeBits($$$%) # Set the size of a bits bus.
214 {my ($chip, $name, $bits, %options) = @_; # Chip, bits bus name, options
215 @_ >= 3 or confess "Three or more parameters";
216 defined($chip->sizeBits->{$name}) and confess <<"END";
217 A bit bus with name: $name has already been defined
218 END
219 $chip->sizeBits->{$name} = $bits;
220 $chip
221 }
222  
223 sub bits($$$$%) # Create a bus set to a specified number.
224 {my ($chip, $name, $bits, $value, %options) = @_; # Chip, name of bus, width in bits of bus, value of bus, options
225 @_ >= 4 or confess "Four or more parameters";
226 my @b = reverse split //, sprintf "%0${bits}b", $value; # Bits needed
227 for my $b(1..@b) # Generate constant
228 {my $v = $b[$b-1]; # Bit value
229 $chip->one (n($name, $b)) if $v; # Set 1
230 $chip->zero(n($name, $b)) unless $v; # Set 0
231 }
232 setSizeBits($chip, $name, $bits); # Record bus width
233 }
234  
235 sub inputBits($$$%) # Create an B<input> bus made of bits.
236 {my ($chip, $name, $bits, %options) = @_; # Chip, name of bus, width in bits of bus, options
237 @_ >= 3 or confess "Three or more parameters";
238 setSizeBits($chip, $name, $bits); # Record bus width
239 map {$chip->input(n($name, $_))} 1..$bits; # Bus of input gates
240 }
241  
242 sub outputBits($$$%) # Create an B<output> bus made of bits.
243 {my ($chip, $name, $input, %options) = @_; # Chip, name of bus, name of inputs, options
244 @_ >= 3 or confess "Three or more parameters";
245 my $bits = sizeBits($chip, $input, %options);
246 map {$chip->output(n($name, $_), n($input, $_))} 1..$bits; # Bus of output gates
247 setSizeBits($chip, $name, $bits); # Record bus width
248 }
249  
250 sub notBits($$$%) # Create a B<not> bus made of bits.
251 {my ($chip, $name, $input, %options) = @_; # Chip, name of bus, name of inputs, options
252 @_ >= 3 or confess "Three or more parameters";
253 my $bits = sizeBits($chip, $input, %options);
254 map {$chip->not(n($name, $_), n($input, $_))} 1..$bits; # Bus of not gates
255 setSizeBits($chip, $name, $bits); # Record bus width
256 }
257  
258 sub andBits($$$%) # B<and> a bus made of bits.
259 {my ($chip, $name, $input, %options) = @_; # Chip, name of bus, name of inputs, options
260 @_ >= 3 or confess "Three or more parameters";
261 my $bits = sizeBits($chip, $input, %options);
262 $chip->and($name, {map {($_=>n($input, $_))} 1..$bits}); # Combine inputs in one B<and> gate
263 setSizeBits($chip, $name, $bits); # Record bus width
264 }
265  
266 sub nandBits($$$%) # B<nand> a bus made of bits.
267 {my ($chip, $name, $input, %options) = @_; # Chip, name of bus, name of inputs, options
268 @_ >= 3 or confess "Three or more parameters";
269 my $bits = sizeBits($chip, $input, %options);
270 $chip->nand($name, {map {($_=>n($input, $_))} 1..$bits}); # Combine inputs in one B<nand> gate
271 setSizeBits($chip, $name, $bits); # Record bus width
272 }
273  
274 sub orBits($$$%) # B<or> a bus made of bits.
275 {my ($chip, $name, $input, %options) = @_; # Chip, name of bus, options
276 @_ >= 3 or confess "Three or more parameters";
277 my $bits = sizeBits($chip, $input, %options);
278 $chip->or($name, {map {($_=>n($input, $_))} 1..$bits}); # Combine inputs in one B<or> gate
279 setSizeBits($chip, $name, $bits); # Record bus width
280 }
281  
282 sub norBits($$$%) # B<nor> a bus made of bits.
283 {my ($chip, $name, $input, %options) = @_; # Chip, name of bus, options
284 @_ >= 3 or confess "Three or more parameters";
285 my $bits = sizeBits($chip, $input, %options);
286 $chip->nor($name, {map {($_=>n($input, $_))} 1..$bits}); # Combine inputs in one B<nor> gate
287 setSizeBits($chip, $name, $bits); # Record bus width
288 }
289  
290 #D3 Words # An array of arrays of bits that can be manipulated via one name.
291  
292 my sub sizeWords($$%) # Size of a words bus.
293 {my ($chip, $name, %options) = @_; # Chip, word bus name, options
294 my $s = $chip->sizeWords->{$name};
295 my $w = $options{bits} // $$s[0];
296 my $b = $options{words} // $$s[1];
297 defined($w) or confess "No words width specified or defaulted for $name";
298 defined($b) or confess "No bits width specified or defaulted for $name";
299 ($w, $b)
300 }
301  
302 sub setSizeWords($$$$%) # Set the size of a bits bus.
303 {my ($chip, $name, $words, $bits, %options) = @_; # Chip, bits bus name, words, bits per word, options
304 @_ >= 4 or confess "Four or more parameters";
305 defined($chip->sizeWords->{$name}) and confess <<"END";
306 A word bus with name: $name has already been defined
307 END
308 $chip->sizeWords->{$name} = [$words, $bits]; # Word bus size
309 setSizeBits($chip, n($name, $_), $bits) for 1..$words; # Size of bit bus for each word in the word bus
310 $chip
311 }
312  
313 sub words($$$@) # Create a word bus set to specified numbers.
314 {my ($chip, $name, $bits, @values) = @_; # Chip, name of bus, width in bits of each word, values of words
315 @_ >= 3 or confess "Three or more parameters";
316 for my $w(1..@values) # Each value to put on the bus
317 {my $value = $values[$w-1]; # Each value to put on the bus
318 my @b = reverse split //, sprintf "%0${bits}b", $value; # Bits needed
319 for my $b(1..@b) # Generate constant
320 {my $v = $b[$b-1]; # Bit value
321 $chip->one (nn($name, $w, $b)) if $v; # Set 1
322 $chip->zero(nn($name, $w, $b)) unless $v; # Set 0
323 }
324 }
325 setSizeWords($chip, $name, scalar(@values), $bits); # Record bus width
326 }
327  
328 sub inputWords($$$$%) # Create an B<input> bus made of words.
329 {my ($chip, $name, $words, $bits, %options) = @_; # Chip, name of bus, width in words of bus, width in bits of each word on bus, options
330 @_ >= 4 or confess "Four or more parameters";
331 for my $w(1..$words) # Each word on the bus
332 {map {$chip->input(nn($name, $w, $_))} 1..$bits; # Bus of input gates
333 }
334 setSizeWords($chip, $name, $words, $bits); # Record bus size
335 }
336  
337 sub outputWords($$$%) # Create an B<output> bus made of words.
338 {my ($chip, $name, $input, %options) = @_; # Chip, name of bus, name of inputs, options
339 @_ >= 3 or confess "Three or more parameters";
340 my ($words, $bits) = sizeWords($chip, $input);
341 for my $w(1..$words) # Each word on the bus
342 {map {$chip->output(nn($name, $w, $_), nn($input, $w, $_))} 1..$bits; # Bus of output gates
343 }
344 setSizeWords($chip, $name, $words, $bits); # Record bus size
345 }
346  
347 sub notWords($$$%) # Create a B<not> bus made of words.
348 {my ($chip, $name, $input, %options) = @_; # Chip, name of bus, name of inputs, options
349 @_ >= 3 or confess "Three or more parameters";
350 my ($words, $bits) = sizeWords($chip, $input, %options);
351 for my $w(1..$words) # Each word on the bus
352 {map {$chip->not(nn($name, $w, $_), nn($input, $w, $_))} 1..$bits; # Bus of not gates
353 }
354 setSizeWords($chip, $name, $words, $bits); # Record bus size
355 }
356  
357 sub andWords($$$%) # B<and> a bus made of words to produce a single word.
358 {my ($chip, $name, $input, %options) = @_; # Chip, name of bus, name of inputs, options
359 @_ >= 3 or confess "Three or more parameters";
360 my ($words, $bits) = sizeWords($chip, $input, %options);
361 for my $w(1..$words) # Each word on the bus
362 {$chip->andBits(n($name, $w), n($input, $w)); # Combine inputs using B<and> gates
363 }
364 setSizeBits($chip, $name, $words); # Record bus size
365 }
366  
367 sub andWordsX($$$%) # B<and> a bus made of words by and-ing the corresponding bits in each word to make a single word.
368 {my ($chip, $name, $input, %options) = @_; # Chip, name of bus, name of inputs, options
369 @_ >= 3 or confess "Three or more parameters";
370 my ($words, $bits) = sizeWords($chip, $input, %options);
371 for my $b(1..$bits) # Each word on the bus
372 {$chip->and(n($name, $b), {map {($_=>nn($input, $_, $b))} 1..$words}); # Combine inputs using B<and> gates
373 }
374 setSizeBits($chip, $name, $bits); # Record bus size
375 }
376  
377 sub orWords($$$%) # B<or> a bus made of words to produce a single word.
378 {my ($chip, $name, $input, %options) = @_; # Chip, name of bus, name of inputs, options
379 @_ >= 3 or confess "Three or more parameters";
380 my ($words, $bits) = sizeWords($chip, $input, %options);
381 for my $w(1..$words) # Each word on the bus
382 {$chip->orBits(n($name, $w), n($input, $w)); # Combine inputs using B<or> gates
383 }
384 setSizeBits($chip, $name, $words); # Record bus size
385 }
386  
387 sub orWordsX($$$%) # B<or> a bus made of words by or-ing the corresponding bits in each word to make a single word.
388 {my ($chip, $name, $input, %options) = @_; # Chip, name of bus, name of inputs, options
389 @_ >= 3 or confess "Three or more parameters";
390 my ($words, $bits) = sizeWords($chip, $input, %options);
391 for my $b(1..$bits) # Each word on the bus
392 {$chip->or(n($name, $b), {map {($_=>nn($input, $_, $b))} 1..$words}); # Combine inputs using B<or> gates
393 }
394 setSizeBits($chip, $name, $bits); # Record bus size
395 }
396  
397 #D2 Connect # Connect input buses to other buses.
398  
399 sub connectInput($$$%) # Connect a previously defined input gate to the output of another gate on the same chip. This allows us to define a set of gates on the chip without having to know, first, all the names of the gates that will provide input to these gates.
400 {my ($chip, $in, $to, %options) = @_; # Chip, input gate, gate to connect input gate to, options
401 @_ >= 3 or confess "Three or more parameters";
402 my $gates = $chip->gates;
403 my $i = $$gates{$in};
404 defined($i) or confess "No definition of input gate $in";
405 $i->type =~ m(\Ainput\Z) or confess "No definition of input gate $in";
406 $i->inputs = {1=>$to};
407 $chip
408 }
409  
410 sub connectInputBits($$$%) # Connect a previously defined input bit bus to another bit bus provided the two buses have the same size.
411 {my ($chip, $in, $to, %options) = @_; # Chip, input gate, gate to connect input gate to, options
412 @_ >= 3 or confess "Three or more parameters";
413 my $I = sizeBits($chip, $in);
414 my $T = sizeBits($chip, $to);
415 $I == $T or confess <<"END" =~ s/\n(.)/ $1/gsr;
416 Mismatched bits bus width: input has $I bits but output has $T bits.
417 END
418 connectInput($chip, n($in, $_), n($to, $_)) for 1..$I;
419 $chip
420 }
421  
422 sub connectInputWords($$$%) # Connect a previously defined input word bus to another word bus provided the two buses have the same size.
423 {my ($chip, $in, $to, %options) = @_; # Chip, input gate, gate to connect input gate to, options
424 @_ >= 3 or confess "Three or more parameters";
425 my ($iw, $ib) = sizeWords($chip, $in);
426 my ($tw, $tb) = sizeWords($chip, $to);
427 $iw == $tw or confess <<"END" =~ s/\n(.)/ $1/gsr;
428 Mismatched words bus: input has $iw words but output has $tw words
429 END
430 $ib == $tb or confess <<"END" =~ s/\n(.)/ $1/gsr;
431 Mismatched bits width of words bus: input has $ib bits but output has $tb bits
432 END
433 connectInputBits($chip, n($in, $_), n($to, $_)) for 1..$iw;
434 $chip
435 }
436  
437 #D2 Install # Install a chip within a chip as a sub chip.
438  
439 sub install($$$$%) # Install a L<chip> within another L<chip> specifying the connections between the inner and outer L<chip>. The same L<chip> can be installed multiple times as each L<chip> description is read only.
440 {my ($chip, $subChip, $inputs, $outputs, %options) = @_; # Outer chip, inner chip, inputs of inner chip to to outputs of outer chip, outputs of inner chip to inputs of outer chip, options
441 @_ >= 4 or confess "Four or more parameters";
442 my $c = genHash(__PACKAGE__."::Install", # Installation of a chip within a chip
443 chip => $subChip, # Chip being installed
444 inputs => $inputs, # Outputs of outer chip to inputs of inner chip
445 outputs => $outputs, # Outputs of inner chip to inputs of outer chip
446 );
447 push $chip->installs->@*, $c; # Install chip
448 $c
449 }
450  
451 my sub getGates($%) # Get the L<lgs> of a L<chip> and all it installed sub chips.
452 {my ($chip, %options) = @_; # Chip, options
453  
454 my %outerGates;
455 for my $g(sort {$a->seq <=> $b->seq} values $chip->gates->%*) # Copy gates from outer chip
456 {my $G = $outerGates{$g->output} = cloneGate($chip, $g);
457 if ($G->type =~ m(\Ainput\Z)i) {$G->io = gateExternalInput} # Input gate on outer chip
458 elsif ($G->type =~ m(\Aoutput\Z)i) {$G->io = gateExternalOutput} # Output gate on outer chip
459 }
460  
461 my @installs = $chip->installs->@*; # Each sub chip used in this chip
462  
463 for my $install(keys @installs) # Each sub chip
464 {my $s = $installs[$install]; # Sub chip installed in this chip
465 my $n = $s->chip->name; # Name of sub chip
466 my $innerGates = __SUB__->($s->chip); # Gates in sub chip
467  
468 for my $G(sort {$$innerGates{$a}->seq <=> $$innerGates{$b}->seq}
469 keys %$innerGates) # Each gate in sub chip on definition order
470 {my $g = $$innerGates{$G}; # Gate in sub chip
471 my $o = $g->output; # Name of gate
472 my $copy = cloneGate $chip, $g; # Clone gate from chip description
473 my $newGateName = sprintf "$n %d", $install+1; # Rename gates to prevent name collisions from the expansions of the definitions of the inner chips
474  
475 if ($copy->type =~ m(\Ainput\Z)i) # Input gate on inner chip - connect to corresponding output gate on containing chip
476 {my $in = $copy->output; # Name of input gate on inner chip
477 my $o = $s->inputs->{$in};
478 $o or confess <<"END";
479 No connection specified to inner input gate: '$in' on sub chip: '$n'
480 END
481 my $O = $outerGates{$o};
482 $O or confess <<"END" =~ s(\n) ( )gsr;
483 No outer output gate '$o' to connect to inner input gate: '$in'
484 on sub chip: '$n'
485 END
486 my $ot = $O->type;
487 my $on = $O->output;
488 $ot =~ m(\Aoutput\Z)i or confess <<"END" =~ s(\n) ( )gsr;
489 Output gate required for connection to: '$in' on sub chip $n,
490 not: '$ot' gate: '$on'
491 END
492 $copy->inputs = {1 => $o}; # Connect inner input gate to outer output gate
493 renameGate $chip, $copy, $newGateName; # Add chip name to gate to disambiguate it from any other gates
494 $copy->io = gateInternalInput; # Mark this as an internal input gate
495 }
496  
497 elsif ($copy->type =~ m(\Aoutput\Z)i) # Output gate on inner chip - connect to corresponding input gate on containing chip
498 {my $on = $copy->output; # Name of output gate on outer chip
499 my $i = $s->outputs->{$on};
500 $i or confess <<"END";
501 No connection specified to inner output gate: '$on' on sub chip: '$n'
502 END
503 my $I = $outerGates{$i};
504 $I or confess <<"END";
505 No outer input gate: '$i' to connect to inner output gate: $on on sub chip: '$n'
506 END
507 my $it = $I->type;
508 my $in = $I->output;
509 $it =~ m(\Ainput\Z)i or confess <<"END" =~ s(\n) ( )gsr;
510 Input gate required for connection to '$in' on sub chip '$n',
511 not gate '$in' of type '$it'
512 END
513 renameGateInputs $chip, $copy, $newGateName;
514 renameGate $chip, $copy, $newGateName;
515 $I->inputs = {11 => $copy->output}; # Connect inner output gate to outer input gate
516 $copy->io = gateInternalOutput; # Mark this as an internal output gate
517 }
518 else # Rename all other gate inputs
519 {renameGateInputs $chip, $copy, $newGateName;
520 renameGate $chip, $copy, $newGateName;
521 }
522  
523 $outerGates{$copy->output} = $copy; # Install gate with new name now it has been connected up
524 }
525 }
526 \%outerGates # Return all the gates in the chip extended by its sub chips
527 }
528  
529 my sub checkIO($%) # Check that each input L<lg> is connected to one output L<lg>.
530 {my ($chip, %options) = @_; # Chip, options
531 my $gates = $chip->gates; # Gates on chip
532  
533 my %o;
534 for my $G(sort keys %$gates) # Find all inputs and outputs
535 {my $g = $$gates{$G}; # Address gate
536 my $t = $g->type; # Type of gate
537 my %i = $g->inputs->%*; # Inputs for gate
538 for my $i(sort keys %i) # Each input
539 {my $o = $i{$i}; # Output driving input
540 defined($o) or confess <<"END"; # No driving output
541 No output driving input pin '$i' on '$t' gate '$G'
542 END
543 my $O = $$gates{$o};
544 defined($O) or confess <<"END"; # No driving output
545 No output driving input '$o' on '$t' gate '$G'
546 END
547 if ($g->io != gateOuterInput) # The gate must inputs driven by the outputs of other gates
548 {$o{$o}++; # Show that this output has been used
549 my $T = $O->type;
550 if ($g->type =~ m(\Ainput\Z)i)
551 {$O->type =~ m(\Aoutput\Z)i or confess <<"END" =~ s(\n) ( )gsr;
552 Input gate: '$G' must connect to an output gate on pin: '$i'
553 not to '$T' gate: '$o'
554 END
555 }
556 elsif (!$g->io) # Not an io gate so it cannot have an input from an output gate
557 {$O->type =~ m(\Aoutput\Z) and confess <<"END";
558 Cannot drive a '$t' gate: '$G' using output gate: '$o'
559 END
560 }
561 }
562 }
563 }
564  
565 for my $G(sort keys %$gates) # Check all inputs and outputs are being used
566 {my $g = $$gates{$G}; # Address gate
567 next if $g->type =~ m(\Aoutput\Z)i;
568 $o{$G} or confess <<"END" =~ s/\n/ /gsr;
569 Output from gate '$G' is never used
570 END
571 }
572 }
573  
574 my sub setOuterGates($$%) # Set outer L<lgs> on external chip that connect to the outer world.
575 {my ($chip, $gates, %options) = @_; # Chip, gates in chip plus all sub chips as supplied by L<getGates>.
576  
577 for my $G(sort keys %$gates) # Find all inputs and outputs
578 {my $g = $$gates{$G}; # Address gate
579 next unless $g->io == gateExternalInput; # Input on external chip
580 my ($i) = values $g->inputs->%*;
581 $g->io = gateOuterInput if $g->output eq $i; # Unconnected input gates reflect back on themselves - this is a short hand way of discovering such gates
582 }
583  
584 gate: for my $G(sort keys %$gates) # Find all inputs and outputs
585 {my $g = $$gates{$G}; # Address gate
586 next unless $g->io == gateExternalOutput; # Output on external chip
587 for my $H(sort keys %$gates) # Gates driven by this gate
588 {next if $G eq $H;
589 my %i = $$gates{$H}->inputs->%*; # Inputs to this gate
590 for my $I(sort keys %i) # Each input
591 {next gate if $i{$I} eq $G; # Found a gate that accepts input from this gate
592 }
593 }
594 $g->io = gateOuterOutput; # Does not drive any other gate
595 }
596 }
597  
598 my sub removeExcessIO($$%) # Remove unneeded IO L<lgs> .
599 {my ($chip, $gates, %options) = @_; # Chip, gates in chip plus all sub chips as supplied by L<getGates>.
600  
601 my %d; # Names of gates to delete
602 for(;;) # Multiple passes until no more gates can be replaced
603 {my $changes = 0;
604  
605 gate: for my $G(sort keys %$gates) # Find all inputs and outputs
606 {my $g = $$gates{$G}; # Address gate
607 next unless $g->io; # Skip non IO gates
608 next if $g->io == gateOuterInput or $g->io == gateOuterOutput; # Cannot be collapsed
609 my ($n) = values $g->inputs->%*; # Name of the gate driving this gate
610  
611 for my $H(sort keys %$gates) # Gates driven by this gate
612 {next if $G eq $H;
613 my $h = $$gates{$H}; # Address gate
614 my %i = $h->inputs->%*; # Inputs
615 for my $i(sort keys %i) # Each input
616 {if ($i{$i} eq $G) # Found a gate that accepts input from this gate
617 {my $replace = $h->inputs->{$i};
618 $h->inputs->{$i} = $n; # Bypass io gate
619 $d{$G}++; # Delete this gate
620 ++$changes; # Count changes in this pass
621 }
622 }
623 }
624 }
625 last unless $changes;
626 }
627 for my $d(sort keys %d) # Gates to delete
628 {delete $$gates{$d};
629 }
630 }
631  
632 #D1 Visualize # Visualize the L<chip> in various ways.
633  
634 my sub orderGates($%) # Order the L<lgs> on a L<chip> so that input L<lg> are first, the output L<lgs> are last and the non io L<lgs> are in between. All L<lgs> are first ordered alphabetically. The non io L<lgs> are then ordered by the step number at which they last changed during simulation of the L<chip>. This has the effect of placing all the buses in the upper right corner as there are no loops.
635 {my ($chip, %options) = @_; # Chip, options
636  
637 my $gates = $chip->gates; # Gates on chip
638 my @i; my @n; my @o;
639  
640 for my $G(sort {$$gates{$a}->seq <=> $$gates{$b}->seq} keys %$gates) # Dump each gate one per line in definition order
641 {my $g = $$gates{$G};
642 push @i, $G if $g->type =~ m(\Ainput\Z)i;
643 push @n, $G if $g->type !~ m(\A(in|out)put\Z)i;
644 push @o, $G if $g->type =~ m(\Aoutput\Z)i;
645 }
646  
647 if (my $c = $options{changed}) # Order non IO gates by last change time during simulation if possible
648 {@n = sort {($$c{$a}//0) <=> ($$c{$b}//0)} @n;
649 }
650  
651 (\@i, \@n, \@o)
652 }
653  
654 sub print($%) # Dump the L<lgs> present on a L<chip>.
655 {my ($chip, %options) = @_; # Chip, gates, options
656 my $gates = $chip->gates; # Gates on chip
657 my $values = $options{values}; # Values of each gate if known
658 my @s;
659 my ($i, $n, $o) = orderGates $chip, %options; # Gates by type
660 for my $G(@$i, @$n, @$o) # Dump each gate one per line
661 {my $g = $$gates{$G};
662 my %i = $g->inputs ? $g->inputs->%* : ();
663  
664 my $p = sub # Instruction name and type
665 {my $v = $$values{$G}; # Value if known for this gate
666 my $o = $g->output;
667 my $t = $g->type;
668 return sprintf "%-32s: %3d %-32s", $o, $v, $t if defined($v); # With value
669 return sprintf "%-32s: %-32s", $o, $t; # Without value
670 }->();
671  
672 if (my @i = map {$i{$_}} sort keys %i) # Add actual inputs in same line sorted in input pin name
673 {$p .= join " ", @i;
674 }
675 push @s, $p;
676 }
677 my $s = join "\n", @s, ''; # Representation of gates as text
678 owf fpe($options{print}, q(txt)), $s if $options{print}; # Write representation of gates as text to the named file
679 $s
680 }
681  
682 sub Silicon::Chip::Simulation::print($%) # Print simulation results as text.
683 {my ($sim, %options) = @_; # Simulation, options
684 $sim->chip->print(%options, values=>$sim->values);
685 }
686  
687 my sub newGatePosition(%) # Specify the position of a L<lg> on a drawing of the containing L<chip>.
688 {my (%options) = @_; # Options
689  
690 genHash(__PACKAGE__."::Position", # Gate position
691 gate => $options{gate} // undef, # Gate
692 x => $options{x} // undef, # X position of gate
693 y => $options{y} // undef, # Y position of gate
694 width => $options{width} // undef, # Width of gate
695 busLine => $options{busLine} // undef, # Bus line
696 busStart => $options{busStart} // undef, # Bus line start
697 busEnd => $options{busEnd} // undef, # Bus Line end
698 );
699 }
700  
701 my sub firstLastOne($) # Find the first and last ones in a bit string and return the 1-based indices as a pair.
702 {my ($a) = @_; # First string, second string
703 my sub a($) {substr($a, $_[0]-1, 1)} # Index to element of first bit string array
704  
705 my $f; my $l; # First B<1> and last B<1> in the string
706 for my $i(1..length($a))
707 {$l = $i if a $i; # Later B<1>
708 $f = $i if a($i) and !defined $f; # First B<1>
709 }
710 ($f, $l)
711 }
712  
713 my sub layoutInputBus(@) # Given an array of bit strings lay them out from left to right in lines so that the B<1>s of each possible pairs of bit strings do not overlap per L<canBothFitOnSameLine>. Returns an array mapping the strings to lines. There is no reason to suppose that the proposed layout is optimal - this is a packing problem with all the usual difficulties associated with such problems. This layout requires three levels. 1: Down from input gate. 2: horizontal until vertically above a gate we wish to connect this input pin to. 3: down to the gate we wish to connect to. Three levels is enough because in the worst case each input gate can have its own horizontal which we can reach because the gates are spaced horizontally. Each such horizontal can be connected vertically on level 3 to an input of a non input gate because no two input gates are connected to the same pin on any other gate.
714 {my (@a) = @_; # Array of bit strings to be laid out
715  
716 my @l; # Proposed input bus lines
717 my %u = map {$_=>1} 1..@a; # Unplaced inputs
718 my @m; # Input index to input bus line
719  
720 my sub combine($$) # Combine the latest element to fit on the specified line
721 {my ($a, $b) = @_; # Old line new line
722 my $c = ''; # Resulting line
723 for my $i(1..length($a))
724 {$c .= substr($a, $i-1, 1) || substr($b, $i-1, 1) ? '1' : '0'; # Merge bit by bit
725 }
726 $c
727 }
728  
729 my sub findFirst() # Find first remaining input to place
730 {my ($a) = sort {$a <=> $b} keys %u;
731 $a
732 }
733  
734 for(;keys %u;) # Unplaced inputs still
735 {my $p = findFirst; # New bus line with first remaining input gate
736 delete $u{$p}; # Show placed
737 my $l = $a[$p-1]; # Places required
738 my ($s, $e) = firstLastOne($l); # Placement range
739 push @l, $l; # New bus line
740 $m[$p] = @l; # Map gate to bus line
741  
742 for my $i(1..@a) # Possible inputs on this line
743 {next unless $u{$i}; # Skip inputs already placed
744 my $l = $a[$i-1]; # Places required
745 my ($S, $F) = firstLastOne($l); # Position requested on bus line
746 if ($S > $e) # Can fit on the current line
747 {$l[-1] = combine($l[-1], $l); # Place latest addition to current line
748 $m[$i] = @l; # Map placement
749 $e = $F; # Current end point
750 delete $u{$i}; # Used
751 }
752 }
753 }
754 shift @m; # Remove initial L<undef> to make result array zero based
755 @m
756 }
757  
758 sub printSvg($%) # Mask the L<lgs> onto a L<chip> as an L<svg> drawing to help visualize the structure of the L<chip> using a condensed input bus.
759 {my ($chip, %options) = @_; # Chip, options
760 my $gates = $chip->gates; # Gates on chip
761 my $title = $chip->title; # Title of chip
762 my $changed = $options{changed}; # Step at which gate last changed in simulation
763 my $values = $options{values}; # Values of each gate if known
764 my $steps = $options{steps}; # Number of steps to equilibrium
765  
766 my sub fs {0.2} my sub fw {0.02} # Font sizes
767 my sub Fs {0.4} my sub Fw {0.04}
768 my sub op0 {q(transparent)}
769  
770 my @defaults = (defaults=>{stroke_width=>fw, font_size=>fs}); # Default values
771 my $s = Svg::Simple::new(@defaults, %options, grid=>0); # Draw each gate via Svg
772  
773 my %p; # Dimensions and drawing positions of gates
774 my ($iG, $nG, $oG) = orderGates $chip, %options; # Gates by type
775  
776 for my $i(keys @$iG) # Position of each input gate
777 {my $G = $$iG[$i]; # Gate name
778 my $g = $$gates{$G}; # Gate
779 $p{$G} = newGatePosition(gate=>$g, x=>$i, y=>0, width=>1); # Position input gate. The gates are drawn horizontally across the top with the input bus beneath them.
780 }
781  
782 my $W = 0; # Number of inputs to all the non IO gates
783 my @iBus; # Input bus
784 my $miw = 0; # Maximum width of input bus
785  
786 for my $i(keys @$nG) # Position of each non io gate
787 {my $G = $$nG[$i]; # Gate name
788 my $g = $$gates{$G}; # Gate
789 my %i = $g->inputs->%*; # Gates driving this gate
790 my $w = 0; # Input pin position on gate
791 for my $I(sort keys %i) # Each driver of this gate in pin order
792 {my $D = $i{$I}; # Name of driving gate
793 my $d = $$gates{$D}; # Details of driving gate
794 if ($d->io == gateOuterInput)
795 {my $ix = $p{$d->output}->x; # Position of input gate in x
796 my $nx = $W+$w; # Position of driven gate in x
797 $iBus[$ix][$ix] = '1'; # Mark position of driving input gate on input bus
798 $iBus[$ix][$nx] = '1'; # Mark position of pin on driven gate on input bus
799 $miw = max($miw, $ix+1, $nx+1); # Maximum width of input bus. Plus one because we must take into account the width of the input gate and the driven pins
800 }
801 $w++; # Next driver position
802 }
803 $p{$G} = newGatePosition(gate => $g, x => $W, y => $i, width =>$w); # Position non io gate
804 $W += $w; # Width of area needed for non io gates
805 }
806  
807 for my $b(@iBus) # Represent the input bus lines as strings as they are easier to visualize
808 {$b = pad join('', map {$_ ? '1' : '0'} @$b), $miw, '0';
809 }
810  
811 my @iBusLayout = layoutInputBus(@iBus); # Input bus line for each input gate
812  
813 if (@iBusLayout) # Usually there are outer input pins - but not always.
814 {my $iBusHeight = 1 + max(@iBusLayout); # The height of the input bus area
815 #say STDERR "Improvement: ", scalar(@iBus) / $iBusHeight);
816 for my $i(keys @$iG) # Position of each input gate
817 {my $G = $$iG[$i]; # Gate name
818 my $L = $p{$G}; # Layout for input gate
819 my $B = $L->busLine = $iBusLayout[$i]; # Bus line for this input gate
820 my ($f, $l) = firstLastOne($iBus[$i]); # Limits on bus line for this input gate
821 $L->busStart = $f; $L->busEnd = $l; # Save limits on bus line for this input gate
822 my $y = 1/2 + $B; # Vertical position of input bus line
823 my $c = q(#DC143C); # B<Spanish Crimson> for horizontal input bus lines
824 if ($f != $l) # Horizontal input bar required for this gate
825 {$s->line(x1 => $f-1/2, x2 => $l-1/2, y1 => $y, y2 => $y, stroke => $c); # Draw level 2 input bus line
826 }
827 my $Lx = $L->x+1/2; my $Ly = 1/2 + $B; my @o = (opacity=>0.3);
828 $s->line (x1 => $Lx, x2 => $Lx, @o, stroke_width => 2*Fw, # Draw vertical level 1 input bus line
829 y1 => 1, y2 => $Ly, stroke => "blue");
830 $s->circle(cx => $Lx, cy => $Ly, r => 3*Fw, @o, fill => "blue"); # Draw circle connecting vertical level 1 input bus line to horizontal level 2
831 }
832  
833 for my $i(keys @$nG) # Reposition the non io gates a little further down to make room for the input bus area
834 {my $G = $$nG[$i]; # Gate name
835 my $n = $p{$G}; # Layout for input gate
836 $n->y += $iBusHeight;
837 }
838 }
839  
840 for my $i(keys @$oG) # Position each output gate
841 {my $G = $$oG[$i]; # Gate name
842 my $g = $$gates{$G}; # Gate
843 my %i = $g->inputs ? $g->inputs->%* : (); # Inputs to gate
844 my ($d) = values %i; # The one driver for this gate
845 next unless defined $p{$d};
846 my $y = $p{$d}->y;
847 $p{$G} = newGatePosition(gate=>$g, x=>$W, y=>$y, width=>1); # Position output gate
848 }
849  
850 my $pageWidth = $W + 1; # Width of input, output and non io gates as laid out.
851  
852 if (defined($title)) # Title if known
853 {$s->text(x=>$pageWidth, y=>0.5, fill=>"darkGreen", text_anchor=>"end",
854 stroke_width=>Fw, font_size=>Fs, z=>-1,
855 cdata=>$title);
856 }
857  
858 if (defined($steps)) # Number of steps taken if known
859 {$s->text(x=>$pageWidth, y=>1.5, fill=>"darkGreen", text_anchor=>"end",
860 stroke_width=>Fw, font_size=>Fs, z=>-1,
861 cdata=>"$steps steps");
862 }
863  
864 for my $P(sort keys %p) # Each gate with text describing it
865 {my $p = $p{$P};
866 my $x = $p->x;
867 my $y = $p->y;
868 my $w = $p->width;
869 my $g = $p->gate;
870  
871 my $color = sub
872 {return "red" if $g->io == gateOuterOutput;
873 return "blue" if $g->io == gateOuterInput;
874 "green"
875 }->();
876  
877 if ($g->io) # Circle for io pin
878 {$s->circle(cx=>$x+1/2, cy=>$y+1/2, r=>1/2, fill=>op0, stroke=>$color);
879 }
880 else # Rectangle for non io gate
881 {$s->rect(x=>$x, y=>$y, width=>$w, height=>1, fill=>op0, stroke=>$color);
882 }
883  
884 if (defined(my $v = $$values{$g->output})) # Value of gate if known
885 {$s->text(
886 x => $g->io != gateOuterOutput ? $x : $x + 1,
887 y => $y,
888 fill =>"black",
889 stroke_width => Fw,
890 font_size => Fs,
891 text_anchor => $g->io != gateOuterOutput ? "start": "end",
892 dominant_baseline => "hanging",
893 cdata => $v ? "1" : "0");
894 }
895  
896 if (defined(my $t = $$changed{$g->output}) and !$g->io) # Gate change time if known for a non io gate
897 {$s->text(
898 x => $w + ($g->io != gateOuterOutput ? $x : $x + 1),
899 y => 1 + $y,
900 fill =>"black",
901 stroke_width => fw,
902 font_size => fs,
903 text_anchor => "end",
904 cdata => $t+1);
905 }
906  
907 my sub ot($$$$) # Output svg text
908 {my ($dy, $fill, $pos, $text) = @_;
909 $s->text(x => $x+$w/2,
910 y => $y+$dy,
911 fill => $fill,
912 text_anchor => "middle",
913 dominant_baseline => $pos,
914 cdata => $text);
915 }
916  
917 ot(5/12, "red", "auto", $g->type); # Type of gate
918 ot(7/12, "darkblue", "hanging", $g->output);
919  
920 if ($g->io != gateOuterInput) # Not an input pin
921 {my %i = $g->inputs ? $g->inputs->%* : ();
922 my @i = sort keys %i; # Connections to each gate
923 my $o = $g->output;
924  
925 for my $i(keys @i) # Connections to each gate
926 {my $D = $i{$i[$i]}; # Driving gate name
927 my $P = $p{$D}; # Driving gate
928 defined($P) or confess <<"END";
929 No such gate as: '$D' on gate $o
930 END
931 my $X = $P->x; my $Y = $P->y; my $W = $P->width; my $G = $P->gate; # Position of source gate
932 my $dx = $i + 1/2;
933 my $dy = $Y < $y ? 0 : 1;
934 my $dX = $X < $x ? $W : 0;
935 my $dY = $Y < $y ? 0 : 0;
936 my $cx = $x+$dx; # Horizontal line corner x
937 my $cy = $Y+$dY+1/2; # Horizontal line corner y
938  
939 my $xc = $X < $x ? q(black) : q(darkBlue); # Horizontal line color
940 my $x2 = $g->io == gateOuterOutput ? $cx - 1/2 : $cx;
941  
942 if ($P->gate->io != gateOuterInput) # Not being driven by an outer input gate.
943 {$s->line(x1=>$X+$dX, x2=>$x2, y1=>$cy, y2=>$cy, stroke=>$xc); # Outgoing value along horizontal lines
944 }
945  
946 my $yc = $Y < $y ? q(purple) : q(darkRed); # Vertical lines
947  
948 if ($g->io != gateOuterOutput) # Not an output gate
949 {my $Cy = $cy;
950 $Cy = $P->busLine + 1/2 if $P->gate->io == gateOuterInput; # Connect to input level 2 horizontal bar if connecting to an outer input gate
951 $s->line (x1=>$cx, x2=>$cx, y1=>$Cy, y2=>$y+$dy, stroke=>$yc); # Incoming value along vertical line - not needed for outer output gates
952 $s->circle(cx=>$cx, cy=>$Cy, r=>0.06, fill=>"red"); # Line corner
953 $s->circle(cx=>$x2, cy=>$y+$dy, r=>0.04, fill=>"blue"); # Line entering gate
954 }
955 else # External output gate
956 {$s->circle(cx=>$x2, cy=>$y+$dy-1/2, r=>0.04, fill=>"blue"); # Line entering output
957 }
958  
959 if ($P->gate->io != gateOuterInput) # Not an outer input gate
960 {$s->circle(cx=>$X+$W, cy=>$cy, r=>0.04, fill=>"red"); # Horizontal line exiting gate
961 }
962  
963 if (defined(my $v = $$values{$G->output}) and $g->io != gateOuterOutput)# Value of gate if known except for output gates written else where
964 {my $bottom = $x > $X || $G->io == gateOuterInput;
965 my $Y = $y + $dy + fs;
966 $s->text(
967 x => $cx,
968 y => $Y,
969 fill => "black",
970 stroke_width => fw,
971 font_size => fs,
972 text_anchor => "middle",
973 $bottom ? () : (dominant_baseline=>"hanging"),
974 cdata => $v ? "1" : "0");
975 }
976 }
977 }
978 }
979 my $t = $s->print;
980 return owf(fpe($options{svg}, q(svg)), $t) if $options{svg};
981 $t
982 }
983  
984 sub Silicon::Chip::Simulation::printSvg($%) # Print simulation results as svg.
985 {my ($sim, %options) = @_; # Simulation, options
986 printSvg($sim->chip, %options, values=>$sim->values);
987 }
988  
989 my sub layoutAsFiberBundle($%) # Layout the gates as a fiber bundle collapsed down to as close to the gates as possible. The returned information is sufficient to draw an svg image of the fiber bundle.
990 {my ($chip, %options) = @_; # Chip, options
991 my %gates = $chip->gates->%*; # Gates on chip
992 my $changed = $options{changed}; # Step at which gate last changed in simulation
993 my $values = $options{values}; # Values of each gate if known
994  
995 my @gates = sort {$gates{$a}->seq <=> $gates{$b}->seq} keys %gates; # Gates in definition order
996 if (my $c = $options{changed}) # Order non IO gates by last change time during simulation if possible
997 {@gates = sort {($$c{$a}//0) <=> ($$c{$b}//0)} @gates;
998 }
999  
1000 my @fibers; # Squares of the page, each of which can either be undefined or contain the name of the fiber crossing it from left to right or up and down
1001 my @inPlay; # Squares of the page in play
1002 my @positions; # Position of each gate indexed by position in layout
1003 my %positions; # Position of each gate indexed by gate name
1004 my $width = 1; # Width of page consumed so far until it becomes the page width.
1005 my $height = 0; # Height of page consumed so far until it becomes the page height
1006  
1007 for my $i(keys @gates) # Position each gate
1008 {my $g = $gates{$gates[$i]}; # Gate details
1009 my $s = $g->type =~ m(\A(input|one|output|zero)\Z); # These gates can be positioned without consuming more horizontal space
1010 my %i = $g->inputs->%*; # Inputs hash for gate
1011 my @i = sort keys %i; # Connections to each gate in pin order
1012 my $w = $s ? 1 : scalar(@i); # Width of this gate
1013 my $n = $g->output; # Name of gate
1014  
1015 my sub color() # Color of gate
1016 {return "red" if $g->io == gateOuterOutput;
1017 return "blue" if $g->io == gateOuterInput;
1018 "green"
1019 }
1020  
1021 my $x = $width; $x-- if $s; # Position of gate
1022 my $y = $i;
1023  
1024 my $p = genHash(__PACKAGE__."::GatePosition",
1025 output => $g->output, # Gate name
1026 x => $x, # Gate x position
1027 y => $y, # Gate y position
1028 width => $w, # Width of gate
1029 fiber => 0, # Number of fibers running past this gate
1030 position => $i, # Number of fibers running past this gate
1031 type => $g->type, # Type of gate
1032 value => $$values {$g->output}, # Value of gate if known
1033 changed => $$changed{$g->output}, # Last change time of gate if known
1034 inputs => [map {$i{$_}} @i], # Names of gates driving input pins on this gate
1035 inputValues => [map {$$values{$i{$_}}} @i], # Values on input pins if known
1036 color => color, # Color of gate
1037 inPin => $g->io == gateOuterInput, # Input pin for chip
1038 outPin => $g->io == gateOuterOutput, # Output pin for chip
1039 );
1040  
1041 $positions[$i] = $p; $positions{$p->output} = $p; # Index the gates
1042 $width += $w unless $s; # Io gates are tucked in in such way that they do not contribute to the width
1043 $height++ unless $g->io == gateOuterOutput; # Output gates do not contribute to the height of the mask
1044 }
1045  
1046 for my $i(keys @positions) # Position output pins along bottom of mask
1047 {my $p = $positions[$i];
1048 next unless $p->outPin;
1049 my ($D) = $p->inputs->@*; # An output gate only has one input so we can safe relocate it next to the single gate that produces that output
1050 my $d = $positions{$D}; # Driving gate
1051 $p->x = $d->x - 1; # Reposition output gate
1052 $p->y = $d->y;
1053 }
1054  
1055 for my $p(@positions) # Connect gates loosely
1056 {my $g = $gates{$p->output}; # Detail for this gate
1057 my @i = $p->inputs->@*; # Connections to each gate
1058 for my $i(keys @i) # Connections to each gate
1059 {my $D = $i[$i]; # Driving gate name
1060 my $d = $positions{$D}; # Driving gate position
1061 my $X = $p->x+$i; # X position of input pin to gate
1062 my $Y = $p->y; # Y position of input pin to gate
1063 $fibers[$_][$d->y][0] = $D for $d->x+$d->width..$X; # Horizontal line
1064 $fibers[$X][$_] [1] = $D for $d->y..$Y-1; # Vertical line
1065 if (!$g->io) # Mark column as in play
1066 {for my $j(0..$Y-1)
1067 {$inPlay[$X][$j] = 1;
1068 }
1069 }
1070 }
1071 }
1072  
1073 my sub collapseFibers() # Perform one collapse pass of the fibers returning the number of collapses performed
1074 {my $changes = 0; # Number of changes made in this pass
1075  
1076 my sub removeOrphans($) # Remove any vertical orphans in the specified column
1077 {my ($i) = @_; # Column to check
1078 for my $j(keys $fibers[$i]->@*)
1079 {my $h = $fibers[$i][$j][0]; # Horizontal line
1080 my $v = $fibers[$i][$j][1]; # Vertical line
1081 last if defined($h) and defined($v) and $h eq $v; # Found the vertical so we can stop
1082 $fibers[$i][$j][1] = undef; # Remove vertical as it never meets a corresponding horizontal and so is of no use
1083 }
1084 }
1085  
1086 for my $i(keys @fibers) # Examine each cell for a corner that we can collapse either left or down
1087 {for my $j(keys $fibers[$i]->@*)
1088 {my sub i() {$i}
1089 my sub j() {$j}
1090 my sub h($$) :lvalue {my ($i, $j) = @_; return undef unless $i >= 0 and $j >= 0 and $inPlay[$i][$j]; $fibers[$i][$j][0]} # A horizontal element relative to the current corner
1091 my sub v($$) :lvalue {my ($i, $j) = @_; return undef unless $i >= 0 and $j >= 0 and $inPlay[$i][$j]; $fibers[$i][$j][1]} # A vertical element relative to the current corner
1092  
1093 my $a = h(i-1, j+0); my sub a() {$a}
1094 my $b = h(i+0, j+0);
1095 my $B = v(i+0, j+0);
1096 my $C = v(i+0, j+1);
1097 my $D = v(i+0, j-1);
1098 my $e = h(i+1, j+0);
1099 next unless defined($a) and defined($b) and defined($B) and defined($C);# Possible corner
1100 next unless $a eq $b and $b eq $B and $B eq $C; # Confirm corner
1101 next if defined($D) and $D eq $a; # If it is a corner it points north east.
1102 next if defined($e) and $e eq $a; # If it is a corner it points north east.
1103  
1104 my $wentLeft; # If we collapsed left we made a change and so need to come around again before attempting to collapse down
1105 if (1) # Collapse left
1106 {my $k; my sub k() :lvalue {$k} # Position of new corner going left
1107 for my $I(reverse 0..i-1) # Look for an opposite corner
1108 {last if $j+2 >= $fibers[$I]->$#*;
1109 last unless defined(h($I, j)) and h($I, j) eq $a; # Make sure horizontal is occupied with expected bus line
1110 last if defined h($I, j+1); # Horizontal is occupied so we will not be able to reuse it
1111 k = $I if !defined v($I, j+1); # Possible opposite because it is not being used vertically
1112 }
1113  
1114 if (defined(k)) # Reroute through new corner
1115 {v(i, j) = undef; # Remove old upper right corner vertical
1116 v(k, j) = a; # New upper left corner
1117 h(k, j) = undef unless k > 0 and defined(h(k-1, j)) and h(k-1, j) eq a; # Situation x: we might, or might not be on a corner here
1118 v(i, j+1) = undef unless j+1 < $fibers[i]->$#* and defined(v(i, j+2)) and v(i, j+2) eq a; # Situation y: we might, or might not be on a corner here
1119 h(k, j+1) = a; # New lower left corner
1120 v(k, j+1) = a; # New lower left corner
1121 for my $I(k+1..i) # Route along lower side
1122 {h($I, j ) = undef; # Remove upper side
1123 h($I, j+1) = a; # Add lower side
1124 if (defined(v($I, j)) and v($I, j) eq a) # Crossing a T so we need to move the cross down one
1125 {v($I, j) = undef; # Remove upper cross
1126 v($I, j+1) = a; # Enable lower cross
1127 }
1128 }
1129 ++$changes; $wentLeft++;
1130 #removeOrphans(k) if k;
1131 #removeOrphans(k-1) if k;
1132 }
1133 }
1134 # d |x |
1135 # abe +-+ => |
1136 # c |y |
1137 # +-- +---
1138  
1139 if (!$wentLeft) # Collapse down
1140 {my $k; my sub k() :lvalue {$k} # Position of new corner going down
1141 for my $J(j..scalar($fibers[i-1]->$#*)) # Look for an opposite corner
1142 {last unless defined(v(i, $J)) and v(i, $J) eq a; # Make sure vertical is occupied with expected fiber
1143 last if defined(v(i-1, $J)) and v(i-1, $J) ne a; # Vertical is occupied so we will not be able to reuse it
1144 k = $J if !defined(h(i-1, $J)); # Possible corner as horizontal is free
1145 }
1146  
1147 if (defined(k)) # Reroute through new corner
1148 {h(i, j) = undef; # Remove old upper right corner horizontal
1149 v(i, j) = undef; # Remove old upper right corner vertical
1150 v(i-1, j) = a; # New upper left corner
1151 h(i-1, j) = undef unless i-1 > 0 and defined(h(i-2, j)) and h(i-2, j) eq a; # Situation x: we might, or might not be on a corner here
1152 v(i, k) = undef unless k < $fibers[i]->$#* and defined(v(i, k+1)) and v(i, k+1) eq a; # Situation y: we might, or might not be on a corner here
1153 h(i-1, k) = a; # New lower left corner
1154 v(i-1, k) = a; # New lower left corner
1155 h(i, k) = a; # Add lower right corner
1156 for my $J(j..k-1) # Route down opposite side
1157 {v(i , $J) = undef; # Remove right side
1158 v(i-1, $J) = a; # Add left side
1159 }
1160 ++$changes;
1161 #removeOrphans(i+1);
1162 #removeOrphans(i);
1163 }
1164 }
1165 }
1166 }
1167  
1168 $changes
1169 }
1170  
1171 for my $i(1..@positions) {last unless collapseFibers()} # Collapse fibers
1172  
1173 my $t = 0; # Size of thickest bundle
1174 for my $i(keys @fibers)
1175 {my $c = 0;
1176 for my $j(keys $fibers[$i]->@*)
1177 {++$c if defined $fibers[$i][$j][0]; # Only horizontal fibers count to the total thickness
1178 }
1179 $t = $c if $c > $t;
1180 }
1181  
1182 genHash(__PACKAGE__."::Layout", # Details of layout
1183 chip => $chip, # Chip being masked
1184 positionsArray => \@positions, # Position array
1185 positionsHash => \%positions, # Position hash
1186 fibers => \@fibers, # Fibers after collapse
1187 inPlay => \@inPlay, # Squares in play for collapsing
1188 height => $height, # Height of drawing
1189 width => $width, # Width of drawing
1190 steps => $options{steps}, # Steps in simulation
1191 thickness => $t, # Width of the thickest fiber bundle
1192 );
1193 }
1194  
1195 sub Silicon::Chip::Layout::draw($%) #P Draw a mask for the gates.
1196 {my ($layout, %options) = @_; # Layout, options
1197 my $chip = $layout->chip; # Chip being masked
1198 my %gates = $chip->gates->%*; # Gates on chip
1199 my @fibers = $layout->fibers->@*; # Squares of the page, each of which can either be undefined or contain the name of the fiber crossing it from left to right or up and down
1200 my @inPlay = $layout->inPlay->@*; # Squares available for collapsing
1201 my @positions = $layout->positionsArray->@*; # Position of each gate indexed by position in layout
1202 my %positions = $layout->positionsHash ->%*; # Position of each gate indexed by gate name
1203 my $width = $layout->width; # Width of mask
1204 my $height = $layout->height; # Height of mask
1205 my $steps = $layout->steps; # Number of steps to equilibrium
1206 my $thickness = $layout->thickness; # Thickness of fiber bundle
1207  
1208 my sub ts() {$height/64} my sub tw() {ts/16} my sub tl() {1.25 * ts} # Font sizes for titles
1209 my sub Ts() {2*ts} my sub Tw() {2*tw} my sub Tl() {2*tl}
1210  
1211 my sub fs() {1/6} my sub fw() {fs/16} my sub fl() {1.25 * fs} # Font sizes for gates
1212 my sub Fs() {2*fs} my sub Fw() {2*fw} my sub Fl() {2*fl}
1213  
1214 my @defaults = (defaults=> # Default values
1215 {stroke_width => fw,
1216 font_size => fs,
1217 fill => q(transparent)});
1218  
1219 my $svg = Svg::Simple::new(@defaults, %options, grid=>debugMask ? 1 : 0); # Draw each gate via Svg. Grid set to 1 produces a grid that can be helpful debugging layout problems
1220  
1221 if (1) # Show squares in play with a small number of rectangles
1222 {my @i = map {$_ ? [@$_] : $_} @inPlay; # Deep copy
1223 for my $i(keys @i) # Each row
1224 {for my $j(keys $i[$i]->@*) # Each column
1225 {if ($i[$i][$j]) # Found a square in play
1226 {my $w = 1; # Width of rectangle
1227 for my $I($i+1..$#inPlay) # Extend as far as possible to the right
1228 {if ($i[$I][$j])
1229 {++$w;
1230 $i[$I][$j] = undef; # Show that this square has been written - safe because we did a deep copy earlier
1231 }
1232 }
1233 $svg->rect(x=>$i, y=>$j, width=>$w, height=>1,
1234 fill=>"mistyrose", stroke=>"transparent");
1235 }
1236 }
1237 }
1238 }
1239  
1240 my $py = 0;
1241 my sub wt($;$) # Write titles on following lines
1242 {my ($t, $T) = @_; # Value, title to write
1243 if (defined($t)) # Value to write
1244 {$py += Tl; # Position to write at
1245 my $s = $t; $s .= " $T" if $T; # Text to write
1246 $svg->text(x => $width, y => $py, cdata => $s, # Write text
1247 fill=>"darkGreen", text_anchor=>"end", stroke_width=>Tw, font_size=>Ts);
1248 }
1249 }
1250  
1251 wt($chip->title); # Title if known
1252 wt($steps, "steps"); # Number of steps taken if known
1253 wt($thickness, "thick"); # Thickness of bundle
1254 wt($width, "wide"); # Width of page
1255  
1256 for my $p(@positions) # Draw each gate
1257 {my $x = $p->x; my $y = $p->y; my $w = $p->width; my $c = $p->color;
1258 my $io = $p->inPin || $p->outPin;
1259 $svg->circle(cx => $x+1/2, cy=>$y+1/2, r=>1/2, stroke=>$c) if $io; # Circle for io pin
1260 $svg->rect(x=>$x, y=>$y, width=>$w, height=>1, stroke=>$c) if !$io; # Rectangle for non io gate
1261  
1262 if (defined(my $v = $p->value)) # Value of gate if known
1263 {$svg->text(
1264 x => $p->x,
1265 y => $p->y,
1266 fill =>"black",
1267 stroke_width => Fw,
1268 font_size => Fs,
1269 text_anchor => "start",
1270 dominant_baseline => "hanging",
1271 cdata => $v ? "1" : "0");
1272 }
1273  
1274 if (defined(my $t = $p->changed) and !$p->inPin and !$p->outPin) # Gate change time if known for a non io gate
1275 {$svg->text(
1276 x => $p->x + $p->width,
1277 y => $p->y + 1,
1278 fill => "darkBlue",
1279 stroke_width => fw,
1280 font_size => fs,
1281 text_anchor => "end",
1282 cdata => $t+1);
1283 }
1284  
1285 my sub ot($$$$) # Output svg text
1286 {my ($dy, $fill, $pos, $text) = @_;
1287 $svg->text(x => $p->x+$p->width/2,
1288 y => $p->y+$dy,
1289 fill => $fill,
1290 text_anchor => "middle",
1291 dominant_baseline => $pos,
1292 cdata => $text);
1293 }
1294  
1295 ot(5/12, "red", "auto", $p->type); # Type of gate
1296 ot(7/12, "darkblue", "hanging", $p->output);
1297  
1298 my @i = $p->inputValues->@*;
1299  
1300 for my $i(keys @i) # Draw input values to each pin on the gate
1301 {next if $p->inPin or $p->outPin;
1302 my $v = $p->inputValues->[$i];
1303 if (defined($v))
1304 {$svg->text(
1305 x => $p->x + $i + 1/2,
1306 y => $p->y,
1307 fill => "darkRed",
1308 stroke_width => fw,
1309 font_size => fs,
1310 text_anchor => "middle",
1311 dominant_baseline => "hanging",
1312 cdata => $v ? "1" : "0");
1313 }
1314 }
1315 }
1316  
1317 if (debugMask) # Show fiber names - useful when debugging bus lines
1318 {for my $i(keys @fibers)
1319 {for my $j(keys $fibers[$i]->@*)
1320 {if (defined(my $n = $fibers[$i][$j][0])) # Horizontal
1321 {$svg->text(
1322 x => $i+1/2,
1323 y => $j+1/2,
1324 fill =>"black",
1325 stroke_width => fw,
1326 font_size => fs,
1327 text_anchor => 'middle',
1328 dominant_baseline => 'auto',
1329 cdata => $n,
1330 )# if $n eq "a4" || $n eq "a4";
1331 }
1332 if (defined(my $n = $fibers[$i][$j][1])) # Vertical
1333 {$svg->text(
1334 x => $i+1/2,
1335 y => $j+1/2,
1336 fill =>"red",
1337 stroke_width => fw,
1338 font_size => fs,
1339 text_anchor => 'middle',
1340 dominant_baseline => 'hanging',
1341 cdata => $n,
1342 )# if $n eq "a4" || $n eq "a4";
1343 }
1344 }
1345 }
1346 }
1347  
1348 if (1) # Show fiber lines
1349 {my @h = (stroke =>"darkgreen", stroke_width => Fw); # Fiber lines horizontal
1350 my @v = (stroke =>"darkgreen", stroke_width => Fw); # Fiber lines vertical
1351 my @f = @fibers;
1352 my @i = @inPlay;
1353 my @H; my @V; # Straight line cells
1354  
1355 for my $i(keys @f)
1356 {for my $j(keys $f[$i]->@*)
1357 {my $h = $f[$i][$j][0]; # Horizontal
1358 my $v = $f[$i][$j][1]; # Vertical
1359  
1360 if (defined($h) and defined($v) and $h eq $v) # Cross
1361 {my $l = !$i[$i-1][$j] || ($i[$i-1][$j] && ($f[$i-1][$j][0]//'') eq $h); # Left horizontal
1362 my $r = $i[$i+1][$j] && ($f[$i+1][$j][0]//'') eq $h; # Right horizontal
1363 my $a = $j > 0 && $i[$i][$j-1] && ($f[$i][$j-1][1]//'') eq $h; # Vertically above
1364 my $b = $j >= $f[$i]->$#* || ($i[$i][$j+1] && ($f[$i][$j+1][1]//'') eq $h); # Vertically below
1365  
1366 # | A --+ |C D
1367 # +-- B | +-- --+--
1368 # | |
1369  
1370 my $D = $l && $r && $b;
1371 my $C = $a && $r && $b;
1372 my $A = $a && $r;
1373 my $B = $l && $b;
1374  
1375 my @B = my @A = (r=> Fw, fill=>"darkRed"); # Fiber connections
1376 my @C = (r=>1.5*Fw, fill=>"darkRed");
1377  
1378 if ($C)
1379 {$svg->line(x1=>$i+1/2, y1=>$j, x2=>$i+1/2, y2=>$j+1, @h);
1380 $svg->line(x1=>$i+1/2, y1=>$j+1/2, x2=>$i+1, y2=>$j+1/2, @h);
1381 $svg->circle(cx=>$i+1/2, cy=>$j+1/2, @C);
1382 }
1383 elsif ($D)
1384 {$svg->line(x1=>$i, y1=>$j+1/2, x2=>$i+1, y2=>$j+1/2, @h);
1385 $svg->line(x1=>$i+1/2, y1=>$j+1/2, x2=>$i+1/2, y2=>$j+1, @h);
1386 $svg->circle(cx=>$i+1/2, cy=>$j+1/2, @C);
1387 }
1388 elsif ($A) # Draw corners
1389 {$svg->line (x1=>$i+1/2, y1=>$j, x2=>$i+1, y2=>$j+1/2, @h);
1390 $svg->circle(cx=>$i+1/2, cy=>$j, @A);
1391 $svg->circle(cx=>$i+1, cy=>$j+1/2, @A);
1392 }
1393 elsif ($B)
1394 {$svg->line (x1=>$i, y1=>$j+1/2, x2=>$i+1/2, y2=>$j+1, @h);
1395 $svg->circle(cx=>$i, cy=>$j+1/2, @B);
1396 $svg->circle(cx=>$i+1/2, cy=>$j+1, @B);
1397 }
1398 }
1399 else # Straight
1400 {$H[$i][$j] = $h; # Horizontal
1401 $V[$i][$j] = $v; # Vertical
1402 }
1403 }
1404 }
1405  
1406 my @hc = (stroke => "darkgreen", stroke_width => Fw); # Horizontal line color
1407 my @vc = (stroke => "darkgreen", stroke_width => Fw); # Vertical line color
1408  
1409 for my $i(keys @f) # Draw horizontal and vertical bars with a minimal number of lines otherwise the svg files get very big
1410 {for my $j(keys $f[$i]->@*)
1411 {if (defined(my $h = $H[$i][$j])) # Horizontal
1412 {my $e = $i;
1413 for my $I($i..$#f) # Go as far right as possible
1414 {my $H = \$H[$I][$j];
1415 last unless $$H and $$H eq $h; # Still in line
1416 $$H = undef; # Erase line as no longer needed
1417 $e = $I; # Current known end of the line
1418 }
1419 $svg->line(x1=>$i, y1=>$j+1/2, x2=>$e+1, y2=>$j+1/2, @hc); # Draw horizontal line
1420 }
1421 if (defined(my $v = $V[$i][$j])) # Vertical
1422 {my $e = $j;
1423 for my $J($j..$f[$i]->$#*) # Go as far down as possible
1424 {my $V = \$V[$i][$J];
1425 last unless $$V and $$V eq $v; # Still in line
1426 $$V = undef; # Erase line as no longer needed
1427 $e = $J; # Current known end of the line
1428 }
1429 $svg->line(x1=>$i+1/2, y1=>$j, x2=>$i+1/2, y2=>$e+1, @vc); # Draw vertical line
1430 }
1431 }
1432 }
1433 }
1434  
1435 my $t = $svg->print; # Text of svg
1436 my $f = $options{svg}; # Svg file
1437 return owf(fpe($f, q(svg)), $t) if $f; # Draw bundle as an svg drawing
1438 $t
1439 }
1440  
1441 my %drawMask; # Track masks drawn so we can complain about duplicates
1442  
1443 my sub drawMask($%) # Draw a mask for the gates.
1444 {my ($chip, %options) = @_; # Chip, options
1445 my $s = $options{svg};
1446 $drawMask{$s}++ and confess <<"END" =~ s/\n(.)/ $1/gsr; # Complain about duplicate mask names
1447 Duplicate mask name: $s specified
1448 END
1449 my $layout = layoutAsFiberBundle($chip, %options); # Gates on chip
1450 $layout->draw(%options); # Draw mask
1451 }
1452  
1453 #D1 Basic Circuits # Some well known basic circuits.
1454  
1455 sub n(*$) # Gate name from single index.
1456 {my ($c, $i) = @_; # Gate name, bit number
1457 !@_ or !ref($_[0]) or confess <<"END";
1458 Call as a sub not as a method
1459 END
1460 "${c}_$i"
1461 }
1462  
1463 sub nn(*$$) # Gate name from double index.
1464 {my ($c, $i, $j) = @_; # Gate name, word number, bit number
1465 !@_ or !ref($_[0]) or confess confess <<"END";
1466 Call as a sub not as a method
1467 END
1468 "${c}_${i}_$j"
1469 }
1470  
1471 #D2 Comparisons # Compare unsigned binary integers of specified bit widths.
1472  
1473 sub compareEq($$$$%) # Compare two unsigned binary integers of a specified width returning B<1> if they are equal else B<0>.
1474 {my ($chip, $output, $a, $b, %options) = @_; # Chip, name of component also the output bus, first integer, second integer, options
1475 @_ >= 4 or confess "Four or more parameters";
1476 my $o = $output;
1477 my $A = sizeBits($chip, $a);
1478 my $B = sizeBits($chip, $b);
1479 $A == $B or confess <<"END" =~ s/\n(.)/ $1/gsr;
1480 Input $a has width $A but input $b has width $B
1481 END
1482 $chip->nxor(n("$o.e", $_), n($a, $_), n($b, $_)) for 1..$B; # Test each bit pair for equality
1483 $chip->andBits($o, "$o.e", bits=>$B); # All bits must be equal
1484  
1485 $chip
1486 }
1487  
1488 sub compareGt($$$$%) # Compare two unsigned binary integers and return B<1> if the first integer is more than B<b> else B<0>.
1489 {my ($chip, $output, $a, $b, %options) = @_; # Chip, name of component also the output bus, first integer, second integer, options
1490 @_ >= 4 or confess "Four or more parameters";
1491 my $o = $output;
1492 my $A = sizeBits($chip, $a);
1493 my $B = sizeBits($chip, $b);
1494 $A == $B or confess <<"END" =~ s/\n(.)/ $1/gsr;
1495 Input $a has width $A but input $b has width $B
1496 END
1497 $chip->nxor (n("$o.e", $_), n($a, $_), n($b, $_)) for 2..$B; # Test all but the lowest bit pair for equality
1498 $chip->gt (n("$o.g", $_), n($a, $_), n($b, $_)) for 1..$B; # Test each bit pair for more than
1499  
1500 for my $b(2..$B) # More than on one bit and all preceding bits are equal
1501 {$chip->and(n("$o.c", $b),
1502 {(map {$_=>n("$o.e", $_)} $b..$B), ($b-1)=>n("$o.g", $b-1)});
1503 }
1504  
1505 $chip->or ($o, {$B=>n("$o.g", $B), (map {($_-1)=>n("$o.c", $_)} 2..$B)}); # Any set bit indicates that B<a> is more than B<b>
1506  
1507 $chip
1508 }
1509  
1510 sub compareLt($$$$%) # Compare two unsigned binary integers B<a>, B<b> of a specified width. Output B<out> is B<1> if B<a> is less than B<b> else B<0>.
1511 {my ($chip, $output, $a, $b, %options) = @_; # Chip, name of component also the output bus, first integer, second integer, options
1512 @_ >= 4 or confess "Four or more parameters";
1513  
1514 my $A = sizeBits($chip, $a);
1515 my $B = sizeBits($chip, $b);
1516 $A == $B or confess <<"END" =~ s/\n(.)/ $1/gsr;
1517 Input $a has width $A but input $b has width $B
1518 END
1519  
1520 my $o = $output;
1521  
1522 $chip->nxor (n("$o.e", $_), n($a, $_), n($b, $_)) for 2..$B; # Test all but the lowest bit pair for equality
1523 $chip->lt (n("$o.l", $_), n($a, $_), n($b, $_)) for 1..$B; # Test each bit pair for less than
1524  
1525 for my $b(2..$B) # More than on one bit and all preceding bits are equal
1526 {$chip->and(n("$o.c", $b),
1527 {(map {$_=>n("$o.e", $_)} $b..$B), ($b-1)=>n("$o.l", $b-1)});
1528 }
1529  
1530 $chip->or ($o, {$B=>n("$o.l", $B), (map {($_-1)=>n("$o.c", $_)} 2..$B)}); # Any set bit indicates that B<a> is less than B<b>
1531  
1532 $chip
1533 }
1534  
1535 sub chooseFromTwoWords($$$$$%) # Choose one of two words based on a bit. The first word is chosen if the bit is B<0> otherwise the second word is chosen.
1536 {my ($chip, $output, $a, $b, $choose, %options) = @_; # Chip, name of component also the chosen word, the first word, the second word, the choosing bit, options
1537 @_ >= 5 or confess "Five or more parameters";
1538 my $o = $output;
1539  
1540 my $A = sizeBits($chip, $a);
1541 my $B = sizeBits($chip, $b);
1542 $A == $B or confess <<"END" =~ s/\n(.)/ $1/gsr;
1543 Input $a has width $A but input $b has width $B
1544 END
1545  
1546 $chip->not("$o.n", $choose); # Not of the choosing bit
1547 for my $i(1..$B)
1548 {$chip->and(n("$o.a", $i), [n($a, $i), "$o.n" ]); # Choose first word
1549 $chip->and(n("$o.b", $i), [n($b, $i), $choose ]); # Choose second word
1550 $chip->or (n($o, $i), [n("$o.a", $i), n("$o.b", $i)]); # Or results of choice
1551 }
1552 setSizeBits($chip, $o, $B); # Record bus size
1553  
1554 $chip
1555 }
1556  
1557 sub enableWord($$$$%) # Output a word or zeros depending on a choice bit. The first word is chosen if the choice bit is B<1> otherwise all zeroes are chosen.
1558 {my ($chip, $output, $a, $enable, %options) = @_; # Chip, name of component also the chosen word, the first word, the second word, the choosing bit, options
1559 @_ >= 4 or confess "Four or more parameters";
1560 my $o = $output;
1561 my $B = sizeBits($chip, $a);
1562  
1563 for my $i(1..$B) # Choose each bit of input word
1564 {$chip->and(n($o, $i), [n($a, $i), $enable]);
1565 }
1566 setSizeBits($chip, $o, $B); # Record bus size
1567 $chip
1568 }
1569  
1570 #D2 Masks # Point masks and monotone masks. A point mask has a single B<1> in a sea of B<0>s as in B<00100>. A monotone mask has zero or more B<0>s followed by all B<1>s as in: B<00111>.
1571  
1572 sub pointMaskToInteger($$$%) # Convert a mask B<i> known to have at most a single bit on - also known as a B<point mask> - to an output number B<a> representing the location in the mask of the bit set to B<1>. If no such bit exists in the point mask then output number B<a> is B<0>.
1573 {my ($chip, $output, $input, %options) = @_; # Chip, output name, input mask, options
1574 @_ >= 3 or confess "Three or more parameters";
1575 my $B = sizeBits($chip, $input); # Bits in input bus
1576 my $I = containingPowerOfTwo($B); # Bits in integer
1577 my $i = $input; # The bits in the input mask
1578 my $o = $output; # The name of the output bus
1579  
1580 my %b;
1581 for my $b(1..$B) # Bits in mask to bits in resulting number
1582 {my $s = sprintf "%b", $b;
1583 for my $p(1..length($s))
1584 {$b{$p}{$b}++ if substr($s, -$p, 1);
1585 }
1586 }
1587  
1588 for my $b(sort keys %b)
1589 {$chip->or(n($o, $b), {map {$_=>n($i, $_)} sort keys $b{$b}->%*}); # Bits needed to drive a bit in the resulting number
1590 }
1591 setSizeBits $chip, $o, $I; # Size of resulting integer
1592 $chip
1593 }
1594  
1595 sub integerToPointMask($$$%) # Convert an integer B<i> of specified width to a point mask B<m>. If the input integer is B<0> then the mask is all zeroes as well.
1596 {my ($chip, $output, $input, %options) = @_; # Chip, output name, input mask, options
1597 @_ >= 3 or confess "Three or more parameters";
1598 my $bits = sizeBits($chip, $input); # Size of input integer in bits
1599 my $B = 2**$bits-1;
1600 my $o = $output; # Output mask
1601  
1602 $chip->notBits("$o.n", $input); # Not of each input
1603  
1604 for my $b(1..$B) # Each bit of the mask
1605 {my @s = reverse split //, sprintf "%0${bits}b", $b; # Bits for this point in the mask
1606 my %a;
1607 for my $i(1..@s)
1608 {$a{$i} = n($s[$i-1] ? 'i' : "$o.n", $i); # Combination of bits to enable this mask bit
1609 }
1610 $chip->and(n($output, $b), {%a}); # And to set this point in the mask
1611 }
1612 setSizeBits($chip, $output, $B); # Size of output bus
1613  
1614 $chip
1615 }
1616  
1617 sub monotoneMaskToInteger($$$%) # Convert a monotone mask B<i> to an output number B<r> representing the location in the mask of the bit set to B<1>. If no such bit exists in the point then output in B<r> is B<0>.
1618 {my ($chip, $output, $input, %options) = @_; # Chip, output name, input mask, options
1619 @_ >= 3 or confess "Three or more parameters";
1620 my $B = sizeBits($chip, $input);
1621 my $I = containingPowerOfTwo($B);
1622 my $o = $output;
1623  
1624 my %b;
1625 for my $b(1..$B)
1626 {my $s = sprintf "%b", $b;
1627 for my $p(1..length($s))
1628 {$b{$p}{$b}++ if substr($s, -$p, 1);
1629 }
1630 }
1631 $chip->not (n("$o.n", $_), n($input, $_)) for 1..$B-1; # Not of each input
1632 $chip->continue(n("$o.a", 1), n($input, 1));
1633 $chip->and (n("$o.a", $_), [n("$o.n", $_-1), n('i', $_)]) for 2..$B; # Look for trailing edge
1634  
1635 for my $b(sort keys %b)
1636 {$chip->or (n($o, $b), [map {n("$o.a", $_)} sort keys $b{$b}->%*]); # Bits needed to drive a bit in the resulting number
1637 }
1638 setSizeBits($chip, $o, $I);
1639  
1640 $chip
1641 }
1642  
1643 sub monotoneMaskToPointMask($$$%) # Convert a monotone mask B<i> to a point mask B<o> representing the location in the mask of the first bit set to B<1>. If the monotone mask is all B<0>s then point mask is too.
1644 {my ($chip, $output, $input, %options) = @_; # Chip, output name, input mask, options
1645 @_ >= 3 or confess "Three or more parameters";
1646 my $o = $output;
1647 my $bits = sizeBits($chip, $input);
1648 $chip->continue(n($o, 1), n($input, 1)); # The first bit in the monotone mask matches the first bit of the point mask
1649 for my $b(2..$bits)
1650 {$chip->xor(n($o, $b), n($input, $b-1), n($input, $b)); # Detect transition
1651 }
1652 setSizeBits($chip, $o, $bits);
1653  
1654 $chip
1655 }
1656  
1657 sub integerToMonotoneMask($$$%) # Convert an integer B<i> of specified width to a monotone mask B<m>. If the input integer is B<0> then the mask is all zeroes. Otherwise the mask has B<i-1> leading zeroes followed by all ones thereafter.
1658 {my ($chip, $output, $input, %options) = @_; # Chip, output name, input mask, options
1659 @_ >= 3 or confess "Three or more parameters";
1660 my $I = sizeBits($chip, $input);
1661 my $B = 2**$I-1;
1662 my $o = $output;
1663  
1664 $chip->notBits("$o.n", $input); # Not of each input
1665  
1666 for my $b(1..$B) # Each bit of the mask
1667 {my @s = (reverse split //, sprintf "%0${I}b", $b); # Bits for this point in the mask
1668 my %a;
1669 for my $i(1..@s)
1670 {$a{$i} = n($s[$i-1] ? $input : "$o.n", $i); # Choose either the input bit or the not of the input but depending on the number being converted to binary
1671 }
1672 $chip->and(n("$o.a", $b), {%a}); # Set at this point and beyond
1673 $chip-> or(n($o, $b), [map {n("$o.a", $_)} 1..$b]); # Set mask
1674 }
1675 setSizeBits($chip, $o, $B);
1676 $chip
1677 }
1678  
1679 sub chooseWordUnderMask($$$$%) # Choose one of a specified number of words B<w>, each of a specified width, using a point mask B<m> placing the selected word in B<o>. If no word is selected then B<o> will be zero.
1680 {my ($chip, $output, $input, $mask, %options) = @_; # Chip, output, inputs, mask, options
1681 @_ >= 3 or confess "Three or more parameters";
1682 my $o = $output;
1683  
1684 my ($words, $bits) = sizeWords($chip, $input);
1685 my ($mi) = sizeBits ($chip, $mask);
1686 $mi == $words or confess <<"END" =~ s/\n(.)/ $1/gsr;
1687 Mask width $mi does not match number of words $words.
1688 END
1689  
1690 for my $w(1..$words) # And each bit of each word with the mask
1691 {for my $b(1..$bits) # Bits in each word
1692 {$chip->and(nn("$o.a", $w, $b), [n($mask, $w), nn($input, $w, $b)]);
1693 }
1694 }
1695  
1696 for my $b(1..$bits) # Bits in each word
1697 {$chip->or(n($o, $b), [map {nn("$o.a", $_, $b)} 1..$words]);
1698 }
1699 setSizeBits($chip, $o, $bits);
1700  
1701 $chip
1702 }
1703  
1704 sub findWord($$$$%) # Choose one of a specified number of words B<w>, each of a specified width, using a key B<k>. Return a point mask B<o> indicating the locations of the key if found or or a mask equal to all zeroes if the key is not present.
1705 {my ($chip, $output, $key, $words, %options) = @_; # Chip, found point mask, key, words to search, options
1706 @_ >= 4 or confess "Four or more parameters";
1707 my $o = $output;
1708 my ($W, $B) = sizeWords($chip, $words);
1709 my $bits = sizeBits ($chip, $key);
1710 $B == $bits or confess <<"END" =~ s/\n(.)/ $1/gsr;
1711 Number of bits in each word $B differs from words in key $bits.
1712 END
1713 for my $w(1..$W) # Input words
1714 {$chip->compareEq(n($o, $w), n($words, $w), $key); # Compare each input word with the key to make a mask
1715 }
1716 setSizeBits($chip, $o, $W);
1717  
1718 $chip
1719 }
1720  
1721 #D1 Simulate # Simulate the behavior of the L<chip> given a set of values on its input gates.
1722  
1723 my sub setBit($*$%) # Set a single bit
1724 {my ($chip, $name, $value, %options) = @_; # Chip, name of input gates, number to set to, options
1725 @_ >= 3 or confess "Three or more parameters";
1726 my $g = getGate($chip, $name);
1727 my $t = $g->type;
1728 $g->io == gateOuterInput or confess <<"END" =~ s/\n(.)/ $1/gsr;
1729 Only outer input gates are setable. Gate $name is of type $t
1730 END
1731 my %i = ($name => $value ? $value : 0);
1732 %i
1733 }
1734  
1735 sub setBits($*$%) # Set an array of input gates to a number prior to running a simulation.
1736 {my ($chip, $name, $value, %options) = @_; # Chip, name of input gates, number to set to, options
1737 @_ >= 3 or confess "Three or more parameters";
1738 my $bits = sizeBits($chip, $name); # Size of bus
1739 my $W = 2**$bits;
1740 $value >= 0 or confess <<"END";
1741 Value $value is less than 0
1742 END
1743 $value < $W or confess <<"END";
1744 Value $value is greater then or equal to $W
1745 END
1746 my @b = reverse split //, sprintf "%0${bits}b", $value;
1747 my %i = map {n($name, $_) => $b[$_-1]} 1..$bits;
1748 %i
1749 }
1750  
1751 sub setWords($$@) # Set an array of arrays of gates to an array of numbers prior to running a simulation.
1752 {my ($chip, $name, @values) = @_; # Chip, name of input gates, number of bits in each array element, numbers to set to
1753 @_ >= 3 or confess "Three or more parameters";
1754 my ($words, $bits) = sizeWords($chip, $name);
1755 my %i;
1756 my $M = 2**$bits-1; # Maximum we can store in a word of this many bits
1757 for my $w(1..$words) # Each word
1758 {my $n = shift @values;
1759 $n >= 0 or confess <<"END";
1760 Value $n is less than 0
1761 END
1762 $n <= $M or confess <<"END";
1763 "Value $n is greater then or equal to $M";
1764 END
1765 my @b = split //, sprintf "%0${bits}b", $n;
1766 for my $b(1..$bits) # Each bit
1767 {$i{nn($name, $w, $b)} = $b[-$b];
1768 }
1769 }
1770 %i
1771 }
1772  
1773 sub connectBits($*$*%) # Create a connection list connecting a set of output bits on the one chip to a set of input bits on another chip.
1774 {my ($oc, $o, $ic, $i, %options) = @_; # First chip, name of gates on first chip, second chip, names of gates on second chip, options
1775 @_ >= 4 or confess "Four or more parameters";
1776 my %c;
1777 my $O = sizeBits($oc, $o);
1778 my $I = sizeBits($ic, $i);
1779 $O == $I or confess <<"END";
1780 Mismatch between size of bus $o at $O and bus $i at $I
1781 END
1782  
1783 for my $b(1..$I) # Bit to connect
1784 {$c{n($o, $b)} = n($i, $b); # Connect bits
1785 }
1786 %c # Connection list
1787 }
1788  
1789 sub connectWords($*$*$$%) # Create a connection list connecting a set of words on the outer chip to a set of words on the inner chip.
1790 {my ($oc, $o, $ic, $i, $words, $bits, %options) = @_; # First chip, name of gates on first chip, second chip, names of gates on second chip, number of words to connect, options
1791 @_ >= 6 or confess "Six or more parameters";
1792 my %c;
1793 for my $w(1..$bits) # Word to connect
1794 {for my $b(1..$bits) # Bit to connect
1795 {$c{nn($o, $w, $b)} = nn($i, $w, $b); # Connection list
1796 }
1797 }
1798 %c # Connection list
1799 }
1800  
1801 my sub merge($%) # Merge a L<chip> and all its sub L<chips> to make a single L<chip>.
1802 {my ($chip, %options) = @_; # Chip, options
1803  
1804 my $gates = getGates $chip; # Gates implementing the chip and all of its sub chips
1805 setOuterGates ($chip, $gates); # Set the outer gates which are to be connected to in the real word
1806 removeExcessIO($chip, $gates); # By pass and then remove all interior IO gates as they are no longer needed
1807  
1808 my $c = newChip %$chip, %options, gates=>$gates, installs=>[]; # Create the new chip with all installs expanded
1809 #print($c, %options) if $options{print}; # Print the gates
1810 #printSvg ($c, %options) if $options{svg}; # Draw the gates using svg
1811 checkIO $c; # Check all inputs are connected to valid gates and that all outputs are used
1812  
1813 $c
1814 }
1815  
1816 my sub simulationResults($%) # Simulation results obtained by specifying the inputs to all the L<lgs> on the L<chip> and allowing its output L<lgs> to stabilize.
1817 {my ($chip, %options) = @_; # Chip, hash of final values for each gate, options
1818  
1819 genHash(__PACKAGE__."::Simulation", # Simulation results
1820 chip => $chip, # Chip being simulated
1821 changed => $options{changed}, # Last time this gate changed
1822 steps => $options{steps}, # Number of steps to reach stability
1823 values => $options{values}, # Values of every output at point of stability
1824 svg => $options{svg}, # Name of file containing svg drawing if requested
1825 );
1826 }
1827  
1828 sub Silicon::Chip::Simulation::value($$%) # Get the value of a gate as seen in a simulation.
1829 {my ($simulation, $name, %options) = @_; # Chip, gate, options
1830 @_ >= 2 or confess "Two or more parameters";
1831 $simulation->values->{$name} # Value of gate
1832 }
1833  
1834 my sub checkInputs($$%) # Check that an input value has been provided for every input pin on the chip.
1835 {my ($chip, $inputs, %options) = @_; # Chip, inputs, hash of final values for each gate, options
1836  
1837 for my $g(values $chip->gates->%*) # Each gate on chip
1838 {if ($g->io == gateOuterInput) # Outer input gate
1839 {my ($i) = values $g->inputs->%*; # Inputs
1840 if (!defined($$inputs{$i})) # Check we have a corresponding input
1841 {my $n = $g->output;
1842 confess "No input value for input gate: $n\n";
1843 }
1844 }
1845 }
1846 }
1847  
1848 sub Silicon::Chip::Simulation::bInt($$%) # Represent the state of bits in the simulation results as an unsigned binary integer.
1849 {my ($simulation, $output, %options) = @_; # Chip, name of gates on bus, options
1850 @_ >= 2 or confess "Two or more parameters";
1851 my $B = sizeBits($simulation->chip, $output);
1852 my %v = $simulation->values->%*;
1853 my @b;
1854 for my $b(1..$B) # Bits
1855 {push @b, $v{n $output, $b};
1856 }
1857  
1858 eval join '', '0b', reverse @b; # Convert to number
1859 }
1860  
1861 sub Silicon::Chip::Simulation::wInt($$%) # Represent the state of words in the simulation results as an array of unsigned binary integer.
1862 {my ($simulation, $output, %options) = @_; # Chip, name of gates on bus, options
1863 @_ >= 2 or confess "Two or more parameters";
1864 my ($words, $bits) = sizeWords($simulation->chip, $output);
1865 my %v = $simulation->values->%*;
1866 my @w;
1867 for my $w(1..$words) # Words
1868 {my @b;
1869 for my $b(1..$bits) # Bits
1870 {push @b, $v{nn $output, $w, $b};
1871 }
1872  
1873 push @w, eval join '', '0b', reverse @b; # Convert to number
1874 }
1875 @w
1876 }
1877  
1878 sub Silicon::Chip::Simulation::wordXToInteger($$%) # Represent the state of words in the simulation results as an array of unsigned binary integer.
1879 {my ($simulation, $output, %options) = @_; # Chip, name of gates on bus, options
1880 @_ >= 2 or confess "Two or more parameters";
1881 my ($words, $bits) = sizeWords($simulation->chip, $output);
1882 my %v = $simulation->values->%*;
1883 my @w;
1884 for my $b(1..$bits) # Bits
1885 {my @b;
1886 for my $w(1..$words) # Words
1887 {push @b, $v{nn $output, $w, $b};
1888 }
1889  
1890 push @w, eval join '', '0b', reverse @b; # Convert to number
1891 }
1892 @w
1893 }
1894  
1895 my sub simulationStep($$%) # One step in the simulation of the L<chip> after expansion of inner L<chips>.
1896 {my ($chip, $values, %options) = @_; # Chip, current value of each gate, options
1897 my $gates = $chip->gates; # Gates on chip
1898 my %changes; # Changes made
1899  
1900 for my $G(sort {$$gates{$a}->seq <=> $$gates{$b}->seq} keys %$gates) # Each gate in sub chip on definition order to get a repeatable order
1901 {my $g = $$gates{$G}; # Address gate
1902 my $t = $g->type; # Gate type
1903 my $n = $g->output; # Gate name
1904 my %i = $g->inputs->%*; # Inputs to gate
1905 my @i = map {$$values{$i{$_}}} sort keys %i; # Values of inputs to gates in input pin name order
1906  
1907 my $u = 0; # Number of undefined inputs
1908 for my $i(@i)
1909 {++$u unless defined $i;
1910 }
1911  
1912 if ($u == 0) # All inputs defined
1913 {my $r; # Result of gate operation
1914 if ($t =~ m(\Aand|nand\Z)i) # Elaborate and B<and> and B<nand> gates
1915 {my $z = grep {!$_} @i; # Count zero inputs
1916 $r = $z ? 0 : 1;
1917 $r = !$r if $t =~ m(\Anand\Z)i;
1918 }
1919 elsif ($t =~ m(\A(input)\Z)i) # An B<input> gate takes its value from the list of inputs or from an output gate in an inner chip
1920 {if (my @i = values $g->inputs->%*) # Get the value of the input gate from the current values
1921 {my $n = $i[0];
1922 $r = $$values{$n};
1923 }
1924 else
1925 {confess "No driver for input gate: $n\n";
1926 }
1927 }
1928 elsif ($t =~ m(\A(continue|nor|not|or|output)\Z)i) # Elaborate B<not>, B<or> or B<output> gate. A B<continue> gate places its single input unchanged on its output
1929 {my $o = grep {$_} @i; # Count one inputs
1930 $r = $o ? 1 : 0;
1931 $r = $r ? 0 : 1 if $t =~ m(\Anor|not\Z)i;
1932 }
1933 elsif ($t =~ m(\A(nxor|xor)\Z)i) # Elaborate B<xor>
1934 {@i == 2 or confess "$t gate: '$n' must have exactly two inputs\n";
1935 $r = $i[0] ^ $i[1] ? 1 : 0;
1936 $r = $r ? 0 : 1 if $t =~ m(\Anxor\Z)i;
1937 }
1938 elsif ($t =~ m(\A(gt|ngt)\Z)i) # Elaborate B<a> more than B<b> - the input pins are assumed to be sorted by name with the first pin as B<a> and the second as B<b>
1939 {@i == 2 or confess "$t gate: '$n' must have exactly two inputs\n";
1940 $r = $i[0] > $i[1] ? 1 : 0;
1941 $r = $r ? 0 : 1 if $t =~ m(\Angt\Z)i;
1942 }
1943 elsif ($t =~ m(\A(lt|nlt)\Z)i) # Elaborate B<a> less than B<b> - the input pins are assumed to be sorted by name with the first pin as B<a> and the second as B<b>
1944 {@i == 2 or confess "$t gate: '$n' must have exactly two inputs\n";
1945 $r = $i[0] < $i[1] ? 1 : 0;
1946 $r = $r ? 0 : 1 if $t =~ m(\Anlt\Z)i;
1947 }
1948 elsif ($t =~ m(\Aone\Z)i) # One
1949 {@i == 0 or confess "$t gate: '$n' must have no inputs\n";
1950 $r = 1;
1951 }
1952 elsif ($t =~ m(\Azero\Z)i) # Zero
1953 {@i == 0 or confess "$t gate: '$n' must have no inputs\n";
1954 $r = 0;
1955 }
1956 else # Unknown gate type
1957 {confess "Need implementation for '$t' gates";
1958 }
1959 $changes{$G} = $r unless defined($$values{$G}) and $$values{$G} == $r; # Value computed by this gate
1960 }
1961 }
1962 %changes
1963 }
1964  
1965 sub simulate($$%) # Simulate the action of the L<lgs> on a L<chip> for a given set of inputs until the output value of each L<lg> stabilizes.
1966 {my ($chip, $inputs, %options) = @_; # Chip, Hash of input names to values, options
1967 @_ >= 2 or confess "Two or more parameters";
1968 my $c = merge($chip, %options); # Merge all the sub chips to make one chip with no sub chips
1969 checkInputs($c, $inputs); # Confirm that there is an input value for every input to the chip
1970  
1971 my %values = %$inputs; # The current set of values contains just the inputs at the start of the simulation
1972 my %changed; # Last step on which this gate changed. We use this to order the gates on layout
1973  
1974 my $T = maxSimulationSteps; # Maximum steps
1975 for my $t(0..$T) # Steps in time
1976 {my %changes = simulationStep $c, \%values; # Changes made
1977  
1978 if (!keys %changes) # Keep going until nothing changes
1979 {my $svg; # Svg drawing of chip if requested
1980 # if ($options{svg}) # Draw the gates using svg with the final values attached
1981 # {$svg = printSvg $c, values=>\%values, changed=>\%changed,
1982 # steps=>$t, %options;
1983 # }
1984 if ($options{svg}) # Layout the gates as a fiber bundle
1985 {$svg = drawMask $c, values=>\%values, changed=>\%changed,
1986 steps=>$t, %options;
1987 }
1988 return simulationResults $chip, values=>\%values, changed=>\%changed, # Keep going until nothing changes
1989 steps=>$t, svg=>$svg;
1990 }
1991  
1992 for my $c(keys %changes) # Update state of circuit
1993 {$values{$c} = $changes{$c};
1994 if ($options{latest})
1995 {$changed{$c} = $t; # Latest time we changed this gate
1996 }
1997 else
1998 {$changed{$c} = $t unless defined($changed{$c}); # Earliest time we changed this gate
1999 }
2000 }
2001 }
2002  
2003 confess "Out of time after $T steps"; # Not enough steps available
2004 }
2005  
2006 #-------------------------------------------------------------------------------
2007 # Export
2008 #-------------------------------------------------------------------------------
2009  
2010 use Exporter qw(import);
2011  
2012 use vars qw(@ISA @EXPORT @EXPORT_OK %EXPORT_TAGS);
2013  
2014 # containingFolder
2015  
2016 @ISA = qw(Exporter);
2017 @EXPORT = qw();
2018 @EXPORT_OK = qw(connectBits connectWords n nn setBits setWords);
2019 %EXPORT_TAGS = (all=>[@EXPORT, @EXPORT_OK]);
2020  
2021 #Images https://raw.githubusercontent.com/philiprbrenan/SiliconChip/main/lib/Silicon/svg/
2022  
2023 =pod
2024  
2025 =encoding utf-8
2026  
2027 =for html <p><a href="https://github.com/philiprbrenan/SiliconChip"><img src="https://github.com/philiprbrenan/SiliconChip/workflows/Test/badge.svg"></a>
2028  
2029 =head1 Name
2030  
2031 Silicon::Chip - Design a L<silicon|https://en.wikipedia.org/wiki/Silicon> L<chip|https://en.wikipedia.org/wiki/Integrated_circuit> by combining L<logic gates|https://en.wikipedia.org/wiki/Logic_gate> and sub L<chips|https://en.wikipedia.org/wiki/Integrated_circuit>.
2032  
2033 =head1 Synopsis
2034  
2035 Create a chip to compare two 4 bit big endian unsigned integers for equality:
2036  
2037 my $B = 4; # Number of bits
2038  
2039 my $c = Silicon::Chip::newChip(title=>"$B Bit Equals"); # Create chip
2040  
2041 $c->input ("a$_") for 1..$B; # First number
2042 $c->input ("b$_") for 1..$B; # Second number
2043  
2044 $c->nxor ("e$_", {1=>"a$_", 2=>"b$_"}) for 1..$B; # Test each bit for equality
2045 $c->and ("and", {map{$_=>"e$_"} 1..$B}); # And tests together to get total equality
2046  
2047 $c->output("out", "and"); # Output gate
2048  
2049 my $s = $c->simulate({a1=>1, a2=>0, a3=>1, a4=>0, # Input gate values
2050 b1=>1, b2=>0, b3=>1, b4=>0},
2051 svg=>q(svg/Equals$B)); # Svg drawing of layout
2052  
2053 is_deeply($s->steps, 3); # Three steps
2054 is_deeply($s->values->{out}, 1); # Out is 1 for equals
2055  
2056 my $t = $c->simulate({a1=>1, a2=>1, a3=>1, a4=>0,
2057 b1=>1, b2=>0, b3=>1, b4=>0});
2058 is_deeply($t->values->{out}, 0); # Out is 0 for not equals
2059  
2060 To obtain:
2061  
2062 =for html <img src="https://raw.githubusercontent.com/philiprbrenan/SiliconChip/main/lib/Silicon/svg/Equals.svg">
2063  
2064 Other circuit diagrams can be seen in folder: L<lib/Silicon/svg|https://github.com/philiprbrenan/SiliconChip/tree/main/lib/Silicon/svg>
2065  
2066 =head1 Description
2067  
2068 Design a L<silicon|https://en.wikipedia.org/wiki/Silicon> L<chip|https://en.wikipedia.org/wiki/Integrated_circuit> by combining L<logic gates|https://en.wikipedia.org/wiki/Logic_gate> and sub L<chips|https://en.wikipedia.org/wiki/Integrated_circuit>.
2069  
2070  
2071 Version 20231118.
2072  
2073  
2074 The following sections describe the methods in each functional area of this
2075 module. For an alphabetic listing of all methods by name see L<Index|/Index>.
2076  
2077  
2078  
2079 =head1 Construct
2080  
2081 Construct a L<Silicon|https://en.wikipedia.org/wiki/Silicon> L<chip|https://en.wikipedia.org/wiki/Integrated_circuit> using standard L<logic gates|https://en.wikipedia.org/wiki/Logic_gate>, components and sub chips combined via buses.
2082  
2083 =head2 newChip (%options)
2084  
2085 Create a new L<chip|https://en.wikipedia.org/wiki/Integrated_circuit>.
2086  
2087 Parameter Description
2088 1 %options Options
2089  
2090 B<Example:>
2091  
2092  
2093 if (1)
2094  
2095 {my $c = Silicon::Chip::newChip; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
2096  
2097 $c->one ("one");
2098 $c->zero("zero");
2099 $c->or ("or", [qw(one zero)]);
2100 $c->and ("and", [qw(one zero)]);
2101 $c->output("o1", "or");
2102 $c->output("o2", "and");
2103 my $s = $c->simulate({}, svg=>q(svg/oneZero));
2104 is_deeply($s->steps , 3);
2105 is_deeply($s->value("o1"), 1);
2106 is_deeply($s->value("o2"), 0);
2107 }
2108  
2109  
2110 =for html <img src="https://raw.githubusercontent.com/philiprbrenan/SiliconChip/main/lib/Silicon/svg/oneZero.svg">
2111  
2112 if (1) # Single AND gate
2113  
2114 {my $c = Silicon::Chip::newChip; # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
2115  
2116 $c->input ("i1");
2117 $c->input ("i2");
2118 $c->and ("and1", [qw(i1 i2)]);
2119 $c->output("o", "and1");
2120 my $s = $c->simulate({i1=>1, i2=>1}, svg=>q(svg/and));
2121 ok($s->steps == 2);
2122 ok($s->value("and1") == 1);
2123 }
2124  
2125  
2126 =for html <img src="https://raw.githubusercontent.com/philiprbrenan/SiliconChip/main/lib/Silicon/svg/and.svg">
2127  
2128 if (1) # 4 bit equal
2129 {my $B = 4; # Number of bits
2130  
2131  
2132 my $c = Silicon::Chip::newChip(title=><<"END"); # Create chip # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
2133  
2134 $B Bit Equals
2135 END
2136 $c->input ("a$_") for 1..$B; # First number
2137 $c->input ("b$_") for 1..$B; # Second number
2138  
2139 $c->nxor ("e$_", "a$_", "b$_") for 1..$B; # Test each bit for equality
2140 $c->and ("and", {map{$_=>"e$_"} 1..$B}); # And tests together to get total equality
2141  
2142 $c->output("out", "and"); # Output gate
2143  
2144 my $s = $c->simulate({a1=>1, a2=>0, a3=>1, a4=>0, # Input gate values
2145 b1=>1, b2=>0, b3=>1, b4=>0},
2146 svg=>q(svg/Equals)); # Svg drawing of layout
2147  
2148 is_deeply($s->steps, 3); # Three steps
2149 is_deeply($s->value("out"), 1); # Out is 1 for equals
2150 is_deeply(substr(md5_hex(readFile $s->svg), 0, 4), '9ff8');
2151  
2152 my $t = $c->simulate({a1=>1, a2=>1, a3=>1, a4=>0,
2153 b1=>1, b2=>0, b3=>1, b4=>0});
2154 is_deeply($t->value("out"), 0); # Out is 0 for not equals
2155 }
2156  
2157  
2158 =for html <img src="https://raw.githubusercontent.com/philiprbrenan/SiliconChip/main/lib/Silicon/svg/Equals.svg">
2159  
2160  
2161 =head2 gate($chip, $type, $output, $input1, $input2)
2162  
2163 A L<logic gate|https://en.wikipedia.org/wiki/Logic_gate> chosen from B<and|continue|gt|input|lt|nand|nor|not|nxor|one|or|output|xor|zero>. The gate type can be used as a method name, so B<-E<gt>gate("and",> can be reduced to B<-E<gt>and(>.
2164  
2165 Parameter Description
2166 1 $chip Chip
2167 2 $type Gate type
2168 3 $output Output name
2169 4 $input1 Input from another gate
2170 5 $input2 Input from another gate
2171  
2172 B<Example:>
2173  
2174  
2175  
2176 if (1) # Two AND gates driving an OR gate # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
2177  
2178 {my $c = newChip;
2179 $c->input ("i11");
2180 $c->input ("i12");
2181 $c->and ("and1", [qw(i11 i12)]);
2182 $c->input ("i21");
2183 $c->input ("i22");
2184 $c->and ("and2", [qw(i21 i22 )]);
2185 $c->or ("or", [qw(and1 and2)]);
2186 $c->output( "o", "or");
2187 my $s = $c->simulate({i11=>1, i12=>1, i21=>1, i22=>1}, svg=>q(svg/andOr));
2188 ok($s->steps == 3);
2189 ok($s->value("or") == 1);
2190 $s = $c->simulate({i11=>1, i12=>0, i21=>1, i22=>1});
2191 ok($s->steps == 3);
2192 ok($s->value("or") == 1);
2193 $s = $c->simulate({i11=>1, i12=>0, i21=>1, i22=>0});
2194 ok($s->steps == 3);
2195 ok($s->value("o") == 0);
2196 }
2197  
2198  
2199 =for html <img src="https://raw.githubusercontent.com/philiprbrenan/SiliconChip/main/lib/Silicon/svg/andOr.svg">
2200  
2201  
2202 =head2 Buses
2203  
2204 A bus is an array of bits or an array of arrays of bits
2205  
2206 =head3 Bits
2207  
2208 An array of bits that can be manipulated via one name.
2209  
2210 =head4 setSizeBits ($chip, $name, $bits, %options)
2211  
2212 Set the size of a bits bus.
2213  
2214 Parameter Description
2215 1 $chip Chip
2216 2 $name Bits bus name
2217 3 $bits Options
2218 4 %options
2219  
2220 B<Example:>
2221  
2222  
2223 if (1)
2224 {my $c = newChip();
2225  
2226 $c->setSizeBits ('i', 2); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
2227  
2228 $c->setSizeWords('j', 3, 2);
2229 is_deeply($c->sizeBits, {i => 2, j_1 => 2, j_2 => 2, j_3 => 2});
2230 is_deeply($c->sizeWords, {j => [3, 2]});
2231 }
2232  
2233  
2234 =head4 bits($chip, $name, $bits, $value, %options)
2235  
2236 Create a bus set to a specified number.
2237  
2238 Parameter Description
2239 1 $chip Chip
2240 2 $name Name of bus
2241 3 $bits Width in bits of bus
2242 4 $value Value of bus
2243 5 %options Options
2244  
2245 B<Example:>
2246  
2247  
2248 if (1)
2249 {my $N = 4;
2250 for my $i(0..2**$N-1)
2251 {my $c = Silicon::Chip::newChip;
2252  
2253 $c->bits ("c", $N, $i); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
2254  
2255 $c->outputBits("o", "c");
2256  
2257 my $s = $c->simulate({}, $i == 3 ? (svg=>q(svg/bits)) : ()); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
2258  
2259 is_deeply($s->steps, 2);
2260 is_deeply($s->bInt("o"), $i);
2261 }
2262 }
2263  
2264  
2265 =for html <img src="https://raw.githubusercontent.com/philiprbrenan/SiliconChip/main/lib/Silicon/svg/bits.svg">
2266  
2267  
2268 =head4 inputBits   ($chip, $name, $bits, %options)
2269  
2270 Create an B<input> bus made of bits.
2271  
2272 Parameter Description
2273 1 $chip Chip
2274 2 $name Name of bus
2275 3 $bits Width in bits of bus
2276 4 %options Options
2277  
2278 B<Example:>
2279  
2280  
2281 if (1)
2282 {my $W = 8;
2283 my $i = newChip(name=>"not");
2284  
2285 $i->inputBits('i', $W); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
2286  
2287 $i->notBits (qw(n i));
2288 $i->outputBits(qw(o n));
2289  
2290 my $o = newChip(name=>"outer");
2291  
2292 $o->inputBits ('a', $W); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
2293  
2294 $o->outputBits(qw(A a));
2295  
2296 $o->inputBits ('b', $W); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
2297  
2298 $o->outputBits(qw(B b));
2299  
2300 my %i = connectBits($i, 'i', $o, 'A');
2301 my %o = connectBits($i, 'o', $o, 'b');
2302 $o->install($i, {%i}, {%o});
2303  
2304 my %d = setBits($o, 'a', 0b10110);
2305 my $s = $o->simulate({%d}, svg=>q(svg/not));
2306 is_deeply($s->bInt('B'), 0b11101001);
2307 }
2308  
2309  
2310 =for html <img src="https://raw.githubusercontent.com/philiprbrenan/SiliconChip/main/lib/Silicon/svg/not.svg">
2311  
2312  
2313 =head4 outputBits  ($chip, $name, $input, %options)
2314  
2315 Create an B<output> bus made of bits.
2316  
2317 Parameter Description
2318 1 $chip Chip
2319 2 $name Name of bus
2320 3 $input Name of inputs
2321 4 %options Options
2322  
2323 B<Example:>
2324  
2325  
2326 if (1)
2327 {my $W = 8;
2328 my $i = newChip(name=>"not");
2329 $i->inputBits('i', $W);
2330 $i->notBits (qw(n i));
2331  
2332 $i->outputBits(qw(o n)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
2333  
2334  
2335 my $o = newChip(name=>"outer");
2336 $o->inputBits ('a', $W);
2337  
2338 $o->outputBits(qw(A a)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
2339  
2340 $o->inputBits ('b', $W);
2341  
2342 $o->outputBits(qw(B b)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
2343  
2344  
2345 my %i = connectBits($i, 'i', $o, 'A');
2346 my %o = connectBits($i, 'o', $o, 'b');
2347 $o->install($i, {%i}, {%o});
2348  
2349 my %d = setBits($o, 'a', 0b10110);
2350 my $s = $o->simulate({%d}, svg=>q(svg/not));
2351 is_deeply($s->bInt('B'), 0b11101001);
2352 }
2353  
2354  
2355 =for html <img src="https://raw.githubusercontent.com/philiprbrenan/SiliconChip/main/lib/Silicon/svg/not.svg">
2356  
2357 if (1)
2358 {my @B = ((my $W = 4), (my $B = 2));
2359  
2360 my $c = newChip();
2361 $c->inputWords ('i', @B);
2362 $c->andWords (qw(and i));
2363 $c->andWordsX (qw(andX i));
2364 $c-> orWords (qw( or i));
2365 $c-> orWordsX (qw( orX i));
2366 $c->notWords (qw(n i));
2367  
2368 $c->outputBits (qw(And and)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
2369  
2370  
2371 $c->outputBits (qw(AndX andX)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
2372  
2373  
2374 $c->outputBits (qw(Or or)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
2375  
2376  
2377 $c->outputBits (qw(OrX orX)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
2378  
2379 $c->outputWords(qw(N n));
2380 my %d = setWords($c, 'i', 0b00, 0b01, 0b10, 0b11);
2381 my $s = $c->simulate({%d}, svg=>q(svg/andOrWords));
2382  
2383 is_deeply($s->bInt('And'), 0b1000);
2384 is_deeply($s->bInt('AndX'), 0b0000);
2385  
2386 is_deeply($s->bInt('Or'), 0b1110);
2387 is_deeply($s->bInt('OrX'), 0b11);
2388 is_deeply([$s->wInt('N')], [3, 2, 1, 0]);
2389 }
2390  
2391  
2392 =for html <img src="https://raw.githubusercontent.com/philiprbrenan/SiliconChip/main/lib/Silicon/svg/andOrWords.svg">
2393  
2394  
2395 =head4 notBits ($chip, $name, $input, %options)
2396  
2397 Create a B<not> bus made of bits.
2398  
2399 Parameter Description
2400 1 $chip Chip
2401 2 $name Name of bus
2402 3 $input Name of inputs
2403 4 %options Options
2404  
2405 B<Example:>
2406  
2407  
2408 if (1)
2409 {my $W = 8;
2410 my $i = newChip(name=>"not");
2411 $i->inputBits('i', $W);
2412  
2413 $i->notBits (qw(n i)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
2414  
2415 $i->outputBits(qw(o n));
2416  
2417 my $o = newChip(name=>"outer");
2418 $o->inputBits ('a', $W);
2419 $o->outputBits(qw(A a));
2420 $o->inputBits ('b', $W);
2421 $o->outputBits(qw(B b));
2422  
2423 my %i = connectBits($i, 'i', $o, 'A');
2424 my %o = connectBits($i, 'o', $o, 'b');
2425 $o->install($i, {%i}, {%o});
2426  
2427 my %d = setBits($o, 'a', 0b10110);
2428 my $s = $o->simulate({%d}, svg=>q(svg/not));
2429 is_deeply($s->bInt('B'), 0b11101001);
2430 }
2431  
2432  
2433 =for html <img src="https://raw.githubusercontent.com/philiprbrenan/SiliconChip/main/lib/Silicon/svg/not.svg">
2434  
2435  
2436 =head4 andBits ($chip, $name, $input, %options)
2437  
2438 B<and> a bus made of bits.
2439  
2440 Parameter Description
2441 1 $chip Chip
2442 2 $name Name of bus
2443 3 $input Name of inputs
2444 4 %options Options
2445  
2446 B<Example:>
2447  
2448  
2449 if (1)
2450 {my $W = 8;
2451  
2452 my $c = newChip();
2453 $c-> inputBits('i', $W);
2454  
2455 $c-> andBits(qw(and i)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
2456  
2457 $c-> orBits(qw(or i));
2458 $c-> nandBits(qw(nand i));
2459 $c-> norBits(qw(nor i));
2460 $c->output (qw(And and));
2461 $c->output (qw(Or or));
2462 $c->output (qw(nAnd nand));
2463 $c->output (qw(nOr nor));
2464  
2465 my %d = setBits($c, 'i', 0b10110);
2466 my $s = $c->simulate({%d}, svg=>q(svg/andOrBits));
2467  
2468 is_deeply($s->value("And"), 0);
2469 is_deeply($s->value("Or"), 1);
2470 is_deeply($s->value("nAnd"), 1);
2471 is_deeply($s->value("nOr"), 0);
2472 }
2473  
2474  
2475 =for html <img src="https://raw.githubusercontent.com/philiprbrenan/SiliconChip/main/lib/Silicon/svg/andOrBits.svg">
2476  
2477  
2478 =head4 nandBits($chip, $name, $input, %options)
2479  
2480 B<nand> a bus made of bits.
2481  
2482 Parameter Description
2483 1 $chip Chip
2484 2 $name Name of bus
2485 3 $input Name of inputs
2486 4 %options Options
2487  
2488 B<Example:>
2489  
2490  
2491 if (1)
2492 {my $W = 8;
2493  
2494 my $c = newChip();
2495 $c-> inputBits('i', $W);
2496 $c-> andBits(qw(and i));
2497 $c-> orBits(qw(or i));
2498  
2499 $c-> nandBits(qw(nand i)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
2500  
2501 $c-> norBits(qw(nor i));
2502 $c->output (qw(And and));
2503 $c->output (qw(Or or));
2504 $c->output (qw(nAnd nand));
2505 $c->output (qw(nOr nor));
2506  
2507 my %d = setBits($c, 'i', 0b10110);
2508 my $s = $c->simulate({%d}, svg=>q(svg/andOrBits));
2509  
2510 is_deeply($s->value("And"), 0);
2511 is_deeply($s->value("Or"), 1);
2512 is_deeply($s->value("nAnd"), 1);
2513 is_deeply($s->value("nOr"), 0);
2514 }
2515  
2516  
2517 =for html <img src="https://raw.githubusercontent.com/philiprbrenan/SiliconChip/main/lib/Silicon/svg/andOrBits.svg">
2518  
2519  
2520 =head4 orBits  ($chip, $name, $input, %options)
2521  
2522 B<or> a bus made of bits.
2523  
2524 Parameter Description
2525 1 $chip Chip
2526 2 $name Name of bus
2527 3 $input Options
2528 4 %options
2529  
2530 B<Example:>
2531  
2532  
2533 if (1)
2534 {my $W = 8;
2535  
2536 my $c = newChip();
2537 $c-> inputBits('i', $W);
2538 $c-> andBits(qw(and i));
2539  
2540 $c-> orBits(qw(or i)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
2541  
2542 $c-> nandBits(qw(nand i));
2543 $c-> norBits(qw(nor i));
2544 $c->output (qw(And and));
2545 $c->output (qw(Or or));
2546 $c->output (qw(nAnd nand));
2547 $c->output (qw(nOr nor));
2548  
2549 my %d = setBits($c, 'i', 0b10110);
2550 my $s = $c->simulate({%d}, svg=>q(svg/andOrBits));
2551  
2552 is_deeply($s->value("And"), 0);
2553 is_deeply($s->value("Or"), 1);
2554 is_deeply($s->value("nAnd"), 1);
2555 is_deeply($s->value("nOr"), 0);
2556 }
2557  
2558  
2559 =for html <img src="https://raw.githubusercontent.com/philiprbrenan/SiliconChip/main/lib/Silicon/svg/andOrBits.svg">
2560  
2561  
2562 =head4 norBits ($chip, $name, $input, %options)
2563  
2564 B<nor> a bus made of bits.
2565  
2566 Parameter Description
2567 1 $chip Chip
2568 2 $name Name of bus
2569 3 $input Options
2570 4 %options
2571  
2572 B<Example:>
2573  
2574  
2575 if (1)
2576 {my $W = 8;
2577  
2578 my $c = newChip();
2579 $c-> inputBits('i', $W);
2580 $c-> andBits(qw(and i));
2581 $c-> orBits(qw(or i));
2582 $c-> nandBits(qw(nand i));
2583  
2584 $c-> norBits(qw(nor i)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
2585  
2586 $c->output (qw(And and));
2587 $c->output (qw(Or or));
2588 $c->output (qw(nAnd nand));
2589 $c->output (qw(nOr nor));
2590  
2591 my %d = setBits($c, 'i', 0b10110);
2592 my $s = $c->simulate({%d}, svg=>q(svg/andOrBits));
2593  
2594 is_deeply($s->value("And"), 0);
2595 is_deeply($s->value("Or"), 1);
2596 is_deeply($s->value("nAnd"), 1);
2597 is_deeply($s->value("nOr"), 0);
2598 }
2599  
2600  
2601 =for html <img src="https://raw.githubusercontent.com/philiprbrenan/SiliconChip/main/lib/Silicon/svg/andOrBits.svg">
2602  
2603  
2604 =head3 Words
2605  
2606 An array of arrays of bits that can be manipulated via one name.
2607  
2608 =head4 setSizeWords($chip, $name, $words, $bits, %options)
2609  
2610 Set the size of a bits bus.
2611  
2612 Parameter Description
2613 1 $chip Chip
2614 2 $name Bits bus name
2615 3 $words Words
2616 4 $bits Bits per word
2617 5 %options Options
2618  
2619 B<Example:>
2620  
2621  
2622 if (1)
2623 {my $c = newChip();
2624 $c->setSizeBits ('i', 2);
2625  
2626 $c->setSizeWords('j', 3, 2); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
2627  
2628 is_deeply($c->sizeBits, {i => 2, j_1 => 2, j_2 => 2, j_3 => 2});
2629 is_deeply($c->sizeWords, {j => [3, 2]});
2630 }
2631  
2632  
2633 =head4 words   ($chip, $name, $bits, @values)
2634  
2635 Create a word bus set to specified numbers.
2636  
2637 Parameter Description
2638 1 $chip Chip
2639 2 $name Name of bus
2640 3 $bits Width in bits of each word
2641 4 @values Values of words
2642  
2643 B<Example:>
2644  
2645  
2646 if (1) # Internal input gate
2647 {my @n = qw(3 2 1 2 3);
2648 my $c = newChip();
2649  
2650 $c->words('i', 2, @n); # Input # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
2651  
2652 $c->outputWords(qw(o i)); # Output
2653  
2654 my $s = $c->simulate({}, svg=>q(svg/words)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
2655  
2656 is_deeply($s->steps, 2);
2657 is_deeply([$s->wInt("i")], [@n]);
2658 }
2659  
2660  
2661 =for html <img src="https://raw.githubusercontent.com/philiprbrenan/SiliconChip/main/lib/Silicon/svg/words.svg">
2662  
2663  
2664 =head4 inputWords  ($chip, $name, $words, $bits, %options)
2665  
2666 Create an B<input> bus made of words.
2667  
2668 Parameter Description
2669 1 $chip Chip
2670 2 $name Name of bus
2671 3 $words Width in words of bus
2672 4 $bits Width in bits of each word on bus
2673 5 %options Options
2674  
2675 B<Example:>
2676  
2677  
2678 if (1)
2679 {my @b = ((my $W = 4), (my $B = 3));
2680  
2681 my $c = newChip();
2682  
2683 $c->inputWords ('i', @b); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
2684  
2685 $c->outputWords(qw(o i));
2686  
2687 my %d = setWords($c, 'i', 0b000, 0b001, 0b010, 0b011);
2688 my $s = $c->simulate({%d}, svg=>q(svg/words$W));
2689  
2690 is_deeply([$s->wInt('o')], [0..3]);
2691 is_deeply([$s->wordXToInteger('o')], [10, 12, 0]);
2692 }
2693  
2694  
2695 =for html <img src="https://raw.githubusercontent.com/philiprbrenan/SiliconChip/main/lib/Silicon/svg/words$W.svg">
2696  
2697  
2698 =head4 outputWords ($chip, $name, $input, %options)
2699  
2700 Create an B<output> bus made of words.
2701  
2702 Parameter Description
2703 1 $chip Chip
2704 2 $name Name of bus
2705 3 $input Name of inputs
2706 4 %options Options
2707  
2708 B<Example:>
2709  
2710  
2711 if (1)
2712 {my @b = ((my $W = 4), (my $B = 3));
2713  
2714 my $c = newChip();
2715 $c->inputWords ('i', @b);
2716  
2717 $c->outputWords(qw(o i)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
2718  
2719  
2720 my %d = setWords($c, 'i', 0b000, 0b001, 0b010, 0b011);
2721 my $s = $c->simulate({%d}, svg=>q(svg/words$W));
2722  
2723 is_deeply([$s->wInt('o')], [0..3]);
2724 is_deeply([$s->wordXToInteger('o')], [10, 12, 0]);
2725 }
2726  
2727  
2728 =for html <img src="https://raw.githubusercontent.com/philiprbrenan/SiliconChip/main/lib/Silicon/svg/words$W.svg">
2729  
2730  
2731 =head4 notWords($chip, $name, $input, %options)
2732  
2733 Create a B<not> bus made of words.
2734  
2735 Parameter Description
2736 1 $chip Chip
2737 2 $name Name of bus
2738 3 $input Name of inputs
2739 4 %options Options
2740  
2741 B<Example:>
2742  
2743  
2744 if (1)
2745 {my @B = ((my $W = 4), (my $B = 2));
2746  
2747 my $c = newChip();
2748 $c->inputWords ('i', @B);
2749 $c->andWords (qw(and i));
2750 $c->andWordsX (qw(andX i));
2751 $c-> orWords (qw( or i));
2752 $c-> orWordsX (qw( orX i));
2753  
2754 $c->notWords (qw(n i)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
2755  
2756 $c->outputBits (qw(And and));
2757 $c->outputBits (qw(AndX andX));
2758 $c->outputBits (qw(Or or));
2759 $c->outputBits (qw(OrX orX));
2760 $c->outputWords(qw(N n));
2761 my %d = setWords($c, 'i', 0b00, 0b01, 0b10, 0b11);
2762 my $s = $c->simulate({%d}, svg=>q(svg/andOrWords));
2763  
2764 is_deeply($s->bInt('And'), 0b1000);
2765 is_deeply($s->bInt('AndX'), 0b0000);
2766  
2767 is_deeply($s->bInt('Or'), 0b1110);
2768 is_deeply($s->bInt('OrX'), 0b11);
2769 is_deeply([$s->wInt('N')], [3, 2, 1, 0]);
2770 }
2771  
2772  
2773 =for html <img src="https://raw.githubusercontent.com/philiprbrenan/SiliconChip/main/lib/Silicon/svg/andOrWords.svg">
2774  
2775  
2776 =head4 andWords($chip, $name, $input, %options)
2777  
2778 B<and> a bus made of words to produce a single word.
2779  
2780 Parameter Description
2781 1 $chip Chip
2782 2 $name Name of bus
2783 3 $input Name of inputs
2784 4 %options Options
2785  
2786 B<Example:>
2787  
2788  
2789 if (1)
2790 {my @B = ((my $W = 4), (my $B = 2));
2791  
2792 my $c = newChip();
2793 $c->inputWords ('i', @B);
2794  
2795 $c->andWords (qw(and i)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
2796  
2797 $c->andWordsX (qw(andX i));
2798 $c-> orWords (qw( or i));
2799 $c-> orWordsX (qw( orX i));
2800 $c->notWords (qw(n i));
2801 $c->outputBits (qw(And and));
2802 $c->outputBits (qw(AndX andX));
2803 $c->outputBits (qw(Or or));
2804 $c->outputBits (qw(OrX orX));
2805 $c->outputWords(qw(N n));
2806 my %d = setWords($c, 'i', 0b00, 0b01, 0b10, 0b11);
2807 my $s = $c->simulate({%d}, svg=>q(svg/andOrWords));
2808  
2809 is_deeply($s->bInt('And'), 0b1000);
2810 is_deeply($s->bInt('AndX'), 0b0000);
2811  
2812 is_deeply($s->bInt('Or'), 0b1110);
2813 is_deeply($s->bInt('OrX'), 0b11);
2814 is_deeply([$s->wInt('N')], [3, 2, 1, 0]);
2815 }
2816  
2817  
2818 =for html <img src="https://raw.githubusercontent.com/philiprbrenan/SiliconChip/main/lib/Silicon/svg/andOrWords.svg">
2819  
2820 if (1)
2821 {my @b = ((my $W = 4), (my $B = 3));
2822  
2823 my $c = newChip();
2824 $c->inputWords ('i', @b);
2825 $c->outputWords(qw(o i));
2826  
2827 my %d = setWords($c, 'i', 0b000, 0b001, 0b010, 0b011);
2828 my $s = $c->simulate({%d}, svg=>q(svg/words$W));
2829  
2830 is_deeply([$s->wInt('o')], [0..3]);
2831 is_deeply([$s->wordXToInteger('o')], [10, 12, 0]);
2832 }
2833  
2834  
2835 =for html <img src="https://raw.githubusercontent.com/philiprbrenan/SiliconChip/main/lib/Silicon/svg/words$W.svg">
2836  
2837  
2838 =head4 andWordsX   ($chip, $name, $input, %options)
2839  
2840 B<and> a bus made of words by and-ing the corresponding bits in each word to make a single word.
2841  
2842 Parameter Description
2843 1 $chip Chip
2844 2 $name Name of bus
2845 3 $input Name of inputs
2846 4 %options Options
2847  
2848 B<Example:>
2849  
2850  
2851 if (1)
2852 {my @B = ((my $W = 4), (my $B = 2));
2853  
2854 my $c = newChip();
2855 $c->inputWords ('i', @B);
2856 $c->andWords (qw(and i));
2857  
2858 $c->andWordsX (qw(andX i)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
2859  
2860 $c-> orWords (qw( or i));
2861 $c-> orWordsX (qw( orX i));
2862 $c->notWords (qw(n i));
2863 $c->outputBits (qw(And and));
2864 $c->outputBits (qw(AndX andX));
2865 $c->outputBits (qw(Or or));
2866 $c->outputBits (qw(OrX orX));
2867 $c->outputWords(qw(N n));
2868 my %d = setWords($c, 'i', 0b00, 0b01, 0b10, 0b11);
2869 my $s = $c->simulate({%d}, svg=>q(svg/andOrWords));
2870  
2871 is_deeply($s->bInt('And'), 0b1000);
2872 is_deeply($s->bInt('AndX'), 0b0000);
2873  
2874 is_deeply($s->bInt('Or'), 0b1110);
2875 is_deeply($s->bInt('OrX'), 0b11);
2876 is_deeply([$s->wInt('N')], [3, 2, 1, 0]);
2877 }
2878  
2879  
2880 =for html <img src="https://raw.githubusercontent.com/philiprbrenan/SiliconChip/main/lib/Silicon/svg/andOrWords.svg">
2881  
2882  
2883 =head4 orWords ($chip, $name, $input, %options)
2884  
2885 B<or> a bus made of words to produce a single word.
2886  
2887 Parameter Description
2888 1 $chip Chip
2889 2 $name Name of bus
2890 3 $input Name of inputs
2891 4 %options Options
2892  
2893 B<Example:>
2894  
2895  
2896 if (1)
2897 {my @B = ((my $W = 4), (my $B = 2));
2898  
2899 my $c = newChip();
2900 $c->inputWords ('i', @B);
2901 $c->andWords (qw(and i));
2902 $c->andWordsX (qw(andX i));
2903  
2904 $c-> orWords (qw( or i)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
2905  
2906 $c-> orWordsX (qw( orX i));
2907 $c->notWords (qw(n i));
2908 $c->outputBits (qw(And and));
2909 $c->outputBits (qw(AndX andX));
2910 $c->outputBits (qw(Or or));
2911 $c->outputBits (qw(OrX orX));
2912 $c->outputWords(qw(N n));
2913 my %d = setWords($c, 'i', 0b00, 0b01, 0b10, 0b11);
2914 my $s = $c->simulate({%d}, svg=>q(svg/andOrWords));
2915  
2916 is_deeply($s->bInt('And'), 0b1000);
2917 is_deeply($s->bInt('AndX'), 0b0000);
2918  
2919 is_deeply($s->bInt('Or'), 0b1110);
2920 is_deeply($s->bInt('OrX'), 0b11);
2921 is_deeply([$s->wInt('N')], [3, 2, 1, 0]);
2922 }
2923  
2924  
2925 =for html <img src="https://raw.githubusercontent.com/philiprbrenan/SiliconChip/main/lib/Silicon/svg/andOrWords.svg">
2926  
2927 if (1)
2928 {my @b = ((my $W = 4), (my $B = 3));
2929  
2930 my $c = newChip();
2931 $c->inputWords ('i', @b);
2932 $c->outputWords(qw(o i));
2933  
2934 my %d = setWords($c, 'i', 0b000, 0b001, 0b010, 0b011);
2935 my $s = $c->simulate({%d}, svg=>q(svg/words$W));
2936  
2937 is_deeply([$s->wInt('o')], [0..3]);
2938 is_deeply([$s->wordXToInteger('o')], [10, 12, 0]);
2939 }
2940  
2941  
2942 =for html <img src="https://raw.githubusercontent.com/philiprbrenan/SiliconChip/main/lib/Silicon/svg/words$W.svg">
2943  
2944  
2945 =head4 orWordsX($chip, $name, $input, %options)
2946  
2947 B<or> a bus made of words by or-ing the corresponding bits in each word to make a single word.
2948  
2949 Parameter Description
2950 1 $chip Chip
2951 2 $name Name of bus
2952 3 $input Name of inputs
2953 4 %options Options
2954  
2955 B<Example:>
2956  
2957  
2958 if (1)
2959 {my @B = ((my $W = 4), (my $B = 2));
2960  
2961 my $c = newChip();
2962 $c->inputWords ('i', @B);
2963 $c->andWords (qw(and i));
2964 $c->andWordsX (qw(andX i));
2965 $c-> orWords (qw( or i));
2966  
2967 $c-> orWordsX (qw( orX i)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
2968  
2969 $c->notWords (qw(n i));
2970 $c->outputBits (qw(And and));
2971 $c->outputBits (qw(AndX andX));
2972 $c->outputBits (qw(Or or));
2973 $c->outputBits (qw(OrX orX));
2974 $c->outputWords(qw(N n));
2975 my %d = setWords($c, 'i', 0b00, 0b01, 0b10, 0b11);
2976 my $s = $c->simulate({%d}, svg=>q(svg/andOrWords));
2977  
2978 is_deeply($s->bInt('And'), 0b1000);
2979 is_deeply($s->bInt('AndX'), 0b0000);
2980  
2981 is_deeply($s->bInt('Or'), 0b1110);
2982 is_deeply($s->bInt('OrX'), 0b11);
2983 is_deeply([$s->wInt('N')], [3, 2, 1, 0]);
2984 }
2985  
2986  
2987 =for html <img src="https://raw.githubusercontent.com/philiprbrenan/SiliconChip/main/lib/Silicon/svg/andOrWords.svg">
2988  
2989  
2990 =head2 Connect
2991  
2992 Connect input buses to other buses.
2993  
2994 =head3 connectInput($chip, $in, $to, %options)
2995  
2996 Connect a previously defined input gate to the output of another gate on the same chip. This allows us to define a set of gates on the chip without having to know, first, all the names of the gates that will provide input to these gates.
2997  
2998 Parameter Description
2999 1 $chip Chip
3000 2 $in Input gate
3001 3 $to Gate to connect input gate to
3002 4 %options Options
3003  
3004 B<Example:>
3005  
3006  
3007 if (1) # Internal input gate
3008 {my $c = newChip();
3009 $c->input ('i'); # Input
3010 $c->input ('j'); # Internal input which we will connect to later
3011 $c->output(qw(o j)); # Output
3012  
3013  
3014 $c->connectInput(qw(j i)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
3015  
3016  
3017  
3018 my $s = $c->simulate({i=>1}, svg=>q(svg/connectInput)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
3019  
3020 is_deeply($s->steps, 1);
3021 is_deeply($s->value("j"), undef);
3022 is_deeply($s->value("o"), 1);
3023 }
3024  
3025  
3026 =for html <img src="https://raw.githubusercontent.com/philiprbrenan/SiliconChip/main/lib/Silicon/svg/connectInput.svg">
3027  
3028 if (1) # Internal input gate
3029 {my @n = qw(3 2 1 2 3);
3030 my $c = newChip();
3031 $c->words('i', 2, @n); # Input
3032 $c->outputWords(qw(o i)); # Output
3033 my $s = $c->simulate({}, svg=>q(svg/words));
3034 is_deeply($s->steps, 2);
3035 is_deeply([$s->wInt("i")], [@n]);
3036 }
3037  
3038  
3039 =for html <img src="https://raw.githubusercontent.com/philiprbrenan/SiliconChip/main/lib/Silicon/svg/words.svg">
3040  
3041  
3042 =head3 connectInputBits($chip, $in, $to, %options)
3043  
3044 Connect a previously defined input bit bus to another bit bus provided the two buses have the same size.
3045  
3046 Parameter Description
3047 1 $chip Chip
3048 2 $in Input gate
3049 3 $to Gate to connect input gate to
3050 4 %options Options
3051  
3052 B<Example:>
3053  
3054  
3055 if (1)
3056 {my $N = 5; my $B = 5;
3057 my $c = newChip();
3058 $c->bits ('a', $B, $N);
3059 $c->inputBits ('i', $N);
3060 $c->outputBits(qw(o i));
3061  
3062 $c->connectInputBits(qw(i a)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
3063  
3064  
3065 my $s = $c->simulate({}, svg=>q(svg/connectInputBits)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
3066  
3067 is_deeply($s->steps, 2);
3068 is_deeply($s->bInt("o"), $N);
3069 }
3070  
3071  
3072 =for html <img src="https://raw.githubusercontent.com/philiprbrenan/SiliconChip/main/lib/Silicon/svg/connectInputBits.svg">
3073  
3074  
3075 =head3 connectInputWords   ($chip, $in, $to, %options)
3076  
3077 Connect a previously defined input word bus to another word bus provided the two buses have the same size.
3078  
3079 Parameter Description
3080 1 $chip Chip
3081 2 $in Input gate
3082 3 $to Gate to connect input gate to
3083 4 %options Options
3084  
3085 B<Example:>
3086  
3087  
3088 if (1)
3089 {my $W = 6; my $B = 5;
3090 my $c = newChip();
3091 $c->words ('a', $B, 1..$W);
3092 $c->inputWords ('i', $W, $B);
3093 $c->outputWords(qw(o i));
3094  
3095 $c->connectInputWords(qw(i a)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
3096  
3097  
3098 my $s = $c->simulate({}, svg=>q(svg/connectInputWords)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
3099  
3100 is_deeply($s->steps, 2);
3101 is_deeply([$s->wInt("o")], [1..$W]);
3102 }
3103  
3104  
3105 =for html <img src="https://raw.githubusercontent.com/philiprbrenan/SiliconChip/main/lib/Silicon/svg/connectInputWords.svg">
3106  
3107  
3108 =head2 Install
3109  
3110 Install a chip within a chip as a sub chip.
3111  
3112 =head3 install ($chip, $subChip, $inputs, $outputs, %options)
3113  
3114 Install a L<chip|https://en.wikipedia.org/wiki/Integrated_circuit> within another L<chip|https://en.wikipedia.org/wiki/Integrated_circuit> specifying the connections between the inner and outer L<chip|https://en.wikipedia.org/wiki/Integrated_circuit>. The same L<chip|https://en.wikipedia.org/wiki/Integrated_circuit> can be installed multiple times as each L<chip|https://en.wikipedia.org/wiki/Integrated_circuit> description is read only.
3115  
3116 Parameter Description
3117 1 $chip Outer chip
3118 2 $subChip Inner chip
3119 3 $inputs Inputs of inner chip to to outputs of outer chip
3120 4 $outputs Outputs of inner chip to inputs of outer chip
3121 5 %options Options
3122  
3123 B<Example:>
3124  
3125  
3126 if (1) # Install one chip inside another chip, specifically one chip that performs NOT is installed once to flip a value
3127 {my $i = newChip(name=>"not");
3128 $i-> inputBits('i', 1);
3129 $i-> notBits(qw(n i));
3130 $i->outputBits(qw(o n));
3131  
3132 my $o = newChip(name=>"outer");
3133 $o->inputBits('i', 1); $o->outputBits(qw(n i));
3134 $o->inputBits('I', 1); $o->outputBits(qw(N I));
3135  
3136 my %i = connectBits($i, 'i', $o, 'n');
3137 my %o = connectBits($i, 'o', $o, 'I');
3138  
3139 $o->install($i, {%i}, {%o}); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
3140  
3141 my %d = $o->setBits('i', 1);
3142 my $s = $o->simulate({%d}, svg=>q(svg/notb1));
3143  
3144 is_deeply($s->steps, 2);
3145 is_deeply($s->values, {"(not 1 n_1)"=>0, "i_1"=>1, "N_1"=>0 });
3146 }
3147  
3148  
3149 =for html <img src="https://raw.githubusercontent.com/philiprbrenan/SiliconChip/main/lib/Silicon/svg/notb1.svg">
3150  
3151  
3152 =head1 Visualize
3153  
3154 Visualize the L<chip|https://en.wikipedia.org/wiki/Integrated_circuit> in various ways.
3155  
3156 =head2 print   ($chip, %options)
3157  
3158 Dump the L<logic gates|https://en.wikipedia.org/wiki/Logic_gate> present on a L<chip|https://en.wikipedia.org/wiki/Integrated_circuit>.
3159  
3160 Parameter Description
3161 1 $chip Chip
3162 2 %options Gates
3163  
3164 B<Example:>
3165  
3166  
3167 if (1)
3168 {my $c = Silicon::Chip::newChip(title=>"And gate");
3169 $c->input ("i1");
3170 $c->input ("i2");
3171 $c->and ("and1", [qw(i1 i2)]);
3172 $c->output("o", "and1");
3173 my $s = $c->simulate({i1=>1, i2=>1});
3174  
3175  
3176 is_deeply($c->print, <<END); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
3177  
3178 i1 : input i1
3179 i2 : input i2
3180 and1 : and i1 i2
3181 o : output and1
3182 END
3183  
3184  
3185 is_deeply($s->print, <<END); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
3186  
3187 i1 : 1 input i1
3188 i2 : 1 input i2
3189 and1 : 1 and i1 i2
3190 o : 1 output and1
3191 END
3192  
3193 ok($s->printSvg ne $c->printSvg);
3194 }
3195  
3196  
3197 =head2 Silicon::Chip::Simulation::print($sim, %options)
3198  
3199 Print simulation results as text.
3200  
3201 Parameter Description
3202 1 $sim Simulation
3203 2 %options Options
3204  
3205 B<Example:>
3206  
3207  
3208 if (1)
3209 {my $c = Silicon::Chip::newChip(title=>"And gate");
3210 $c->input ("i1");
3211 $c->input ("i2");
3212 $c->and ("and1", [qw(i1 i2)]);
3213 $c->output("o", "and1");
3214 my $s = $c->simulate({i1=>1, i2=>1});
3215  
3216 is_deeply($c->print, <<END);
3217 i1 : input i1
3218 i2 : input i2
3219 and1 : and i1 i2
3220 o : output and1
3221 END
3222  
3223 is_deeply($s->print, <<END);
3224 i1 : 1 input i1
3225 i2 : 1 input i2
3226 and1 : 1 and i1 i2
3227 o : 1 output and1
3228 END
3229  
3230 ok($s->printSvg ne $c->printSvg);
3231 }
3232  
3233  
3234 =head2 printSvg($chip, %options)
3235  
3236 Mask the L<logic gates|https://en.wikipedia.org/wiki/Logic_gate> onto a L<chip|https://en.wikipedia.org/wiki/Integrated_circuit> as an L<Scalar Vector Graphics|https://en.wikipedia.org/wiki/Scalable_Vector_Graphics> drawing to help visualize the structure of the L<chip|https://en.wikipedia.org/wiki/Integrated_circuit> using a condensed input bus.
3237  
3238 Parameter Description
3239 1 $chip Chip
3240 2 %options Options
3241  
3242 B<Example:>
3243  
3244  
3245 if (1)
3246 {my $c = Silicon::Chip::newChip(title=>"And gate");
3247 $c->input ("i1");
3248 $c->input ("i2");
3249 $c->and ("and1", [qw(i1 i2)]);
3250 $c->output("o", "and1");
3251 my $s = $c->simulate({i1=>1, i2=>1});
3252  
3253 is_deeply($c->print, <<END);
3254 i1 : input i1
3255 i2 : input i2
3256 and1 : and i1 i2
3257 o : output and1
3258 END
3259  
3260 is_deeply($s->print, <<END);
3261 i1 : 1 input i1
3262 i2 : 1 input i2
3263 and1 : 1 and i1 i2
3264 o : 1 output and1
3265 END
3266  
3267  
3268 ok($s->printSvg ne $c->printSvg); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
3269  
3270 }
3271  
3272  
3273 =head2 Silicon::Chip::Simulation::printSvg ($sim, %options)
3274  
3275 Print simulation results as svg.
3276  
3277 Parameter Description
3278 1 $sim Simulation
3279 2 %options Options
3280  
3281 B<Example:>
3282  
3283  
3284 if (1)
3285 {my $c = Silicon::Chip::newChip(title=>"And gate");
3286 $c->input ("i1");
3287 $c->input ("i2");
3288 $c->and ("and1", [qw(i1 i2)]);
3289 $c->output("o", "and1");
3290 my $s = $c->simulate({i1=>1, i2=>1});
3291  
3292 is_deeply($c->print, <<END);
3293 i1 : input i1
3294 i2 : input i2
3295 and1 : and i1 i2
3296 o : output and1
3297 END
3298  
3299 is_deeply($s->print, <<END);
3300 i1 : 1 input i1
3301 i2 : 1 input i2
3302 and1 : 1 and i1 i2
3303 o : 1 output and1
3304 END
3305  
3306 ok($s->printSvg ne $c->printSvg);
3307 }
3308  
3309  
3310 =head1 Basic Circuits
3311  
3312 Some well known basic circuits.
3313  
3314 =head2 n   ($c, $i)
3315  
3316 Gate name from single index.
3317  
3318 Parameter Description
3319 1 $c Gate name
3320 2 $i Bit number
3321  
3322 B<Example:>
3323  
3324  
3325 if (1)
3326  
3327 {is_deeply( n(a,1), "a_1"); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
3328  
3329 is_deeply(nn(a,1,2), "a_1_2");
3330 }
3331  
3332  
3333 =head2 nn  ($c, $i, $j)
3334  
3335 Gate name from double index.
3336  
3337 Parameter Description
3338 1 $c Gate name
3339 2 $i Word number
3340 3 $j Bit number
3341  
3342 B<Example:>
3343  
3344  
3345 if (1)
3346 {is_deeply( n(a,1), "a_1");
3347  
3348 is_deeply(nn(a,1,2), "a_1_2"); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
3349  
3350 }
3351  
3352  
3353 =head2 Comparisons
3354  
3355 Compare unsigned binary integers of specified bit widths.
3356  
3357 =head3 compareEq   ($chip, $output, $a, $b, %options)
3358  
3359 Compare two unsigned binary integers of a specified width returning B<1> if they are equal else B<0>.
3360  
3361 Parameter Description
3362 1 $chip Chip
3363 2 $output Name of component also the output bus
3364 3 $a First integer
3365 4 $b Second integer
3366 5 %options Options
3367  
3368 B<Example:>
3369  
3370  
3371 if (1) # Compare unsigned integers
3372 {my $B = 2;
3373  
3374 my $c = Silicon::Chip::newChip(title=><<"END");
3375 $B Bit Compare Equal
3376 END
3377 $c->inputBits($_, $B) for qw(a b); # First and second numbers
3378  
3379 $c->compareEq(qw(o a b)); # Compare equals # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
3380  
3381 $c->output (qw(out o)); # Comparison result
3382  
3383 for my $i(0..2**$B-1) # Each possible number
3384 {for my $j(0..2**$B-1) # Each possible number
3385 {my %a = $c->setBits('a', $i); # Number a
3386 my %b = $c->setBits('b', $j); # Number b
3387  
3388 my $s = $c->simulate({%a, %b}, $i==1&&$j==1?(svg=>q(svg/CompareEq)):()); # Svg drawing of layout
3389  
3390 is_deeply($s->value("out"), $i == $j ? 1 : 0); # Equal
3391 is_deeply($s->steps, 3); # Number of steps to stability
3392 }
3393 }
3394 }
3395  
3396  
3397 =for html <img src="https://raw.githubusercontent.com/philiprbrenan/SiliconChip/main/lib/Silicon/svg/CompareEq.svg">
3398  
3399  
3400 =head3 compareGt   ($chip, $output, $a, $b, %options)
3401  
3402 Compare two unsigned binary integers and return B<1> if the first integer is more than B<b> else B<0>.
3403  
3404 Parameter Description
3405 1 $chip Chip
3406 2 $output Name of component also the output bus
3407 3 $a First integer
3408 4 $b Second integer
3409 5 %options Options
3410  
3411 B<Example:>
3412  
3413  
3414 if (1) # Compare 8 bit unsigned integers 'a' > 'b' - the pins used to input 'a' must be alphabetically less than those used for 'b'
3415 {my $B = 3;
3416 my $c = Silicon::Chip::newChip(title=><<END);
3417 $B Bit Compare more than
3418 END
3419 $c->inputBits($_, $B) for qw(a b); # First and second numbers
3420  
3421 $c->compareGt(qw(o a b)); # Compare more than # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
3422  
3423 $c->output (qw(out o)); # Comparison result
3424  
3425 for my $i(0..2**$B-1) # Each possible number
3426 {for my $j(0..2**$B-1) # Each possible number
3427 {#$i = 2; $j = 1;
3428 my %a = $c->setBits('a', $i); # Number a
3429 my %b = $c->setBits('b', $j); # Number b
3430  
3431 my $s = $c->simulate({%a, %b}, $i==2&&$j==1?(svg=>q(svg/CompareGt)):()); # Svg drawing of layout
3432 is_deeply($s->value("out"), $i > $j ? 1 : 0); # More than
3433 is_deeply($s->steps, 4); # Number of steps to stability
3434 }
3435 }
3436 }
3437  
3438  
3439 =for html <img src="https://raw.githubusercontent.com/philiprbrenan/SiliconChip/main/lib/Silicon/svg/CompareGt.svg">
3440  
3441  
3442 =head3 compareLt   ($chip, $output, $a, $b, %options)
3443  
3444 Compare two unsigned binary integers B<a>, B<b> of a specified width. Output B<out> is B<1> if B<a> is less than B<b> else B<0>.
3445  
3446 Parameter Description
3447 1 $chip Chip
3448 2 $output Name of component also the output bus
3449 3 $a First integer
3450 4 $b Second integer
3451 5 %options Options
3452  
3453 B<Example:>
3454  
3455  
3456 if (1) # Compare 8 bit unsigned integers 'a' < 'b' - the pins used to input 'a' must be alphabetically less than those used for 'b'
3457 {my $B = 3;
3458 my $c = Silicon::Chip::newChip(title=><<"END");
3459 $B Bit Compare Less Than
3460 END
3461 $c->inputBits($_, $B) for qw(a b); # First and second numbers
3462  
3463 $c->compareLt(qw(o a b)); # Compare less than # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
3464  
3465 $c->output (qw(out o)); # Comparison result
3466  
3467 for my $i(0..2**$B-1) # Each possible number
3468 {for my $j(0..2**$B-1) # Each possible number
3469 {my %a = $c->setBits('a', $i); # Number a
3470 my %b = $c->setBits('b', $j); # Number b
3471  
3472 my $s = $c->simulate({%a, %b}, $i==1&&$j==2?(svg=>q(svg/CompareLt)):()); # Svg drawing of layout
3473 is_deeply($s->value("out"), $i < $j ? 1 : 0); # More than
3474 is_deeply($s->steps, 4); # Number of steps to stability
3475 }
3476 }
3477 }
3478  
3479  
3480 =for html <img src="https://raw.githubusercontent.com/philiprbrenan/SiliconChip/main/lib/Silicon/svg/CompareLt.svg">
3481  
3482  
3483 =head3 chooseFromTwoWords  ($chip, $output, $a, $b, $choose, %options)
3484  
3485 Choose one of two words based on a bit. The first word is chosen if the bit is B<0> otherwise the second word is chosen.
3486  
3487 Parameter Description
3488 1 $chip Chip
3489 2 $output Name of component also the chosen word
3490 3 $a The first word
3491 4 $b The second word
3492 5 $choose The choosing bit
3493 6 %options Options
3494  
3495 B<Example:>
3496  
3497  
3498 if (1)
3499 {my $B = 4;
3500  
3501 my $c = newChip();
3502 $c->inputBits('a', $B); # First word
3503 $c->inputBits('b', $B); # Second word
3504 $c->input ('c'); # Chooser
3505  
3506 $c->chooseFromTwoWords(qw(o a b c)); # Generate gates # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
3507  
3508 $c->outputBits('out', 'o'); # Result
3509  
3510 my %a = setBits($c, 'a', 0b0011);
3511 my %b = setBits($c, 'b', 0b1100);
3512  
3513  
3514 my $s = $c->simulate({%a, %b, c=>1}, svg=>q(svg/chooseFromTwoWords)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
3515  
3516 is_deeply($s->steps, 4);
3517 is_deeply($s->bInt('out'), 0b1100);
3518  
3519 my $t = $c->simulate({%a, %b, c=>0});
3520 is_deeply($t->steps, 4);
3521 is_deeply($t->bInt('out'), 0b0011);
3522 }
3523  
3524  
3525 =for html <img src="https://raw.githubusercontent.com/philiprbrenan/SiliconChip/main/lib/Silicon/svg/chooseFromTwoWords.svg">
3526  
3527  
3528 =head3 enableWord  ($chip, $output, $a, $enable, %options)
3529  
3530 Output a word or zeros depending on a choice bit. The first word is chosen if the choice bit is B<1> otherwise all zeroes are chosen.
3531  
3532 Parameter Description
3533 1 $chip Chip
3534 2 $output Name of component also the chosen word
3535 3 $a The first word
3536 4 $enable The second word
3537 5 %options The choosing bit
3538  
3539 B<Example:>
3540  
3541  
3542 if (1)
3543 {my $B = 4;
3544  
3545 my $c = newChip();
3546 $c->inputBits ('a', $B); # Word
3547 $c->input ('c'); # Choice bit
3548  
3549 $c->enableWord(qw(o a c)); # Generate gates # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
3550  
3551 $c->outputBits(qw(out o)); # Result
3552  
3553 my %a = setBits($c, 'a', 3);
3554  
3555  
3556 my $s = $c->simulate({%a, c=>1}, svg=>q(svg/enableWord)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
3557  
3558 is_deeply($s->steps, 2);
3559 is_deeply($s->bInt('out'), 3);
3560  
3561 my $t = $c->simulate({%a, c=>0});
3562 is_deeply($t->steps, 2);
3563 is_deeply($t->bInt('out'), 0);
3564 }
3565  
3566  
3567 =for html <img src="https://raw.githubusercontent.com/philiprbrenan/SiliconChip/main/lib/Silicon/svg/enableWord.svg">
3568  
3569  
3570 =head2 Masks
3571  
3572 Point masks and monotone masks. A point mask has a single B<1> in a sea of B<0>s as in B<00100>. A monotone mask has zero or more B<0>s followed by all B<1>s as in: B<00111>.
3573  
3574 =head3 pointMaskToInteger  ($chip, $output, $input, %options)
3575  
3576 Convert a mask B<i> known to have at most a single bit on - also known as a B<point mask> - to an output number B<a> representing the location in the mask of the bit set to B<1>. If no such bit exists in the point mask then output number B<a> is B<0>.
3577  
3578 Parameter Description
3579 1 $chip Chip
3580 2 $output Output name
3581 3 $input Input mask
3582 4 %options Options
3583  
3584 B<Example:>
3585  
3586  
3587 if (1)
3588 {my $B = 4;
3589 my $N = 2**$B-1;
3590  
3591 my $c = Silicon::Chip::newChip(title=><<"END");
3592 $B bits point mask to integer
3593 END
3594 $c->inputBits (qw( i), $N); # Mask with no more than one bit on
3595  
3596 $c->pointMaskToInteger(qw(o i)); # Convert # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
3597  
3598 $c->outputBits (qw(out o)); # Mask with no more than one bit on
3599  
3600 for my $i(0..$N) # Each position of mask
3601 {my %i = setBits($c, 'i', $i ? 1<<($i-1) : 0); # Point in each position with zero representing no position
3602 my $s = $c->simulate(\%i, $i == 5 ? (svg=>q(svg/point)) : ());
3603 is_deeply($s->steps, 2);
3604 my %o = $s->values->%*; # Output bits
3605 my $n = eval join '', '0b', map {$o{n(o,$_)}} reverse 1..$B; # Output bits as number
3606 is_deeply($n, $i);
3607 }
3608 }
3609  
3610  
3611 =for html <img src="https://raw.githubusercontent.com/philiprbrenan/SiliconChip/main/lib/Silicon/svg/point.svg">
3612  
3613  
3614 =head3 integerToPointMask  ($chip, $output, $input, %options)
3615  
3616 Convert an integer B<i> of specified width to a point mask B<m>. If the input integer is B<0> then the mask is all zeroes as well.
3617  
3618 Parameter Description
3619 1 $chip Chip
3620 2 $output Output name
3621 3 $input Input mask
3622 4 %options Options
3623  
3624 B<Example:>
3625  
3626  
3627 if (1)
3628 {my $B = 3;
3629 my $N = 2**$B-1;
3630  
3631 my $c = Silicon::Chip::newChip(title=><<"END");
3632 $B bit integer to $N bit monotone mask.
3633 END
3634 $c->inputBits (qw( i), $B); # Input bus
3635  
3636 $c->integerToPointMask(qw(m i)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
3637  
3638 $c->outputBits (qw(o m));
3639 for my $i(0..$N) # Each position of mask
3640 {my %i = setBits($c, 'i', $i);
3641  
3642 my $s = $c->simulate(\%i, $i == 5 ? (svg=>q(svg/integerToPointMask)):()); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
3643  
3644 is_deeply($s->steps, 3);
3645  
3646 my $r = $s->bInt('o'); # Mask values
3647 is_deeply($r, $i ? 1<<($i-1) : 0); # Expected mask
3648 }
3649 }
3650  
3651  
3652 =for html <img src="https://raw.githubusercontent.com/philiprbrenan/SiliconChip/main/lib/Silicon/svg/integerToPointMask.svg">
3653  
3654  
3655 =head3 monotoneMaskToInteger   ($chip, $output, $input, %options)
3656  
3657 Convert a monotone mask B<i> to an output number B<r> representing the location in the mask of the bit set to B<1>. If no such bit exists in the point then output in B<r> is B<0>.
3658  
3659 Parameter Description
3660 1 $chip Chip
3661 2 $output Output name
3662 3 $input Input mask
3663 4 %options Options
3664  
3665 B<Example:>
3666  
3667  
3668 if (1)
3669 {my $B = 4;
3670 my $N = 2**$B-1;
3671  
3672 my $c = Silicon::Chip::newChip(title=><<"END");
3673 $N bit monotone mask to $B bit integer
3674 END
3675 $c->inputBits ('i', $N);
3676  
3677 $c->monotoneMaskToInteger(qw(m i)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
3678  
3679 $c->outputBits (qw(o m));
3680  
3681 for my $i(0..$N-1) # Each monotone mask
3682 {my %i = setBits($c, 'i', $i > 0 ? 1<<$i-1 : 0);
3683 my $s = $c->simulate(\%i,
3684  
3685 $i == 5 ? (svg=>q(svg/monotoneMaskToInteger)) : ()); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
3686  
3687  
3688 is_deeply($s->steps, 4);
3689 is_deeply($s->bInt('m'), $i);
3690 }
3691 }
3692  
3693  
3694 =for html <img src="https://raw.githubusercontent.com/philiprbrenan/SiliconChip/main/lib/Silicon/svg/monotoneMaskToInteger.svg">
3695  
3696  
3697 =head3 monotoneMaskToPointMask ($chip, $output, $input, %options)
3698  
3699 Convert a monotone mask B<i> to a point mask B<o> representing the location in the mask of the first bit set to B<1>. If the monotone mask is all B<0>s then point mask is too.
3700  
3701 Parameter Description
3702 1 $chip Chip
3703 2 $output Output name
3704 3 $input Input mask
3705 4 %options Options
3706  
3707 B<Example:>
3708  
3709  
3710 if (1)
3711 {my $B = 4;
3712  
3713 my $c = newChip();
3714 $c->inputBits('m', $B); # Monotone mask
3715  
3716 $c->monotoneMaskToPointMask(qw(o m)); # Generate gates # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
3717  
3718 $c->outputBits('out', 'o'); # Point mask
3719  
3720 for my $i(0..$B)
3721 {my %m = $c->setBits('m', eval '0b'.(1 x $i).('0' x ($B-$i)));
3722  
3723 my $s = $c->simulate({%m}, $i == 2 ? (svg=>q(svg/monotoneMaskToPointMask)) : ()); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
3724  
3725 is_deeply($s->steps, 2);
3726 is_deeply($s->bInt('out'), $i ? (1<<($B-1)) / (1<<($i-1)) : 0);
3727 }
3728 }
3729  
3730  
3731 =for html <img src="https://raw.githubusercontent.com/philiprbrenan/SiliconChip/main/lib/Silicon/svg/monotoneMaskToPointMask.svg">
3732  
3733  
3734 =head3 integerToMonotoneMask   ($chip, $output, $input, %options)
3735  
3736 Convert an integer B<i> of specified width to a monotone mask B<m>. If the input integer is B<0> then the mask is all zeroes. Otherwise the mask has B<i-1> leading zeroes followed by all ones thereafter.
3737  
3738 Parameter Description
3739 1 $chip Chip
3740 2 $output Output name
3741 3 $input Input mask
3742 4 %options Options
3743  
3744 B<Example:>
3745  
3746  
3747 if (1)
3748 {my $B = 4;
3749 my $N = 2**$B-1;
3750  
3751 my $c = Silicon::Chip::newChip(title=><<"END");
3752 Convert $B bit integer to $N bit monotone mask
3753 END
3754 $c->inputBits ('i', $B); # Input gates
3755  
3756 $c->integerToMonotoneMask(qw(m i)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
3757  
3758 $c->outputBits (qw(o m)); # Output gates
3759  
3760 for my $i(0..$N) # Each position of mask
3761 {my %i = setBits($c, 'i', $i); # The number to convert
3762 my $s = $c->simulate(\%i, $i == 2 ? (svg=>q(svg/integerToMontoneMask)):());
3763 is_deeply($s->steps, 4);
3764 is_deeply($s->bInt('o'), $i > 0 ? ((1<<$N)-1)>>($i-1)<<($i-1) : 0); # Expected mask
3765 }
3766 }
3767  
3768  
3769 =for html <img src="https://raw.githubusercontent.com/philiprbrenan/SiliconChip/main/lib/Silicon/svg/integerToMontoneMask.svg">
3770  
3771  
3772 =head3 chooseWordUnderMask ($chip, $output, $input, $mask, %options)
3773  
3774 Choose one of a specified number of words B<w>, each of a specified width, using a point mask B<m> placing the selected word in B<o>. If no word is selected then B<o> will be zero.
3775  
3776 Parameter Description
3777 1 $chip Chip
3778 2 $output Output
3779 3 $input Inputs
3780 4 $mask Mask
3781 5 %options Options
3782  
3783 B<Example:>
3784  
3785  
3786 if (1)
3787 {my $B = 3; my $W = 4;
3788  
3789 my $c = Silicon::Chip::newChip(title=><<"END");
3790 Choose one of $W words of $B bits
3791 END
3792 $c->inputWords ('w', $W, $B);
3793 $c->inputBits ('m', $W);
3794  
3795 $c->chooseWordUnderMask(qw(W w m)); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
3796  
3797 $c->outputBits (qw(o W));
3798  
3799 my %i = setWords($c, 'w', 0b000, 0b001, 0b010, 0b0100);
3800 my %m = setBits ($c, 'm', 1<<2); # Choose the third word
3801  
3802 my $s = $c->simulate({%i, %m}, svg=>q(svg/choose));
3803  
3804 is_deeply($s->steps, 3);
3805 is_deeply($s->bInt('o'), 0b010);
3806 }
3807  
3808  
3809 =for html <img src="https://raw.githubusercontent.com/philiprbrenan/SiliconChip/main/lib/Silicon/svg/choose.svg">
3810  
3811  
3812 =head3 findWord($chip, $output, $key, $words, %options)
3813  
3814 Choose one of a specified number of words B<w>, each of a specified width, using a key B<k>. Return a point mask B<o> indicating the locations of the key if found or or a mask equal to all zeroes if the key is not present.
3815  
3816 Parameter Description
3817 1 $chip Chip
3818 2 $output Found point mask
3819 3 $key Key
3820 4 $words Words to search
3821 5 %options Options
3822  
3823 B<Example:>
3824  
3825  
3826 if (1)
3827 {my $B = 3; my $W = 2**$B-1;
3828  
3829 my $c = Silicon::Chip::newChip(title=><<END);
3830 Search $W words of $B bits
3831 END
3832 $c->inputBits ('k', $B); # Search key
3833 $c->inputWords('w', 2**$B-1, $B); # Words to search
3834  
3835 $c->findWord (qw(m k w)); # Find the word # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
3836  
3837 $c->outputBits(qw(M m)); # Output mask
3838  
3839 my %w = setWords($c, 'w', reverse 1..$W);
3840  
3841 for my $k(0..$W) # Each possible key
3842 {my %k = setBits($c, 'k', $k);
3843  
3844 my $s = $c->simulate({%k, %w}, $k == 3 ? (svg=>q(svg/findWord)) : ()); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
3845  
3846 is_deeply($s->steps, 3);
3847 is_deeply($s->bInt('M'),$k ? 2**($W-$k) : 0);
3848 }
3849 }
3850  
3851  
3852 =for html <img src="https://raw.githubusercontent.com/philiprbrenan/SiliconChip/main/lib/Silicon/svg/findWord.svg">
3853  
3854  
3855 =head1 Simulate
3856  
3857 Simulate the behavior of the L<chip|https://en.wikipedia.org/wiki/Integrated_circuit> given a set of values on its input gates.
3858  
3859 =head2 setBits ($chip, $name, $value, %options)
3860  
3861 Set an array of input gates to a number prior to running a simulation.
3862  
3863 Parameter Description
3864 1 $chip Chip
3865 2 $name Name of input gates
3866 3 $value Number to set to
3867 4 %options Options
3868  
3869 B<Example:>
3870  
3871  
3872 if (1) # Compare two 4 bit unsigned integers 'a' > 'b' - the pins used to input 'a' must be alphabetically less than those used for 'b'
3873 {my $B = 4; # Number of bits
3874 my $c = Silicon::Chip::newChip(title=><<"END");
3875 $B Bit Compare
3876 END
3877 $c->inputBits("a", $B); # First number
3878 $c->inputBits("b", $B); # Second number
3879 $c->nxor (n(e,$_), n(a,$_), n(b,$_)) for 1..$B-1; # Test each bit for equality
3880 $c->gt (n(g,$_), n(a,$_), n(b,$_)) for 1..$B; # Test each bit pair for greater
3881  
3882 for my $b(2..$B)
3883 {$c->and(n(c,$b), [(map {n(e, $_)} 1..$b-1), n(g,$b)]); # Greater on one bit and all preceding bits are equal
3884 }
3885 $c->or ("or", [n(g,1), (map {n(c, $_)} 2..$B)]); # Any set bit indicates that 'a' is more than 'b'
3886 $c->output("out", "or"); # Output 1 if a > b else 0
3887  
3888  
3889 my %a = $c->setBits('a', 0); # Number a # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
3890  
3891  
3892 my %b = $c->setBits('b', 0); # Number b # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
3893  
3894  
3895 my $s = $c->simulate({%a, %b, n(a,2)=>1, n(b,2)=>1}, svg=>q(svg/equals)); # Two equal numbers
3896 is_deeply($s->value("out"), 0);
3897  
3898 my $t = $c->simulate({%a, %b, n(a,2)=>1});
3899 is_deeply($t->value("out"), 1);
3900 }
3901  
3902  
3903 =for html <img src="https://raw.githubusercontent.com/philiprbrenan/SiliconChip/main/lib/Silicon/svg/equals.svg">
3904  
3905 if (1)
3906 {my $B = 3; my $W = 4;
3907  
3908 my $c = Silicon::Chip::newChip(title=><<"END");
3909 Choose one of $W words of $B bits
3910 END
3911 $c->inputWords ('w', $W, $B);
3912 $c->inputBits ('m', $W);
3913 $c->chooseWordUnderMask(qw(W w m));
3914 $c->outputBits (qw(o W));
3915  
3916 my %i = setWords($c, 'w', 0b000, 0b001, 0b010, 0b0100);
3917  
3918 my %m = setBits ($c, 'm', 1<<2); # Choose the third word # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
3919  
3920  
3921 my $s = $c->simulate({%i, %m}, svg=>q(svg/choose));
3922  
3923 is_deeply($s->steps, 3);
3924 is_deeply($s->bInt('o'), 0b010);
3925 }
3926  
3927  
3928 =for html <img src="https://raw.githubusercontent.com/philiprbrenan/SiliconChip/main/lib/Silicon/svg/choose.svg">
3929  
3930  
3931 =head2 setWords($chip, $name, @values)
3932  
3933 Set an array of arrays of gates to an array of numbers prior to running a simulation.
3934  
3935 Parameter Description
3936 1 $chip Chip
3937 2 $name Name of input gates
3938 3 @values Number of bits in each array element
3939  
3940 B<Example:>
3941  
3942  
3943 if (1)
3944 {my $B = 3; my $W = 4;
3945  
3946 my $c = Silicon::Chip::newChip(title=><<"END");
3947 Choose one of $W words of $B bits
3948 END
3949 $c->inputWords ('w', $W, $B);
3950 $c->inputBits ('m', $W);
3951 $c->chooseWordUnderMask(qw(W w m));
3952 $c->outputBits (qw(o W));
3953  
3954  
3955 my %i = setWords($c, 'w', 0b000, 0b001, 0b010, 0b0100); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
3956  
3957 my %m = setBits ($c, 'm', 1<<2); # Choose the third word
3958  
3959 my $s = $c->simulate({%i, %m}, svg=>q(svg/choose));
3960  
3961 is_deeply($s->steps, 3);
3962 is_deeply($s->bInt('o'), 0b010);
3963 }
3964  
3965  
3966 =for html <img src="https://raw.githubusercontent.com/philiprbrenan/SiliconChip/main/lib/Silicon/svg/choose.svg">
3967  
3968  
3969 =head2 connectBits ($oc, $o, $ic, $i, %options)
3970  
3971 Create a connection list connecting a set of output bits on the one chip to a set of input bits on another chip.
3972  
3973 Parameter Description
3974 1 $oc First chip
3975 2 $o Name of gates on first chip
3976 3 $ic Second chip
3977 4 $i Names of gates on second chip
3978 5 %options Options
3979  
3980 B<Example:>
3981  
3982  
3983 if (1) # Install one chip inside another chip, specifically one chip that performs NOT is installed once to flip a value
3984 {my $i = newChip(name=>"not");
3985 $i-> inputBits('i', 1);
3986 $i-> notBits(qw(n i));
3987 $i->outputBits(qw(o n));
3988  
3989 my $o = newChip(name=>"outer");
3990 $o->inputBits('i', 1); $o->outputBits(qw(n i));
3991 $o->inputBits('I', 1); $o->outputBits(qw(N I));
3992  
3993  
3994 my %i = connectBits($i, 'i', $o, 'n'); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
3995  
3996  
3997 my %o = connectBits($i, 'o', $o, 'I'); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
3998  
3999 $o->install($i, {%i}, {%o});
4000 my %d = $o->setBits('i', 1);
4001 my $s = $o->simulate({%d}, svg=>q(svg/notb1));
4002  
4003 is_deeply($s->steps, 2);
4004 is_deeply($s->values, {"(not 1 n_1)"=>0, "i_1"=>1, "N_1"=>0 });
4005 }
4006  
4007  
4008 =for html <img src="https://raw.githubusercontent.com/philiprbrenan/SiliconChip/main/lib/Silicon/svg/notb1.svg">
4009  
4010  
4011 =head2 connectWords($oc, $o, $ic, $i, $words, $bits, %options)
4012  
4013 Create a connection list connecting a set of words on the outer chip to a set of words on the inner chip.
4014  
4015 Parameter Description
4016 1 $oc First chip
4017 2 $o Name of gates on first chip
4018 3 $ic Second chip
4019 4 $i Names of gates on second chip
4020 5 $words Number of words to connect
4021 6 $bits Options
4022 7 %options
4023  
4024 B<Example:>
4025  
4026  
4027 if (1) # Install one chip inside another chip, specifically one chip that performs NOT is installed three times sequentially to flip a value
4028 {my $i = newChip(name=>"not");
4029 $i-> inputWords('i', 1, 1);
4030 $i-> notWords(qw(n i));
4031 $i->outputWords(qw(o n));
4032  
4033 my $o = newChip(name=>"outer");
4034 $o->inputWords('i', 1, 1); $o->output(nn('n', 1, 1), nn('i', 1, 1));
4035 $o->inputWords('I', 1, 1); $o->output(nn('N', 1, 1), nn('I', 1, 1));
4036  
4037  
4038 my %i = connectWords($i, 'i', $o, 'n', 1, 1); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
4039  
4040  
4041 my %o = connectWords($i, 'o', $o, 'I', 1, 1); # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
4042  
4043 $o->install($i, {%i}, {%o});
4044 my %d = $o->setWords('i', 1);
4045 my $s = $o->simulate({%d}, svg=>q(svg/notw1));
4046  
4047 is_deeply($s->steps, 2);
4048 is_deeply($s->values, { "(not 1 n_1_1)" => 0, "i_1_1" => 1, "N_1_1" => 0 });
4049 }
4050  
4051  
4052 =for html <img src="https://raw.githubusercontent.com/philiprbrenan/SiliconChip/main/lib/Silicon/svg/notw1.svg">
4053  
4054  
4055 =head2 Silicon::Chip::Simulation::value($simulation, $name, %options)
4056  
4057 Get the value of a gate as seen in a simulation.
4058  
4059 Parameter Description
4060 1 $simulation Chip
4061 2 $name Gate
4062 3 %options Options
4063  
4064 B<Example:>
4065  
4066  
4067 if (1) # Internal input gate
4068 {my $c = newChip();
4069 $c->input ('i'); # Input
4070 $c->input ('j'); # Internal input which we will connect to later
4071 $c->output(qw(o j)); # Output
4072  
4073 $c->connectInput(qw(j i));
4074  
4075 my $s = $c->simulate({i=>1}, svg=>q(svg/connectInput));
4076 is_deeply($s->steps, 1);
4077 is_deeply($s->value("j"), undef);
4078 is_deeply($s->value("o"), 1);
4079 }
4080  
4081  
4082 =for html <img src="https://raw.githubusercontent.com/philiprbrenan/SiliconChip/main/lib/Silicon/svg/connectInput.svg">
4083  
4084 if (1) # Internal input gate
4085 {my @n = qw(3 2 1 2 3);
4086 my $c = newChip();
4087 $c->words('i', 2, @n); # Input
4088 $c->outputWords(qw(o i)); # Output
4089 my $s = $c->simulate({}, svg=>q(svg/words));
4090 is_deeply($s->steps, 2);
4091 is_deeply([$s->wInt("i")], [@n]);
4092 }
4093  
4094  
4095 =for html <img src="https://raw.githubusercontent.com/philiprbrenan/SiliconChip/main/lib/Silicon/svg/words.svg">
4096  
4097  
4098 =head2 Silicon::Chip::Simulation::bInt ($simulation, $output, %options)
4099  
4100 Represent the state of bits in the simulation results as an unsigned binary integer.
4101  
4102 Parameter Description
4103 1 $simulation Chip
4104 2 $output Name of gates on bus
4105 3 %options Options
4106  
4107 B<Example:>
4108  
4109  
4110 if (1)
4111 {my $W = 8;
4112 my $i = newChip(name=>"not");
4113 $i->inputBits('i', $W);
4114 $i->notBits (qw(n i));
4115 $i->outputBits(qw(o n));
4116  
4117 my $o = newChip(name=>"outer");
4118 $o->inputBits ('a', $W);
4119 $o->outputBits(qw(A a));
4120 $o->inputBits ('b', $W);
4121 $o->outputBits(qw(B b));
4122  
4123 my %i = connectBits($i, 'i', $o, 'A');
4124 my %o = connectBits($i, 'o', $o, 'b');
4125 $o->install($i, {%i}, {%o});
4126  
4127 my %d = setBits($o, 'a', 0b10110);
4128 my $s = $o->simulate({%d}, svg=>q(svg/not));
4129 is_deeply($s->bInt('B'), 0b11101001);
4130 }
4131  
4132  
4133 =for html <img src="https://raw.githubusercontent.com/philiprbrenan/SiliconChip/main/lib/Silicon/svg/not.svg">
4134  
4135  
4136 =head2 Silicon::Chip::Simulation::wInt ($simulation, $output, %options)
4137  
4138 Represent the state of words in the simulation results as an array of unsigned binary integer.
4139  
4140 Parameter Description
4141 1 $simulation Chip
4142 2 $output Name of gates on bus
4143 3 %options Options
4144  
4145 B<Example:>
4146  
4147  
4148 if (1)
4149 {my @b = ((my $W = 4), (my $B = 3));
4150  
4151 my $c = newChip();
4152 $c->inputWords ('i', @b);
4153 $c->outputWords(qw(o i));
4154  
4155 my %d = setWords($c, 'i', 0b000, 0b001, 0b010, 0b011);
4156 my $s = $c->simulate({%d}, svg=>q(svg/words$W));
4157  
4158 is_deeply([$s->wInt('o')], [0..3]);
4159 is_deeply([$s->wordXToInteger('o')], [10, 12, 0]);
4160 }
4161  
4162  
4163 =for html <img src="https://raw.githubusercontent.com/philiprbrenan/SiliconChip/main/lib/Silicon/svg/words$W.svg">
4164  
4165  
4166 =head2 Silicon::Chip::Simulation::wordXToInteger   ($simulation, $output, %options)
4167  
4168 Represent the state of words in the simulation results as an array of unsigned binary integer.
4169  
4170 Parameter Description
4171 1 $simulation Chip
4172 2 $output Name of gates on bus
4173 3 %options Options
4174  
4175 B<Example:>
4176  
4177  
4178 if (1)
4179 {my @b = ((my $W = 4), (my $B = 3));
4180  
4181 my $c = newChip();
4182 $c->inputWords ('i', @b);
4183 $c->outputWords(qw(o i));
4184  
4185 my %d = setWords($c, 'i', 0b000, 0b001, 0b010, 0b011);
4186 my $s = $c->simulate({%d}, svg=>q(svg/words$W));
4187  
4188 is_deeply([$s->wInt('o')], [0..3]);
4189 is_deeply([$s->wordXToInteger('o')], [10, 12, 0]);
4190 }
4191  
4192  
4193 =for html <img src="https://raw.githubusercontent.com/philiprbrenan/SiliconChip/main/lib/Silicon/svg/words$W.svg">
4194  
4195  
4196 =head2 simulate($chip, $inputs, %options)
4197  
4198 Simulate the action of the L<logic gates|https://en.wikipedia.org/wiki/Logic_gate> on a L<chip|https://en.wikipedia.org/wiki/Integrated_circuit> for a given set of inputs until the output value of each L<logic gate|https://en.wikipedia.org/wiki/Logic_gate> stabilizes.
4199  
4200 Parameter Description
4201 1 $chip Chip
4202 2 $inputs Hash of input names to values
4203 3 %options Options
4204  
4205 B<Example:>
4206  
4207  
4208 if (1) # 4 bit equal
4209 {my $B = 4; # Number of bits
4210  
4211 my $c = Silicon::Chip::newChip(title=><<"END"); # Create chip
4212 $B Bit Equals
4213 END
4214 $c->input ("a$_") for 1..$B; # First number
4215 $c->input ("b$_") for 1..$B; # Second number
4216  
4217 $c->nxor ("e$_", "a$_", "b$_") for 1..$B; # Test each bit for equality
4218 $c->and ("and", {map{$_=>"e$_"} 1..$B}); # And tests together to get total equality
4219  
4220 $c->output("out", "and"); # Output gate
4221  
4222  
4223 my $s = $c->simulate({a1=>1, a2=>0, a3=>1, a4=>0, # Input gate values # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
4224  
4225 b1=>1, b2=>0, b3=>1, b4=>0},
4226 svg=>q(svg/Equals)); # Svg drawing of layout
4227  
4228 is_deeply($s->steps, 3); # Three steps
4229 is_deeply($s->value("out"), 1); # Out is 1 for equals
4230 is_deeply(substr(md5_hex(readFile $s->svg), 0, 4), '9ff8');
4231  
4232  
4233 my $t = $c->simulate({a1=>1, a2=>1, a3=>1, a4=>0, # 𝗘𝘅𝗮𝗺𝗽𝗹𝗲
4234  
4235 b1=>1, b2=>0, b3=>1, b4=>0});
4236 is_deeply($t->value("out"), 0); # Out is 0 for not equals
4237 }
4238  
4239  
4240 =for html <img src="https://raw.githubusercontent.com/philiprbrenan/SiliconChip/main/lib/Silicon/svg/Equals.svg">
4241  
4242  
4243  
4244 =head1 Hash Definitions
4245  
4246  
4247  
4248  
4249 =head2 Silicon::Chip Definition
4250  
4251  
4252 Simulation results
4253  
4254  
4255  
4256  
4257 =head3 Output fields
4258  
4259  
4260 =head4 busEnd
4261  
4262 Bus Line end
4263  
4264 =head4 busLine
4265  
4266 Bus line
4267  
4268 =head4 busStart
4269  
4270 Bus line start
4271  
4272 =head4 changed
4273  
4274 Last time this gate changed
4275  
4276 =head4 chip
4277  
4278 Chip being simulated
4279  
4280 =head4 fibers
4281  
4282 Fibers after collapse
4283  
4284 =head4 gate
4285  
4286 Gate
4287  
4288 =head4 gateSeq
4289  
4290 Gate sequence number - this allows us to display the gates in the order they were defined ti simplify the understanding of drawn layouts
4291  
4292 =head4 gates
4293  
4294 Gates in chip
4295  
4296 =head4 height
4297  
4298 Height of drawing
4299  
4300 =head4 inPlay
4301  
4302 Squares in play for collapsing
4303  
4304 =head4 inputs
4305  
4306 Outputs of outer chip to inputs of inner chip
4307  
4308 =head4 installs
4309  
4310 Chips installed within the chip
4311  
4312 =head4 io
4313  
4314 Whether an input/output gate or not
4315  
4316 =head4 name
4317  
4318 Name of chip
4319  
4320 =head4 output
4321  
4322 Output name which is used as the name of the gate as well
4323  
4324 =head4 outputs
4325  
4326 Outputs of inner chip to inputs of outer chip
4327  
4328 =head4 positionsArray
4329  
4330 Position array
4331  
4332 =head4 positionsHash
4333  
4334 Position hash
4335  
4336 =head4 seq
4337  
4338 Sequence number for this gate
4339  
4340 =head4 sizeBits
4341  
4342 Sizes of buses
4343  
4344 =head4 sizeWords
4345  
4346 Sizes of buses
4347  
4348 =head4 steps
4349  
4350 Number of steps to reach stability
4351  
4352 =head4 svg
4353  
4354 Name of file containing svg drawing if requested
4355  
4356 =head4 thickness
4357  
4358 Width of the thickest fiber bundle
4359  
4360 =head4 title
4361  
4362 Title if known
4363  
4364 =head4 type
4365  
4366 Gate type
4367  
4368 =head4 values
4369  
4370 Values of every output at point of stability
4371  
4372 =head4 width
4373  
4374 Width of drawing
4375  
4376 =head4 x
4377  
4378 X position of gate
4379  
4380 =head4 y
4381  
4382 Y position of gate
4383  
4384  
4385  
4386 =head1 Private Methods
4387  
4388 =head2 AUTOLOAD($chip, @options)
4389  
4390 Autoload by L<logic gate|https://en.wikipedia.org/wiki/Logic_gate> name to provide a more readable way to specify the L<logic gates|https://en.wikipedia.org/wiki/Logic_gate> on a L<chip|https://en.wikipedia.org/wiki/Integrated_circuit>.
4391  
4392 Parameter Description
4393 1 $chip Chip
4394 2 @options Options
4395  
4396 =head2 Silicon::Chip::Layout::draw ($layout, %options)
4397  
4398 Draw a mask for the gates.
4399  
4400 Parameter Description
4401 1 $layout Layout
4402 2 %options Options
4403  
4404  
4405 =head1 Index
4406  
4407  
4408 1 L<andBits|/andBits> - B<and> a bus made of bits.
4409  
4410 2 L<andWords|/andWords> - B<and> a bus made of words to produce a single word.
4411  
4412 3 L<andWordsX|/andWordsX> - B<and> a bus made of words by and-ing the corresponding bits in each word to make a single word.
4413  
4414 4 L<AUTOLOAD|/AUTOLOAD> - Autoload by L<logic gate|https://en.wikipedia.org/wiki/Logic_gate> name to provide a more readable way to specify the L<logic gates|https://en.wikipedia.org/wiki/Logic_gate> on a L<chip|https://en.wikipedia.org/wiki/Integrated_circuit>.
4415  
4416 5 L<bits|/bits> - Create a bus set to a specified number.
4417  
4418 6 L<chooseFromTwoWords|/chooseFromTwoWords> - Choose one of two words based on a bit.
4419  
4420 7 L<chooseWordUnderMask|/chooseWordUnderMask> - Choose one of a specified number of words B<w>, each of a specified width, using a point mask B<m> placing the selected word in B<o>.
4421  
4422 8 L<compareEq|/compareEq> - Compare two unsigned binary integers of a specified width returning B<1> if they are equal else B<0>.
4423  
4424 9 L<compareGt|/compareGt> - Compare two unsigned binary integers and return B<1> if the first integer is more than B<b> else B<0>.
4425  
4426 10 L<compareLt|/compareLt> - Compare two unsigned binary integers B<a>, B<b> of a specified width.
4427  
4428 11 L<connectBits|/connectBits> - Create a connection list connecting a set of output bits on the one chip to a set of input bits on another chip.
4429  
4430 12 L<connectInput|/connectInput> - Connect a previously defined input gate to the output of another gate on the same chip.
4431  
4432 13 L<connectInputBits|/connectInputBits> - Connect a previously defined input bit bus to another bit bus provided the two buses have the same size.
4433  
4434 14 L<connectInputWords|/connectInputWords> - Connect a previously defined input word bus to another word bus provided the two buses have the same size.
4435  
4436 15 L<connectWords|/connectWords> - Create a connection list connecting a set of words on the outer chip to a set of words on the inner chip.
4437  
4438 16 L<enableWord|/enableWord> - Output a word or zeros depending on a choice bit.
4439  
4440 17 L<findWord|/findWord> - Choose one of a specified number of words B<w>, each of a specified width, using a key B<k>.
4441  
4442 18 L<gate|/gate> - A L<logic gate|https://en.wikipedia.org/wiki/Logic_gate> chosen from B<and|continue|gt|input|lt|nand|nor|not|nxor|one|or|output|xor|zero>.
4443  
4444 19 L<inputBits|/inputBits> - Create an B<input> bus made of bits.
4445  
4446 20 L<inputWords|/inputWords> - Create an B<input> bus made of words.
4447  
4448 21 L<install|/install> - Install a L<chip|https://en.wikipedia.org/wiki/Integrated_circuit> within another L<chip|https://en.wikipedia.org/wiki/Integrated_circuit> specifying the connections between the inner and outer L<chip|https://en.wikipedia.org/wiki/Integrated_circuit>.
4449  
4450 22 L<integerToMonotoneMask|/integerToMonotoneMask> - Convert an integer B<i> of specified width to a monotone mask B<m>.
4451  
4452 23 L<integerToPointMask|/integerToPointMask> - Convert an integer B<i> of specified width to a point mask B<m>.
4453  
4454 24 L<monotoneMaskToInteger|/monotoneMaskToInteger> - Convert a monotone mask B<i> to an output number B<r> representing the location in the mask of the bit set to B<1>.
4455  
4456 25 L<monotoneMaskToPointMask|/monotoneMaskToPointMask> - Convert a monotone mask B<i> to a point mask B<o> representing the location in the mask of the first bit set to B<1>.
4457  
4458 26 L<n|/n> - Gate name from single index.
4459  
4460 27 L<nandBits|/nandBits> - B<nand> a bus made of bits.
4461  
4462 28 L<newChip|/newChip> - Create a new L<chip|https://en.wikipedia.org/wiki/Integrated_circuit>.
4463  
4464 29 L<nn|/nn> - Gate name from double index.
4465  
4466 30 L<norBits|/norBits> - B<nor> a bus made of bits.
4467  
4468 31 L<notBits|/notBits> - Create a B<not> bus made of bits.
4469  
4470 32 L<notWords|/notWords> - Create a B<not> bus made of words.
4471  
4472 33 L<orBits|/orBits> - B<or> a bus made of bits.
4473  
4474 34 L<orWords|/orWords> - B<or> a bus made of words to produce a single word.
4475  
4476 35 L<orWordsX|/orWordsX> - B<or> a bus made of words by or-ing the corresponding bits in each word to make a single word.
4477  
4478 36 L<outputBits|/outputBits> - Create an B<output> bus made of bits.
4479  
4480 37 L<outputWords|/outputWords> - Create an B<output> bus made of words.
4481  
4482 38 L<pointMaskToInteger|/pointMaskToInteger> - Convert a mask B<i> known to have at most a single bit on - also known as a B<point mask> - to an output number B<a> representing the location in the mask of the bit set to B<1>.
4483  
4484 39 L<print|/print> - Dump the L<logic gates|https://en.wikipedia.org/wiki/Logic_gate> present on a L<chip|https://en.wikipedia.org/wiki/Integrated_circuit>.
4485  
4486 40 L<printSvg|/printSvg> - Mask the L<logic gates|https://en.wikipedia.org/wiki/Logic_gate> onto a L<chip|https://en.wikipedia.org/wiki/Integrated_circuit> as an L<Scalar Vector Graphics|https://en.wikipedia.org/wiki/Scalable_Vector_Graphics> drawing to help visualize the structure of the L<chip|https://en.wikipedia.org/wiki/Integrated_circuit> using a condensed input bus.
4487  
4488 41 L<setBits|/setBits> - Set an array of input gates to a number prior to running a simulation.
4489  
4490 42 L<setSizeBits|/setSizeBits> - Set the size of a bits bus.
4491  
4492 43 L<setSizeWords|/setSizeWords> - Set the size of a bits bus.
4493  
4494 44 L<setWords|/setWords> - Set an array of arrays of gates to an array of numbers prior to running a simulation.
4495  
4496 45 L<Silicon::Chip::Layout::draw|/Silicon::Chip::Layout::draw> - Draw a mask for the gates.
4497  
4498 46 L<Silicon::Chip::Simulation::bInt|/Silicon::Chip::Simulation::bInt> - Represent the state of bits in the simulation results as an unsigned binary integer.
4499  
4500 47 L<Silicon::Chip::Simulation::print|/Silicon::Chip::Simulation::print> - Print simulation results as text.
4501  
4502 48 L<Silicon::Chip::Simulation::printSvg|/Silicon::Chip::Simulation::printSvg> - Print simulation results as svg.
4503  
4504 49 L<Silicon::Chip::Simulation::value|/Silicon::Chip::Simulation::value> - Get the value of a gate as seen in a simulation.
4505  
4506 50 L<Silicon::Chip::Simulation::wInt|/Silicon::Chip::Simulation::wInt> - Represent the state of words in the simulation results as an array of unsigned binary integer.
4507  
4508 51 L<Silicon::Chip::Simulation::wordXToInteger|/Silicon::Chip::Simulation::wordXToInteger> - Represent the state of words in the simulation results as an array of unsigned binary integer.
4509  
4510 52 L<simulate|/simulate> - Simulate the action of the L<logic gates|https://en.wikipedia.org/wiki/Logic_gate> on a L<chip|https://en.wikipedia.org/wiki/Integrated_circuit> for a given set of inputs until the output value of each L<logic gate|https://en.wikipedia.org/wiki/Logic_gate> stabilizes.
4511  
4512 53 L<words|/words> - Create a word bus set to specified numbers.
4513  
4514 =head1 Installation
4515  
4516 This module is written in 100% Pure Perl and, thus, it is easy to read,
4517 comprehend, use, modify and install via B<cpan>:
4518  
4519 sudo cpan install Silicon::Chip
4520  
4521 =head1 Author
4522  
4523 L<philiprbrenan@gmail.com|mailto:philiprbrenan@gmail.com>
4524  
4525 L<http://www.appaapps.com|http://www.appaapps.com>
4526  
4527 =head1 Copyright
4528  
4529 Copyright (c) 2016-2023 Philip R Brenan.
4530  
4531 This module is free software. It may be used, redistributed and/or modified
4532 under the same terms as Perl itself.
4533  
4534 =cut
4535  
4536  
4537  
4538 #D0 Tests # Tests and examples
4539 goto finish if caller; # Skip testing if we are being called as a module
4540 clearFolder(q(svg), 99); # Clear the output svg folder
4541 eval "use Test::More tests=>545";
4542 eval "Test::More->builder->output('/dev/null')" if -e q(/home/phil/);
4543 eval {goto latest};
4544  
4545 #svg https://raw.githubusercontent.com/philiprbrenan/SiliconChip/main/lib/Silicon/
4546  
4547 if (1) #Tn #Tnn
4548 {is_deeply( n(a,1), "a_1");
4549 is_deeply(nn(a,1,2), "a_1_2");
4550 }
4551  
4552 if (1) # Unused output
4553 {my $c = Silicon::Chip::newChip;
4554 $c->input( "i1");
4555 eval {$c->simulate({i1=>1})};
4556 ok($@ =~ m(Output from gate 'i1' is never used)i);
4557 }
4558  
4559 if (1) # Gate already specified
4560 {my $c = Silicon::Chip::newChip;
4561 $c->input("i1");
4562 eval {$c->input("i1")};
4563 ok($@ =~ m(Gate: 'i1' has already been specified));
4564 }
4565  
4566 #latest:;
4567 if (1) # Check all inputs have values
4568 {my $c = Silicon::Chip::newChip;
4569 $c->input ("i1");
4570 $c->input ("i2");
4571 $c->and ("and", [qw(i1 i2)]);
4572 $c->output("o", q(and));
4573 eval {$c->simulate({i1=>1, i22=>1})};
4574 ok($@ =~ m(No input value for input gate: i2)i);
4575 }
4576  
4577 #latest:;
4578 if (1) # Check each input to each gate receives output from another gate
4579 {my $c = Silicon::Chip::newChip;
4580 $c->input("i1");
4581 $c->input("i2");
4582 $c->and ("and1", [qw(i1 i2)]);
4583 $c->output( "o", q(an1));
4584 eval {$c->simulate({i1=>1, i2=>1})};
4585 ok($@ =~ m(No output driving input 'an1' on 'output' gate 'o')i);
4586 }
4587  
4588 #latest:;
4589 if (1) #Tzero
4590 {my $c = Silicon::Chip::newChip;
4591 $c->zero ("z");
4592 $c->output("o", "z");
4593 my $s = $c->simulate({}, svg=>q(svg/zero));
4594 is_deeply($s->steps, 2);
4595 is_deeply($s->value("o"), 0);
4596 }
4597  
4598 #latest:;
4599 if (1) #Tone
4600 {my $c = Silicon::Chip::newChip;
4601 $c->one ("o");
4602 $c->output("O", "o");
4603 my $s = $c->simulate({}, svg=>q(svg/one));
4604 is_deeply($s->steps , 2);
4605 is_deeply($s->value("O"), 1);
4606 }
4607  
4608 #latest:;
4609 if (1) #TnewChip
4610 {my $c = Silicon::Chip::newChip;
4611 $c->one ("one");
4612 $c->zero("zero");
4613 $c->or ("or", [qw(one zero)]);
4614 $c->and ("and", [qw(one zero)]);
4615 $c->output("o1", "or");
4616 $c->output("o2", "and");
4617 my $s = $c->simulate({}, svg=>q(svg/oneZero));
4618 is_deeply($s->steps , 3);
4619 is_deeply($s->value("o1"), 1);
4620 is_deeply($s->value("o2"), 0);
4621 }
4622  
4623 #latest:;
4624 if (1) #Tbits
4625 {my $N = 4;
4626 for my $i(0..2**$N-1)
4627 {my $c = Silicon::Chip::newChip;
4628 $c->bits ("c", $N, $i);
4629 $c->outputBits("o", "c");
4630 my $s = $c->simulate({}, $i == 3 ? (svg=>q(svg/bits)) : ());
4631 is_deeply($s->steps, 2);
4632 is_deeply($s->bInt("o"), $i);
4633 }
4634 }
4635  
4636 #latest:;
4637 if (1) #TnewChip # Single AND gate
4638 {my $c = Silicon::Chip::newChip;
4639 $c->input ("i1");
4640 $c->input ("i2");
4641 $c->and ("and1", [qw(i1 i2)]);
4642 $c->output("o", "and1");
4643 my $s = $c->simulate({i1=>1, i2=>1}, svg=>q(svg/and));
4644 ok($s->steps == 2);
4645 ok($s->value("and1") == 1);
4646 }
4647  
4648 #latest:;
4649 if (1) #TSilicon::Chip::Simulation::print #Tprint #TSilicon::Chip::Simulation::printSvg #TprintSvg
4650 {my $c = Silicon::Chip::newChip(title=>"And gate");
4651 $c->input ("i1");
4652 $c->input ("i2");
4653 $c->and ("and1", [qw(i1 i2)]);
4654 $c->output("o", "and1");
4655 my $s = $c->simulate({i1=>1, i2=>1});
4656  
4657 is_deeply($c->print, <<END);
4658 i1 : input i1
4659 i2 : input i2
4660 and1 : and i1 i2
4661 o : output and1
4662 END
4663  
4664 is_deeply($s->print, <<END);
4665 i1 : 1 input i1
4666 i2 : 1 input i2
4667 and1 : 1 and i1 i2
4668 o : 1 output and1
4669 END
4670  
4671 ok($s->printSvg ne $c->printSvg);
4672 }
4673  
4674 #latest:;
4675 if (1) # Three AND gates in a tree
4676 {my $c = Silicon::Chip::newChip;
4677 $c->input( "i11");
4678 $c->input( "i12");
4679 $c->and( "and1", [qw(i11 i12)]);
4680 $c->input( "i21");
4681 $c->input( "i22");
4682 $c->and( "and2", [qw(i21 i22)]);
4683 $c->and( "and", [qw(and1 and2)]);
4684 $c->output( "o", "and");
4685 my $s = $c->simulate({i11=>1, i12=>1, i21=>1, i22=>1}, svg=>q(svg/and3));
4686 ok($s->steps == 3);
4687 ok($s->value("and") == 1);
4688 $s = $c->simulate({i11=>1, i12=>0, i21=>1, i22=>1});
4689 ok($s->steps == 3);
4690 ok($s->value("and") == 0);
4691 }
4692  
4693 #latest:;
4694 if (1) #Tgate # Two AND gates driving an OR gate
4695 {my $c = newChip;
4696 $c->input ("i11");
4697 $c->input ("i12");
4698 $c->and ("and1", [qw(i11 i12)]);
4699 $c->input ("i21");
4700 $c->input ("i22");
4701 $c->and ("and2", [qw(i21 i22 )]);
4702 $c->or ("or", [qw(and1 and2)]);
4703 $c->output( "o", "or");
4704 my $s = $c->simulate({i11=>1, i12=>1, i21=>1, i22=>1}, svg=>q(svg/andOr));
4705 ok($s->steps == 3);
4706 ok($s->value("or") == 1);
4707 $s = $c->simulate({i11=>1, i12=>0, i21=>1, i22=>1});
4708 ok($s->steps == 3);
4709 ok($s->value("or") == 1);
4710 $s = $c->simulate({i11=>1, i12=>0, i21=>1, i22=>0});
4711 ok($s->steps == 3);
4712 ok($s->value("o") == 0);
4713 }
4714  
4715 #latest:;
4716 if (1) #Tsimulate # 4 bit equal #TnewChip
4717 {my $B = 4; # Number of bits
4718  
4719 my $c = Silicon::Chip::newChip(title=><<"END"); # Create chip
4720 $B Bit Equals
4721 END
4722 $c->input ("a$_") for 1..$B; # First number
4723 $c->input ("b$_") for 1..$B; # Second number
4724  
4725 $c->nxor ("e$_", "a$_", "b$_") for 1..$B; # Test each bit for equality
4726 $c->and ("and", {map{$_=>"e$_"} 1..$B}); # And tests together to get total equality
4727  
4728 $c->output("out", "and"); # Output gate
4729  
4730 my $s = $c->simulate({a1=>1, a2=>0, a3=>1, a4=>0, # Input gate values
4731 b1=>1, b2=>0, b3=>1, b4=>0},
4732 svg=>q(svg/Equals)); # Svg drawing of layout
4733  
4734 is_deeply($s->steps, 3); # Three steps
4735 is_deeply($s->value("out"), 1); # Out is 1 for equals
4736 is_deeply(substr(md5_hex(readFile $s->svg), 0, 4), '9ff8');
4737  
4738 my $t = $c->simulate({a1=>1, a2=>1, a3=>1, a4=>0,
4739 b1=>1, b2=>0, b3=>1, b4=>0});
4740 is_deeply($t->value("out"), 0); # Out is 0 for not equals
4741 }
4742  
4743 #latest:;
4744 if (1) #TsetBits # Compare two 4 bit unsigned integers 'a' > 'b' - the pins used to input 'a' must be alphabetically less than those used for 'b'
4745 {my $B = 4; # Number of bits
4746 my $c = Silicon::Chip::newChip(title=><<"END");
4747 $B Bit Compare
4748 END
4749 $c->inputBits("a", $B); # First number
4750 $c->inputBits("b", $B); # Second number
4751 $c->nxor (n(e,$_), n(a,$_), n(b,$_)) for 1..$B-1; # Test each bit for equality
4752 $c->gt (n(g,$_), n(a,$_), n(b,$_)) for 1..$B; # Test each bit pair for greater
4753  
4754 for my $b(2..$B)
4755 {$c->and(n(c,$b), [(map {n(e, $_)} 1..$b-1), n(g,$b)]); # Greater on one bit and all preceding bits are equal
4756 }
4757 $c->or ("or", [n(g,1), (map {n(c, $_)} 2..$B)]); # Any set bit indicates that 'a' is more than 'b'
4758 $c->output("out", "or"); # Output 1 if a > b else 0
4759  
4760 my %a = $c->setBits('a', 0); # Number a
4761 my %b = $c->setBits('b', 0); # Number b
4762  
4763 my $s = $c->simulate({%a, %b, n(a,2)=>1, n(b,2)=>1}, svg=>q(svg/equals)); # Two equal numbers
4764 is_deeply($s->value("out"), 0);
4765  
4766 my $t = $c->simulate({%a, %b, n(a,2)=>1});
4767 is_deeply($t->value("out"), 1);
4768 }
4769  
4770 #latest:;
4771 if (1) #TcompareEq # Compare unsigned integers
4772 {my $B = 2;
4773  
4774 my $c = Silicon::Chip::newChip(title=><<"END");
4775 $B Bit Compare Equal
4776 END
4777 $c->inputBits($_, $B) for qw(a b); # First and second numbers
4778 $c->compareEq(qw(o a b)); # Compare equals
4779 $c->output (qw(out o)); # Comparison result
4780  
4781 for my $i(0..2**$B-1) # Each possible number
4782 {for my $j(0..2**$B-1) # Each possible number
4783 {my %a = $c->setBits('a', $i); # Number a
4784 my %b = $c->setBits('b', $j); # Number b
4785  
4786 my $s = $c->simulate({%a, %b}, $i==1&&$j==1?(svg=>q(svg/CompareEq)):()); # Svg drawing of layout
4787  
4788 is_deeply($s->value("out"), $i == $j ? 1 : 0); # Equal
4789 is_deeply($s->steps, 3); # Number of steps to stability
4790 }
4791 }
4792 }
4793  
4794 #latest:;
4795 if (1) #TcompareGt # Compare 8 bit unsigned integers 'a' > 'b' - the pins used to input 'a' must be alphabetically less than those used for 'b'
4796 {my $B = 3;
4797 my $c = Silicon::Chip::newChip(title=><<END);
4798 $B Bit Compare more than
4799 END
4800 $c->inputBits($_, $B) for qw(a b); # First and second numbers
4801 $c->compareGt(qw(o a b)); # Compare more than
4802 $c->output (qw(out o)); # Comparison result
4803  
4804 for my $i(0..2**$B-1) # Each possible number
4805 {for my $j(0..2**$B-1) # Each possible number
4806 {#$i = 2; $j = 1;
4807 my %a = $c->setBits('a', $i); # Number a
4808 my %b = $c->setBits('b', $j); # Number b
4809  
4810 my $s = $c->simulate({%a, %b}, $i==2&&$j==1?(svg=>q(svg/CompareGt)):()); # Svg drawing of layout
4811 is_deeply($s->value("out"), $i > $j ? 1 : 0); # More than
4812 is_deeply($s->steps, 4); # Number of steps to stability
4813 }
4814 }
4815 }
4816  
4817 #latest:;
4818 if (1) #TcompareLt # Compare 8 bit unsigned integers 'a' < 'b' - the pins used to input 'a' must be alphabetically less than those used for 'b'
4819 {my $B = 3;
4820 my $c = Silicon::Chip::newChip(title=><<"END");
4821 $B Bit Compare Less Than
4822 END
4823 $c->inputBits($_, $B) for qw(a b); # First and second numbers
4824 $c->compareLt(qw(o a b)); # Compare less than
4825 $c->output (qw(out o)); # Comparison result
4826  
4827 for my $i(0..2**$B-1) # Each possible number
4828 {for my $j(0..2**$B-1) # Each possible number
4829 {my %a = $c->setBits('a', $i); # Number a
4830 my %b = $c->setBits('b', $j); # Number b
4831  
4832 my $s = $c->simulate({%a, %b}, $i==1&&$j==2?(svg=>q(svg/CompareLt)):()); # Svg drawing of layout
4833 is_deeply($s->value("out"), $i < $j ? 1 : 0); # More than
4834 is_deeply($s->steps, 4); # Number of steps to stability
4835 }
4836 }
4837 }
4838  
4839 #latest:;
4840 if (1) # Masked multiplexer: copy B bit word selected by mask from W possible locations
4841 {my $B = 4; my $W = 4;
4842 my $c = newChip;
4843 for my $w(1..$W) # Input words
4844 {$c->input("s$w"); # Selection mask
4845 for my $b(1..$B) # Bits of input word
4846 {$c->input("i$w$b");
4847 $c->and( "s$w$b", ["i$w$b", "s$w"]);
4848 }
4849 }
4850 for my $b(1..$B) # Or selected bits together to make output
4851 {$c->or ("c$b", [map {"s$b$_"} 1..$W]); # Combine the selected bits to make a word
4852 $c->output("o$b", "c$b"); # Output the word selected
4853 }
4854 my $s = $c->simulate(
4855 {s1 =>0, s2 =>0, s3 =>1, s4 =>0,
4856 i11=>0, i12=>0, i13=>0, i14=>1,
4857 i21=>0, i22=>0, i23=>1, i24=>0,
4858 i31=>0, i32=>1, i33=>0, i34=>0,
4859 i41=>1, i42=>0, i43=>0, i44=>0}, svg=>q(svg/maskedMultiplexor));
4860  
4861 is_deeply([@{$s->values}{qw(o1 o2 o3 o4)}], [qw(0 0 1 0)]); # Number selected by mask
4862 is_deeply($s->steps, 3);
4863 }
4864  
4865 #latest:;
4866 if (1) # Rename a gate
4867 {my $i = newChip(name=>"inner");
4868 $i->input ("i");
4869 my $n = $i->not ("n", "i");
4870 $i->output("io", "n");
4871  
4872 my $ci = cloneGate $i, $n;
4873 renameGate $i, $ci, "aaa";
4874 is_deeply($ci->inputs, { n => "i" });
4875 is_deeply($ci->output, "(aaa n)");
4876 is_deeply($ci->io, 0);
4877 }
4878  
4879 #latest:;
4880 if (1) #Tinstall #TconnectBits # Install one chip inside another chip, specifically one chip that performs NOT is installed once to flip a value
4881 {my $i = newChip(name=>"not");
4882 $i-> inputBits('i', 1);
4883 $i-> notBits(qw(n i));
4884 $i->outputBits(qw(o n));
4885  
4886 my $o = newChip(name=>"outer");
4887 $o->inputBits('i', 1); $o->outputBits(qw(n i));
4888 $o->inputBits('I', 1); $o->outputBits(qw(N I));
4889  
4890 my %i = connectBits($i, 'i', $o, 'n');
4891 my %o = connectBits($i, 'o', $o, 'I');
4892 $o->install($i, {%i}, {%o});
4893 my %d = $o->setBits('i', 1);
4894 my $s = $o->simulate({%d}, svg=>q(svg/notb1));
4895  
4896 is_deeply($s->steps, 2);
4897 is_deeply($s->values, {"(not 1 n_1)"=>0, "i_1"=>1, "N_1"=>0 });
4898 }
4899  
4900 #latest:;
4901 if (1) #TconnectWords # Install one chip inside another chip, specifically one chip that performs NOT is installed three times sequentially to flip a value
4902 {my $i = newChip(name=>"not");
4903 $i-> inputWords('i', 1, 1);
4904 $i-> notWords(qw(n i));
4905 $i->outputWords(qw(o n));
4906  
4907 my $o = newChip(name=>"outer");
4908 $o->inputWords('i', 1, 1); $o->output(nn('n', 1, 1), nn('i', 1, 1));
4909 $o->inputWords('I', 1, 1); $o->output(nn('N', 1, 1), nn('I', 1, 1));
4910  
4911 my %i = connectWords($i, 'i', $o, 'n', 1, 1);
4912 my %o = connectWords($i, 'o', $o, 'I', 1, 1);
4913 $o->install($i, {%i}, {%o});
4914 my %d = $o->setWords('i', 1);
4915 my $s = $o->simulate({%d}, svg=>q(svg/notw1));
4916  
4917 is_deeply($s->steps, 2);
4918 is_deeply($s->values, { "(not 1 n_1_1)" => 0, "i_1_1" => 1, "N_1_1" => 0 });
4919 }
4920  
4921 #latest:;
4922 if (1)
4923 {my $i = newChip(name=>"inner");
4924 $i->input ("Ii");
4925 $i->not ("In", "Ii");
4926 $i->output( "Io", "In");
4927  
4928 my $o = newChip(name=>"outer");
4929 $o->input ("Oi1");
4930 $o->output("Oo1", "Oi1");
4931 $o->input ("Oi2");
4932 $o->output("Oo2", "Oi2");
4933 $o->input ("Oi3");
4934 $o->output("Oo3", "Oi3");
4935 $o->input ("Oi4");
4936 $o->output("Oo", "Oi4");
4937  
4938 $o->install($i, {Ii=>"Oo1"}, {Io=>"Oi2"});
4939 $o->install($i, {Ii=>"Oo2"}, {Io=>"Oi3"});
4940 $o->install($i, {Ii=>"Oo3"}, {Io=>"Oi4"});
4941  
4942 my $s = $o->simulate({Oi1=>1}, svg=>q(svg/not3));
4943 is_deeply($s->value("Oo"), 0);
4944 is_deeply($s->steps, 4);
4945  
4946 my $t = $o->simulate({Oi1=>0});
4947 is_deeply($t->value("Oo"), 1);
4948 is_deeply($t->steps, 4);
4949 }
4950  
4951 #latest:;
4952 if (1) #TpointMaskToInteger
4953 {my $B = 4;
4954 my $N = 2**$B-1;
4955  
4956 my $c = Silicon::Chip::newChip(title=><<"END");
4957 $B bits point mask to integer
4958 END
4959 $c->inputBits (qw( i), $N); # Mask with no more than one bit on
4960 $c->pointMaskToInteger(qw(o i)); # Convert
4961 $c->outputBits (qw(out o)); # Mask with no more than one bit on
4962  
4963 for my $i(0..$N) # Each position of mask
4964 {my %i = setBits($c, 'i', $i ? 1<<($i-1) : 0); # Point in each position with zero representing no position
4965 my $s = $c->simulate(\%i, $i == 5 ? (svg=>q(svg/point)) : ());
4966 is_deeply($s->steps, 2);
4967 my %o = $s->values->%*; # Output bits
4968 my $n = eval join '', '0b', map {$o{n(o,$_)}} reverse 1..$B; # Output bits as number
4969 is_deeply($n, $i);
4970 }
4971 }
4972  
4973 #latest:;
4974 if (1) #TintegerToPointMask
4975 {my $B = 3;
4976 my $N = 2**$B-1;
4977  
4978 my $c = Silicon::Chip::newChip(title=><<"END");
4979 $B bit integer to $N bit monotone mask.
4980 END
4981 $c->inputBits (qw( i), $B); # Input bus
4982 $c->integerToPointMask(qw(m i));
4983 $c->outputBits (qw(o m));
4984 for my $i(0..$N) # Each position of mask
4985 {my %i = setBits($c, 'i', $i);
4986 my $s = $c->simulate(\%i, $i == 5 ? (svg=>q(svg/integerToPointMask)):());
4987 is_deeply($s->steps, 3);
4988  
4989 my $r = $s->bInt('o'); # Mask values
4990 is_deeply($r, $i ? 1<<($i-1) : 0); # Expected mask
4991 }
4992 }
4993  
4994 #latest:;
4995 if (1) #TmonotoneMaskToInteger
4996 {my $B = 4;
4997 my $N = 2**$B-1;
4998  
4999 my $c = Silicon::Chip::newChip(title=><<"END");
5000 $N bit monotone mask to $B bit integer
5001 END
5002 $c->inputBits ('i', $N);
5003 $c->monotoneMaskToInteger(qw(m i));
5004 $c->outputBits (qw(o m));
5005  
5006 for my $i(0..$N-1) # Each monotone mask
5007 {my %i = setBits($c, 'i', $i > 0 ? 1<<$i-1 : 0);
5008 my $s = $c->simulate(\%i,
5009 $i == 5 ? (svg=>q(svg/monotoneMaskToInteger)) : ());
5010  
5011 is_deeply($s->steps, 4);
5012 is_deeply($s->bInt('m'), $i);
5013 }
5014 }
5015  
5016 #latest:;
5017 if (1) #TintegerToMonotoneMask
5018 {my $B = 4;
5019 my $N = 2**$B-1;
5020  
5021 my $c = Silicon::Chip::newChip(title=><<"END");
5022 Convert $B bit integer to $N bit monotone mask
5023 END
5024 $c->inputBits ('i', $B); # Input gates
5025 $c->integerToMonotoneMask(qw(m i));
5026 $c->outputBits (qw(o m)); # Output gates
5027  
5028 for my $i(0..$N) # Each position of mask
5029 {my %i = setBits($c, 'i', $i); # The number to convert
5030 my $s = $c->simulate(\%i, $i == 2 ? (svg=>q(svg/integerToMontoneMask)):());
5031 is_deeply($s->steps, 4);
5032 is_deeply($s->bInt('o'), $i > 0 ? ((1<<$N)-1)>>($i-1)<<($i-1) : 0); # Expected mask
5033 }
5034 }
5035  
5036 #latest:;
5037 if (1) #TchooseWordUnderMask #TsetBits #TsetWords
5038 {my $B = 3; my $W = 4;
5039  
5040 my $c = Silicon::Chip::newChip(title=><<"END");
5041 Choose one of $W words of $B bits
5042 END
5043 $c->inputWords ('w', $W, $B);
5044 $c->inputBits ('m', $W);
5045 $c->chooseWordUnderMask(qw(W w m));
5046 $c->outputBits (qw(o W));
5047  
5048 my %i = setWords($c, 'w', 0b000, 0b001, 0b010, 0b0100);
5049 my %m = setBits ($c, 'm', 1<<2); # Choose the third word
5050  
5051 my $s = $c->simulate({%i, %m}, svg=>q(svg/choose));
5052  
5053 is_deeply($s->steps, 3);
5054 is_deeply($s->bInt('o'), 0b010);
5055 }
5056  
5057 #latest:;
5058 if (1) #TfindWord
5059 {my $B = 3; my $W = 2**$B-1;
5060  
5061 my $c = Silicon::Chip::newChip(title=><<END);
5062 Search $W words of $B bits
5063 END
5064 $c->inputBits ('k', $B); # Search key
5065 $c->inputWords('w', 2**$B-1, $B); # Words to search
5066 $c->findWord (qw(m k w)); # Find the word
5067 $c->outputBits(qw(M m)); # Output mask
5068  
5069 my %w = setWords($c, 'w', reverse 1..$W);
5070  
5071 for my $k(0..$W) # Each possible key
5072 {my %k = setBits($c, 'k', $k);
5073 my $s = $c->simulate({%k, %w}, $k == 3 ? (svg=>q(svg/findWord)) : ());
5074 is_deeply($s->steps, 3);
5075 is_deeply($s->bInt('M'),$k ? 2**($W-$k) : 0);
5076 }
5077 }
5078  
5079 #latest:;
5080 if (1) #TinputBits #ToutputBits #TnotBits #TSilicon::Chip::Simulation::bInt
5081 {my $W = 8;
5082 my $i = newChip(name=>"not");
5083 $i->inputBits('i', $W);
5084 $i->notBits (qw(n i));
5085 $i->outputBits(qw(o n));
5086  
5087 my $o = newChip(name=>"outer");
5088 $o->inputBits ('a', $W);
5089 $o->outputBits(qw(A a));
5090 $o->inputBits ('b', $W);
5091 $o->outputBits(qw(B b));
5092  
5093 my %i = connectBits($i, 'i', $o, 'A');
5094 my %o = connectBits($i, 'o', $o, 'b');
5095 $o->install($i, {%i}, {%o});
5096  
5097 my %d = setBits($o, 'a', 0b10110);
5098 my $s = $o->simulate({%d}, svg=>q(svg/not));
5099 is_deeply($s->bInt('B'), 0b11101001);
5100 }
5101  
5102 #latest:;
5103 if (1) #TandBits #TorBits #TnandBits #TnorBits
5104 {my $W = 8;
5105  
5106 my $c = newChip();
5107 $c-> inputBits('i', $W);
5108 $c-> andBits(qw(and i));
5109 $c-> orBits(qw(or i));
5110 $c-> nandBits(qw(nand i));
5111 $c-> norBits(qw(nor i));
5112 $c->output (qw(And and));
5113 $c->output (qw(Or or));
5114 $c->output (qw(nAnd nand));
5115 $c->output (qw(nOr nor));
5116  
5117 my %d = setBits($c, 'i', 0b10110);
5118 my $s = $c->simulate({%d}, svg=>q(svg/andOrBits));
5119  
5120 is_deeply($s->value("And"), 0);
5121 is_deeply($s->value("Or"), 1);
5122 is_deeply($s->value("nAnd"), 1);
5123 is_deeply($s->value("nOr"), 0);
5124 }
5125  
5126 #latest:;
5127 if (1) #TandWords #TandWordsX #TorWords #TorWordsX #ToutputBits #TnotWords
5128 {my @B = ((my $W = 4), (my $B = 2));
5129  
5130 my $c = newChip();
5131 $c->inputWords ('i', @B);
5132 $c->andWords (qw(and i));
5133 $c->andWordsX (qw(andX i));
5134 $c-> orWords (qw( or i));
5135 $c-> orWordsX (qw( orX i));
5136 $c->notWords (qw(n i));
5137 $c->outputBits (qw(And and));
5138 $c->outputBits (qw(AndX andX));
5139 $c->outputBits (qw(Or or));
5140 $c->outputBits (qw(OrX orX));
5141 $c->outputWords(qw(N n));
5142 my %d = setWords($c, 'i', 0b00, 0b01, 0b10, 0b11);
5143 my $s = $c->simulate({%d}, svg=>q(svg/andOrWords));
5144  
5145 is_deeply($s->bInt('And'), 0b1000);
5146 is_deeply($s->bInt('AndX'), 0b0000);
5147  
5148 is_deeply($s->bInt('Or'), 0b1110);
5149 is_deeply($s->bInt('OrX'), 0b11);
5150 is_deeply([$s->wInt('N')], [3, 2, 1, 0]);
5151 }
5152  
5153 #latest:;
5154 if (1) #TandWords #TorWords #TSilicon::Chip::Simulation::wordXToInteger #TSilicon::Chip::Simulation::wInt #TinputWords #ToutputWords
5155 {my @b = ((my $W = 4), (my $B = 3));
5156  
5157 my $c = newChip();
5158 $c->inputWords ('i', @b);
5159 $c->outputWords(qw(o i));
5160  
5161 my %d = setWords($c, 'i', 0b000, 0b001, 0b010, 0b011);
5162 my $s = $c->simulate({%d}, svg=>q(svg/words$W));
5163  
5164 is_deeply([$s->wInt('o')], [0..3]);
5165 is_deeply([$s->wordXToInteger('o')], [10, 12, 0]);
5166 }
5167  
5168 #latest:;
5169 if (1)
5170 {my $B = 4;
5171  
5172 my $c = newChip();
5173 $c->inputBits('i', 4);
5174 $c->not (n('n', 1), n('i', 2)); $c->output(n('o', 1), n('n', 1));
5175 $c->not (n('n', 2), n('i', 3)); $c->output(n('o', 2), n('n', 2));
5176 $c->not (n('n', 3), n('i', 4)); $c->output(n('o', 3), n('n', 3));
5177 $c->not (n('n', 4), n('i', 1)); $c->output(n('o', 4), n('n', 4));
5178  
5179 my %a = setBits($c, 'i', 0b0011);
5180  
5181 my $s = $c->simulate({%a}, svg=>q(svg/collapseLeftSimple));
5182 is_deeply($s->steps, 2);
5183 }
5184  
5185 #latest:;
5186 if (1) #TchooseFromTwoWords
5187 {my $B = 4;
5188  
5189 my $c = newChip();
5190 $c->inputBits('a', $B); # First word
5191 $c->inputBits('b', $B); # Second word
5192 $c->input ('c'); # Chooser
5193 $c->chooseFromTwoWords(qw(o a b c)); # Generate gates
5194 $c->outputBits('out', 'o'); # Result
5195  
5196 my %a = setBits($c, 'a', 0b0011);
5197 my %b = setBits($c, 'b', 0b1100);
5198  
5199 my $s = $c->simulate({%a, %b, c=>1}, svg=>q(svg/chooseFromTwoWords));
5200 is_deeply($s->steps, 4);
5201 is_deeply($s->bInt('out'), 0b1100);
5202  
5203 my $t = $c->simulate({%a, %b, c=>0});
5204 is_deeply($t->steps, 4);
5205 is_deeply($t->bInt('out'), 0b0011);
5206 }
5207  
5208 #latest:;
5209 if (1) #TenableWord
5210 {my $B = 4;
5211  
5212 my $c = newChip();
5213 $c->inputBits ('a', $B); # Word
5214 $c->input ('c'); # Choice bit
5215 $c->enableWord(qw(o a c)); # Generate gates
5216 $c->outputBits(qw(out o)); # Result
5217  
5218 my %a = setBits($c, 'a', 3);
5219  
5220 my $s = $c->simulate({%a, c=>1}, svg=>q(svg/enableWord));
5221 is_deeply($s->steps, 2);
5222 is_deeply($s->bInt('out'), 3);
5223  
5224 my $t = $c->simulate({%a, c=>0});
5225 is_deeply($t->steps, 2);
5226 is_deeply($t->bInt('out'), 0);
5227 }
5228  
5229 #latest:;
5230 if (1) #TmonotoneMaskToPointMask
5231 {my $B = 4;
5232  
5233 my $c = newChip();
5234 $c->inputBits('m', $B); # Monotone mask
5235 $c->monotoneMaskToPointMask(qw(o m)); # Generate gates
5236 $c->outputBits('out', 'o'); # Point mask
5237  
5238 for my $i(0..$B)
5239 {my %m = $c->setBits('m', eval '0b'.(1 x $i).('0' x ($B-$i)));
5240 my $s = $c->simulate({%m}, $i == 2 ? (svg=>q(svg/monotoneMaskToPointMask)) : ());
5241 is_deeply($s->steps, 2);
5242 is_deeply($s->bInt('out'), $i ? (1<<($B-1)) / (1<<($i-1)) : 0);
5243 }
5244 }
5245  
5246 #latest:;
5247 if (1) # Internal input gate #TconnectInput #TSilicon::Chip::Simulation::value
5248 {my $c = newChip();
5249 $c->input ('i'); # Input
5250 $c->input ('j'); # Internal input which we will connect to later
5251 $c->output(qw(o j)); # Output
5252  
5253 $c->connectInput(qw(j i));
5254  
5255 my $s = $c->simulate({i=>1}, svg=>q(svg/connectInput));
5256 is_deeply($s->steps, 1);
5257 is_deeply($s->value("j"), undef);
5258 is_deeply($s->value("o"), 1);
5259 }
5260  
5261 #latest:;
5262 if (1) #Twords # Internal input gate #TconnectInput #TSilicon::Chip::Simulation::value
5263 {my @n = qw(3 2 1 2 3);
5264 my $c = newChip();
5265 $c->words('i', 2, @n); # Input
5266 $c->outputWords(qw(o i)); # Output
5267 my $s = $c->simulate({}, svg=>q(svg/words));
5268 is_deeply($s->steps, 2);
5269 is_deeply([$s->wInt("i")], [@n]);
5270 }
5271  
5272 #latest:;
5273 if (1) #TsetSizeBits #TsetSizeWords
5274 {my $c = newChip();
5275 $c->setSizeBits ('i', 2);
5276 $c->setSizeWords('j', 3, 2);
5277 is_deeply($c->sizeBits, {i => 2, j_1 => 2, j_2 => 2, j_3 => 2});
5278 is_deeply($c->sizeWords, {j => [3, 2]});
5279 }
5280  
5281 #latest:;
5282 if (1) #TconnectInputBits
5283 {my $N = 5; my $B = 5;
5284 my $c = newChip();
5285 $c->bits ('a', $B, $N);
5286 $c->inputBits ('i', $N);
5287 $c->outputBits(qw(o i));
5288 $c->connectInputBits(qw(i a));
5289 my $s = $c->simulate({}, svg=>q(svg/connectInputBits));
5290 is_deeply($s->steps, 2);
5291 is_deeply($s->bInt("o"), $N);
5292 }
5293  
5294 #latest:;
5295 if (1) #TconnectInputWords
5296 {my $W = 6; my $B = 5;
5297 my $c = newChip();
5298 $c->words ('a', $B, 1..$W);
5299 $c->inputWords ('i', $W, $B);
5300 $c->outputWords(qw(o i));
5301 $c->connectInputWords(qw(i a));
5302 my $s = $c->simulate({}, svg=>q(svg/connectInputWords));
5303 is_deeply($s->steps, 2);
5304 is_deeply([$s->wInt("o")], [1..$W]);
5305 }
5306  
5307 #latest:;
5308 if (1) #TcanBothFitOnSameLine
5309 {is_deeply([firstLastOne "10"], [1,1]);
5310 is_deeply([firstLastOne "01010"], [2,4]);
5311 }
5312  
5313 #latest:;
5314 if (1) #TcanBothFitOnSameLine
5315 {is_deeply([layoutInputBus qw(1000 1100 0010 0001)], [1,2,1,1]);
5316 is_deeply([layoutInputBus qw(1100 1100 0011 0011)], [1,2,1,2]);
5317 is_deeply([layoutInputBus qw(11000 10100 01000 00011)], [1,2,3,1]);
5318 is_deeply([layoutInputBus qw(11000 10100 01000 00011 00010)], [1, 2, 3, 1, 2]);
5319 is_deeply([layoutInputBus qw(11000 10100 01000 00011 00010 00010)], [1, 2, 3, 1, 2, 3]);
5320 }
5321  
5322 #latest:;
5323 if (1) # Collapse left
5324 {my $c = Silicon::Chip::newChip;
5325 $c->input ('a');
5326 $c->input ( n('ia', $_)) for 1..8;
5327 $c->and ('aa', [map {n('ia', $_)} 1..8]);
5328 $c->output('oa', 'aa');
5329 $c->not ('n1', 'a'); $c->output('o1', 'n1');
5330 $c->input ( n('ib', $_)) for 1..8;
5331 $c->and ('ab', [map {n('ib', $_)} 1..8]);
5332 $c->output('ob', 'ab');
5333 $c->not ('n2', 'a'); $c->output('o2', 'n2');
5334 my %a = map {(n('ia', $_)=>1)} 1..8;
5335 my %b = map {(n('ib', $_)=>1)} 1..8;
5336 my $s = $c->simulate({%a, %b, a=>0}, svg=>q(svg/collapseLeft));
5337 is_deeply(substr(md5_hex(readFile $s->svg), 0, 4), q(850e));
5338 }
5339  
5340 done_testing();
5341 finish: 1;
↑ Summary