From be01ec55b2a2f7dd4d156283e254659d9433cfe9 Mon Sep 17 00:00:00 2001 From: TimRudy <3942818+TimRudy@users.noreply.github.com> Date: Tue, 29 Sep 2020 00:56:07 -0400 Subject: [PATCH] Update README.md and validation-scheme.md --- README.md | 224 ++++++++++++++++++++++++----- docs/validation-scheme.md | 190 ++++++++++++++++-------- images/TTL_chip_14pin.svg | 259 +++++++++++++++++++++++++++++++++ images/TTL_chip_16pin.svg | 265 ++++++++++++++++++++++++++++++++++ images/TTL_chip_24pin.svg | 292 +++++++++++++++++++++++++++++++++++++ images/proj_icon_a.svg | 294 ++++++++++++++++++++++++++++++++++++++ images/proj_icon_b.svg | 267 ++++++++++++++++++++++++++++++++++ images/proj_icon_c.svg | 261 +++++++++++++++++++++++++++++++++ 8 files changed, 1958 insertions(+), 94 deletions(-) create mode 100644 images/TTL_chip_14pin.svg create mode 100644 images/TTL_chip_16pin.svg create mode 100644 images/TTL_chip_24pin.svg create mode 100644 images/proj_icon_a.svg create mode 100644 images/proj_icon_b.svg create mode 100644 images/proj_icon_c.svg diff --git a/README.md b/README.md index 8e14a00..89e61d8 100644 --- a/README.md +++ b/README.md @@ -1,48 +1,93 @@ + + + +
+ # ice-chips-verilog [![Build Status][ico-travisci]][link-travisci] -[topdesc]: #desc -I'm focusing on the 74xx family: devices that were TTL originally (bipolar technologies such as LS, AS), that are now implemented as CMOS (HC, HCT, LV or many other technology variations) +The 74LS, 74HC, 74HCT family of chips in Verilog for Electronic Design Automation + + Fully validated by test bench · Parametrized code · DELAY parameters for timing simulation + +IceChips is built to support the [Icestudio][link-icestudio] and [FPGAwars][link-fpgawars] manifesto: + + + +## Getting Started + +The easiest way to use these devices is [download the collection](/releases/latest) and open it in the Icestudio design environment. + +In Icestudio, go to `Tools > Collections > Add` and select the downloaded .zip file. Place and wire up your components, run and test the result. There's a variety of ways to provide inputs and view outputs; but no need for actual parts, wires or power supply. + +Alternatively, you can download an individual device (.v file) and use it in your own simulation in Verilog. This is the way to go if you wish to set the parameters for #bits, #inputs per gate, #blocks in a device. See the Index to browse devices. + +## Index + +  [Devices by type and name](device-index.md) + +#### What are the 7400-series TTL chips? + +  They are digital logic: Gates, multiplexers, counters, registers, adders, multipliers and more + +  [7400-series integrated circuits (Wikipedia)][link-wiki-7400] + +## Icestudio Design Flow + +Welcome to virtual breadboarding. -#### Index -> [Devices by type and name](device-index.md) +Icestudio provides circuit simulation (for digital circuits) that's arbitrarily scalable. Explore, build and create, but most importantly, get near-instant feedback in testing your real hardware design. Each time you add a new input or a gate, hit "Build" and "Upload". In the parlance of a silicon fab, you've gone through a "spin". But you're actually programming a reusable and fairly inexpensive FPGA. -#### Who -> Hobbyist who wants to program an FPGA, or do general digital circuit simulation, and wants to do it from already-proven building blocks + CAD-style layout using drag and drop + -> Full Verilog model + -> Validation of design rules & connectivity + -> Synthesis of circuit + -> Bitstream to FPGA + -> Live circuit to test or put in-situ -#### What -> Basic logic such as gates, registers, multiplexers, counters, adders, but also non-retriggerable monostable multivibrators +It's done with entirely open source tools (the IceStorm toolchain); and most of the magic is due to the representation in Hardware Description Language, i.e. Verilog, because HDL is translatable to H: -#### Why -> I noticed the [74xx chips][link-wiki7400] do not exist in one place as an open-source catalogue in Verilog (or in VHDL to my knowledge). To see them and create a simulation with them, you would need to open up Xilinx Vivado or ISE or the Intel/Altera Quartus IDE. You can find free [simulators and digital playgrounds][link-websim], but what to type into them? You'll need [IceChips](source-7400). +- Once you have a system fully modelled in HDL, you have everything. The HDL is used to generate hardware in any way you require, in a process called [logic synthesis][link-wiki-synth] -...Of course you could just buy a breadboard and the ICs. But that's going by different logic. +- The toolchain can synthesize the circuit onto an expanding selection of FPGAs; see [Icestudio][link-icestudio] for details - +- What's cool about the Icestudio graphical editing, with internal Verilog, is the hierarchy, encapsulation and layering that it makes easy and explicit; this promotes compositional design; it means scalability and testability -## What to Expect +## Tests and Validation -* Each device validated by test bench -* Implemented formally: A single Input/Output/Code template; industry pin names; consistent Verilog -* Fully parametrized (so you could pretend that a quad or a hex buffer/line driver is actually 64 bits for your FPGA design; you could turn a triple 3-input NAND gate - the workhorse [7410](source-7400/7410.v) - into a heptal 5-input NAND gate just by plugging in the two numbers) +A test bench accompanies every device (74xx-tb.v file with 74xx.v file) and the tests are run automatically. Click on the “tests|passed” icon near the top of the page to see the log of the validation run. -> Coming soon in 2019: As you see, the sequential devices are being worked on (counters etc.), with tri-state capability being worked on as we speak. +Tests are a definitive feature of this library. They must be: -> Please contact me if you have a request (and the device number is less than about 74699!) +1. Comprehensive +2. Meaningful (each test adding value) +3. Annotated with descriptions +4. Pass/Fail when run -## Purpose +The tests are for documentation and transparency and create a kind of audit trail - that's in addition to their role in correctness! -Using one module per logic device (in other words: encapsulated Verilog) promotes compositional design and bottom-up design so that hopefully large logic blocks/cores (from a crypto accelerator, or a [coin mining][link-coinmining] FPGA, to a CPU?) can be created if you validate and spec out each module, step by step. All you need to do is wire the modules together! +The tests are actively Pass/Fail, because they "assert" and they log a failure message if the stated condition is not met. They are not just doing a demonstration run of the device, with a waveform output. See more details in the Validation Contract and in the project code. -> Stay tuned because exciting things will happen once the library is built out more! +Coverage will continue at the highest standard as the library expands going forward. -## Usage -[usage]: #usage +You have to "trust but verify" when scaling up a hardware design from lower-layer components. -The test benches can be run using the open-source simulator Icarus Verilog: [Installation][link-iverilogi], [Getting Started][link-iverilogs]. +#### Validation Contract -With it installed on your system you can run a command like the following that specifies the required input files and one output file (.vvp): +The stamp of approval comes from the test bench code, but more is involved: Scripts and templates generate the code files of IceChips, and also ensure they are validated reliably and completely. + +  [Validation scheme](docs/validation-scheme.md) · How the the code files and .ice components are validated + +#### Running the tests on your machine + +
+Details +
+ +The test benches can be run using the open source simulator Icarus Verilog: [Installation][link-iverilogi], [Getting Started][link-iverilogs]. + +With it installed, you can run a command like the following that specifies the required input files and one output file (.vvp): ``` > iverilog -g2012 -o 7400-tb.vvp ../includes/helper.v ../includes/tbhelper.v 7400-tb.v 7400.v ``` @@ -52,29 +97,138 @@ It then requires a second step: Run the Icarus Verilog simulator/runtime to see > vvp 7400-tb.vvp ``` -If you're interested in looking even closer, the above vvp run stores signal and timing data of all the inputs, outputs, and the connection paths in the .vcd file, so run GTKWave viewer to see it all as a waveform: [Installation][link-gtkwavei], [Getting Started][link-gtkwaves]. +If you're interested in looking even closer, the above "vvp" run stores all signal and timing data - inputs, outputs, and the connection paths between them - in a .vcd file, so run GTKWave viewer to see the run as a waveform: [Installation][link-gtkwavei], [Getting Started][link-gtkwaves]. With GTKWave installed, just click on the .vcd file to open. +
+ +## Technical Notes + +  [Implementation info, quirks, challenges in the technology, usage notes, and some bibliographic and specialty interest links](docs/technical-notes.md) + +## Other Resources for your Digital Project + +To brush up on digital logic design, or get started with an EDA flow to create, test out and tape-out your project: + +
+Topics to get started +
+ +- [Combinational Circuit versus Sequential Circuit][link-web-comb-seq] +- [RTL Description][link-web-rtl] · Register Transfer Level Description +- [HDLs][link-web-hdls] · Hardware Description Languages +- [Logic Simulation][link-web-logic-sim] +- [Logic Synthesis][link-web-logic-synth] +- [Logic Friday (Program)][link-web-logic-friday] +- [Espresso Logic Minimizer (Program)][link-web-esp-logic-min] +- [EDA][link-web-eda] · Electronic Design Automation +- [FPGAs][link-web-fpgas] · Field-Programmable Gate Arrays + +
+
+ +Clarification about this design flow versus PCB (Printed Circuit Board) flow: + +
+PCB design flow +
+ +Simulating and testing your design can put you in a position to populate your components onto a custom PCB (Printed Circuit Board) to be manufactured. + +You have a head start because you have a digital circuit that you know meets all its specs. + +However, it's a different workflow area that you'll have to get into for a PCB: A different type of visual editing ("schematic capture"); placing, routing and design of layout for manufacture; verification of design rules - this time for geometric/electrical properties - for manufacture. + +Note: Having said that, using 74xx standard parts will set you up well for using PCB software, since the parts are well-known and modelled for geometric/electrical properties. + +The following keywords are related to PCBs and are **not** part of the present workflow: + +- Ngspice +- SPICE +- Eagle +- Gerber format +- Most software programs that have CAD in them (KiCAD) and the ones that have PCB in them (LibrePCB) +- gEDA suite (for the most part) + +
+ +## This project gains inspiration from + +[www.homebrewcpuring.org][link-homebrew] · Amazing Homebrew CPUs + +[Hackaday Homebrew CPU projects][link-hackbrew] · More Homebrew CPUs + +[FPGAwars list of projects][link-fpgawarsp] developed with Open Source FPGAs, including CPUs + ## Acknowledgments -Coming soon. +Juan González-Gómez [@Obijuan], Jesús Arroyo Torrens, Salvador E. Tropea, Democrito · for Icestudio collections + +Warren Toomey [@DoctorWkt] · for inspiration because he builds real CPUs, and for using early versions of these devices + +Eddie Hung [@FPGeh] · for Yosys advice and feedback + +[digitaljs.tilk.eu](http://digitaljs.tilk.eu) Marek Materzok [@tilk] · for helpful feedback and has an amazing convenient simulator "DigitalJS Online" + +[www.edaboard.com](https://www.edaboard.com/threads/two-dimensional-input-output-ports-in-verilog.208692) "mrflibble" · provided solution for 2-dimensional inputs to a module + +["Inside the vintage 74181 ALU chip"](http://www.righto.com/2017/03/inside-vintage-74181-alu-chip-how-it.html) Ken Shirriff · invaluable info on the 74181 and a fabulous simulator in the browser + +Marcus Lindholm · SVG graphic design help + +[www.msarnoff.org/chipdb](http://www.msarnoff.org/chipdb/list) Matt Sarnoff · chip and pin info + +["TTL_74xx_DIL.m4"](https://fossies.org/linux/pcb/lib/TTL_74xx_DIL.m4) Thomas Nau, "diplib" in PCB for Linux distribution · chip and pin info + +[www.referencedesigner.com/tutorials](http://www.referencedesigner.com/tutorials/verilog/verilog_01.php) · practical intro to Verilog with examples, tutorials, quizzes + +[www.doulos.com/knowhow](https://www.doulos.com/knowhow/verilog_designers_guide/sequential_always_blocks) · practical intro to design and concepts in Verilog + +[www.verilogpro.com](https://www.verilogpro.com/verilog-generate-configurable-rtl) · practical intro to generate loops and elaboration + +#### And to these supporting pieces of technology: + +[Icestudio][link-icestudio] and Apio built on top of IceStorm, Yosys, Arachne-pnr + +[Yosys][link-yosys] synthesis by Clifford Wolf + +[Icarus Verilog][link-iverilog] simulator by Stephen Williams + +[GTKWave][link-gtkwavei] for viewing waveforms ## © 2018-2020 Tim Rudy -[ico-license]: https://img.shields.io/badge/license-GPL--3.0%2B-blue.svg -[ico-language]: https://img.shields.io/badge/Verilog-100%25-orange.svg [ico-travisci]: images/passed.svg -[link-travisci]: https://travis-ci.org/TimRudy/ice-chips-verilog -[link-wiki7400]: https://en.wikipedia.org/wiki/List_of_7400_series_integrated_circuits -[link-websim]: https://www.google.com/search?q=free+web+verilog+editor+simulator +[link-travisci]: https://travis-ci.com/TimRudy/ice-chips-verilog "See the latest build and test report" +[link-icestudio]: https://icestudio.io +[link-icestudiob]: https://github.com/FPGAwars/icestudio-blocks/wiki +[link-openfpgat]: https://github.com/Obijuan/open-fpga-verilog-tutorial/wiki +[link-fpgawars]: https://fpgawars.github.io +[link-fpgawarsp]: https://fpgawars.github.io/#projects +[link-wiki-7400]: https://en.wikipedia.org/wiki/List_of_7400_series_integrated_circuits +[link-wiki-synth]: https://en.wikipedia.org/wiki/Logic_synthesis +[link-web-comb-seq]: https://www.google.com/search?q=Combinational+versus+Sequential+Circuit +[link-web-rtl]: https://www.google.com/search?q=RTL+Description +[link-web-logic-sim]: https://www.google.com/search?q=Logic+Simulation+in+HDL +[link-web-logic-synth]: https://www.google.com/search?q=Logic+Synthesis +[link-web-logic-friday]: https://www.google.com/search?q=Logic+Friday +[link-web-esp-logic-min]: https://www.google.com/search?q=Espresso+Logic+Minimizer +[link-web-hdls]: https://www.google.com/search?q=Hardware+Description+Languages +[link-web-eda]: https://www.google.com/search?q=Electronic+Design+Automation +[link-web-fpgas]: https://www.google.com/search?q=Field-Programmable+Gate+Arrays [link-coinmining]: http://whattomine.com -[link-iverilogi]: http://iverilog.wikia.com/wiki/Installation_Guide -[link-iverilogs]: http://iverilog.wikia.com/wiki/Getting_Started +[link-homebrew]: https://www.homebrewcpuring.org/ringhome.html +[link-hackbrew]: https://hackaday.io/list/25846-homebrew-cpu +[link-yosys]: http://www.clifford.at/yosys +[link-iverilog]: http://iverilog.icarus.com +[link-iverilogi]: https://iverilog.fandom.com/wiki/Installation_Guide +[link-iverilogs]: https://iverilog.fandom.com/wiki/Getting_Started +[link-iverilogu]: https://iverilog.fandom.com/wiki/User_Guide [link-gtkwavei]: http://gtkwave.sourceforge.net -[link-gtkwaves]: http://iverilog.wikia.com/wiki/GTKWAVE +[link-gtkwaves]: https://iverilog.fandom.com/wiki/GTKWAVE diff --git a/docs/validation-scheme.md b/docs/validation-scheme.md index 7af03ca..cf0e68d 100644 --- a/docs/validation-scheme.md +++ b/docs/validation-scheme.md @@ -1,16 +1,65 @@ ## The Validation Contract -[top-intro]: #desc -Validation means running the code here on the GitHub site through the program "iverilog" to test it; and that's only done once, if and when the code changes. +Test benches are provided to give complete confidence in the published code. This note, however, will explain how the test bench stamp of approval translates into an overall site guarantee. It's a discussion of the site infrastructure for providing structured code, code that is validated reliably and completely. -The .ice file that you download and use in Icestudio, however, is indirectly tested; its working code is shared in common with the .v file, but some parts of the code are not in common, as you see in the file comparison below. +A main question is how the .ice component file that you download and use in Icestudio is tested (with a guarantee), when it is the .v file source code published here that is explicitly run through a test. You would say the .ice file is tested indirectly. So is there a role for human error in all this? Hint: Read on, Macduff. + +
+Outline +
+ +  [Problem Statement](#problem-statement) + +  [Requirements](#requirements) · problem goes away if 3 requirements are met + +  [Solution](#solution) · an Automation script + +  [Verilog Structure](#verilog-structure) · examining the .v and .ice code -> statement of no essential differences between them + +  [Proof is in the Outputting](#proof-is-in-the-outputting) + +    [File content and structure](#file-content-and-structure) · how the two files are the same and the abstractions they are based on + +    [Code-generation script](#code-generation-script) · what the Automation script does exactly + +  [The Contract](#the-contract) + +    [Preamble](#preamble) · Automation is actually one unit of work, with two artifacts (files) as output + +    [Statement](#statement) · Validation applies equally to all published file versions + +    [Coda](#coda) · list of 4 assumptions and questions, with affirmative answers + +  [Appendices](#appendices) + +    [Notes and details about generated code structure](#notes-and-details-about-generated-code-structure) + +    [What is a good test bench?](#what-is-a-good-test-bench) · goal, policy & guidelines + +
+ +### Problem Statement + +Validation means running the code here on the GitHub site through the program "iverilog" to test it; this happens once, if and when the code changes. + +The validation step runs the Device Under Test (DUT), the 74xx.v file, with its test bench the 74xx-tb.v file. + +The .ice file (component within the Icestudio collection) is seen on the right-hand side in this example comparison. Note its working code is shared in common with the .v file - which if there's one thing I'd like you to take away from this today, is the thing to remember; and then other parts of the code are not in common - which is a problem statement. + +**7485.v file (left) compared to the Verilog code in 7485_Comparator.ice (right):** + + +
+
I can guarantee you the .ice component is signed off, verified and validated. -How? Well, the validation step runs the Device Under Test (DUT), the 74xx.v file, with its test bench the 74xx-tb.v file. So for the .ice component, validation relies on three specifics: +How? ### Requirements +Well, from the .ice file point of view, validation relies on three specifics: + 1. It relies on the fact that between the .v file and the .ice file, the Verilog working code is an identical copy. This you can see for yourself if you open and compare each .v and .ice file pair. @@ -19,31 +68,31 @@ How? Well, the validation step runs the Device Under Test (DUT), the 74xx.v file This second criterion is deeply important since we are talking about validation. It addresses some questions: - - Could you be seeing a good old copy-pasting job if you open and compare the files to check them? + - Are you looking at a good copy-pasting job if you open and compare the files to check them? - Worse - Could the code in a file be tweaked? Could code that **was at one time** identical be, temporarily, not identical awaiting the next proper release?! ..."There was a slight issue and we are working on it." No. There won't be errors and shoddy handling. It's not going to happen. -3. It relies on the same kind of guarantee that no error can be introduced in the extra, non-shared code, which is a mapping layer between the .v and .ice file pair. +3. It relies on the same kind of guarantee that no error can be introduced in the extra, non-shared code (i.e. header and footer), which is a mapping layer between the .v and .ice file pair. - Same comment as above. + Same comment: No. There won't be any errors. ### Solution -A site-level or "infrastructure" guarantee takes care of the two files sharing their code, and this is the Automation feature of IceChips. It generates and concatenates Verilog, including the "write-once" portion supplied by human input, and publishes the files. You'll be hearing more about it. +A site-level or "infrastructure" guarantee takes care of the two files sharing their code, and this is the Automation feature of IceChips. It generates and concatenates Verilog, including the "write-once" portion supplied by human input, and publishes the files. All three requirements are met by the code-generation script. -As to what is happening for a typical pair of files, let's take a look. +The diff of the 7485 files represents a typical pair of files. The next section goes through details and explanation, with reference to Verilog. (You know or you're learning Verilog, right?) If you don't have time, skip ahead. In the following section, Proof, we'll come back to code-generation and tie it to the Validation Contract for this project. ### Verilog Structure -Compare the 7485.v file (left) to the Verilog code inside 7485_Comparator.ice (right): - - +Here is a run-down of the relationship of the two sides; how the Verilog you see comprises four sections; and how the high-level structure of four sections is always the same, in fact, for any IceChips device. -Here's the context of these two pieces of code, for a quick recap: +
+Side-by-side +
-#### Side-by-side +The context of the two pieces of code, for a quick recap: - **The left-hand side** is a **module**. That's the basic unit of packaging up Verilog, and the basic unit of hierarchy in a Verilog design or circuit schematic (also referred to as a component or device). A module can be composed of nested modules; a module can have parameters (see top line) that allow for reuse of the same code in a different use case, such as instantiating it with a different number of bits. @@ -61,43 +110,58 @@ Here's the context of these two pieces of code, for a quick recap: This is Verilog without the module wrapper; all redundancy is removed for user convenience; but Icestudio wraps this code in a module internally. - On the right-hand side a central concern is to group related pins of the component into vectors (see the assign lines). "A" and "B" are the vectors; the other variables are single pins/single bits. + On the right-hand side, a central concern is to group related pins of the component into vectors (see the assign lines). "A" and "B" are the vectors; the other variables are single pins/single bits. -#### Top-to-bottom +
+
-I was thinking the identical section would stand out the most in this code diff. It's supposed to; but the non-identical sections seem to catch the eye. Anyway, the really important thing is not apparent from looking at only one example... that the high-level structure of the Verilog in IceChips is **always the same** and it's of this form: +
+Top-to-bottom +
-- First, the declaration of the interface (I/O list) - Parameters are included as a prerequisite +I was thinking the identical section would stand out the most in the code diff. It's supposed to; but the non-identical sections seem to catch the eye. Anyway, the important thing that is not apparent from only looking at one example... is that the high-level structure of the Verilog in IceChips is **always the same** and it's of this form: -- Second, the required variables - These comprise all the computed results; other ones may be present to track intermediates +- First, the declaration of the interface (I/O list) - Parameters are included as a prerequisite; -- Third, the actual "procedural" Verilog code, the portion that implements the functionality and is written by the developer - Horizontal dividers in the .v file delineate where this code was inserted by human intervention +- Second, the required variables - These comprise all the computed results; other ones may be present to track intermediates; -- Fourth, assignments - These connect the inside (Verilog program code) to the outside by wiring to the ports of the interface +- Third, the actual "procedural" Verilog code, the portion that implements the functionality and is written by the developer - Horizontal dividers in the .v file delineate where this code was inserted by human intervention; -The take-away? +- Fourth, assignments - These connect the inside (Verilog program code) to the outside by wiring to the ports of the interface. -All the highlighted lines - the first and fourth segments, that is - are just plumbing code. They're declarative: the code constitutes variable and wire declarations, then wire connections. All of this deals specifically with the I/Os; the I/Os are pre-determined elements; so, the bottom line is this code is all amenable to auto-generation. +(As a side note, if one enumerates sub-sections also, to take a more fine-grained view of the above, then the structure of the Verilog is still always the same for every IceChips device. Consistent ordering schemes ensure this. There are 3 sub-sections within the first section; being parameters, inputs, then outputs. There are 2 sub-sections within the second section, being output results variables and other, intermediate variables. There are 2 sub-sections within the fourth section, being always the inputs followed by the outputs. That is 8 total.) -Skip ahead to next section where the topic of auto-generation is tied back to validation, and trust, and integrity. +
+
-#### The essential differences? +
+The essential differences +
-There is a satisfying regularity to the lines that are different, and the segments of code are all "structurally identical" if you know the prescribed purpose of each line. +The segments of code, side-by-side, are all "structurally identical". One can see how, if one knows the prescribed purpose of each line. -Take a look again at the diff. +Refer again to the diff. -5 wires on the right-hand side (RHS) put in an appearance - but they replicate the 5 inputs on the LHS. Each of these 5 declaration lines then gets an assign statement at the bottom; 10 lines of extra code on RHS; these recreate the "input" line semantics of the LHS - structurally identical, bringing in the same amount of data, but with the noticeable incorporation of named individual pins that are part of the .ice component. +5 wires on the right-hand side (RHS) put in an appearance - but they replicate the 5 inputs on the LHS. Each of these 5 declaration lines then gets an assign statement at the bottom; 10 lines of extra code on RHS; these recreate the "input" line semantics of the LHS. It is structurally identical, bringing in the same amount of data, but the noticeable difference in detail on the RHS is incorporating named individual pins that are part of the .ice component. For the 3 outputs on the LHS, replication like the above is not needed. The 3 assign statements for outputs match up on both sides, just with named pins on the RHS; they're in place of the "output" line variables on the LHS. -In other words, there are no essential differences. (I give some more details [later on this page](#struct-detail) that explain the "DELAY" parameters if you are curious.) +
+
+ +The take-away from the top-to-bottom view? + +All the highlighted lines - the first and fourth segments, that is - are just plumbing code. They're declarative: the code constitutes variable and wire declarations, then wire connections. All of this deals specifically with the I/Os of the device; the I/O list is pre-determined; so the take-away is this code is all amenable to auto-generation. + +The take-away from the essential differences? + +There are no essential differences. (I give more details [later on this page](#notes-and-details-about-generated-code-structure) that explain the "DELAY" parameters if you are curious.) ### Proof is in the Outputting The concluding point is that Automation, which is code-generation, creates these files. -A template or skeleton is created, with the I/O definitions and wiring making up a header and footer, as you see above in the example. Logic code that forms the guts of the file is added. +A template or skeleton is created. I/O definitions make up a header, and wiring makes up a footer, essentially, as seen in the example 7485. Logic code forms the guts of the file. #### File content and structure: @@ -105,25 +169,27 @@ A template or skeleton is created, with the I/O definitions and wiring making up - The non-identical segments are declarative code only, constituting wrappers; -- The wrappers are basically wiring; for example, one wiring function is to collate scalar elements into vectors; on the LHS, vectors are part of the abstraction and are implicit - on the RHS vectors are constructed: the abstract from the concrete; +- The wrappers are basically wiring; for example, one wiring function is to collate scalar elements into vectors. On the LHS, vectors are part of the abstraction and are implicit - on the RHS, vectors are constructed: the abstract from the concrete; - Abstractions are used in the logic code; they're what makes the code identical. #### Code-generation script: -- Starts with metadata which gives the "form-factor" of a device; that is, the names and the ordering of its input and output ports; +- Starts with metadata which gives the "form-factor" of a device; that is, the names and ordering of its input and output ports; - Provides the rolling up of pins such as "{... pin12_A1, pin10_A0}" to a vector "A"; - Generates skeleton .v and .ice files; -- Clones the common code block, written by human developer, from .v file to .ice file thus completing the files. +- Clones the common code block, written by human developer, from .v file to .ice file, thus completing the files. + +I've not yet published the "generate" script. You'll be hearing more about it, to be mentioned on the Wiki. -The Automation code is a "generate" script (that I've not yet published). +Think of the simulated Integrated Circuit like an Integrated Circuit: The header and footer of the file, the code-generated part, is like the DIP package with the complement of metal pins - it provides a given form-factor. The logic code put in the file is like the silicon chip, fresh from the fab line, that's dropped in and bonded inside. -Think of the simulated Integrated Circuit like an Integrated Circuit: The header and footer of the file, the code-generated part, is like a DIP package with metal pins - it provides a given form-factor. The logic code put in the file is like the silicon chip, fresh from the fab line, that's dropped in and bonded inside. +### The Contract -#### Contract: +#### Preamble: The responsibility to physically handle and publish the files is built into IceChips Automation. @@ -131,65 +197,71 @@ The responsibility to physically handle and publish the files is built into IceC - The creation of those files is, in fact, one logical unit of work - there happen to be two artifacts coming out. -It's a basis for the contract: +That's the basis for the contract: The Automation handles the .ice file "essential commonality" to its counterpart, and lends repeatability and a closed-ended nature to the process of validation. + +#### Statement: - Every device published in the library is validated by test bench, and the validation applies equally to both .v and .ice versions of the device. This completes the "steps in the proof" that your .ice device has been validated. -#### What about? +#### Coda: There are some implicit aspects, some real-world assumptions that require comment: -1. **Validation step is performed.** Yes, the Verilog is run using ["iverilog"][link-iverilogu], to get a Pass or Fail from each test bench. This is a separate part of Automation. It's tied in with publishing to GitHub using Travis CI. Observe there is a [![Build Status][ico-travisci]][link-travisci] badge near the main title of the README, and you can click on it to see Travis CI's results of the validation run. +1. **Validation step is performed.** Yes, the Verilog is run using ["iverilog"][link-iverilogu], getting a Pass or Fail from each test bench. This is a separate part of Automation. It's tied in with publishing to GitHub using Travis CI. Observe there is a [![Build Status][ico-travisci]][link-travisci] badge near the main title of the README, and you can click on it to see Travis CI's results of the validation run. For those interested in the technicals about this, look in the [scripts folder](/scripts/validate "scripts and validate folders"), and see [package.json](/scripts/package.json "package.json") which includes the entry point "npm test". 2. **There is a test bench.** The extremely skeptical and the subversives need to know: the validation step when publishing to GitHub requires a test bench paired with each device file, by automated check, not just by policy; so there will never be a device published without its test bench being completed. -3. **The test bench could be bogus?** This gets a bit personal; but you can refer to the community for community review of test benches, because they are all published. I provide [my perspective on tests below](#test-bench-desc). +3. **The test bench could be bogus?** This gets a bit personal; but you can refer to the community for community review of test benches, because they are all published. I provide [my perspective on tests below](#what-is-a-good-test-bench). -4. **Automation script exists.** The IceChips "generate" script needs to be published with the library for community review, as a pillar of the claims leading to the validation contract. True. We are working on this. (There was just a little issue: The code is ugly and needs to be cleaned up.) +4. **Automation script exists.** The IceChips "generate" script needs to be published with the library for community review, as a pillar of the claims leading to the Validation Contract. True. We are working on this. (There was just a little issue: The code is ugly and needs to be cleaned up.) ## - -### Notes and details about generated code structure +### Appendices + +#### Notes and details about generated code structure -For the "DELAY" parameters seen in the example, just a quick note that these are declared on the left-hand side only, and they are present in the output assignments, because the primary purpose of the LHS, the module, is to run simulations and tests. The parameters affect the time domain, the response time of a simulated circuit element, so they're useful and can be very important to model a real-world circuit. (Think of a clocked, synchronous digital circuit, in which settling time to each stable state must account for switching delay and propagation delay.) +For the "DELAY" parameters seen in the example, just a quick note that these are declared on the left-hand side only, and they are present in the output assignments, because the primary purpose of the LHS, the module, is to run simulations and tests. The parameters affect the time domain, the response time of a simulated circuit element, so they're useful and can be very important to model a real-world, clocked synchronous circuit. -On the other hand, the primary purpose of the RHS is synthesis of a real circuit - logic gates and components. Synthesis, as opposed to simulation, targets a real circuit output and there is no artificial parametrization provided for delays. +On the other hand, the primary purpose of the RHS is synthesis of a hardware circuit: logic gates and components. Synthesis, as opposed to simulation, targets these real circuit components and there is no artificial parametrization provided for delays. - -### What is a good test bench? +#### What is a good test bench? -The policy and guidelines that I take a stab at use an engineering or pragmatic technology point of view to manage this library. +An "engineering" or pragmatic technologist's point of view is used in managing this library. I take a stab at policy and guidelines for the tests, below. -The verification of behaviour of a device is not going to be mathematical (Formal Verification); it is more in the spirit of what a commercial or legal contract provides, stating the detailed description of the device, its functions and transformations, and stating that it conforms to the same, as a sign-off of quality from the provider. +Verification of device behaviour is not going to be mathematical (Formal Verification). It is more in the spirit of what a commercial or legal contract provides: stating the detailed description of the device, its functions and transformations, and stating that it conforms to the same, as a sign-off of quality from the provider. -The test bench, actually, states and makes explicit all those details of functions and transformations. It can be the contract. And whatever it provides, it is a signifier of quality too. +The test bench, actually, states and makes explicit all those details of functions and transformations. It stands as a contract. (If there is a gap discovered later, it can be adjudicated in the court of open source and remedied with a pull request.) -By the way, on a technical note... IceChips testing is a binary, Pass/Fail exercise, because tests are written with a set of macros. These are simply "assert" statements that log a failure message if the stated condition is not met. Take a look at tests in any test bench, for example [7485-tb.v](/source-7400/7485-tb.v "7485 test bench"), and see [tbhelper.v](/includes/tbhelper.v "Assert macros"). With Pass/Fail tests, the test bench is not just doing a demonstration run of the device, with a waveform result that needs to be interpreted. +I would just like to make the point that a test bench, and the effort put into it, is a signifier of quality too. -#### Policy: +By the way, on a technical note... IceChips testing is a binary, Pass/Fail exercise, because tests are written with a set of macros. These macros are "assert" statements that log a failure message if the stated condition is not met. Take a look at tests in any test bench, for example [7485-tb.v](/source-7400/7485-tb.v "7485 test bench"), and see [tbhelper.v](/includes/tbhelper.v "Assert macros"). Pass/Fail tests mean the test bench is not just doing a demonstration run of the device, with a waveform result that needs to be interpreted. + +##### Policy: The sequence of tests is intended to be comprehensive. It's intended to cover **the entire scope** of behaviour - which means running through all basic inputs (and examining all outputs); running through all mixtures and crosses of allowed inputs or a realistic sampling thereof (if not **all**, then certainly all that represent "interestingly" different mixtures); and a realistic sampling of the complete ranges of data values; a coverage of all edge-cases that are reasonably deduced from all inputs, outputs, complete ranges of data values, and the stated functionality; and all this with an awareness and an intentionality applied to the semantics of the data and semantics of the operations that the device applies. -So two points, from opposite poles of this endeavour: +##### Guidelines: + +Two guidelines, from opposite poles: -#### Guidelines: +1. **Good Cop.** In practice, life does not usually give the chance to prove everything with 100% coverage. Get the most value out of limited coverage that "explores the parameter space"; to guide whether your effort is adding value, think about the [80%/20% rule][link-pareto]; do not be redundant, do not spend unneeded effort to reach an ideal of 100%. Certainly do not spend run-time looping through 100% of all possibilities if you do not demonstrate what is resulting inside the loops. -1. **Good Cop.** In practice, life does not usually give the chance to prove everything with 100% coverage. Get the most value out of limited coverage that "explores the parameter space"; think about the [80%/20% rule][link-pareto]; do not be redundant, do not spend unneeded effort to reach an ideal of 100%. Certainly do not spend run-time looping through 100% of all possibilities if you do not demonstrate what is resulting inside the loops. +2. **Bad Cop.** Applied technology and testing are usually [not good enough][link-swbugs]. Use the advantages of Open Source - time, resources, extra thought? If there's any doubt, apply more diligence; the aim and goal of your work **must** be a defect-free product; cover the domain - and really: review later, to check if you covered it. The domain here on this hardware (compared to most software) is not that huge. -2. **Bad Cop.** Applied technology and testing are usually [not good enough][link-swbugs]. Use the advantages of Open Source - time, resources, extra thought? If there's any doubt, apply more diligence; aim for a defect-free product; write tests with excellence; cover the domain - and really, review to check if you covered it. Here on this hardware, the domain is thankfully limited, much narrower than in software. +Working on a test suite late at night and it is boring...? Try to think of the long term; try to think of this: -The beauty of test suites (in software or hardware) is that they mean **doing it right**. Functionality that is unassailable, works right the first time, and doesn't break at a later time? Priceless. + Functionality that is unassailable, works right the first time, and doesn't break at a later time? Priceless. -If Intel had put a test suite in place under this policy and guidelines, I'm going to suggest they would have caught their [Pentium floating-point divide bug][link-hwbug] of 1993. Running some number theory calculations covering a nice range, particularly using prime numbers, comparing the answers to reference numbers, would have forestalled cranking out $475 million in silicon paper weights. +If Intel had put a test suite in place under this policy and guidelines, they would have caught their [Pentium floating-point divide bug][link-hwbug] of 1993. Covering a nice range, running some number theory calculations, particularly using prime numbers, and checking the exact results in tables, would have forestalled cranking out $475 million in silicon paper weights. [ico-travisci]: /images/passed.svg -[link-travisci]: https://travis-ci.org/TimRudy/ice-chips-verilog +[link-travisci]: https://travis-ci.com/TimRudy/ice-chips-verilog "See the latest build and test report" [link-iverilogu]: https://iverilog.fandom.com/wiki/User_Guide [link-pareto]: https://en.wikipedia.org/wiki/Pareto_principle [link-swbugs]: https://www.techrepublic.com/article/microsoft-fixes-windows-and-internet-explorer-zero-day-flaws-in-latest-patch-tuesday diff --git a/images/TTL_chip_14pin.svg b/images/TTL_chip_14pin.svg new file mode 100644 index 0000000..2e0cd69 --- /dev/null +++ b/images/TTL_chip_14pin.svg @@ -0,0 +1,259 @@ + + + + + image/svg+xml + + © 2020 Tim Rudy, Marcus Lindholm + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 7400 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/images/TTL_chip_16pin.svg b/images/TTL_chip_16pin.svg new file mode 100644 index 0000000..a051226 --- /dev/null +++ b/images/TTL_chip_16pin.svg @@ -0,0 +1,265 @@ + + + + + image/svg+xml + + © 2020 Tim Rudy, Marcus Lindholm + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 74139 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/images/TTL_chip_24pin.svg b/images/TTL_chip_24pin.svg new file mode 100644 index 0000000..b6ff483 --- /dev/null +++ b/images/TTL_chip_24pin.svg @@ -0,0 +1,292 @@ + + + + + image/svg+xml + + © 2020 Tim Rudy, Marcus Lindholm + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 74181 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/images/proj_icon_a.svg b/images/proj_icon_a.svg new file mode 100644 index 0000000..cbe1524 --- /dev/null +++ b/images/proj_icon_a.svg @@ -0,0 +1,294 @@ + + + + + + image/svg+xml + + © 2020 Tim Rudy, Marcus Lindholm + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 74181 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/images/proj_icon_b.svg b/images/proj_icon_b.svg new file mode 100644 index 0000000..a9c1388 --- /dev/null +++ b/images/proj_icon_b.svg @@ -0,0 +1,267 @@ + + + + + + image/svg+xml + + © 2020 Tim Rudy, Marcus Lindholm + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 74139 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/images/proj_icon_c.svg b/images/proj_icon_c.svg new file mode 100644 index 0000000..32d84fe --- /dev/null +++ b/images/proj_icon_c.svg @@ -0,0 +1,261 @@ + + + + + + image/svg+xml + + © 2020 Tim Rudy, Marcus Lindholm + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 7400 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +