Using airhdl to Design a PN Sequence Checker for Analog Devices ADCs

Analog Devices Analog-to-Digital Converters like the 14-bit AD9645 feature built-in pseudo-random sequence generators, which are invaluable when it comes to checking that the ADC samples can be transmitted error-free to a receiving device, such as an FPGA, over a high-speed link. When bringing up a board featuring such an ADC-to-FPGA link, you want the ADC to output a known pattern so that you can check that the FPGA is indeed receiving the expected data.

For initial smoke tests, a fixed or a checkerboard pattern is fine, but in order to thoroughly check that your data transmission is working error-free, you will want to use more “difficult” test patterns like the PN9 and PN23 ones. Those are industry-standard sequences, which can easily be generated (and checked) using circuits called linear-feedback shift registers (LFSRs). In case you’re not familiar with them, LFSRs are just a chains of registers, with a few strategically placed XOR-type feedback taps.

The difference between the PN9 and the PN23 patterns is the sequence length. The PN9 sequence repeats every 2^9 – 1 = 511 cycles, whereas the PN23 sequence repeats every 2^23 – 1 = 8388607 cycles. This makes the PN23 sequence more suited for higher data rates, as the bit patterns repeat less often than with the PN9 sequence. Also, the PN23 will have longer sequences of contiguous zeros and ones than the PN9 sequence, which is of importance for AC-coupled links. In general, the PN23 sequence is considered more difficult than the PN9 sequence.

To bring up a board like the one shown below, with an AD9645 outputting samples over an LVDS link and an FPGA receiving them, I like to have the test pattern checker(s) built directly into the FPGA. In this article, I’ll show you how to implement such a test pattern checker using the LFSR components generated by the web-based airhdl code generator. We’ll be looking at the PN9 checker, but once you understand how it’s done, you’ll find it very easy to design your own checker for PN23 or other sequences.

Built-in test pattern checkers are great for board bring-ups.

First let’s look at the AD9645 datasheet to find out how to PN9 sequence (also called the PN sequence short) is defined:

PN sequence short description (source: AD9645 datasheet)

The description above is only part of the information we need to fully define the PN9 sequence. The missing part is the generator polynomial, which is given in another part of the datasheet as X^9 +X^5 +1. This is very mathematical way of describing a 9-bit shift-register with XOR feedback taps at bit positions 9 and 5 (using 1-based bit indexing).

The datasheet also gives the first words of the PN9 and PN23 sequences, which is super valuable information because it will allow us to easily check that we’re indeed generating the correct sequence:

The first words of the AD9645 PN sequences (source: AD9645 datasheet)

To create a PN9 checker, we’ll be generating the expected PN9 sequence internally in the FPGA and checking that the words we receive from the FPGA actually match the expected ones. Of course, we’ll need to somehow synchronize the internally-generated sequence with the received one. For that, we’ll just wait until the initial value shown in the table above (0x1FE0) is received and then we’ll let our internal sequence generator update on every received word.

The first step is to head over to airhdl.com. After you have logged in, select the LFSRs entry in the left sidebar to show the Linear-Feedback Shift Registers view, and click the round “+” action button to bring up the New LFSR dialog:

The airhdl New LFSR dialog

By setting the length to 9 bits and the feedback type to xor, airhdl will generate the following LFSR circuit. Note that based on the configured length of the LFSR (9 bits), airhdl automatically computes the correct positions of the feedback taps (5 and 9):

The generated 9-bit LFSR circuit

If you’re curious about the sequence of numbers that the circuit shown above generates, you can download the corresponding Python model and run it like this:

% python PN9_lfsr.py
1FF
1FE
1FC
1F8
1F0
1E0
1C1
183
107
00F
01E
03D
07B
0F7
1EF
1DF

The output above shows the first 16 states of this 9-bit LFSR (as we have said above, the sequence repeats every 2^9 – 1 = 511 cycles). This is not exactly the sequence that the AD9645 will output when placed in the PN9 test mode though, as the AD9645 is a 14-bit ADC and the PN9 circuit has a 9-bit word length. The AD9645 datasheet explains how to construct the 14-bit words from the LFSR output:

Source: AD9645 datasheet

Using the airhdl-generated Python model for our PN9 LFSR, let’s look at the first 14 output words in binary form (we can use the -r bin option for that):

% python PN9_lfsr.py -r bin 14
111111111
111111110
111111100
111111000
111110000
111100000
111000001
110000011
100000111
000001111
000011110
000111101
001111011
011110111

As explained above, we can construct the first 14-bit word of the PN9 sequence by concatenating the MSBs of the LFSR’s first 14 output words: 11_1111_1110_0000. In order to match the two’s complement sequence that is indicated in the datasheet, we also need to invert the MSB, which gives us 01_1111_1110_0000 = 0x1FE0. This nicely matches the initial value of the PN sequence short from the table above!

Of course, there is always the risk that this is pure coincidence and a bit of paranoia is always a good thing for a developer; so let’s compute one more output word. This time we’ll ask our Python model to output the first 28 LFSR output words, and take the MSBs of the last 14 words:

% python PN9_lfsr.py -r bin 28  
(...)
111101111
111011111
110111110
101111100
011111000
111110001
111100010
111000101
110001011
100010111
000101110
001011100
010111001
101110011

The corresponding output word, again obtained by concatenating the MSBs of the 9-bit LFSR states equals 11_1101_1111_0001. Inverting the MSB and converting the word to hexadecimal gives 0x1DF1, which matches the second output sample of the PN sequence short in the table above. At this point, the result being a pure coincidence is quite unlikely and we’ll assume that our algorithm works fine.

We now have a clear understanding of the algorithm for generating the 14-bit PN9 sequence. The next step is to design the corresponding checker circuit, using a hardware description language such as VHDL. As a starting point, we can download the VHDL package for our pn9 LFSR from the airhdl.com website. This package contains all the constants and a function we need to get us started:

The VHDL LFSR package generated by airhdl.com

In particular, the next_pn9_lfsr function allows us to compute the next LFSR state, given the current one.

The principle of operation for our checker is as follows:

  1. Receive the first 14-bit ADC output word, let’s call it adc_output[n].
  2. Using the next_pn9_lfsr function, compute the next expected ADC output word; let’s call it adc_expected[n+1].
  3. Wait for the next ADC output word, adc_output[n+1], and compare it to adc_expected[n+1]. If both values match, declare the test pattern checker synchronized and proceed with step 2. If there is a mismatch, the pattern checker is not synchronized and re-start at step 1.

The checker has two states: SYNC and TRACK. In the SYNC state, the checker waits until the PN9 initial value, which is given in the datasheet as 0x1FE0, appears on the data input. When that happens, the checker jumps into the TRACK state where it checks that every subsequent input word matches the next expected word from the PN9 sequence. As long as this is the case, the checker is considered synchronized and this is reflected by the pn9_ok output port being asserted high. If at any time an input word doesn’t match the next expected word, the checker immediately de-asserts its pn9_ok and jumps back into the SYNC state.

When doing hardware tests, you can connect the pn9_ok signal to a debug port of your FPGA design for easy monitoring using an oscilloscope. That way you can just trigger on falling edges of the pn9_ok signal to catch any bit errors, even transient ones.

The VHDL code for the PN9 checker, including a VUnit testbench, is available on the airhdl GitHub. We hope you’ll find this useful!

New Feature: ‘volatile’ Register Fields

Following several user requests, we added support for volatile register fields to the airhdl generator. Volatile fields are a special kind of read-write field whose write-value is set using an AXI4-Lite write transaction, and whose read-value originates from the user logic.

A typical application for volatile fields is time synchronization, where you want to read a counter value from the user logic, perform some adjustment on that value, and write it back to the hardware. Previously, this would have required two registers: a read-only register to read the current counter value, and a write-only register to update the counter value. Using the new volatile field, you can do it with just one counter register as shown in the diagram below:

An airhdl register bank with a volatile counter.value field allows reading a hardware counter and loading that counter to a new value through a single AXI4-Lite register.

The diagram above assumes a read-write counter register with a volatile value field, which looks like this in the airhdl user interface:

Reading from the counter register over the AXI4-Lite interface returns the value of the register bank’s counter_value_rd input port, which reflects the current counter value.

Writing a new value to the counter register over the AXI4-Lite interface updates the corresponding counter_value port of the register bank and pulses the counter_strobe port, which has the effect of loading the new value into the external counter component.

To create a volatile field within a read-write register or register array, activate the Volatile checkbox in the Create or Edit Field dialog:

Volatile fields are currently in beta and available to selected users. To get early access to this feature, please get in touch with support@airhdl.com.

New Generator: Linear-Feedback Shift Registers

Building on our vision to offer a comprehensive, web-based code generator for FPGA and ASIC developers, we are thrilled to announce the initial rollout of our Linear-Feedback Shift Register (LFSR) generator.

LFSRs are a class of pseudo-random number generators that can be implemented very efficiently in FPGA or ASIC technologies. As you can see in the figure below, a 7-bit LFSR is just a chain of 7 register stages with two XNOR feedback taps at positions 6 and 7. When initialized to zero, and provided with a clock signal, this marvelous little circuit will almost magically cycle through every possible state (except one) of the 7-bit word in a defined sequence that repeats itself every 127 cycles.

The micro-architecture of a 7-bit linear-feedback shift register

LFSRs have a single invalid state which—like a beetle stuck on its back—they cannot exit on their own. For XNOR feedback types LFSRs, the invalid state is all ones. Fortunately, the invalid word is not part of the LFSR’s natural sequence whose length is thus 2N-1 instead of 2N, N being the LFSR length in bits.

In digital electronics, LFSRs are often used to generate Pseudorandom Binary Sequences (PRBS) for testing serial or parallel communication links. PRBS-7 and PRBS-31 are two common kinds of Pseudorandom Binary Sequences, which can be generated respectively with 7-bit and 31-bit LFSRs. In the case of a serial communication link, the bit sequence is obtained from the MSB of the shift register (e.g. Q7 in the diagram above).

Implementing LFSRs in hardware is no rocket science. Still, since it’s not something that developers do every day, it can easily take an hour or two until the proper feedback taps and feedback type have been figured out and the circuit is finally working in simulation and in synthesis.

Using the new LFSR generator in airhdl, you can now design an LFSR in minutes and immediately download the VHDL or SystemVerilog implementation.

The new LFSR view in airhdl.com

For your convenience, airhdl also provides C and Python models of the LFSR so that you can easily display the sequence of numbers that the LFSR will cycle through. This can be super convenient when it comes to comparing numbers recorded with a logic analyzer with the expected sequence.

By default, the Python model outputs the first 16 words of the LFSR sequence in hexadecimal format:

$ python .\prbs7_lfsr.py
00
01
03
07
0F
1F
3F
7E
7D
7B
77
6F
5F
3E
7C
79

Using the optional count argument, you can tell the script how many output words to generate:

$ python .\prbs7_lfsr.py 4
00
01
03
07

The -i option allows you to start the sequence on an arbitrary initial value:

$ python .\prbs7_lfsr.py -i 0x3F 8
3F
7E
7D
7B
77
6F
5F
3E

This way you can easily convince yourself that it’s a very bad idea to initialize the LFSR to all ones (that’s the beetle stuck on its back):

$ python .\prbs7_lfsr.py -i 0x7F 8
7F
7F
7F
7F
7F
7F
7F
7F

We hope you’ll find the new LFSR generator useful and as always, make sure to let us know what you think!

Update (30-AUG-2023): Philip Abbey has generic VHDL implementation of LFSRs, which is described on his blog: Swapping Synchronous and LFSR Counters

Using the OSVVM AXI4 Verification Components to Simulate an airhdl Register Bank

Back in 2015, when I first attended Jim Lewis’ excellent Advanced VHDL Testbenches & Verification training in Bracknell (England), OSVVM was mostly a collection of VHDL packages that could be used to simplify the task of writing VHDL testbenches. At the time, OSVVM already included things like constrained random stimulus generation, scoreboards, functional coverage, and logging capabilities, but it wasn’t yet a one-stop shop for all your VHDL verification needs.

Fast forward a few years and thanks to Jim’s incredible work, OSVVM has become a world-class VHDL verification framework that is used by professional design teams around the world. Plus, when it comes to AXI4 verification, OSVVM probably has the most comprehensive set of verification components covering the AXI4, AXI4-Lite, and AXI4-Stream protocols.

To show you how simple an OSVVM-style testbench for an AXI4-Lite slave component can be, I have created a small project called osvvm-demo, which you can find on the airhdl GitHub. The testbench, whose architecture is depicted in the diagram below, consists of the following components:

  • The device under test (osvvm_regs), is an airhdl-generated register bank with two registers: a Control register that can be read and written from the bus, and a Status register that can only be read from the bus. I’ve given each of those registers a 16-bit field called value.
  • Axi4LiteManager is an OSVVM Verification Component (OSVVM has many of them) that acts as an AXI4-Lite bus master. It can issue AXI4-Lite read and write transactions to the device under test.
  • The Test Controller is the testbench orchestrator. It remote controls AxiLiteManager, instructing it to issue AXI4-Lite transactions, over a transaction interface that is implemented using record-typed VHDL signals.

Notice that the register bank output port corresponding to the Control register is looped back to the input port which drives the value of the Status register. This makes it very easy to check that both the Control and the Status registers are working as expected, by simply writing a value such as 0x1234 into the Control register and checking that the same value can be read back from the Status register.

Architecture of the osvvm-demo testbench

In a typical OSVVM fashion, there may be different incarnations of the Test Controller component, which OSVVM calls Test Cases, where each test case is implemented as a different architecture of the Test Controller entity. Although our demonstration testbench has only one test case, it’s usually a good idea to have several of them, such as a test case for normal operation and a test case for error conditions. I recommend keeping your test cases simple and focused on one particular aspect of the verification.

Our test case, which is called operation, has a single control process whose source code is shown below. What that process does is wait for initialization and reset to complete, write a magic value (0x1234) to the Control register using the Write procedure, read back the value of the Status register using the Read procedure, and check that both values are matching. When everything is done, it prints out a PASS/FAIL report on the simulator console.

    ControlProc : process
        variable addr           : unsigned(31 downto 0);
        variable wdata          : std_logic_vector(31 downto 0);
        variable rdata          : std_logic_vector(31 downto 0);
        variable actual_value   : std_logic_vector(STATUS_VALUE_BIT_WIDTH - 1 downto 0);
        variable expected_value : std_logic_vector(CONTROL_VALUE_BIT_WIDTH - 1 downto 0);
    begin
        -- Initialization of test
        SetAlertLogName("tb_osvvm_regs_operation");
        SetLogEnable(INFO, TRUE);
        SetLogEnable(DEBUG, FALSE);
        SetLogEnable(PASSED, FALSE);

        -- Wait for testbench initialization 
        wait for 0 ns;

        -- Wait for Design Reset
        wait until nReset = '1';
        ClearAlerts;

        Log("Write Control register");
        addr  := unsigned(REGS_BASEADDR) + CONTROL_OFFSET;
        wdata := x"00001234";
        Write(Axi4MemRec, std_logic_vector(addr), wdata);

        Log("Read Status register");
        Read(Axi4MemRec, std_logic_vector(addr), rdata);

        -- Extract field value from register value
        actual_value   := rdata(STATUS_VALUE_BIT_WIDTH + STATUS_VALUE_BIT_OFFSET - 1 downto STATUS_VALUE_BIT_OFFSET);
        expected_value := wdata(CONTROL_VALUE_BIT_OFFSET + CONTROL_VALUE_BIT_WIDTH - 1 downto CONTROL_VALUE_BIT_OFFSET);

        -- Compare write and read field values
        AffirmIfEqual(expected_value, actual_value, "read data");

        EndOfTestReports;
        std.env.stop;
        wait;
    end process ControlProc;

Notice the procedural and abstract coding style of the Test Case. We are not fiddling with signals here, only calling high-level procedures that do all the underlying protocols and bit-bouncing for us.

When it comes to compiling and simulating the testbench in a VHDL simulator, OSVVM has you covered as well. You can declare your source sets in the form of project (*.pro) files, which can recursively include project files from other directories. The top-level project file for this testbench is RunAllTests.pro.

The beauty of OSVVM project files is that they will work with virtually every capable VHDL simulator, without requiring any simulator-specific Tcl scripting.

To learn more about the OSVVM library, you can visit the OSVVM website or the project’s GitHub.

New Feature: Transfer Register Map Ownership

One of the many benefits of the airhdl Professional plans is the ability to share register maps with other airhdl users, either in a read-only way or with full editing priviledges. Technically, the user who first creates a register map becomes the owner of that register map, and that gives him or her special priviledges, such as being able the share the register map with other users, or to delete the register map from the database.

After a few years of working with airhdl (and possibly switching jobs in between), some of our users have expressed the need to transfer the ownership of one or more register maps to other airhdl users. Until now, that wasn’t possible in the user interface but the latest airhdl release now allows you to do that very easily, provided you have an active Professional subscription.

To transfer ownership of a register map to another airhdl user, click on the gear icon in the Register Map view and select Transfer Ownership in the drop down menu:

This brings up the Transfer Ownership dialog, which prompts you for the e-mail address of the user you’d like to transfer that register map to. The e-mail address should correspond to the one of a registered airhdl user:

Once you’ve entered the e-mail address, click the Transfer Ownership button to trigger the transfer.

Note that transferring ownership of a register map cannot be undone. Please make sure to double-check the e-mail address of the destination user before clicking the Transfer Ownership button.

How to Import 100 Registers from a Text File to airhdl

One of our users recently asked how he could import a list of 100 registers into airhdl without having to create every single register by hand in the user interface. He had the names of the registers available in a text file, one name per line:

REG_0
REG_1
REG_2

REG_99

Subscribers to the airhdl Professional CL plan can import register maps into airhdl by uploading a JSON file whose structure is described in the documentation.

To help import the user’s registers into airhdl, we have created a small Python script that transforms the user’s text file into an airhdl register map JSON object. The script, which is called regs2json.py, is available on our GitHub page. It can be used as follows:

python regs2user.py registers.txt map_name

Where registers.txt is the path to the text file containing the register names and map_name is the name of the register map to be created. The script generates an output file called out.json in the current working directory, which looks like this:

{
  "jsonVersion": 2,
  "registerMap": {
    "name": "my_map",
    "description": "",
    "width": 32,
    "baseAddress": 0,
    "addrWidthBits": 32,
    "revision": 1,
    "generateRecordPorts": false,
    "registers": [
      {
        "type": "Register",
        "name": "REG_0",
        "description": "",
        "access": "READ_WRITE",
        "addressOffset": 0,
        "size": 32,
        "fields": [
          {
            "name": "value",
            "description": "",
            "bitWidth": 32,
            "bitOffset": 0,
            "reset": 0,
            "selfClear": false
          }
        ]
      },
      ...
    ]
  }
}

The last step is to upload the generated out.json file to the airhdl web application using the Upload button in the Register Maps view:

This creates a new register map with the name that we have specified when executing the regs2json.py script (in this example, my_map):

The out.json file can also be used as an input to the airhdl command line generator, which can generate all the airhdl output products (VHDL and SystemVerilog RTL code, testbenches, C header and documentation) locally on the user’s machine:

java -jar airhdl-cl.jar out.json

As we have seen, all it takes is a few lines of Python code to turn a text file into an airhdl register map JSON object that can be either uploaded to the airhdl web application to create a new register map, or used locally as an input to the airhdl command line generator.

Shiny and New: the SPI to AXI4-Lite Bridge

Following a user request, we have created an open-source SPI to AXI4-Lite bridge which allows you to access register banks generated by airhdl.com from any microcontroller over a Serial Peripheral Interface (SPI).

SPI to AXI4-Lite Bridge

The bridge is available in both VHDL and SystemVerilog versions, and comes as a single, self-contained file with no additional dependencies. It supports all four combinations of SPI clock phases and polarities, also known as SPI modes.

The source-code repository includes a VHDL testbench that was developed using the Open-Source VHDL Verification Methodology (OSVVM). The simulation requires a VHDL-2008 capable simulator such as Aldec Riviera-Pro.

We are releasing the SPI to AXI4-Lite bridge under a permissive Apache License 2.0, which allows you to use it in commercial applications.

Please feel free to try it out and let us know what you think!

How to initialize 30,000 coefficients over AXI4 using airhdl (and a bit of custom logic)

One of our airhdl users recently asked how he could use an airhdl-generated register bank to initialize the 30,000 (or so) weights of a neural network circuit.

When dealing with such large numbers of coefficients, it’s not practical to create a dedicated addressable register for every coefficient as the corresponding logic becomes too large and and slow. What you can do instead is to either store them in a memory, which is very efficient in terms of logic resources, or in a register chain in case you need to concurrent access to the coefficients.

The memory option is quite straightforward as airhdl allows you to create memory-typed register map elements, which you can connect to a block memory components as shown in this article. The downside of this option is that you can only access one element at a time from the user logic.

In the register chain option, the coefficients are stored in the flip-flops of a large shift register, which gives you concurrent access to all of the elements. To implement the register chain, you will first need to create a write-only register (e.g. weight) with a value field corresponding to the width of your coefficients (e.g. 10 bits):

Consequently, the following user output ports are exposed in the generated RTL component:

weight_strobepulsed every time a new value is written to the weight register
weight_valuethe current value of the weight.value register field

You then connect those ports to the input of a 30,000-deep shift register that is part of the user logic, with the weight_strobe acting as a clock-enable to the shift register. To initialize the shift register and thus your coefficients, all you have to do is write the 30,000 coefficients in a row over the AXI4 interface to the weight register using a fixed address pattern. Make sure not to use an incrementing address pattern as there is really only one adressable register in the register bank.

One issue you may run into while implementing this circuit is the high fanout on the weight_strobe signal, which can cause excessive delays and thus timing violations. Here are two ideas to improve the situation:

  • Split the register chain into several smaller chain, each connected to a dedicated register.
  • Route the weight_strobe net through a global buffer like a Xilinx BUFG or BUFR. This adds a fixed delay to the net but in exchange the signal can then be distributed with low skew to a large number of cells.

We hope you will find this useful. To stay informed about what’s going on at airhdl, please follow us on twitter or on LinkedIn.

New Feature: Auto-Compute Register Offsets

Following several user requests, airhdl now offers a way to auto-compute the register offsets within a register map. By clicking the Auto-compute register offsets button, airhdl automatically re-computes the address offsets of all the registers in the register map, starting at zero, and ensuring that there are no address gaps between them.

Auto-compute register offsets button

We hope you’ll find this feature useful. If you use airhdl, please make sure check out our Feature Requests board where you can submit new ideas for improvement and/or vote for existing proposals.

New Feature: Markdown Generator

Following a user request, airhdl is introducing a new a Markdown documentation generator. You can now choose to download your register map documentation in either HTML or Markdown formats:

In case you haven’t come across Markdown before, it’s lightweight, text-based markup format that was initially proposed by John Gruber. You can find a description of the Markdown syntax here.

Markdown being such a popular markup language, it is well supported by source code editors such as Visual Studio Code or Eclipse. Besides that, there are many other tools for processing Markdown documents.

For example, you can use the Python grip package to render a Markdown document in a web browser:

python grip my_regs.md

Or you can use pandoc to convert a Markdown document to a PDF file:

pandoc -o my_regs.pdf my_regs.md

We hope that you’ll find the new Markdown documentation generator useful!