diff --git a/.gitignore b/.gitignore index c69c870b7..d70f0cd5e 100644 --- a/.gitignore +++ b/.gitignore @@ -25,6 +25,8 @@ var/ *.egg-info/ .installed.cfg *.egg +uv.lock +.venv/ # icarus verilog host/tests/Makefile diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 000000000..e699f38de --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,15 @@ +version: 2 + +build: + os: ubuntu-lts-latest + tools: + python: "3.12" + +sphinx: + configuration: docs/conf.py + +python: + install: + - requirements: docs/requirements.txt + - method: pip + path: . diff --git a/README.rst b/README.rst index 8a1626a35..35add651f 100644 --- a/README.rst +++ b/README.rst @@ -12,9 +12,7 @@ Basil :target: http://basil.rtfd.org :alt: Documentation -Basil is a modular data acquisition system and system testing framework in Python. - -It also provides generic FPGA firmware modules for different hardware platforms and drivers for wide range of lab appliances. +Basil is a modular data acquisition (DAQ) framework developed by `SiLab `_ for the characterization of `monolithic `_ and `hybrid `_ pixel detectors. It comprises a library of HDL modules (written in Verilog) for custom FPGA readout boards, paired with a collection of Python code that control the hardware over USB, Ethernet, or serial interfaces from a host PC. Basil also includes Python drivers for common lab instruments such as power supplies, oscilloscopes, and other bench equipment. Features ======== @@ -26,36 +24,28 @@ Software: - layer structure following hardware - generation based on yaml file - register abstract layer (RAL) - - simulator interface allows software test against simulated RTL (thanks to `cocotb `_) + - simulator interface allows software test against simulated RTL (thanks to `cocotb `_) Installation ============ -Clone the repository to get a copy of the source code (for developers): +Install via PyPI: .. code-block:: bash - git clone https://github.com/SiLab-Bonn/basil.git - cd basil - pip install -e . - -or install via PyPI into the Python's site-packages folder (for non-developers): - -.. code-block:: bash + pip install basil-daq - pip install basil_daq==version +.. note:: -where version is a version number (e.g., 3.0.1) + The PyPI package may be outdated. Installing from source (below) is recommended to get the latest version. -or install from git, when no PyPI package is available (for non-developers): +Or install from source: .. code-block:: bash - pip install git+https://github.com/SiLab-Bonn/basil.git@branch - -where branch is a branch name or tag (e.g., master or v3.0.1). - -Check `.travis.yml <.travis.yml>`_ for installation/testing hints. + git clone https://github.com/SiLab-Bonn/basil.git + cd basil + pip install -e . Support ======= @@ -69,11 +59,12 @@ Documentation Documentation can be found under: https://basil.rtfd.org -Example Projects: -================= -- `pyBAR `_ - Bonn ATLAS Readout in Python -- `MCA `_ - Multi Channel Analyzer -- `fe65_p2 `_ - DAQ for FE65P2 prototype +Example Projects +================ +- `TJ-Monopix2 `_ - DAQ for TJ-Monopix2 depleted monolithic pixel sensor +- `BDAQ53 `_ - Readout system for ATLAS ITkPix (RD53) chips +- `LF-Monopix2 `_ - DAQ for LF-Monopix2 depleted monolithic pixel sensor +- `FRIDA `_ - DAQ for FRIDA, an ADC test array for frame-based imaging detectors License ======= diff --git a/basil/HL/i2c.py b/basil/HL/i2c.py index 5396d02d7..6dca732e4 100644 --- a/basil/HL/i2c.py +++ b/basil/HL/i2c.py @@ -67,8 +67,7 @@ def is_done(self): @property def is_ready(self): ''' - :raises ExceptionType: IOError - Transfer not acknowledged. + :raises IOError: Transfer not acknowledged. ''' if self.NO_ACK: raise IOError('i2c:Transfer not acknowledged') diff --git a/basil/firmware/modules/README.rst b/basil/firmware/modules/README.rst index f332fc359..492a3b927 100644 --- a/basil/firmware/modules/README.rst +++ b/basil/firmware/modules/README.rst @@ -4,48 +4,48 @@ Basil modules .. begin-include -Modules use simple bus single master interconnection bus. -Every module has same/similar set of parameters and pins that allow to properly connect to bus. - -Full list of modules can be found in `firmware/modules folder `_. - -Software drivers for modules can be found in `basil/HL folder `_. - -Parameters - +--------------+---------------------+--------------------------------------------------------------------+ - | Name | Default | Description | - +==============+=====================+====================================================================+ - | BASEADDR | 0 | Defines base address of module (start address) in memory map space | - +--------------+---------------------+--------------------------------------------------------------------+ - | HIGHADDR | 0 | Defines last module address in memory map space | - +--------------+---------------------+--------------------------------------------------------------------+ - | ABUSWIDTH | 16 | Define address bus with | - +--------------+---------------------+--------------------------------------------------------------------+ - | DBUSWIDTH | 8 | Define data bus with | - +--------------+---------------------+--------------------------------------------------------------------+ - -Pins - +--------------+-------------------------+-----------+------------------------------------------------------+ - | Name | Size | Direction | Description | - +==============+=========================+===========+======================================================+ - | BUS_RST | 1 | input | Synchronous Reset - Active High | - +--------------+-------------------------+-----------+------------------------------------------------------+ - | BUS_CLK | 1 | input | Clock | - +--------------+-------------------------+-----------+------------------------------------------------------+ - | BUS_WR | 1 | input | Write strobe - Active High | - +--------------+-------------------------+-----------+------------------------------------------------------+ - | BUS_RD | 1 | input | Read strobe - Active High | - +--------------+-------------------------+-----------+------------------------------------------------------+ - | BUS_ADD | ABUSWIDTH | input | Address bus` | - +--------------+-------------------------+-----------+------------------------------------------------------+ - | BUS_DATA | DBUSWIDTH (typically 8) | inout | Data Bus | - +--------------+-------------------------+-----------+------------------------------------------------------+ - -Registers - +------------+----------------+-------+----------------------------------------+ - | Name | Address | r/w | Description | - +============+================+=======+========================================+ - | RESET | 0 | wo | Soft reset active on write to address | - +------------+----------------+-------+----------------------------------------+ - | VERSION | 0 | ro | Module version | - +------------+----------------+-------+----------------------------------------+ \ No newline at end of file +Modules connect to a simple single-master bus. Every module has a similar set of parameters and pins for bus integration. The full list of firmware modules can be found in the `firmware/modules `_ folder, and their Python drivers in `basil/HL `_. + +The following parameters, pins, and registers are common to all bus-connected modules. Individual modules add their own on top of these. + +**Common parameters:** + ++--------------+---------------------+--------------------------------------------------------------------+ +| Name | Default | Description | ++==============+=====================+====================================================================+ +| BASEADDR | 0 | Defines base address of module (start address) in memory map space | ++--------------+---------------------+--------------------------------------------------------------------+ +| HIGHADDR | 0 | Defines last module address in memory map space | ++--------------+---------------------+--------------------------------------------------------------------+ +| ABUSWIDTH | 16 | Address bus width | ++--------------+---------------------+--------------------------------------------------------------------+ +| DBUSWIDTH | 8 | Data bus width | ++--------------+---------------------+--------------------------------------------------------------------+ + +**Common pins:** + ++--------------+-------------------------+-----------+------------------------------------------------------+ +| Name | Size | Direction | Description | ++==============+=========================+===========+======================================================+ +| BUS_RST | 1 | input | Synchronous reset, active high | ++--------------+-------------------------+-----------+------------------------------------------------------+ +| BUS_CLK | 1 | input | Bus clock | ++--------------+-------------------------+-----------+------------------------------------------------------+ +| BUS_WR | 1 | input | Write strobe, active high | ++--------------+-------------------------+-----------+------------------------------------------------------+ +| BUS_RD | 1 | input | Read strobe, active high | ++--------------+-------------------------+-----------+------------------------------------------------------+ +| BUS_ADD | ABUSWIDTH | input | Address bus | ++--------------+-------------------------+-----------+------------------------------------------------------+ +| BUS_DATA | DBUSWIDTH | inout | Data bus | ++--------------+-------------------------+-----------+------------------------------------------------------+ + +**Common registers:** + ++------------+----------------+-------+----------------------------------------+ +| Name | Address | r/w | Description | ++============+================+=======+========================================+ +| RESET | 0 | wo | Soft reset on write to address | ++------------+----------------+-------+----------------------------------------+ +| VERSION | 0 | ro | Module version | ++------------+----------------+-------+----------------------------------------+ \ No newline at end of file diff --git a/basil/firmware/modules/cmd_seq/README.rst b/basil/firmware/modules/cmd_seq/README.rst index b4c23b759..947b11656 100644 --- a/basil/firmware/modules/cmd_seq/README.rst +++ b/basil/firmware/modules/cmd_seq/README.rst @@ -1,7 +1,7 @@ -===================================== -**cmd_seq** - cmd generator (FE-I4) -===================================== +========================================= +**cmd_seq** - Command generator (FE-I4) +========================================= Generate arbitrary single bit data stream and clock (mainly to generate FE-I4 commands). Supports hardware loops and Manchester data encoding. diff --git a/basil/firmware/modules/fast_spi_rx/README.rst b/basil/firmware/modules/fast_spi_rx/README.rst index 63652ee41..1816c3560 100644 --- a/basil/firmware/modules/fast_spi_rx/README.rst +++ b/basil/firmware/modules/fast_spi_rx/README.rst @@ -1,6 +1,6 @@ ===================================== -**fast_spi_rx** - fast spi receiver +**fast_spi_rx** - Fast SPI receiver ===================================== Allows continuous serial data receive. Received data are propagated to FIFO data interface. diff --git a/basil/firmware/modules/gpio/README.rst b/basil/firmware/modules/gpio/README.rst index 75482e318..20e2cab61 100644 --- a/basil/firmware/modules/gpio/README.rst +++ b/basil/firmware/modules/gpio/README.rst @@ -1,6 +1,6 @@ ============================= -**gpio** - general purpose io +**gpio** - General purpose IO ============================= General purpose input output (gpio) is a generic pins whose behavior, including whether it is an input or output pin, can be controlled by the user at run time. @@ -9,7 +9,7 @@ General purpose input output (gpio) is a generic pins whose behavior, including `test_SimGpio.v `_ `test_SimGpio.py `_ -Parameters +**Parameters:** +--------------+---------------------+-----------------------------------------------------------------+ | Name | Default | Description | +==============+=====================+=================================================================+ @@ -20,14 +20,14 @@ Parameters | IO_TRI | 0 | instantiate tri-state buffer for given pin | +--------------+---------------------+-----------------------------------------------------------------+ -Pins +**Pins:** +--------------+---------------------+-----------------------+-----------------------------------------+ | Name | Size | Direction | Description | +==============+=====================+=================================================================+ | IO | IO_WIDTH | IO_DIRECTION/IO_TRI | General purpose pins | +--------------+---------------------+-----------------------------------------------------------------+ -Registers +**Registers:** +------------+---------------------+----------------------------------------+ | Name | Address | Description | +============+=====================+========================================+ diff --git a/basil/firmware/modules/i2c/README.rst b/basil/firmware/modules/i2c/README.rst index 583b0ac05..d0bf2c00f 100644 --- a/basil/firmware/modules/i2c/README.rst +++ b/basil/firmware/modules/i2c/README.rst @@ -1,6 +1,6 @@ ====================================== -**i2c** - i2c peripheral interface +**i2c** - I2C peripheral interface ====================================== Module implements master i2c peripheral interface. @@ -9,14 +9,14 @@ Module implements master i2c peripheral interface. `test_SimI2c.v `_ `test_SimI2c.py `_ -Parameters +**Parameters:** +--------------+---------------------+---------------------------------------------------------------------------------+ | Name | Default | Description | +==============+=====================+=================================================================================+ | MEM_BYTES | 16 | Amount of memory (bytes) allocated for data (maximum single transfer in bytes) | +--------------+---------------------+---------------------------------------------------------------------------------+ -Pins +**Pins:** +--------------+---------------------+-----------------------+---------------------------------------------------------+ | Name | Size | Direction | Description | +==============+=====================+=======================+=========================================================+ @@ -27,7 +27,7 @@ Pins | I2C_SCL | 1 | inout | SCL | +--------------+---------------------+-----------------------+---------------------------------------------------------+ -Registers +**Registers:** +--------------+----------------------------------+--------+-------+-------------+---------------------------------------------+ | Name | Address | Bits | r/w | Default | Description | +==============+==================================+========+=======+=============+=============================================+ diff --git a/basil/firmware/modules/jtag_master/README.rst b/basil/firmware/modules/jtag_master/README.rst index ec3a16f8b..143743b91 100644 --- a/basil/firmware/modules/jtag_master/README.rst +++ b/basil/firmware/modules/jtag_master/README.rst @@ -1,6 +1,6 @@ ====================================== -**jtag** - serial peripheral interface +**jtag** - JTAG master ====================================== Module implements master jtag peripheral interface. Supports simple internal loops. @@ -9,14 +9,14 @@ Module implements master jtag peripheral interface. Supports simple internal loo `test_SimJtagMaster.v `_ `test_SimJtagMaster.py `_ -Parameters +**Parameters:** +--------------+---------------------+-------------------------------------------------------------------------+ | Name | Default | Description | +==============+=====================+=========================================================================+ | MEM_BYTES | 16 | Amount of meemory allocated for data (maximum single transfer in bytes) | +--------------+---------------------+-------------------------------------------------------------------------+ -Pins +**Pins:** +--------------+---------------------+-----------------------+------------------------------------------------------+ | Name | Size | Direction | Description | +==============+=====================+=======================+======================================================+ @@ -35,7 +35,7 @@ Pins | SLD | 1 | output | active high strobe indicating end of transfer | +--------------+---------------------+-----------------------+------------------------------------------------------+ -Registers +**Registers:** +--------------+-----------------------------------+--------+-------+-------------+---------------------------------------------------------+ | Name | Address | Bits | r/w | Default | Description | +==============+===================================+========+=======+=============+=========================================================+ diff --git a/basil/firmware/modules/pulse_gen/README.rst b/basil/firmware/modules/pulse_gen/README.rst index 57d299c56..370c2a50f 100644 --- a/basil/firmware/modules/pulse_gen/README.rst +++ b/basil/firmware/modules/pulse_gen/README.rst @@ -1,6 +1,6 @@ =============================== -**pulse_gen** - pulse generator +**pulse_gen** - Pulse generator =============================== Simple pulse generator with configurable delay and width. @@ -9,7 +9,7 @@ Simple pulse generator with configurable delay and width. `test_SimSeq.v `_ `test_SimSeq.py `_ -Pins +**Pins:** +---------------+---------------------+-----------------------+------------------------------------------------------+ | Name | Size | Direction | Description | +===============+=====================+=======================+======================================================+ @@ -20,7 +20,7 @@ Pins | PULSE | 1 | output | output pulse | +---------------+---------------------+-----------------------+------------------------------------------------------+ -Registers +**Registers:** +---------------+----------------------------------+--------+-------+-------------+--------------------------------------------------------------------------------------------+ | Name | Address | Bits | r/w | Default | Description | +===============+==================================+========+=======+=============+============================================================================================+ diff --git a/basil/firmware/modules/rrp_arbiter/README.rst b/basil/firmware/modules/rrp_arbiter/README.rst index 1f62330e8..2524bf673 100644 --- a/basil/firmware/modules/rrp_arbiter/README.rst +++ b/basil/firmware/modules/rrp_arbiter/README.rst @@ -1,18 +1,18 @@ ========================================== -**rrp_arbiter** - round-robin arbiter +**rrp_arbiter** - Round-robin arbiter ========================================== Round-robin arbiter for data (32 bit) streams with priority. Data streams multiplexer. -Parameters +**Parameters:** +--------------+---------------------+-------------------------------------------------------------------------+ | Name | Default | Description | +==============+=====================+=========================================================================+ | WIDTH | 4 | Number of incoming data streams | +--------------+---------------------+-------------------------------------------------------------------------+ -Pins +**Pins:** +--------------+---------------------+-----------------------+------------------------------------------------------+ | Name | Size | Direction | Description | +==============+=====================+=======================+======================================================+ diff --git a/basil/firmware/modules/seq_gen/README.rst b/basil/firmware/modules/seq_gen/README.rst index 4f42971b4..a6e757375 100644 --- a/basil/firmware/modules/seq_gen/README.rst +++ b/basil/firmware/modules/seq_gen/README.rst @@ -1,6 +1,6 @@ ================================ -**seq_gen** - pattern generator +**seq_gen** - Pattern generator ================================ Module implements a simple sequencer/pattern generator base on block ram. Supports 2 levels of internal loops and external start. @@ -10,7 +10,7 @@ For OUT_BITS != 8 user need to provide block memory module (seq_gen_blk_mem) wit `test_SimSeq.v `_ `test_SimSeq.py `_ -Parameters +**Parameters:** +--------------+---------------------+-------------------------------------------------------------------------+ | Name | Default | Description | +==============+=====================+=========================================================================+ @@ -19,7 +19,7 @@ Parameters | OUT_BITS | 8 | Size (bit) for output pattern - word size | +--------------+---------------------+-------------------------------------------------------------------------+ -Pins +**Pins:** +---------------+---------------------+-----------------------+------------------------------------------------------+ | Name | Size | Direction | Description | +===============+=====================+=======================+======================================================+ @@ -30,34 +30,34 @@ Pins | SEQ_OUT | OUT_BITS | output | sequencer output | +---------------+---------------------+-----------------------+------------------------------------------------------+ -Registers - +---------------+----------------------------------+--------+-------+-------------+--------------------------------------------------------------------------------------------+ - | Name | Address | Bits | r/w | Default | Description | - +===============+==================================+========+=======+=============+============================================================================================+ - | START | 1 | | wo | | start transfer on write to address | - +---------------+----------------------------------+--------+-------+-------------+--------------------------------------------------------------------------------------------+ - | DONE | 1 | [0] | ro | 0 | indicate transfer finish | - +---------------+----------------------------------+--------+-------+-------------+--------------------------------------------------------------------------------------------+ - | EN_EXT_START | 2 | [0] | r/w | 0 | enable external start | - +---------------+----------------------------------+--------+-------+-------------+--------------------------------------------------------------------------------------------+ - | CLK_DIV | 3 | [7:0] | r/w | 1 | internal division factor for SEQ_CLK | - +---------------+----------------------------------+--------+-------+-------------+--------------------------------------------------------------------------------------------+ - | COUNT | 7 - 4 | [31:0] | r/w | out_words | set the size of sequence (in output words) | - +---------------+----------------------------------+--------+-------+-------------+--------------------------------------------------------------------------------------------+ - | WAIT | 11 - 8 | [31:0] | r/w | 0 | waits after every sequnce if REPEAT != 0 repeat transfer count (0 -> forever) | - +---------------+----------------------------------+--------+-------+-------------+--------------------------------------------------------------------------------------------+ - | REPEAT | 15 - 12 | [31:0] | r/w | 1 | repeat sequence count (0 -> forever) | - +---------------+----------------------------------+--------+-------+-------------+--------------------------------------------------------------------------------------------+ - | REP_START | 19 - 16 | [31:0] | r/w | 0 | position from witch pattern will start in repeat mode (a first sequence always start at 0) | - +---------------+----------------------------------+--------+-------+-------------+--------------------------------------------------------------------------------------------+ - | NESTED_START | 23 - 20 | [31:0] | r/w | 0 | position from witch pattern will start for nested loop | - +---------------+----------------------------------+--------+-------+-------------+--------------------------------------------------------------------------------------------+ - | NESTED_STOP | 27 - 24 | [31:0] | r/w | 0 | position to witch pattern will stop for nested loop | - +---------------+----------------------------------+--------+-------+-------------+--------------------------------------------------------------------------------------------+ - | NESTED_REPEAT | 31 - 28 | [31:0] | r/w | 0 | repeat count for nested loop | - +---------------+----------------------------------+--------+-------+-------------+--------------------------------------------------------------------------------------------+ - | MEM_BYTES | 35 - 32 | [31:0] | r/w | MEM_BYTE | memory size | - +---------------+----------------------------------+--------+-------+-------------+--------------------------------------------------------------------------------------------+ - | DATA | 64 to 64+MEM_BYTES-1 | | r/w | unknown | memory for pattern | - +---------------+----------------------------------+--------+-------+-------------+--------------------------------------------------------------------------------------------+ +**Registers:** + +---------------+----------------------------------+--------+-------+-------------+--------------------------------------------------------------------------------------------+ + | Name | Address | Bits | r/w | Default | Description | + +===============+==================================+========+=======+=============+============================================================================================+ + | START | 1 | | wo | | start transfer on write to address | + +---------------+----------------------------------+--------+-------+-------------+--------------------------------------------------------------------------------------------+ + | DONE | 1 | [0] | ro | 0 | indicate transfer finish | + +---------------+----------------------------------+--------+-------+-------------+--------------------------------------------------------------------------------------------+ + | EN_EXT_START | 2 | [0] | r/w | 0 | enable external start | + +---------------+----------------------------------+--------+-------+-------------+--------------------------------------------------------------------------------------------+ + | CLK_DIV | 3 | [7:0] | r/w | 1 | internal division factor for SEQ_CLK | + +---------------+----------------------------------+--------+-------+-------------+--------------------------------------------------------------------------------------------+ + | COUNT | 7 - 4 | [31:0] | r/w | out_words | set the size of sequence (in output words) | + +---------------+----------------------------------+--------+-------+-------------+--------------------------------------------------------------------------------------------+ + | WAIT | 11 - 8 | [31:0] | r/w | 0 | waits after every sequence if REPEAT != 0 repeat transfer count (0 -> forever) | + +---------------+----------------------------------+--------+-------+-------------+--------------------------------------------------------------------------------------------+ + | REPEAT | 15 - 12 | [31:0] | r/w | 1 | repeat sequence count (0 -> forever) | + +---------------+----------------------------------+--------+-------+-------------+--------------------------------------------------------------------------------------------+ + | REP_START | 19 - 16 | [31:0] | r/w | 0 | position from which pattern will start in repeat mode (a first sequence always start at 0) | + +---------------+----------------------------------+--------+-------+-------------+--------------------------------------------------------------------------------------------+ + | NESTED_START | 23 - 20 | [31:0] | r/w | 0 | position from which pattern will start for nested loop | + +---------------+----------------------------------+--------+-------+-------------+--------------------------------------------------------------------------------------------+ + | NESTED_STOP | 27 - 24 | [31:0] | r/w | 0 | position to which pattern will stop for nested loop | + +---------------+----------------------------------+--------+-------+-------------+--------------------------------------------------------------------------------------------+ + | NESTED_REPEAT | 31 - 28 | [31:0] | r/w | 0 | repeat count for nested loop | + +---------------+----------------------------------+--------+-------+-------------+--------------------------------------------------------------------------------------------+ + | MEM_BYTES | 35 - 32 | [31:0] | r/w | MEM_BYTE | memory size | + +---------------+----------------------------------+--------+-------+-------------+--------------------------------------------------------------------------------------------+ + | DATA | 64 to 64+MEM_BYTES-1 | | r/w | unknown | memory for pattern | + +---------------+----------------------------------+--------+-------+-------------+--------------------------------------------------------------------------------------------+ diff --git a/basil/firmware/modules/seq_rec/README.rst b/basil/firmware/modules/seq_rec/README.rst index 893b2076f..dbb355097 100644 --- a/basil/firmware/modules/seq_rec/README.rst +++ b/basil/firmware/modules/seq_rec/README.rst @@ -1,6 +1,6 @@ ============================ -**seq_rec** - data recorder +**seq_rec** - Data recorder ============================ Simple module that allow recording arbitrary data vector. diff --git a/basil/firmware/modules/spi/README.rst b/basil/firmware/modules/spi/README.rst index f77902c8f..b11fd5d83 100644 --- a/basil/firmware/modules/spi/README.rst +++ b/basil/firmware/modules/spi/README.rst @@ -1,6 +1,6 @@ ====================================== -**spi** - serial peripheral interface +**spi** - Serial peripheral interface ====================================== Module implements master serial peripheral interface. Supports simple internal loops. @@ -9,14 +9,14 @@ Module implements master serial peripheral interface. Supports simple internal l `test_SimSpi.v `_ `test_SimSpi.py `_ -Parameters - +--------------+---------------------+-------------------------------------------------------------------------+ - | Name | Default | Description | - +==============+=====================+=========================================================================+ - | MEM_BYTES | 16 | Amount of meemory allocated for data (maximum single transfer in bytes) | - +--------------+---------------------+-------------------------------------------------------------------------+ +**Parameters:** + +--------------+---------------------+------------------------------------------------------------------------+ + | Name | Default | Description | + +==============+=====================+========================================================================+ + | MEM_BYTES | 16 | Amount of memory allocated for data (maximum single transfer in bytes) | + +--------------+---------------------+------------------------------------------------------------------------+ -Pins +**Pins:** +--------------+---------------------+-----------------------+------------------------------------------------------+ | Name | Size | Direction | Description | +==============+=====================+=======================+======================================================+ @@ -35,7 +35,7 @@ Pins | EXT_START | 1 | input | active high start signal (synchronous to SPI_CLK) | +--------------+---------------------+-----------------------+------------------------------------------------------+ -Registers +**Registers:** +--------------+----------------------------------+--------+-------+-------------+---------------------------------------------+ | Name | Address | Bits | r/w | Default | Description | +==============+==================================+========+=======+=============+=============================================+ diff --git a/basil/firmware/modules/tdc_s3/README.rst b/basil/firmware/modules/tdc_s3/README.rst index aef1feeba..885acdd10 100644 --- a/basil/firmware/modules/tdc_s3/README.rst +++ b/basil/firmware/modules/tdc_s3/README.rst @@ -1,6 +1,6 @@ ===================================== -**tdc** - time to digital converter +**tdc** - Time-to-digital converter ===================================== Simple time to digital converter. This module digitizes (12 bit resolution) input pulse (TDC_IN) and calculates distance (8 bit resolution) between TDC_IN and TRIG_IN (e.g. trigger signal and hit). @@ -13,8 +13,8 @@ NOTE: 4. ARM_TDC and EXT_EN are assumed to be slower than DV_CLK. **Unit test/Example:** -`test_SimTlu.v `_ -`test_SimTlu.py `_ +`test_SimTdc.v `_ +`test_SimTdc.py `_ Data format (Standard) +-------------------------+--------------------------------------------------------+--------------------+ @@ -29,7 +29,7 @@ Data format (in case of EN_TRIGGER_DIST) | DATA IDENTIFIER (4 bit) | TRIGGER DIST (8 bit) | TIMESTAMP/EVENT COUNTER (8 bit) | TDC value (12 bit) | +-------------------------+----------------------+---------------------------------+--------------------+ -Parameters +**Parameters:** +------------------------------+---------------------+---------------------------------------------------------------------------------------------------------------------+ | Name | Default | Description | +==============================+=====================+=====================================================================================================================+ @@ -44,7 +44,7 @@ Parameters | BROADCAST | 0 | If BROADCAST is 1, 640 MHz sampled trigger signal can be shared with other TDC modules. | +------------------------------+---------------------+---------------------------------------------------------------------------------------------------------------------+ -Pins +**Pins:** +--------------------------+---------------------+-----------------------+-------------------------------------------------------------------------------------------------+ | Name | Size | Direction | Description | +==========================+=====================+=======================+=================================================================================================+ @@ -73,7 +73,7 @@ Pins | TIMESTAMP | 16 | input | timestamp counter from other modules (e.g. tlu module) | +--------------------------+---------------------+-----------------------+-------------------------------------------------------------------------------------------------+ -Registers +**Registers:** +----------------------------------------+----------------------------------+--------+-------+-------------+---------------------------------------------------------------+ | Name | Address | Bits | r/w | Default | Description | +========================================+==================================+========+=======+=============+===============================================================+ diff --git a/basil/firmware/modules/timestamp/README.rst b/basil/firmware/modules/timestamp/README.rst index 8e3ae5e0d..2392feb34 100644 --- a/basil/firmware/modules/timestamp/README.rst +++ b/basil/firmware/modules/timestamp/README.rst @@ -1,6 +1,6 @@ =============================== -**timestamp** - time stamp +**timestamp** - Timestamp =============================== Simple timestamp recorder. @@ -9,7 +9,7 @@ Simple timestamp recorder. `test_Timestamp.v `_ `test_Timestamp.py `_ -Pins +**Pins:** +---------------+---------------------+-----------------------+------------------------------------------------------+ | Name | Size | Direction | Description | +===============+=====================+=======================+======================================================+ @@ -23,7 +23,7 @@ Pins +---------------+---------------------+-----------------------+------------------------------------------------------+ | TIMESTAMP_OUT | 64 | output | | +---------------+---------------------+-----------------------+------------------------------------------------------+ -Registers +**Registers:** +---------------+----------------------------------+--------+-------+-------------+----------------------------------------------+ | Name | Address | Bits | r/w | Default | Description | +===============+==================================+========+=======+=============+==============================================+ diff --git a/basil/firmware/modules/tlu/README.rst b/basil/firmware/modules/tlu/README.rst index 42f577ad2..9627edae5 100644 --- a/basil/firmware/modules/tlu/README.rst +++ b/basil/firmware/modules/tlu/README.rst @@ -1,6 +1,6 @@ ===================================== -**tlu** - trigger logic unit +**tlu** - Trigger logic unit ===================================== General purpose trigger module and EUDAQ Telescope/TLU communication module. Trigger IDs received by the TLU are propagated to FIFO data interface. @@ -31,7 +31,7 @@ DATA_FORMAT[1:0]: `test_SimTlu.v `_ `test_SimTlu.py `_ -Parameters +**Parameters:** +------------------------------+---------------------+--------------------------------------------------------------------------+ | Name | Default | Description | +==============================+=====================+==========================================================================+ @@ -44,7 +44,7 @@ Parameters | TIMESTAMP_N_OF_BIT | 32 | Bus width of time stamp. | +------------------------------+---------------------+--------------------------------------------------------------------------+ -Pins +**Pins:** +--------------------------+---------------------+-----------------------+------------------------------------------------------+ | Name | Size | Direction | Description | +==========================+=====================+=======================+======================================================+ @@ -83,7 +83,7 @@ Pins | TIMESTAMP | TIMESTAMP_N_OF_BIT | output (sync) | internal timestamp provided for other devices/modules| +--------------------------+---------------------+-----------------------+------------------------------------------------------+ -Registers +**Registers:** +----------------------------------------+----------------------------------+--------+-------+-------------+-------------------------------------------------------+ | Name | Address | Bits | r/w | Default | Description | +========================================+==================================+========+=======+=============+=======================================================+ diff --git a/docs/_static/WaveDrom_load.js b/docs/_static/WaveDrom_load.js index 5b65e505b..f67e4b9d2 100644 --- a/docs/_static/WaveDrom_load.js +++ b/docs/_static/WaveDrom_load.js @@ -1,3 +1,3 @@ - -var body = document.getElementsByTagName("body")[0]; -body.addEventListener("load", WaveDrom.ProcessAll(), false); \ No newline at end of file +document.addEventListener("DOMContentLoaded", function () { + WaveDrom.ProcessAll(); +}); diff --git a/docs/_static/bdaq53.jpg b/docs/_static/bdaq53.jpg new file mode 100644 index 000000000..d8e77c805 Binary files /dev/null and b/docs/_static/bdaq53.jpg differ diff --git a/docs/_static/logo_silab.png b/docs/_static/logo_silab.png new file mode 100644 index 000000000..531099b2d Binary files /dev/null and b/docs/_static/logo_silab.png differ diff --git a/docs/_static/theme_overrides.css b/docs/_static/theme_overrides.css index f67eb6095..fb8ae1acd 100644 --- a/docs/_static/theme_overrides.css +++ b/docs/_static/theme_overrides.css @@ -1,4 +1,15 @@ +/* Hide dark mode toggle button */ +button.theme-switch-button { + display: none !important; +} -html body div.wy-nav-content { - max-width: 100% -} \ No newline at end of file +/* Center WaveDrom diagrams */ +svg[id^="svgcontent_"] { + display: block; + margin: 0 auto; +} + +/* Remove underline from links */ +a { + text-decoration: none !important; +} diff --git a/docs/conf.py b/docs/conf.py index 96f88e54f..540e22385 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -14,7 +14,6 @@ import sys import os -import sphinx_rtd_theme # If extensions (or modules to document with autodoc) are in another directory, @@ -37,7 +36,7 @@ 'sphinx.ext.todo', 'sphinx.ext.ifconfig', 'sphinx.ext.viewcode', - 'sphinxcontrib.blockdiag', + 'sphinx.ext.graphviz', ] # Add any paths that contain templates here, relative to this directory. @@ -54,15 +53,18 @@ # General information about the project. project = 'basil' -copyright = '2015, SiLab, Institute of Physics, University of Bonn' +copyright = '2013-2026' +author = 'SiLab, Institute of Physics, University of Bonn' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. # -f = open('../VERSION', 'r') -basil_version = f.readline().strip() -f.close() +try: + from importlib.metadata import version as get_version + basil_version = get_version("basil_daq") +except Exception: + basil_version = "dev" # The short X.Y version. version = basil_version @@ -112,33 +114,22 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -# html_theme = 'default' -html_theme = "sphinx_rtd_theme" - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -# html_theme_options = {} - -# Add any paths that contain custom themes here, relative to this directory. -# html_theme_path = [] -html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] - -# The name for this set of Sphinx documents. If None, it defaults to -# " v documentation". -# html_title = None - -# A shorter title for the navigation bar. Default is the same as html_title. -# html_short_title = None - -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -# html_logo = None +html_theme = "sphinx_book_theme" +html_logo = "_static/logo_silab.png" +html_theme_options = { + "repository_url": "https://github.com/SiLab-Bonn/basil", + "use_repository_button": True, + "use_issues_button": True, + "use_download_button": False, +} -# The name of an image file (within the static path) to use as favicon of the -# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. -# html_favicon = None +# Remove dark mode toggle, force light mode +html_context = { + "default_mode": "light", +} +html_sidebars = { + "**": ["navbar-logo.html", "search-field.html", "sbt-sidebar-nav.html"], +} # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, @@ -148,8 +139,8 @@ def setup(app): app.add_css_file("theme_overrides.css") - app.add_js_file("http://wavedrom.com/skins/default.js") - app.add_js_file("http://wavedrom.com/WaveDrom.js") + app.add_js_file("https://wavedrom.com/skins/default.js") + app.add_js_file("https://wavedrom.com/wavedrom.min.js") app.add_js_file("WaveDrom_load.js") @@ -222,7 +213,7 @@ def setup(app): # author, documentclass [howto, manual, or own class]). latex_documents = [ ('index', 'basil.tex', 'basil Documentation', - 'T', 'manual'), + 'SiLab, University of Bonn', 'manual'), ] # The name of an image file (relative to this directory) to place at the top of @@ -252,7 +243,7 @@ def setup(app): # (source start file, name, description, authors, manual section). man_pages = [ ('index', 'basil', 'basil Documentation', - ['T'], 1) + ['SiLab, University of Bonn'], 1) ] # If true, show URL addresses after external links. @@ -266,7 +257,7 @@ def setup(app): # dir menu entry, description, category) texinfo_documents = [ ('index', 'basil', 'basil Documentation', - 'T', 'basil', 'One line description of project.', + 'SiLab, University of Bonn', 'basil', 'Modular DAQ framework for pixel detectors.', 'Miscellaneous'), ] diff --git a/docs/examples.rst b/docs/examples.rst index 2a2948a41..86ff5d729 100644 --- a/docs/examples.rst +++ b/docs/examples.rst @@ -90,7 +90,7 @@ Result of simulation: .. image:: _static/spi_example_timing.png -A workin example can be seen in tests/test_SimSpi.py. +A working example can be seen in tests/test_SimSpi.py. gpio ------- diff --git a/docs/firmware.rst b/docs/firmware.rst index e84224903..d01efa737 100644 --- a/docs/firmware.rst +++ b/docs/firmware.rst @@ -2,31 +2,47 @@ Firmware ############ -FPGA firmware consists of very simple single master bus definition and set of standard modules used by DAQ systems. +The FPGA firmware is built around a simple single-master bus connecting a set of standard modules. Control modules (SPI, GPIO) configure the DUT, while data-taking modules (receivers, TDCs) pass 32-bit words through an arbiter into a FIFO that the host can continuously read. Each word carries a source identifier so the host can demultiplex data from different modules. -Typical firmware consists of a basil bus connecting all modules. Control modules which provide configuration to DUT (like SPI/GPIO) and data taking modules (like data receivers). Received data (32 bit) are stored in the FIFO (large extremal memory) and can be continuously pulled from host application. Data from different modules are identified by source codding in 32bit data words. +.. graphviz:: -.. blockdiag:: + digraph { + rankdir=LR; + splines=polyline; + nodesep=0.5; + ranksep=0.8; + node [shape=box, fixedsize=true, width=0.75, height=0.4]; + j1 [shape=point, width=0.01]; + j2 [shape=point, width=0.01]; + j3 [shape=point, width=0.01]; + j4 [shape=point, width=0.01]; + j5 [shape=point, width=0.01]; + Interface [fixedsize=true, width=0.9, height=0.4]; + Interface -> j3 [color=blue, arrowhead=none, dir=back]; + j1 -> j2 [color=blue, arrowhead=none]; + j2 -> j3 [color=blue, arrowhead=none]; + j3 -> j4 [color=blue, arrowhead=none]; + j4 -> j5 [color=blue, arrowhead=none]; + j1 -> SPI [color=blue, headport=w, tailport=e]; + j2 -> GPIO [color=blue, headport=w, tailport=e]; + j3 -> RX [color=blue, headport=w, tailport=e]; + j4 -> TDC [color=blue, headport=w, tailport=e]; + j5 -> FIFO [color=blue, headport=w, tailport=e]; + RX -> Arbiter [color=green, headport=n, tailport=e]; + TDC -> Arbiter [color=green, headport=w, tailport=e]; + Arbiter -> FIFO [color=green, headport=e, tailport=s]; + { rank=same; j1; j2; j3; j4; j5; } + { rank=same; SPI; GPIO; RX; TDC; FIFO; } + } - diagram { +Timing diagrams +================ - Interface <-> SPI [color = "blue"]; - Interface <-> GPIO [color = "blue"]; - Interface <-> RX [color = "blue", label = "bus"]; - Interface <-> TDC [color = "blue"]; - Interface <-> FIFO [color = "blue"]; - TDC -> Arbiter [color = "green", label = "data"]; - RX -> Arbiter [color = "green"]; - Arbiter -> FIFO [color = "green"]; +The bus signals are ``BUS_CLK``, ``BUS_WR``, ``BUS_RD``, ``BUS_ADD`` (address), and ``BUS_DATA``. Writes and reads each complete in a single clock cycle. - Arbiter -> FIFO [folded]; - } +**Single write:** assert ``BUS_WR`` for one cycle while placing the address and data on the bus. -basil bus -========= - -single write - .. raw:: html +.. raw:: html +**Single read:** assert ``BUS_RD`` for one cycle with the address. The module responds with data on the following cycle. -single read - .. raw:: html +.. raw:: html - diff --git a/docs/hardware.rst b/docs/hardware.rst index 06cc8d1a4..9b2645c02 100644 --- a/docs/hardware.rst +++ b/docs/hardware.rst @@ -2,19 +2,35 @@ Hardware ############ -Basil also allows easy integration with custom Hardware. +Basil supports integration with several custom hardware platforms developed at SiLab for connecting to devices under test (DUTs). Each board provides FPGA-based digital IO with a host PC interface, and can be paired with analog front-end cards or custom DUT carrier boards. -For our purpuse we developed general purpose hardware components which connect to custom DUTs. The MultiIO board (MIO) implements the main FPGA for digital IO, memory ressources, and the interface (USB 2.0) to the PC. To add analog functionality, the Gerneral Purpose Analog Card (GPAC) was developed. It connects to the MultiIO board and provides 4 programmable power supplies, 12 current sources, 4 voltage sources, 4 fast ADC channels, digital IO with scalable voltages, LVDS, and a programmable injection pulse generator. The device under test (DUT) will be connected with a custom PCB to the MIO/GPAC hardware. + - **BDAQ53** -- Gigabit Ethernet readout board with Enclustra Mercury KX1/KX2 FPGA modules and SiTCP + - **MIO** (MultiIO) -- Digital IO card with Xilinx Spartan-3 FPGA and USB 2.0 interface + - **MIO3** (MultiIO USB3) -- Digital IO card based on Enclustra `KX1 `__ module with USB 3.0 interface + - **GPAC** (General Purpose Analog Card) -- Analog front-end for MIO, with power supplies, current sources, ADCs, and injection pulse generator + - **LX9** -- Xilinx Spartan-6 LX9 MicroBoard adapter - - MultiIO - Digital IO card with FPGA and USB 2.0 interface - - MIO3 - Digital IO card with FPGA and USB 3.0 interface based on Enclustra `KX1 `_ module - - GPAC - General Purpose Analog Card + +BDAQ53 +========================== + +.. image:: _static/bdaq53.jpg + +The BDAQ53 board is a readout board developed at SiLab for lab bench or testbeam characterization of silicon pixel detectors. The software part of the readout system is written in Python and meant to be easily understandable and modifiable. + +Originally designed for the RD53 collaboration, serving the ATLAS ITkPix chip family, the BDAQ53 board has since been adopted by a number of other projects at SiLab, including the `TJ-Monopix2 `_ depleted monolithic pixel sensor, `LF-Monopix2 `_, the Belle II DEPFET upgrade, and the `FRIDA `_ ADC test chip. + +The board accepts Enclustra Mercury FPGA modules, either the `KX1 `_ (speed grade -1) or `KX2 `_, which plug into the top of the board via high-density connectors. Both carry a Xilinx Kintex-7 FPGA. Communication with the host PC is over Gigabit Ethernet using `SiTCP `_, a TCP/IP stack implemented directly in FPGA fabric. + +Around the edges of the board, five DisplayPort connectors (DP1 to DP5) provide high-density differential IO for connecting to custom DUT carrier boards. Four RJ45 connectors offer additional single-ended or differential pairs. A standard PMOD header exposes eight general-purpose signal pins (plus power and ground) for debug probing with a logic analyzer or oscilloscope. The board is powered by an external 5 V supply and programmed via JTAG using a Xilinx Platform Cable. + +More information can be found in the `BDAQ53 wiki `_ as well as the `BDAQ53 paper `_ (NIM A, 2020). MIO (Multi IO Card) -======================== +======================== -The "S3 Multi IO System" is developed as an easy to use multi purpose digital IO card. It includes a free programmable Xilinx Spartan3 FPGA, SRAM Memory, USB2.0 Interface and a 8051 microcontroller with I2C and SPI functionality. It is designed to provide sufficient digital IO capability to any kind of daughter card. +The "S3 Multi IO System" is developed as an easy-to-use multi-purpose digital IO card. It includes a free programmable Xilinx Spartan3 FPGA, SRAM Memory, USB2.0 Interface and a 8051 microcontroller with I2C and SPI functionality. It is designed to provide sufficient digital IO capability to any kind of daughter card. .. image:: _static/MIO.jpg @@ -44,28 +60,32 @@ Features: - via JTAG - via USB2.0 -`Documentation for MIO card. `_ +.. note:: + + Documentation for the MIO card was previously hosted on SiLab Redmine (no longer publicly available). GPAC (General Purpose Analog Card) =================================== -GPAC Card is developed as an easy to use multi purpose analog IO card compatible with MIO Card. +GPAC Card is developed as an easy-to-use multi-purpose analog IO card compatible with MIO Card. .. image:: _static/MIO_GPAC_DUT.png Features: - - 4 regulated power supples, 0.8-1.83/2.83 V, max. 1000 mA, (controlled by I2C) + - 4 regulated power supplies, 0.8-1.83/2.83 V, max. 1000 mA, (controlled by I2C) - 4 RX and 4 TX LVDS Lines - - 4 channel ADC, 25MS, 14bit + - 4 channel ADC, 25MS, 14-bit - 16 CMOS Outputs - 8 CMOS Inouts - - 12 current source/sink, -1mA to +1mA, 12bit (controlled by I2C) - - 4 voltage outputs, 0-2.048 V, 12bit (controlled by I2C) - - 64x (4 available to DUT) channel slow ADC for monitoring (controlled by I2C) + - 12 current source/sink, -1 mA to +1 mA, 12-bit (controlled by I2C) + - 4 voltage outputs, 0-2.048 V, 12-bit (controlled by I2C) + - 64x (4 available to DUT) channel slow ADC for monitoring (controlled by I2C) - Injection Pulse Generator with programmable voltage levels (high and low) -`Documentation for GPAC card. `_ +.. note:: + + Documentation for the GPAC card was previously hosted on SiLab Redmine (no longer publicly available). MIO3 (Multi IO Card USB3) @@ -73,10 +93,11 @@ MIO3 (Multi IO Card USB3) TBD. + LX9 ========================== -`LX9 Board. `_ +The Avnet Xilinx Spartan-6 LX9 MicroBoard (discontinued). **4 channel FE-I4 adepter with TLU:** diff --git a/docs/index.rst b/docs/index.rst index 7322caeff..99fbe6252 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,24 +1,73 @@ +############ +Overview +############ -basil -================================= +Basil is a modular data acquisition (DAQ) framework developed by `SiLab `_ for the characterization of `monolithic `_ and `hybrid `_ pixel detectors. It comprises a library of HDL modules (written in Verilog) for custom FPGA readout boards, paired with a collection of Python code that control the hardware over USB, Ethernet, or serial interfaces from a host PC. Basil also includes Python drivers for common lab instruments such as power supplies, oscilloscopes, and other lab equipment. -Basil is a modular readout framework intended to allow simple and fast data acquisition systems (DAQ) design. It consists of different hardware components, FPGA firmware modulus and a Python based contol software. +Features +=========================== + +Firmware: + - Simple single control `bus definition`_ + - Multiple `HDL modules `_ (ex. SPI, SEQ) + - Multiple `interfaces `_ (UART, USB2, USB3, Ethernet) +Software: + - Layer structure following hardware + - Generation based on YAML file + - Simulator interface allows software test against simulated RTL (thanks to `cocotb `_) + - Python drivers for lab instruments (power supplies, oscilloscopes, chillers, X-ray tubes, etc.) + + +.. _`bus definition`: firmware.html#basil-bus + +Installation +======================== + +A (currently-in-need-of-update) version is available via PyPi: + +.. code-block:: bash + + pip install basil-daq + +or for development from source: + +.. code-block:: bash + + git clone https://github.com/SiLab-Bonn/basil.git + cd basil + pip install -e . + + +Simulation +======================== + +Basil has a simulation interface (SiSim) which allows communication with a simulator as if talking to real hardware, thanks to `cocotb `_. + +To run a simulation you need: + - a Verilog simulator (e.g. `Icarus `_ ) + - `cocotb `_ library + - set interface type to SiSim + +Basil unit tests make extensive use of this feature. See the tests folder. + +License +===================== + +If not stated otherwise: + +Host Software: + The host software is distributed under the BSD 3-Clause ("BSD New" or "BSD Simplified") License. + +FPGA Firmware: + The FPGA firmware is distributed under the GNU Lesser General Public License, version 3.0 (LGPLv3). -Contents: .. toctree:: + :hidden: - introduction + self hardware firmware software modules examples - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` diff --git a/docs/introduction.rst b/docs/introduction.rst deleted file mode 100644 index 994278e89..000000000 --- a/docs/introduction.rst +++ /dev/null @@ -1,60 +0,0 @@ -############ -Introduction -############ - -Basil is a modular readout framework intended to allow simple and fast data acquisition systems (DAQ) design. It consists of different hardware components, FPGA firmware modulus and a Python based control software. - -Features -=========================== - -Firmware: - - very simple single master `bus definition`_ - - multiple `basic modules `_ (ex. SPI, SEQ) - - multiple `interfaces `_ (UART, USB2, USB3, Ethernet) -Software: - - layer structure following hardware - - generation based on yaml file - - register abstract layer (RAL) - - simulator interface allows software test against simulated RTL (thanks to `cocotb `_ ) - - -.. _`bus definition`: firmware.html#basil-bus - -Installation -======================== - -From host folder run: - -.. code-block:: bash - - python setup.py install - -or - -.. code-block:: bash - - pip install -e "git+https://github.com/SiLab-Bonn/basil.git#egg=basil&subdirectory=host" - - -Simulation -======================== - -Thank to `Chris Higgs `_ basil has a simulation interface (SiSim) with allow communication with simulator as if talking to real hardware. - -To make simulation one need: - - verilog simulator (ex. `Icarus `_ ) - - `cocotb `_ library - - set interface type to SiSim - -Basil unit tests make extensive use of this feature. See tests folder. - -License -===================== - -If not stated otherwise. - -Host Software: - The host software is distributed under the BSD 3-Clause (“BSD New” or “BSD Simplified”) License. - -FPGA Firmware: - The FPGA software is distributed under the GNU Lesser General Public License, version 3.0 (LGPLv3). diff --git a/docs/modules.rst b/docs/modules.rst index 77985a208..86c66217f 100644 --- a/docs/modules.rst +++ b/docs/modules.rst @@ -2,17 +2,16 @@ Modules ############ -.. include:: ../firmware/modules/README.rst +.. include:: ../basil/firmware/modules/README.rst :start-after: begin-include .. !!!!!!!!!!!!! .. !GPIO! .. !!!!!!!!!!!!! -.. include:: ../firmware/modules/gpio/README.rst +.. include:: ../basil/firmware/modules/gpio/README.rst -Driver -------- +**Driver:** .. automodule:: basil.HL.gpio @@ -24,10 +23,9 @@ Driver .. !SPI! .. !!!!!!!!!!!!! -.. include:: ../firmware/modules/spi/README.rst +.. include:: ../basil/firmware/modules/spi/README.rst -Driver -------- +**Driver:** .. automodule:: basil.HL.spi @@ -38,10 +36,9 @@ Driver .. !SEQ_GET! .. !!!!!!!!!!!!! -.. include:: ../firmware/modules/seq_gen/README.rst +.. include:: ../basil/firmware/modules/seq_gen/README.rst -Driver -------- +**Driver:** .. automodule:: basil.HL.seq_gen @@ -52,10 +49,9 @@ Driver .. !PULSE_GEN! .. !!!!!!!!!!!!! -.. include:: ../firmware/modules/pulse_gen/README.rst +.. include:: ../basil/firmware/modules/pulse_gen/README.rst -Driver -------- +**Driver:** .. automodule:: basil.HL.pulse_gen @@ -66,16 +62,17 @@ Driver .. !RRP_ARBITER! .. !!!!!!!!!!!!! -.. include:: ../firmware/modules/rrp_arbiter/README.rst +.. include:: ../basil/firmware/modules/rrp_arbiter/README.rst + +No Python driver — this module operates autonomously in the FPGA fabric. .. !!!!!!!!!!!!! .. !SEQ_REC! .. !!!!!!!!!!!!! -.. include:: ../firmware/modules/seq_rec/README.rst +.. include:: ../basil/firmware/modules/seq_rec/README.rst -Driver -------- +**Driver:** .. automodule:: basil.HL.seq_rec @@ -86,10 +83,9 @@ Driver .. !CMD_SEQ! .. !!!!!!!!!!!!! -.. include:: ../firmware/modules/cmd_seq/README.rst +.. include:: ../basil/firmware/modules/cmd_seq/README.rst -Driver -------- +**Driver:** .. automodule:: basil.HL.cmd_seq @@ -100,10 +96,9 @@ Driver .. !FEI4_RX! .. !!!!!!!!!!!!! -.. include:: ../firmware/modules/fei4_rx/README.rst +.. include:: ../basil/firmware/modules/fei4_rx/README.rst -Driver -------- +**Driver:** .. automodule:: basil.HL.fei4_rx @@ -114,10 +109,9 @@ Driver .. !FAST_SPI_RX! .. !!!!!!!!!!!!! -.. include:: ../firmware/modules/fast_spi_rx/README.rst +.. include:: ../basil/firmware/modules/fast_spi_rx/README.rst -Driver -------- +**Driver:** .. automodule:: basil.HL.fast_spi_rx @@ -128,10 +122,9 @@ Driver .. !TLU! .. !!!!!!!!!!!!! -.. include:: ../firmware/modules/tlu/README.rst +.. include:: ../basil/firmware/modules/tlu/README.rst -Driver -------- +**Driver:** .. automodule:: basil.HL.tlu @@ -142,10 +135,9 @@ Driver .. !TDC! .. !!!!!!!!!!!!! -.. include:: ../firmware/modules/tdc_s3/README.rst +.. include:: ../basil/firmware/modules/tdc_s3/README.rst -Driver -------- +**Driver:** .. automodule:: basil.HL.tdc_s3 @@ -156,10 +148,9 @@ Driver .. !BRAM_FIFO! .. !!!!!!!!!!!!! -.. include:: ../firmware/modules/bram_fifo/README.rst +.. include:: ../basil/firmware/modules/bram_fifo/README.rst -Driver -------- +**Driver:** .. automodule:: basil.HL.sram_fifo @@ -171,10 +162,9 @@ Driver .. !GPAC_ADC_RX! .. !!!!!!!!!!!!! -.. include:: ../firmware/modules/gpac_adc_rx/README.rst +.. include:: ../basil/firmware/modules/gpac_adc_rx/README.rst -Driver -------- +**Driver:** .. automodule:: basil.HL.fadc_rx @@ -185,10 +175,9 @@ Driver .. !I2C! .. !!!!!!!!!!!!! -.. include:: ../firmware/modules/i2c/README.rst +.. include:: ../basil/firmware/modules/i2c/README.rst -Driver -------- +**Driver:** .. automodule:: basil.HL.i2c @@ -201,11 +190,11 @@ Driver .. !UART! .. !!!!!!!!!!!!! -.. include:: ../firmware/modules/uart/README.rst +.. include:: ../basil/firmware/modules/uart/README.rst .. !!!!!!!!!!!!! .. !UTILS! .. !!!!!!!!!!!!! -.. include:: ../firmware/modules/utils/README.rst +.. include:: ../basil/firmware/modules/utils/README.rst diff --git a/docs/requirements.txt b/docs/requirements.txt index 825598d07..abafd0c2a 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,4 +1,3 @@ -sphinxcontrib-blockdiag sphinx_rtd_theme -bitarray +bitarray pyyaml diff --git a/docs/software.rst b/docs/software.rst index c54afb7d7..470b6d1c9 100644 --- a/docs/software.rst +++ b/docs/software.rst @@ -2,34 +2,107 @@ Software ############ -The software framework has a modular structure that reflects the firmware and adds extra layers to make hardware interface user friendly. It loosely follows Register Abstract Layer (RAL) concepts. All the layers are automatically created based on yaml configuration file. +The software framework has a modular structure that reflects the firmware and adds extra layers to make hardware interface user friendly. It loosely follows Register Abstract Layer (RAL) concepts. All the layers are automatically created based on a YAML configuration file. .. image:: _static/basil_layers.png + :align: center -Yaml configuration file -======================= +.. note:: + + The diagram shows USB as the physical interface, but TCP/IP (via Ethernet and SiTCP) is now the more common choice for new designs. Both are supported. + +The ``Dut`` class parses a YAML configuration file and instantiates all modules in order: transfer layer first, then hardware drivers, then registers. Each entry has a ``name`` and a ``type`` that maps to a Python class in the corresponding layer package. -TBD Transfer Layer (TL) ==================== -Implements communication interface like UART, USB, Ethernet or Simulation. -Every TL interface implements 2 functions: +Implements communication interfaces. Each entry in the ``transfer_layer`` list defines a connection to hardware. + +.. code-block:: yaml + + transfer_layer: + - name: intf + type: SiTcp + init: + ip: 192.168.10.16 + udp_port: 4660 + tcp_port: 24 + +Available types (see `basil/TL/ `_): + +- ``SiTcp`` -- Ethernet via SiTCP +- ``SiUsb`` / ``SiUsb3`` -- USB 2.0/3.0 +- ``Serial`` -- RS-232 / USB-serial +- ``Visa`` -- PyVISA for GPIB/USB/serial instruments +- ``Socket`` -- Raw TCP socket +- ``SiSim`` -- Simulation interface (`cocotb `_) .. automodule:: basil.TL.TransferLayer .. autoclass:: TransferLayer :members: + Hardware Layer (HL) ==================== -Implements drivers for basil modules and external devices. Drivers can reference other drivers within HL. +Implements drivers for FPGA firmware modules and external lab devices. Each entry in the ``hw_drivers`` list references a transfer layer by name via ``interface``, and FPGA modules are addressed via ``base_addr``. + +.. code-block:: yaml + + hw_drivers: + - name: gpio + type: gpio + interface: intf + base_addr: 0x30000 + size: 8 + + - name: spi + type: spi + interface: intf + base_addr: 0x20000 + + - name: seq + type: seq_gen + interface: intf + base_addr: 0x10000 + mem_size: 8192 + +Available FPGA module types are documented in detail on the :doc:`modules` page. Basil also includes drivers for a wide range of lab instruments, including power supplies, electrometers, oscilloscopes, function generators, climate chambers, chillers, mass flow controllers, temperature/humidity sensors, wafer probers, and Arduino-based peripherals. The full set of drivers can be found in `basil/HL/ `_. + +.. automodule:: basil.HL.HardwareLayer + +.. autoclass:: HardwareLayer + :members: Register Layer (RL) =================== -Implements Register Level Abstraction. Allow to user/control software to work on DUT registers without taking thinking about underlying levels. +Implements Register Level Abstraction. Allows user/control software to work on DUT registers without thinking about underlying levels. Each entry in the ``registers`` list references a hardware driver by name. + +.. code-block:: yaml + registers: + - name: SEQ + type: TrackRegister + hw_driver: seq + seq_width: 8 + seq_size: 8192 + tracks: + - name: CLK_INIT + position: 0 + - name: CLK_SAMP + position: 1 + +Available types (see `basil/RL/ `_): + +- ``StdRegister`` -- Standard bit-field register +- ``TrackRegister`` -- Sequencer track register +- ``FunctionalRegister`` -- Functional register + +.. automodule:: basil.RL.RegisterLayer + +.. autoclass:: RegisterLayer + :members: