diff --git a/.DS_Store b/.DS_Store new file mode 100644 index 000000000..09f7803ef Binary files /dev/null and b/.DS_Store differ diff --git a/amaranth/.DS_Store b/amaranth/.DS_Store new file mode 100644 index 000000000..55ab1772f Binary files /dev/null and b/amaranth/.DS_Store differ diff --git a/docs/glossary.rst b/docs/glossary.rst new file mode 100644 index 000000000..3d04e9005 --- /dev/null +++ b/docs/glossary.rst @@ -0,0 +1,332 @@ +.. glossary:: + +Glossary +======== + +.. _Amaranth: + + **Amaranth** + An open-source toolchain that uses the Python programming language to create hardware definitions based on synchronous digital logic. + + The toolchain consists of the Amaranth language, the standard library, the simulator, and the build system, covering all steps of a typical :abbr:`FPGA(Field Programmable Gate Array)` development workflow. + +.. _ASIC: + + **ASIC (Application-Specific Integrated Circuit)** + A non-standard application-specific integrated circuit chip made for a specific task or product. + + The term *application* refers to the function the circuit will perform, not to a software application. + + ASICs can be configured to be more power efficient and have better performance than an off-the-shelf general purpose integrated circuit. However, unlike FPGAs, ASICs cannot be reprogrammed and are expensive to produce. Design and testing are critical to the success of ASIC development. + + Rather than designing and building them from the ground up, ASICs can be created by interconnecting functional components from :ref:`standard cell libraries`. The resulting system can then be verified via :ref:`simulation`. + +.. _Bitstream generation: + + **Bitstream generation** + The final step in translating requirements into circuits on a chip, the generated bitstream defines the logic blocks and interconnects on an FPGA chip as well as configuring the flash memory or external storage device to boot the FPGA at power on. + +.. _BRAM: + + **BRAM (Block RAM)** + On-chip random access memory, distributed evenly across a chip, to store large amounts of data. + + BRAM, sometimes called embedded RAM, doesn't need refreshing (as :ref:`DRAM` does) and, like :ref:`SRAM`, doesn't need a memory controller. Single-port BRAM can either read or write on the single port; dual-port BRAM supports read and write for any two addresses and both ports can read *and* write. + + BRAM :ref:`FIFO` is used to cross clock domains or to buffer data between two interfaces. + +.. _CLB: + + **CLB (Configurable Logic Block)** + The basic repeating logic block on an FPGA, the purpose of CLBs is to implement combinational and sequential logic on an FPGA. + + Be aware that different FPGA manufacturers use different names for this component. + + Each FPGA contains many logic blocks that are surrounded by a system of programmable interconnects (I/O blocks), called a fabric, that routes signals between the CLBs. The three essential components of a logic block are :ref:`flip-flops`, :ref:`LUTs`, and :ref:`multiplexers`. + +.. _Clock signal: + + **Clock signal** + An electronic logic signal that oscillates between a high and a low state at a constant frequency. + + Used to synchronise the actions of digital circuits, clock signals can be one of two types: primary or derived. Primary clocks are generated using a frequency standard: a stable oscillator that creates a signal with a high degree of accuracy and precision. Derived clocks can be made by dividing another clock signal or using a :ref:`PLL`. + +.. _Clock tree: + + **Clock tree** + A clock distribution network — clocking circuitry and devices — within a hardware design. + + The simplicity or complexity of the clock tree depends on the hardware design. In more complex systems, the clock tree is represented as a hierarchy where a single reference clock is cascaded and synthesized into a number of different output clocks. + +.. _Clock tree synthesis: + + **Clock tree synthesis** + A technique for distributing the clock signal equally among all sequential parts of a design. + + Clock tree synthesis occurs directly after :ref:`placement and before routing` in the :ref:`synthesis` process. It inserts buffers and/or inverters along the clock path to balance the clock delay to all inputs. The aim being to reduce latency and skew to ensure all inputs are synchronized. + +.. _Combinational logic: + + **Combinational logic** + A digital logic function, composed of :ref:`logic gates`, whose outputs are directly related to the current combination of values on its input — combinational logic has no memory or history. + + Combinational logic is also known as combinatorial logic. + +.. _DRAM: + + **DRAM (Dynamic Random Access Memmory)** + Memory that is stored in capacitors and is constantly refreshed. + + Rather than store data in :ref:`flip-flops`, as :ref:`SRAM` does, DRAM constantly reads data into capacitors, row-by-row, in sequence, even when no processing is taking place. Racing the decay of the refresh has a negative impact on speed and performance; and the write process produces extra heat because it uses a strong charge. + + DRAM has a higher storage capacity than other kinds of memory; is cheaper and smaller than SRAM; and memory can be deleted and refreshed while running a program. + + DRAM is incompatible with SRAM. To create a :ref:`SoC` with DRAM requires the design of capacitors; creating a SoC with SRAM requires the design of flip-flops. + +.. _DUT: + + **DUT (Device Under Test)** + A physical chip or logic circuit being tested at :ref:`simulation`. + + Testing can result in a chip being given a grade to represent the extent to which it met tolerance values. + +.. _Elaboration: + + **Elaboration** + The first step in the toolchain process, elaboration begins the translation of requirements into circuits on a chip. + + In elaboration, the behaviour described in the :ref:`HDL` code is analyzed to produce a technology independent :ref:`netlist` that itemizes the required logic elements and interconnects. + + In the toolchain, elaboration is followed by :ref:`synthesis`, :ref:`place and route`, and :ref:`bitstream generation`. + +.. _FIFO: + + **FIFO (First In First Out)** + A method for organizing the processing of data, especially in a buffer, where the oldest entry is processed first. + + An elementary building block of integrated circuits, FIFOs are used when crossing clock domains, buffering data, or storing data for use at a later time. + +.. _Finite state machine: + + **Finite state machine** + A mathematical model describing a system with a limited number of conditional states of being. + + A finite state machine reads a series of inputs. For each input, it will transition to a different state. Each state specifies which state to transition to next, for the given input. When the processing is complete, a ‘then’ action is taken. The abstract machine can process only one state at a time. This approach enables engineers to study and test each input and output scenario. + +.. _Flip-flop: + + **Flip-flop** + An elementary building block of integrated circuits, flip-flops are the basic memory element for storing a single bit of binary data. + + An edge-triggered device, flip-flops react to the edge of a pulse and have two stable states that they ‘flip’ and ‘flop’ between. + + Modern digital design centres around the D flip-flop (DFF) with Set, Reset, and Enable inputs. The D stands for data or delay, the signals to be stored. + +.. _FPGA: + + **FPGA (Field Programmable Gate Array)** + A reconfigurable integrated circuit containing internal hardware blocks with user-programmable interconnects to create a customised application. + + The device’s physical attributes are programmed using a :ref:`hardware definition language`. User-programmable I/O blocks interface between the FPGA and external devices. + + FPGAs combine speed, programmability, and flexibility. In addition, they can process very large volumes of data by duplicating circuits and running them in parallel. + +.. _GDSII: + + **GDSII** + A binary file format consisting of geometric shapes, labels, and additional data that a foundry can use to manufacture a silicon chip. + + GDSII (or GDS2) is a standard for database interchange of ASIC artwork: all shapes in the design are assigned to a layer (or, sometimes, layers). Layers are combined to form a mask. Each mask is used in the photolithography process that produces the GDSII file the foundry will use when manufacturing the chip. + +.. _Hardware register: + + **Hardware register** + Circuits, typically composed of D :ref:`flip-flops` (DFF), that hold configuration and status information. + + Written in low-level :ref:`HDL` code, a hardware register is a set of DFFs with a shared function. At a higher level, a hardware register can be a specific context for making a SoC a function of a peripheral that is controlled by read and write signals to a memory location. + +.. _HDL: + + **HDL (Hardware Definition Language)** + An HDL, such as :ref:`Amaranth`, describes the structure and timing of electronic circuits and digital logic circuits. + + Modern HDLs include synthesizable code that characterises the synchronous logic (:ref:`registers`), combinational logic (:ref:`logic gates`), and behavioural code (used in testing) that describe a circuit. + +.. _IC: + + **IC (Integrated Circuit)** + Sometimes called a microchip or chip, an IC is a semiconductor-based electronic device consisting of transistors, resistors, capacitors, diodes, and inductors that perform the same functions as a larger circuit comprised of discrete components. + + The circuit is a small wafer that can hold anywhere from hundreds to millions of transistors and resistors (with possibly a few capacitors). These components can perform calculations and store data using either digital or analog technology. ICs use :ref:`logic gates` that work only with values of 1s and 0s. + +.. _JTAG: + + **JTAG** + An industry standard for verifying designs and testing devices — micro controllers, FPGAs, etc. — after manufacture. + + JTAG is a hardware interface that provides a way to communicate directly with the microchips on a board. It enables the testing, via software, of all the different interconnects on a chip without having to physically probe the connections. + +.. _Logic gate: + + **Logic gate** + An elementary building block of integrated circuits, logic gates are electronic devices that perform Boolean functions on one or more binary inputs to produce a single binary output. + + The relationship between the input and output is based on the logic gates in the circuit — AND, OR, NOT, XOR, etc. Logic gates can be combined to perform complex processes based on Boolean logic. + +.. _Logic synthesis: + + **Logic synthesis** + The process of translating a high-level logic definition to lower-level :ref:`flip-flops` and :ref:`logic gates`. + + To achieve this, high-level code, written in a program like Python, is translated to register transfer level (:ref:`RTL`) to simulate the behaviour of the circuit for testing. + +.. _LUT: + + **LUT (Look Up Table)** + An elementary building block of integrated circuits, LUTs define how combinational logic behaves: the output for every combination of inputs. + + A single input LUT is made up of two :ref:`flip-flops` and a :ref:`multiplexer`. This structure can be expanded into a tree to provide the required capacity. The larger the number of multiplexers, the longer the associated propagation delay. + + LUTs can be used to implement an arbitrary logic gate with the same or fewer inputs: a 4-LUT can implement 1, 2, 3, or 4 inputs. If five inputs are required, two 4-LUTS can be combined but at the expense of propogation delay. + +.. _MCU: + + **MCU (Microcontroller Unit)** + An integrated circuit designed to govern a specific operation in an embedded system. + + An MCU integrates a CPU, onboard memory (may be volatile, may be non-volatile), peripherals for communication, and, usually, clock functions. A complex MCU can be described as a system on chip :ref:`(SoC)`. + +.. _Memory-mapped peripheral: + + **Memory-mapped peripheral** + A hardware device that is treated as a memory location in a microcontroller or microprocessor. + + A memory-mapped peripheral is identified by a unique 16-bit address and has a specific address in memory that it reads to and writes data from. + +.. _Microprocessor: + + **Microprocessor** + A miniature, programmable digital device — a tiny computer on a chip — that retrieves instructions from memory, decodes and executes them, and returns the output. + + Accepting binary data as input, microprocessors have memory, are clock-driven, and register-based. They contain the arithmetic, logic, and control circuitry necessary to perform the functions of a computer’s central processing unit. + +.. _Multiplexer: + + **Multiplexer** + A combinational logic circuit designed to switch one of several control signals, often from different sources, to a single common output by the application of a control signal. + + Also known as a data selector or input selector, a multiplexer makes it possible for several input signals to share one device rather than having one device per input signal. + +.. _Netlist: + + **Netlist** + A description of the components and connectivity of an electronic circuit. + + Netlists can be generated at different points in the toolchain process: during logical synthesis, where the placement information will not be available; and after place and route, when the placement information is available. + +.. _PLL: + + **PLL (Phase-Locked Loop)** + A feedback circuit designed to allow one circuit board to synchronize the phase of its on-board clock with an external timing signal. + + PLL circuits compare the phase of an external signal to the phase of a clock signal produced by a voltage controlled crystal oscillator. The circuit then adjusts the phase of the oscillator’s clock signal to match the phase of the external signal to ensure the signals are precisely synchronised with each other. + + The derived clock signal can be the result of dividing an input frequency. PLLs can increase frequency by a non-integer factor. Where multiple clock domains are interacting synchronously, PLLs use a fixed phase relationship. + +.. _Place and route: + + **Place and route** + A stage in the IC design process, place and route decides the placement of components on a chip and the wiring routes between those components. + + Placement defines the location of the electronic components, circuitry, and logic elements within the defined space. Routing defines the wiring required to connect the components. These routines are usually performed by the toolchain and produce the layout schema for a chip. + +.. _Propogation delay: + + **Propagation delay** + The time required to change the output from one logic state to another logic state after input is changed. + + In simplified terms, the time it takes for a signal to move from source to destination. Propogation delay impacts :ref:`sequential logic` — logic driven by a clock. The further apart components in a circuit are, the longer the propogation delay will be. This will cause the clock to run more slowly and create timing errors. + + The maximum speed at which a synchronous logic circuit works can be determined by combining the longest path of propagation delay from input to output with the maximum combined propagation delay. Bear in mind that not only do logic gates have propogation delay, wires do too. + +.. _Register: + + **Register** + A memory device, located at a known address, that can store a specific number of data bits. + + Made up of a series of :ref:`flip-flops`, a register can temporarily store data or a set of instructions for a processor. A register can enable both serial and parallel data transfers, allowing logic operations to be performed on the data stored in it. + + A number of flip-flops can be combined to store binary words. The length of the stored binary word depends on the number of flip-flops that make up the register. + +.. _RTL: + + **RTL (Register Transfer Level)** + The lowest abstraction level for developing :ref:`FPGAs`, RTL creates a representation of synchronous digital circuits between :ref:`hardware registers`. + + Hardware definition language is tranformed to RTL which then defines the circuit at gate level. The representation can be verified via :ref:`simulation`. + +.. _Sequential logic: + + **Sequential logic** + A digital logic function whose outputs depend on both current and past inputs. + + Sequential logic has a memory function (unlike :ref:`combinational logic` which has none) and is used to construct :ref:`Finite state machines`. + + Sequential logic circuits can be either synchronous (the state of the device changes in response to a clock signal) or asynchronous (the state of the device changes in response to changing inputs). + +.. _Simulation: + + **Simulation** + A process in which a model of an electronic circuit is analysed by a computer program to validate its functionality. + + Simulation models the behaviour of a circuit; it does not model the hardware components described by the :ref:`HDL`. Despite being written in HDL, the simulator treats the code as event-driven parallel programming language to run programs on a particular operating system or to port a system that doesn't have an :ref:`FPGA`. The output of the simulation is a value change dump (VCD). + +.. _SoC: + + **SoC (System on Chip)** + An integrated circuit, containing almost all the circuitry and components an electronic system (smartphone, small embedded devices) requires. + + In contrast to a computer system that is made up of many distinct components, a SoC integrates the required resources — CPU, memory interfaces, I/O devices, I/O interfaces — into a single chip. SoCs are more complex than a microcontroller with a higher degree of integration and a greater variety of perhipherals. + + SoCs are typically built around a :ref:`microprocessor`, :ref:`microcontroller`, or specialised :ref:`integrated circuit`. This increases performance, reduces power consumption, and requires a smaller footprint on a printed circuit board. + +.. _SRAM: + + **SRAM (Static Random Access Memory)** + Volatile memory that stores data whilst power is supplied (if the power is turned off, data is lost). + + SRAM uses flip-flops to store bits and holds that value until the opposite value replaces it. SRAM is faster in operation than :ref:`DRAM` as it doesn't require a refresh process. + + In comparison with DRAM, SRAM has a lower power consumption, is more expensive to purchase, has lower storage capacity, and is more complex in design. + + SRAM is incompatible with DRAM. + +.. _Standard cell library: + + **Standard cell library** + A collection of low-level logic functions, with fixed height and variable width cells that can be placed in rows, used to simplify automated digital circuit layout. + + The library will usually contain well-defined, pre-characterized logic functions — flip-flops, buffers, etc. — optimised for performance and physical size. Cell library characterization is a process of analyzing a circuit using both static and dynamic methods to generate models suitable for chip implementation flows. + + These functions enable a more modular approach to circuit design by abstracting some of the complexity of component layout and connectivity. Being well-defined, it's easier to estimate factors such as performance and timing and increase the likelihood of a successful design. + +.. _Synthesis: + + **Synthesis** + The process of coverting a high-level behavioural design to a lower-level physical implementation. + + The synthesis process represents the behaviour outlined in a :ref:`hardware definition language` as :ref:`register transfer level` that is then translated into :ref:`logic gates` (:ref:`LUTs` and :ref:`flip-flops`). A bitstream can then be generated to program an FPGA. + +.. _Tapeout: + + **Tapeout** + The final stage of the IC design process where photolithography is used to produce a graphic representation of the photomask of a circuit, in :ref:`GDSII` format, to be sent to the semiconductor foundry for manufacture. + +.. _Waveform: + + **Waveform** + A visual representation of changes in voltage or current in an electrical circuit over time. + + Waveforms have different shapes and three main characteristics: period, the length of time the waveform takes to repeat; frequency, the number of times the waveform repeats within a time period; and amplitude, the magnitude or intensity of the signal waveform measured in volts or amps. + + The waveform of an electrical signal can be visualised using an oscilloscope. The square waveform is commonly used to represent digital information. A waveform dump, one of the outputs of simulation, can be used to measure the performance of devices. \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 0e6e0dfc3..cf0f772a5 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -17,3 +17,4 @@ Language & toolchain platform changes contrib + glossary diff --git a/docs/intro.rst b/docs/intro.rst index 2fed04407..2218678eb 100644 --- a/docs/intro.rst +++ b/docs/intro.rst @@ -6,7 +6,7 @@ Introduction The Amaranth project provides an open-source toolchain for developing hardware based on synchronous digital logic using the Python programming language. It aims to be easy to learn and use, reduce or eliminate common coding mistakes, and simplify the design of complex hardware with reusable components. -The Amaranth toolchain consists of the :ref:`Amaranth language `, the :ref:`standard library `, the :ref:`simulator `, and the :ref:`build system `, covering all steps of a typical FPGA development workflow. At the same time, it does not restrict the designer's choice of tools: existing industry-standard (System)Verilog or VHDL code can be integrated into an Amaranth-based design flow, or, conversely, Amaranth code can be integrated into an existing Verilog-based design flow. +The Amaranth toolchain consists of the :ref:`Amaranth language `, the :ref:`standard library `, the :ref:`simulator `, and the :ref:`build system `, covering all steps of a typical :abbr:`FPGA(Field Programmable Gate Array)` development workflow. At the same time, it does not restrict the designer's choice of tools: existing industry-standard (System)Verilog or VHDL code can be integrated into an Amaranth-based design flow, or, conversely, Amaranth code can be integrated into an existing Verilog-based design flow. .. TODO: add links to connect_rpc docs once they exist @@ -16,11 +16,11 @@ The Amaranth toolchain consists of the :ref:`Amaranth language `, th The Amaranth language ===================== -The :doc:`Amaranth hardware description language ` is a Python library for register transfer level modeling of synchronous logic. Ordinary Python code is used to construct a netlist of a digital circuit, which can be simulated, directly synthesized via Yosys_, or converted to human-readable Verilog code for use with industry-standard toolchains. +The :doc:`Amaranth hardware description language ` is a Python library for modeling of synchronous logic. Ordinary Python code is used to construct a netlist of a digital circuit, which can be simulated, directly synthesized via Yosys_, or converted to human-readable Verilog code for use with industry-standard toolchains. -By relying on the flexibility, rich functionality and widespread adoption of the Python language, the Amaranth language is focused on a single task: modeling digital logic well. It has first-class support for building blocks like clock domains and finite state machines, and uses simple rules for arithmetic operations that closely match the Python semantics. Python classes, functions, loops and conditionals can be used to build organized and flexible designs; Python libraries can be seamlessly used with Amaranth during design or verification; and Python development tools can process Amaranth code. +By relying on the flexibility, rich functionality and widespread adoption of the Python language, the Amaranth language is focused on a single task: modeling digital logic well. It has first-class support for building blocks like clock domains and :term:`finite state machines`, and uses simple rules for arithmetic operations that closely match the Python semantics. Python classes, functions, loops and conditionals can be used to build organized and flexible designs; Python libraries can be seamlessly used with Amaranth during design or verification; and Python development tools can process Amaranth code. -A core design principle of the Amaranth language is to be not only easy to use, but also hard to accidentally misuse. Some HDLs provide functionality that has unexpected and undesirable behavior in synthesis, often with expensive consequences, and require a significant effort in learning a "safe" coding style and adopting third-party linting tools. Amaranth lacks non-synthesizable constructs and avoids error-prone inference in favor of explicit instantiation. It has many diagnostics (and regularly adds new ones) highlighting potential design issues. Most importantly, all usability issues are considered `reportable bugs`_. +A core design principle of the Amaranth language is to be not only easy to use, but also hard to accidentally misuse. Some :abbr:`HDLs(Hardware defintion language)` provide functionality that has unexpected and undesirable behavior in synthesis, often with expensive consequences, and require a significant effort in learning a "safe" coding style and adopting third-party linting tools. Amaranth lacks non-synthesizable constructs and avoids error-prone inference in favor of explicit instantiation. It has many diagnostics (and regularly adds new ones) highlighting potential design issues. Most importantly, all usability issues are considered `reportable bugs`_. .. _Yosys: https://yosyshq.net/yosys/ .. _reportable bugs: https://github.com/amaranth-lang/amaranth/issues @@ -31,11 +31,11 @@ A core design principle of the Amaranth language is to be not only easy to use, The Amaranth standard library ============================= -The Amaranth language comes with a standard library---a collection of essential digital design components and interfaces. It includes clock domain crossing primitives, synchronous and asynchronous FIFOs, a flexible I/O buffer interface, and more. By providing reliable building blocks out of the box, Amaranth allows the designer to focus on their application and avoids subtle differences in behavior between different designs. +The Amaranth language comes with a standard library---a collection of essential digital design components and interfaces. It includes clock domain crossing primitives, synchronous and asynchronous :abbr:`FIFOs(first in, first out)`, a flexible I/O buffer interface, and more. By providing reliable building blocks out of the box, Amaranth allows the designer to focus on their application and avoids subtle differences in behavior between different designs. .. TODO: link to stdlib here -Clock domain crossing often requires special treatment, such as using vendor-defined attributes or instantiating device-specific primitives. The CDC primitives in the Amaranth standard library can be overridden by the platform integration, and every platform integration included with Amaranth follows the vendor recommendations for CDC. +Clock domain crossing (CDC) often requires special treatment, such as using vendor-defined attributes or instantiating device-specific primitives. The CDC primitives in the Amaranth standard library can be overridden by the platform integration, and every platform integration included with Amaranth follows the vendor recommendations for CDC. High-speed designs usually require the use of registered (and sometimes, geared) I/O buffers. The Amaranth standard library provides a common interface to be used between I/O buffers and peripheral implementations. The Amaranth build system, if used, can instantiate I/O buffers for every platform integration included with Amaranth. @@ -78,7 +78,7 @@ FPGA toolchain integration Each FPGA family requires the use of synthesis and place & route tools specific for that device family. The Amaranth build system directly integrates with every major open-source and commercial FPGA toolchain, and can be easily extended to cover others. -Through this integration, Amaranth can specialize the CDC primitives and I/O buffers for a particular device and toolchain; generate I/O and clock constraints from board definition files; synchronize the power-on reset in single-clock designs; include (System)Verilog and VHDL files in the design (if supported by the toolchain); and finally, generate a script running synthesis, placement, routing, and timing analysis. The generated code can be customized to insert additional options, commands, constraints, and so on. +Through this integration, Amaranth can specialize the :abbr:`CDC(Clock domain crossing)` primitives and I/O buffers for a particular device and toolchain; generate I/O and clock constraints from board definition files; synchronize the power-on reset in single-clock designs; include (System)Verilog and VHDL files in the design (if supported by the toolchain); and finally, generate a script running synthesis, placement, routing, and timing analysis. The generated code can be customized to insert additional options, commands, constraints, and so on. The Amaranth build system produces self-contained, portable build trees that require only the toolchain to be present in the environment. This makes builds easier to reproduce, or to run on a remote machine. The generated build scripts are always provided for both \*nix and Windows. @@ -86,7 +86,7 @@ The Amaranth build system produces self-contained, portable build trees that req Development board definitions ----------------------------- -Getting started with a new FPGA development board often requires going through a laborous and error-prone process of deriving toolchain configuration and constraint files from the supplied documentation. The Amaranth project includes a community-maintained repository of definitions for many open-source and commercial FPGA development boards. +Getting started with a new FPGA development board often requires going through a laborious and error-prone process of deriving toolchain configuration and constraint files from the supplied documentation. The Amaranth project includes a community-maintained repository of definitions for many open-source and commercial FPGA development boards. These board definitions contain everything that is necessary to start using the board: FPGA family and model, clocks and resets, descriptions of on-board peripherals (including pin direction and attributes such as I/O standard), connector pinouts, and for boards with a built-in debug probe, the steps required to program the board. It takes a single Python invocation to generate, build, and download a test design that shows whether the board, toolchain, and programmer are working correctly. diff --git a/docs/lang.rst b/docs/lang.rst index 6a1c11086..4f2543791 100644 --- a/docs/lang.rst +++ b/docs/lang.rst @@ -81,7 +81,7 @@ All values have a ``.shape()`` method that computes their shape. The width of a Values ====== -The basic building block of the Amaranth language is a *value*, which is a term for a binary number that is computed or stored anywhere in the design. Each value has a *width*---the amount of bits used to represent the value---and a *signedness*---the interpretation of the value by arithmetic operations---collectively called its *shape*. Signed values always use `two's complement`_ representation. +The basic building block of the Amaranth language is a *value*, which is a term for a binary number that is computed or stored anywhere in the design. Each value has a *width*---the number of bits used to represent the value---and a *signedness*---the interpretation of the value by arithmetic operations---collectively called its *shape*. Signed values always use `two's complement`_ representation. .. _two's complement: https://en.wikipedia.org/wiki/Two's_complement @@ -98,7 +98,7 @@ The simplest Amaranth value is a *constant*, representing a fixed number, and in >>> ten = Const(10) >>> minus_two = C(-2) -The code above does not specify any shape for the constants. If the shape is omitted, Amaranth uses unsigned shape for positive numbers and signed shape for negative numbers, with the width inferred from the smallest amount of bits necessary to represent the number. As a special case, in order to get the same inferred shape for ``True`` and ``False``, ``0`` is considered to be 1-bit unsigned. +The code above does not specify any shape for the constants. If the shape is omitted, Amaranth uses unsigned shape for positive numbers and signed shape for negative numbers, with the width inferred from the smallest number of bits necessary to represent the number. As a special case, to get the same inferred shape for ``True`` and ``False``, ``0`` is considered to be 1-bit unsigned. .. doctest:: @@ -468,7 +468,7 @@ Although the syntax is similar, it is important to remember that Amaranth values ... TypeError: Attempted to convert Amaranth value to Python boolean -Because the value of ``a``, and therefore ``a == 0``, is not known at the time when the ``if`` statement is executed, there is no way to decide whether the body of the statement should be executed---in fact, if the design is synthesized, by the time ``a`` has any concrete value, the Python program has long finished! To solve this problem, Amaranth provides its own :ref:`control structures ` that, also, manipulate circuits. +Because the value of ``a``, and therefore ``a == 0``, is not known at the time the ``if`` statement is executed, there is no way to decide whether the body of the statement should be executed---in fact, if the design is synthesized, by the time ``a`` has any concrete value, the Python program has long finished! To solve this problem, Amaranth provides its own :ref:`control structures ` that, also, manipulate circuits. .. _lang-widthext: @@ -486,7 +486,7 @@ Arithmetic operators Most arithmetic operations on integers provided by Python can be used on Amaranth values, too. -Although Python integers have unlimited precision and Amaranth values are represented with a :ref:`finite amount of bits `, arithmetics on Amaranth values never overflows because the width of the arithmetic expression is always sufficient to represent all possible results. +Although Python integers have unlimited precision and Amaranth values are represented with a :ref:`finite number of bits `, arithmetic computations on Amaranth values never overflows because the width of the arithmetic expression is always sufficient to represent all possible results. .. doctest:: @@ -785,7 +785,7 @@ A *control domain* is a named group of :ref:`signals ` that change All designs have a single predefined *combinatorial domain*, containing all signals that change immediately when any value used to compute them changes. The name ``comb`` is reserved for the combinatorial domain. -A design can also have any amount of user-defined *synchronous domains*, also called *clock domains*, containing signals that change when a specific edge occurs on the domain's clock signal or, for domains with asynchronous reset, on the domain's reset signal. Most modules only use a single synchronous domain, conventionally called ``sync``, but the name ``sync`` does not have to be used, and lacks any special meaning beyond being the default. +A design can also have any number of user-defined *synchronous domains*, also called *clock domains*, containing signals that change when a specific edge occurs on the domain's clock signal or, for domains with asynchronous reset, on the domain's reset signal. Most modules only use a single synchronous domain, conventionally called ``sync``, but the name ``sync`` does not have to be used, and lacks any special meaning beyond being the default. The behavior of assignments differs for signals in :ref:`combinatorial ` and :ref:`synchronous ` domains. Collectively, signals in synchronous domains contain the state of a design, whereas signals in the combinatorial domain cannot form feedback loops or hold state. @@ -887,7 +887,7 @@ Every signal included in the target of an assignment becomes a part of the domai Assignment order ---------------- -Unlike with two different domains, adding multiple assignments to the same signal to the same domain is well-defined. +In contrast to working with two different domains, adding multiple assignments to the same signal to the same domain is well-defined. Assignments to different signal bits apply independently. For example, the following two snippets are equivalent: diff --git a/docs/start.rst b/docs/start.rst index 3d7772fbd..9314fa3d7 100644 --- a/docs/start.rst +++ b/docs/start.rst @@ -51,7 +51,7 @@ The test bench is implemented as a Python generator function that is co-simulate .. TODO: link to simulator reference -When run, the test bench finishes successfully, since all of the assertions hold, and produces a VCD file with waveforms recorded for every ``Signal`` as well as the clock of the ``sync`` domain: +When run, the test bench finishes successfully, since all of the assertions hold, and produces a VCD (Value Change Dump) file with waveforms recorded for every ``Signal`` as well as the clock of the ``sync`` domain: .. image:: _images/up_counter_gtkwave.png :alt: A screenshot of GTKWave displaying waveforms near the clock cycle where the counter overflows.