OpenOCD & Debugging over Intel JTAG / Altera USB Blaster

[NikLeberg]

Hi there! Thanks for this amazingly good documented risc-v processor!

I'm playing around with it on a Cyclone IV E and it's a blast. One thing that was a bummer is, that I'd need an additional JTAG or UART connection to load and or debug the system. I wanted to improve on that and found the excellent blog of tomverbeure that describes how the integrated JTAG primitive of the FPGA can be used.
Basically Intel FPGAs allows the user to use two special ir addresses (10 bit) for their own purpose. USR0 at 0x00c and USR1 at 0x00e. For those (and only those) addresses a user can supply the tdo signals that then are outputted from the FPGA.

OpenOCD does not care about the different ir address or even the size difference. One can set the new addresses simply with:

riscv set_ir dtmcs 0x00c
riscv set_ir dmi 0x00e

• Note: By using those two ir addresses we disable the whole virtual JTAG system (or also called sld) upon which Intel builds its Signal Tap or the NIOS II debugger for example. Support for this virtual JTAG system in OpenOCD was open-sourced by Intel but I have not managed to get it to work (some timing issues). It's a bit more complicated but would allow for more than just two dr chains and would not disable Signal Tap and similar.

To do this all I modified the existing neorv32_debug_dtm: removed bypass and idcode registers, changed addresses of dtmcs and dmi and (strangely) needed to move the tdo assignment out into an asynchronous process.

The modified `neorv32_debug_dtm` entity

library ieee;
use ieee.std_logic_1164.all;

entity neorv32_debug_dtm_intel is
  port (
    -- global control --
    clk_i             : in  std_ulogic; -- global clock line
    rstn_i            : in  std_ulogic; -- global reset line, low-active
    -- jtag connection --
    jtag_trst_i       : in  std_ulogic;
    jtag_tck_i        : in  std_ulogic;
    jtag_tdi_i        : in  std_ulogic;
    jtag_tdo_o        : out std_ulogic;
    jtag_tms_i        : in  std_ulogic;
    -- debug module interface (DMI) --
    dmi_req_valid_o   : out std_ulogic;
    dmi_req_ready_i   : in  std_ulogic; -- DMI is allowed to make new requests when set
    dmi_req_address_o : out std_ulogic_vector(05 downto 0);
    dmi_req_data_o    : out std_ulogic_vector(31 downto 0);
    dmi_req_op_o      : out std_ulogic_vector(01 downto 0);
    dmi_rsp_valid_i   : in  std_ulogic; -- response valid when set
    dmi_rsp_ready_o   : out std_ulogic; -- ready to receive response
    dmi_rsp_data_i    : in  std_ulogic_vector(31 downto 0);
    dmi_rsp_op_i      : in  std_ulogic_vector(01 downto 0)
  );
end neorv32_debug_dtm_intel;

architecture neorv32_debug_dtm_rtl of neorv32_debug_dtm is

  -- DMI Configuration (fixed!) --
  constant dmi_idle_c    : std_ulogic_vector(02 downto 0) := "000"; -- no idle cycles required
  constant dmi_version_c : std_ulogic_vector(03 downto 0) := "0001"; -- debug spec. version (0.13 & 1.0)
  constant dmi_abits_c   : std_ulogic_vector(05 downto 0) := "000110"; -- number of DMI address bits (6)

  -- tap JTAG signal synchronizer --
  type tap_sync_t is record
    -- internal --
    trst_ff     : std_ulogic_vector(2 downto 0);
    tck_ff      : std_ulogic_vector(2 downto 0);
    tdi_ff      : std_ulogic_vector(2 downto 0);
    tms_ff      : std_ulogic_vector(2 downto 0);
    -- external --
    trst        : std_ulogic;
    tck_rising  : std_ulogic;
    tck_falling : std_ulogic;
    tdi         : std_ulogic;
    tms         : std_ulogic;
  end record;
  signal tap_sync : tap_sync_t;

  -- tap controller - fsm --
  type tap_ctrl_state_t is (LOGIC_RESET, DR_SCAN, DR_CAPTURE, DR_SHIFT, DR_EXIT1, DR_PAUSE, DR_EXIT2, DR_UPDATE,
                               RUN_IDLE, IR_SCAN, IR_CAPTURE, IR_SHIFT, IR_EXIT1, IR_PAUSE, IR_EXIT2, IR_UPDATE);
  signal tap_ctrl_state : tap_ctrl_state_t;

  -- update trigger --
  type dr_update_trig_t is record
    valid        : std_ulogic;
    is_update    : std_ulogic;
    is_update_ff : std_ulogic;
  end record;
  signal dr_update_trig : dr_update_trig_t;

  -- intel USR0 and USR1 register address --
  constant adr_dtmcs_c : std_ulogic_vector(09 downto 0) := "0000001100"; -- USR0 0x00c
  constant adr_dmi_c : std_ulogic_vector(09 downto 0) := "0000001110"; -- USR1  0x00e

  -- tap registers --
  type tap_reg_t is record
    ireg             : std_ulogic_vector(09 downto 0); -- size = 10, default on all intel fpgas
    dtmcs, dtmcs_nxt : std_ulogic_vector(31 downto 0);
    dmi,   dmi_nxt   : std_ulogic_vector((6+32+2)-1 downto 0); -- 6-bit address + 32-bit data + 2-bit operation
  end record;
  signal tap_reg : tap_reg_t;

  -- debug module interface --
  type dmi_ctrl_state_t is (DMI_IDLE, DMI_READ_WAIT, DMI_READ, DMI_READ_BUSY,
                            DMI_WRITE_WAIT, DMI_WRITE, DMI_WRITE_BUSY);
  type dmi_ctrl_t is record
    state        : dmi_ctrl_state_t;
    dmihardreset : std_ulogic;
    dmireset     : std_ulogic;
    rsp          : std_ulogic_vector(01 downto 0); -- sticky response status
    rdata        : std_ulogic_vector(31 downto 0);
    wdata        : std_ulogic_vector(31 downto 0);
    addr         : std_ulogic_vector(05 downto 0);
  end record;
  signal dmi_ctrl : dmi_ctrl_t;

begin

  -- JTAG Input Synchronizer ----------------------------------------------------------------
  -- -------------------------------------------------------------------------------------------
  tap_synchronizer: process(rstn_i, clk_i)
  begin
    if (rstn_i = '0') then
      tap_sync.trst_ff <= (others => '0');
      tap_sync.tck_ff  <= (others => '0');
      tap_sync.tdi_ff  <= (others => '0');
      tap_sync.tms_ff  <= (others => '0');
    elsif rising_edge(clk_i) then
      tap_sync.trst_ff <= tap_sync.trst_ff(1 downto 0) & jtag_trst_i;
      tap_sync.tck_ff  <= tap_sync.tck_ff( 1 downto 0) & jtag_tck_i;
      tap_sync.tdi_ff  <= tap_sync.tdi_ff( 1 downto 0) & jtag_tdi_i;
      tap_sync.tms_ff  <= tap_sync.tms_ff( 1 downto 0) & jtag_tms_i;
    end if;
  end process tap_synchronizer;

  -- JTAG reset --
  tap_sync.trst <= '0' when (tap_sync.trst_ff(2 downto 1) = "00") else '1';

  -- JTAG clock edge --
  tap_sync.tck_rising  <= '1' when (tap_sync.tck_ff(2 downto 1) = "01") else '0';
  tap_sync.tck_falling <= '1' when (tap_sync.tck_ff(2 downto 1) = "10") else '0';

  -- JTAG test mode select --
  tap_sync.tms <= tap_sync.tms_ff(2);

  -- JTAG serial data input --
  tap_sync.tdi <= tap_sync.tdi_ff(2);


  -- Tap Control FSM ------------------------------------------------------------------------
  -- -------------------------------------------------------------------------------------------
  tap_control: process(rstn_i, clk_i)
  begin
    if (rstn_i = '0') then
      tap_ctrl_state <= LOGIC_RESET;
    elsif rising_edge(clk_i) then
      if (tap_sync.trst = '0') then -- reset
        tap_ctrl_state <= LOGIC_RESET;
      elsif (tap_sync.tck_rising = '1') then -- clock pulse (evaluate TMS on the rising edge of TCK)
        case tap_ctrl_state is -- JTAG state machine
          when LOGIC_RESET => if (tap_sync.tms = '0') then tap_ctrl_state <= RUN_IDLE;   else tap_ctrl_state <= LOGIC_RESET; end if;
          when RUN_IDLE    => if (tap_sync.tms = '0') then tap_ctrl_state <= RUN_IDLE;   else tap_ctrl_state <= DR_SCAN;     end if;
          when DR_SCAN     => if (tap_sync.tms = '0') then tap_ctrl_state <= DR_CAPTURE; else tap_ctrl_state <= IR_SCAN;     end if;
          when DR_CAPTURE  => if (tap_sync.tms = '0') then tap_ctrl_state <= DR_SHIFT;   else tap_ctrl_state <= DR_EXIT1;    end if;
          when DR_SHIFT    => if (tap_sync.tms = '0') then tap_ctrl_state <= DR_SHIFT;   else tap_ctrl_state <= DR_EXIT1;    end if;
          when DR_EXIT1    => if (tap_sync.tms = '0') then tap_ctrl_state <= DR_PAUSE;   else tap_ctrl_state <= DR_UPDATE;   end if;
          when DR_PAUSE    => if (tap_sync.tms = '0') then tap_ctrl_state <= DR_PAUSE;   else tap_ctrl_state <= DR_EXIT2;    end if;
          when DR_EXIT2    => if (tap_sync.tms = '0') then tap_ctrl_state <= DR_SHIFT;   else tap_ctrl_state <= DR_UPDATE;   end if;
          when DR_UPDATE   => if (tap_sync.tms = '0') then tap_ctrl_state <= RUN_IDLE;   else tap_ctrl_state <= DR_SCAN;     end if;
          when IR_SCAN     => if (tap_sync.tms = '0') then tap_ctrl_state <= IR_CAPTURE; else tap_ctrl_state <= LOGIC_RESET; end if;
          when IR_CAPTURE  => if (tap_sync.tms = '0') then tap_ctrl_state <= IR_SHIFT;   else tap_ctrl_state <= IR_EXIT1;    end if;
          when IR_SHIFT    => if (tap_sync.tms = '0') then tap_ctrl_state <= IR_SHIFT;   else tap_ctrl_state <= IR_EXIT1;    end if;
          when IR_EXIT1    => if (tap_sync.tms = '0') then tap_ctrl_state <= IR_PAUSE;   else tap_ctrl_state <= IR_UPDATE;   end if;
          when IR_PAUSE    => if (tap_sync.tms = '0') then tap_ctrl_state <= IR_PAUSE;   else tap_ctrl_state <= IR_EXIT2;    end if;
          when IR_EXIT2    => if (tap_sync.tms = '0') then tap_ctrl_state <= IR_SHIFT;   else tap_ctrl_state <= IR_UPDATE;   end if;
          when IR_UPDATE   => if (tap_sync.tms = '0') then tap_ctrl_state <= RUN_IDLE;   else tap_ctrl_state <= DR_SCAN;     end if;
          when others      => tap_ctrl_state <= LOGIC_RESET;
        end case;
      end if;
    end if;
  end process tap_control;


  -- Tap Register Access --------------------------------------------------------------------
  -- -------------------------------------------------------------------------------------------
  reg_access: process(rstn_i, clk_i)
  begin
    if (rstn_i = '0') then
      tap_reg.ireg   <= (others => '0');
      tap_reg.dtmcs  <= (others => '0');
      tap_reg.dmi    <= (others => '0');
      -- jtag_tdo_o     <= '0';
    elsif rising_edge(clk_i) then

      -- serial data input: instruction register --
      if (tap_ctrl_state = IR_SHIFT) then -- access phase
        if (tap_sync.tck_rising = '1') then -- [JTAG-SYNC] evaluate TDI on rising edge of TCK
          tap_reg.ireg <= tap_sync.tdi & tap_reg.ireg(tap_reg.ireg'left downto 1);
        end if;
      end if;

      -- serial data input: data register --
      if (tap_ctrl_state = DR_CAPTURE) then -- preload phase
        if (tap_reg.ireg = adr_dtmcs_c) then -- status register
          tap_reg.dtmcs <= tap_reg.dtmcs_nxt;
        elsif (tap_reg.ireg = adr_dmi_c) then -- register interface
          tap_reg.dmi   <= tap_reg.dmi_nxt;
        end if;
      elsif (tap_ctrl_state = DR_SHIFT) then -- access phase
        if (tap_sync.tck_rising = '1') then -- [JTAG-SYNC] evaluate TDI on rising edge of TCK
          if (tap_reg.ireg = adr_dtmcs_c) then
            tap_reg.dtmcs <= tap_sync.tdi & tap_reg.dtmcs(tap_reg.dtmcs'left downto 1);
          elsif (tap_reg.ireg = adr_dmi_c) then
            tap_reg.dmi   <= tap_sync.tdi & tap_reg.dmi(tap_reg.dmi'left downto 1);
          end if;
        end if;
      end if;

    end if;
  end process reg_access;

  -- serial data output --
  jtag_tdo_o <= tap_reg.dtmcs(0) when (tap_reg.ireg = adr_dtmcs_c) else
                tap_reg.dmi(0)   when (tap_reg.ireg = adr_dmi_c) else
                '0';

  -- DTM Control and Status Register (dtmcs) --
  tap_reg.dtmcs_nxt(31 downto 18) <= (others => '0'); -- unused
  tap_reg.dtmcs_nxt(17)           <= '0'; -- dmihardreset, always reads as zero
  tap_reg.dtmcs_nxt(16)           <= '0'; -- dmireset, always reads as zero
  tap_reg.dtmcs_nxt(15)           <= '0'; -- unused
  tap_reg.dtmcs_nxt(14 downto 12) <= dmi_idle_c; -- minimum number of idle cycles
  tap_reg.dtmcs_nxt(11 downto 10) <= tap_reg.dmi_nxt(1 downto 0); -- dmistat
  tap_reg.dtmcs_nxt(09 downto 04) <= dmi_abits_c; -- number of DMI address bits
  tap_reg.dtmcs_nxt(03 downto 00) <= dmi_version_c; -- version

  -- DMI register read access --
  tap_reg.dmi_nxt(39 downto 34) <= dmi_ctrl.addr; -- address
  tap_reg.dmi_nxt(33 downto 02) <= dmi_ctrl.rdata; -- read data
  tap_reg.dmi_nxt(01 downto 00) <= "11" when (dmi_ctrl.state /= DMI_IDLE) else (dmi_ctrl.rsp); -- status


  -- Debug Module Interface -----------------------------------------------------------------
  -- -------------------------------------------------------------------------------------------
  dmi_controller: process(rstn_i, clk_i)
  begin
    if (rstn_i = '0') then
      dmi_ctrl.state        <= DMI_IDLE;
      dmi_ctrl.dmihardreset <= '1';
      dmi_ctrl.dmireset     <= '1';
      dmi_ctrl.rsp          <= "00";
      dmi_ctrl.rdata        <= (others => '0');
      dmi_ctrl.wdata        <= (others => '0');
      dmi_ctrl.addr         <= (others => '0');
    elsif rising_edge(clk_i) then

      -- DMI status and control --
      dmi_ctrl.dmihardreset <= '0'; -- default
      dmi_ctrl.dmireset     <= '0'; -- default
      if (dr_update_trig.valid = '1') and (tap_reg.ireg = adr_dtmcs_c) then
        dmi_ctrl.dmireset     <= tap_reg.dtmcs(16);
        dmi_ctrl.dmihardreset <= tap_reg.dtmcs(17);
      end if;

      -- DMI interface arbiter --
      if (dmi_ctrl.dmihardreset = '1') then -- DMI hard reset
        dmi_ctrl.state <= DMI_IDLE;
      else
        case dmi_ctrl.state is

          when DMI_IDLE => -- waiting for new request
            if (dr_update_trig.valid = '1') and (tap_reg.ireg = adr_dmi_c) then
              dmi_ctrl.addr  <= tap_reg.dmi(39 downto 34);
              dmi_ctrl.wdata <= tap_reg.dmi(33 downto 02);
              if (tap_reg.dmi(1 downto 0) = "01") then -- read
                dmi_ctrl.state <= DMI_READ_WAIT;
              elsif (tap_reg.dmi(1 downto 0) = "10") then -- write
                dmi_ctrl.state <= DMI_WRITE_WAIT;
              end if;
            end if;

          when DMI_READ_WAIT => -- wait for DMI to become ready
            if (dmi_req_ready_i = '1') then
              dmi_ctrl.state <= DMI_READ;
            end if;

          when DMI_READ => -- trigger/start read access
            dmi_ctrl.state <= DMI_READ_BUSY;

          when DMI_READ_BUSY => -- pending read access
            if (dmi_rsp_valid_i = '1') then
              dmi_ctrl.rdata <= dmi_rsp_data_i;
              dmi_ctrl.state <= DMI_IDLE;
            end if;

          when DMI_WRITE_WAIT => -- wait for DMI to become ready
            if (dmi_req_ready_i = '1') then
              dmi_ctrl.state <= DMI_WRITE;
            end if;

          when DMI_WRITE => -- trigger/start write access
            dmi_ctrl.state <= DMI_WRITE_BUSY;

          when DMI_WRITE_BUSY => -- pending write access
            if (dmi_rsp_valid_i = '1') then
              dmi_ctrl.state <= DMI_IDLE;
            end if;

          when others => -- undefined
            dmi_ctrl.state <= DMI_IDLE;

        end case;
      end if;

      -- sticky response flags --
      if (dmi_ctrl.dmireset = '1') or (dmi_ctrl.dmihardreset = '1') then
        dmi_ctrl.rsp <= "00";
      else
        if (dmi_ctrl.state /= DMI_IDLE) and (dr_update_trig.valid = '1') and (tap_reg.ireg = adr_dmi_c) then -- access attempt while DMI is busy
          dmi_ctrl.rsp <= "11";
        elsif (dmi_ctrl.state = DMI_READ_BUSY) or (dmi_ctrl.state = DMI_WRITE_BUSY) then -- accumulate DMI response
          dmi_ctrl.rsp <= dmi_ctrl.rsp or dmi_rsp_op_i;
        end if;
      end if;

    end if;
  end process dmi_controller;

  -- trigger for UPDATE state --
  tap_update_trigger: process(rstn_i, clk_i)
  begin
    if (rstn_i = '0') then
      dr_update_trig.is_update_ff <= '0';
    elsif rising_edge(clk_i) then
      dr_update_trig.is_update_ff <= dr_update_trig.is_update;
    end if;
  end process tap_update_trigger;

  dr_update_trig.is_update <= '1' when (tap_ctrl_state = DR_UPDATE) else '0';
  dr_update_trig.valid     <= '1' when (dr_update_trig.is_update = '1') and (dr_update_trig.is_update_ff = '0') else '0';

  -- direct DMI output --
  dmi_req_valid_o   <= '1' when (dmi_ctrl.state = DMI_READ) or (dmi_ctrl.state = DMI_WRITE) else '0';
  dmi_req_op_o      <= tap_reg.dmi(1 downto 0);
  dmi_rsp_ready_o   <= '1' when (dmi_ctrl.state = DMI_READ_BUSY) or (dmi_ctrl.state = DMI_WRITE_BUSY) else '0';
  dmi_req_address_o <= dmi_ctrl.addr;
  dmi_req_data_o    <= dmi_ctrl.wdata;


end neorv32_debug_dtm_rtl;

Additionally the toplevel needs to instantiate the cycloneive_jtag entity (in my case) and hook up the user JTAG signals.

The toplevel entity

LIBRARY ieee;
USE ieee.std_logic_1164.ALL;
USE ieee.numeric_std.ALL;

LIBRARY neorv32;
USE neorv32.neorv32_package.ALL;

ENTITY top IS
    PORT (
        -- Global control --
        clk_i  : IN STD_ULOGIC; -- global clock, rising edge
        rstn_i : IN STD_ULOGIC; -- global reset, low-active, async
        -- GPIO --
        gpio_o : OUT STD_ULOGIC_VECTOR(7 DOWNTO 0); -- parallel output
        -- JTAG --
        altera_reserved_tck : IN STD_ULOGIC;
        altera_reserved_tms : IN STD_ULOGIC;
        altera_reserved_tdi : IN STD_ULOGIC;
        altera_reserved_tdo : OUT STD_ULOGIC
    );
END ENTITY top;

ARCHITECTURE top_arch OF top IS
    COMPONENT cycloneive_jtag
        GENERIC (
            lpm_type : STRING := "cycloneive_jtag"
        );
        PORT (
            tms         : IN STD_LOGIC := '0';
            tck         : IN STD_LOGIC := '0';
            tdi         : IN STD_LOGIC := '0';
            tdoutap     : IN STD_LOGIC := '0';
            tdouser     : IN STD_LOGIC := '0';
            tdo         : OUT STD_LOGIC;
            tmsutap     : OUT STD_LOGIC;
            tckutap     : OUT STD_LOGIC;
            tdiutap     : OUT STD_LOGIC;
            shiftuser   : OUT STD_LOGIC;
            clkdruser   : OUT STD_LOGIC;
            updateuser  : OUT STD_LOGIC;
            runidleuser : OUT STD_LOGIC;
            usr1user    : OUT STD_LOGIC
        );
    END COMPONENT;

    SIGNAL con_jtag_tck, con_jtag_tdi, con_jtag_tdo, con_jtag_tms : STD_LOGIC;
    SIGNAL con_gpio_o : STD_ULOGIC_VECTOR(63 DOWNTO 0);
BEGIN
    -- The Core Of The Problem ----------------------------------------------------------------
    -- -------------------------------------------------------------------------------------------
    neorv32_top_inst : neorv32_top
    GENERIC MAP(
        -- General --
        CLOCK_FREQUENCY   => 50000000, -- clock frequency of clk_i in Hz
        INT_BOOTLOADER_EN => true,     -- boot configuration: true = boot explicit bootloader; false = boot from int/ext (I)MEM
        -- On-Chip Debugger (OCD) --
        ON_CHIP_DEBUGGER_EN => true, -- implement on-chip debugger
        -- RISC-V CPU Extensions --
        CPU_EXTENSION_RISCV_C        => true, -- implement compressed extension?
        CPU_EXTENSION_RISCV_M        => true, -- implement mul/div extension?
        CPU_EXTENSION_RISCV_Zicsr    => true, -- implement CSR system?
        CPU_EXTENSION_RISCV_Zicntr   => true, -- implement base counters?
        CPU_EXTENSION_RISCV_Zifencei => true, -- implement instruction stream sync.? (required for the on-chip debugger)
        -- Internal Instruction memory --
        MEM_INT_IMEM_EN   => true,      -- implement processor-internal instruction memory
        MEM_INT_IMEM_SIZE => 16 * 1024, -- size of processor-internal instruction memory in bytes
        -- Internal Data memory --
        MEM_INT_DMEM_EN   => true,     -- implement processor-internal data memory
        MEM_INT_DMEM_SIZE => 8 * 1024, -- size of processor-internal data memory in bytes
        -- Processor peripherals --
        IO_GPIO_EN  => true, -- implement general purpose input/output port unit (GPIO)?
        IO_MTIME_EN => true  -- implement machine system timer (MTIME)?
    )
    PORT MAP(
        -- Global control --
        clk_i  => clk_i,  -- global clock, rising edge
        rstn_i => rstn_i, -- global reset, low-active, async
        -- JTAG on-chip debugger interface (available if ON_CHIP_DEBUGGER_EN = true) --
        jtag_trst_i => '1',          -- low-active TAP reset (optional)
        jtag_tck_i  => con_jtag_tck, -- serial clock
        jtag_tdi_i  => con_jtag_tdi, -- serial data input
        jtag_tdo_o  => con_jtag_tdo, -- serial data output
        jtag_tms_i  => con_jtag_tms, -- mode select
        -- GPIO (available if IO_GPIO_EN = true) --
        gpio_o => con_gpio_o -- parallel output
    );

    -- GPIO output --
    gpio_o <= con_gpio_o(7 DOWNTO 0);

    -- JTAG atom --
    jtag_inst : cycloneive_jtag
    PORT MAP(
        tms         => altera_reserved_tms,
        tck         => altera_reserved_tck,
        tdi         => altera_reserved_tdi,
        tdo         => altera_reserved_tdo,
        tdouser     => con_jtag_tdo,
        tmsutap     => con_jtag_tms,
        tckutap     => con_jtag_tck,
        tdiutap     => con_jtag_tdi,
        shiftuser   => OPEN, -- don't care, dtm has it's own JTAG FSM
        clkdruser   => OPEN,
        updateuser  => OPEN,
        runidleuser => OPEN,
        usr1user    => OPEN
    );

END ARCHITECTURE top_arch;

With this in place one can connect with the normal upstream OpenOCD by sourcing the interface/altera_usb_blaster.cfg script and the mentioned ir address configs. Loading executables and general debugging with gdb is working fine albeit a tad slow.

OpenOCD output

Open On-Chip Debugger 0.11.0
Licensed under GNU GPL v2
For bug reports, read
        http://openocd.org/doc/doxygen/bugs.html
Info : only one transport option; autoselect 'jtag'
Info : usb blaster interface using libftdi
Info : This adapter doesn't support configurable speed
Info : JTAG tap: cycloneive.tap tap/device found: 0x020f20dd (mfg: 0x06e (Altera), part: 0x20f2, ver: 0x0)
Info : datacount=1 progbufsize=2
Info : Disabling abstract command reads from CSRs.
Info : Exposing additional CSR 4032
Info : Examined RISC-V core; found 1 harts
Info :  hart 0: XLEN=32, misa=0x801104
Info : starting gdb server for cycloneive.neorv32 on 3333
Info : Listening on port 3333 for gdb connections
Target HALTED.
Ready for remote connections.

My main point for discussion is: How can I provide this information/system back to the community? I think it would be useful to the community. But I'd also guess that neorv32 is not supposed to depend on platform specific VHDL and won't incorporate these changes directly.

Would you approve a pr if some of these changes are made configurable with generics?
How and where should one document this system?

Bonus: If I'm not mistaken then Xilinx FPGAs have a similar system with the primitive BSCAN entity which could benefit from this as well. But I can't test it as I have no such FPGA.

[stnolting]

Hey Nik!

Thanks for this amazingly good documented risc-v processor!

Thank you very much! :D

I'm playing around with it on a Cyclone IV E and it's a blast. One thing that was a bummer is, that I'd need an additional JTAG or UART connection to load and or debug the system. I wanted to improve on that and found the excellent blog of tomverbeure that describes how the integrated JTAG primitive of the FPGA can be used.

This is really amazing! I was also playing with the internal JTAG primitives in Xilinx FPGAs. I tried openOCD'S "tunneling" concept, which is not very well documented... The "remapping" approach you are using seems to be much more straightforward (and way better documented 😉).

(strangely) needed to move the tdo assignment out into an asynchronous proces

Hmm, that's interesting... Maybe it is just a sampling issue on the JTAG adapter's side? openOCD provides a commend to "shift" the actual data point:

ftdi tdo_sample_edge rising|falling (see https://openocd.org/doc/html/Debug-Adapter-Configuration.html)

Anyway, great to see that it works!

My main point for discussion is: How can I provide this information/system back to the community? I think it would be useful to the community. But I'd also guess that neorv32 is not supposed to depend on platform specific VHDL and won't incorporate these changes directly.

I'm glad that you want to provide your setup!

Right, I'd prefer to keep the base repository / base core as platform-independent as possible. So, how about adding a new setup to https://github.com/stnolting/neorv32-setups? We already have some platform-specific setups there that also use FPGA-specifc IPs. What do you think about that?

[NikLeberg]

Thanks for the pointer to the tdo_sample_edge setting in OpenOCD. A quick test showed though that this is not supported by the Altera USB-Blaster that is (commonly) attached to the Intel FPGAs, or at least not with OpenOCD. I'll need to dig deeper..

I'm aware of the neorv32-setups repository. But skimming it I got more the feeling that it's a place for "packaging the neorv32 and setting the generics correctly". So no changes to the core rtl itself are applied. Or it that not true?

I see three approaches:

1. I could of course setup a script like create_project.tcl that just replaces the neorv32_debug_dtm.vhd with a platform-specific one.

2. Alternatively I could add a setup that uses the VHDL inbuilt configuration mechanic and replace the architecture. Something like:

configuration intel_jtag_config of neorv32_top is
  for neorv32_debug_dtm_inst
    for neorv32_debug_dtm_inst : neorv32_debug_dtm
      use entity work.debug_dtm_intel(debug_dtm_intel_arch);
    end for;
  end for;
end HA_Config;

3. With the generics approach I mentioned, the aim would be to allow support for other FPGA vendors as well. I'm thinking about some additional generics like JTAG_IR_SIZE which defaults to 5 or generics to set the addresses and disable idreg & bypass registers with generate statements. So no platform-specific stuff would be in there, only the knobs to configure the system from the toplevel/outside. But I could see this frankensteining the architecture a bit...

Do you have any favourite? Or remarks about the possible approaches?

[stnolting]

Thanks for the pointer to the tdo_sample_edge setting in OpenOCD. A quick test showed though that this is not supported by the Altera USB-Blaster that is (commonly) attached to the Intel FPGAs, or at least not with OpenOCD. I'll need to dig deeper..

Maybe we can remove the synchronous TDO output part from the default debug transfer module. I was also facing some sampling issues now and then (when using very high JTAG clock speeds), but I was not able to find the cause of this. So maybe my initial idea of making the output synchronous was wrong.

I'm aware of the neorv32-setups repository. But skimming it I got more the feeling that it's a place for "packaging the neorv32 and setting the generics correctly". So no changes to the core rtl itself are applied. Or it that not true?

Right... 😅 But there are also some setups that use FPGA-specific modules. For example, the setups for the Lattice iCE40UP use the large 64kB BRAMs for the instruction and data memories:

• https://github.com/stnolting/neorv32-setups/blob/main/radiant/UPduino_v3/neorv32_dmem.ice40up_spram.vhd
• https://github.com/stnolting/neorv32-setups/blob/main/radiant/UPduino_v3/neorv32_imem.ice40up_spram.vhd

1. I could of course setup a script like create_project.tcl that just replaces the neorv32_debug_dtm.vhd with a platform-specific one.

I like this concept as this is (basically) what we already do for the FPGA-specific setups in neorv32-setups.

2. Alternatively I could add a setup that uses the VHDL inbuilt configuration mechanic and replace the architecture. Something like:

I also played with such a mechanism some time ago... However, it feels like making things unnecessarily complicated (just my opinion). Furthermore, I am not sure if Vivado actually supports this.

3. With the generics approach I mentioned, the aim would be to allow support for other FPGA vendors as well. I'm thinking about some additional generics like JTAG_IR_SIZE which defaults to 5 or generics to set the addresses and disable idreg & bypass registers with generate statements. So no platform-specific stuff would be in there, only the knobs to configure the system from the toplevel/outside. But I could see this frankensteining the architecture a bit...

Hmm, it might be a good idea to provide some more flexibility for the default JTAG module. But I am not sure if exposing this additional configuration options via generics is a good idea, as it might make things even more complicated - we already have a lot of configuration generics 😅

Maybe we could make these things configurable by using file-local constants or even package-level constants?!

But maybe it would be more straightforward to just provide platform-tailored alternative JTAG tap modules (in neorv32-setups)... 🤔 I am not sure about this, but I am open for discussion.

[GideonZ]

Hey Stephan, This is really great! I would actually like to make use of this concept also for the Lattice ECP5, aside from the Cyclone V that I use. For the factory tester that I built, I also noticed that I have to generate the TDO in an unclocked process, which is luckily documented in the Lattice datasheet, but at the same time very annoying. It would be better if OpenOCD could be told that the TDO comes one clock cycle later. In any case, I totally agree with you to keep the code clean and platform independent. However, what could be done, and this is something I do in many of my own projects, is to have a directory 'portable' or 'platform_dependent', with modules with the same names but different implementations for different vendors. In most cases I also have a VHDL only implementation of these blocks for simulation purposes. Would this be an approach that you support? Best regards, Gideon Message ID: ***@***.*** com>

…

[NikLeberg]

Hi Gideon, even though you use a Lattice FPGA, could you link me to the datasheet you mention about the tdo needing to be in an unclocked process? I did not encounter a similar statement from Intel. Maybe their techniques are similar enough that I can work from there to help find the reason.

[stnolting]

For the factory tester that I built, I also noticed that I have to generate the TDO in an unclocked process

Ok, so we really should make it async. in the default JTAG module :D

In any case, I totally agree with you to keep the code clean and platform independent.

Totally agree. 👍

However, what could be done, and this is something I do in many of my own projects, is to have a directory 'portable' or 'platform_dependent', with modules with the same names but different implementations for different vendors.

I also agree here. Basically, this is what we (try to) do in neorv32-setups.

Hi Gideon, even though you use a Lattice FPGA, could you link me to the datasheet you mention about the tdo needing to be in an unclocked process?

I would also be interested in this, 😉

[GideonZ]

Wouldn't it be great if the VHDL built-in configuration mechanism would actually work? The problem you will run into when trying this is that with this method you generally compile all code, and your configuration selects which architecture to use. However, you are not able to compile, let's say, an architecture with a Lattice primitive in Quartus or Vivado. So your file set has to be different for different vendors. In this situation, using a configuration as a top level doesn't add any value. In the company where I work, if we need different architectures for one entity, we keep these in different files. For instance neorv32_debug_dtm.vhd is then the entity, and neorv32_debug_dtm-lattice_ecp5.vhd is then the vendor specific architecture. When creating your project, you simply include the correct architecture file. For simulation you take neorv32_debug_dtm-sim.vhd which links the bus functional model (BFM). Message ID: ***@***.***

…

com>

[stnolting]

For instance neorv32_debug_dtm.vhd is then the entity, and neorv32_debug_dtm-lattice_ecp5.vhd is then the vendor specific architecture.

I really like this concept. @umarcor already started to follow this concept by splitting the base core's IMEM & DMEM into entity-only-file and architecture-only-file.

[NikLeberg]

Thanks for your feedback @stnolting and @GideonZ. I think we have a workable concept:

• Separate the current neorv32_debug_dtm.vhd into entity-only neorv32_debug_dtm.entity.vhd and architecture-only neorv32_debug_dtm.default.vhd. This would follow the way the IMEM & DMEM are structured.
  • Shall the default.vhd file reside in its own subfolder (as with the mem folder) for example dtm?
  • I could open a pr for this. But depending on how it will be implemented I suspect it could break some build processes, especially if the default.vhd resides in a new dtm subfolder. @stnolting would it be ok if I open a pr and we fix the errors we notice in additional commits?
• Add a new setup to neorv32-setups and implement the custom Intel specific stuff there.

[stnolting]

I am still not sure about this... 😅

We did the separation of IMEM & DMEM into entity-only and architecture-only files for a set of reasons:

• these memories are mandatory for any setup
• some platforms/toolchains require different coding styles (in rtl/core/mem) in order to infer memory primitives (so we do not have to instantiate them); otherwise the synthesis tool might build those memories from LUTs + FFs, which is a no-go
• last but not least: easy "replacement" by FPGA-specific and optimized memory modules

In contrast, the JTAG TAP is more like an optional feature. The core will work even if this module is not implemented. And the plain-HDL module can be synthesized for any FPGA. An FPGA-specific TAP is just way more "comfortable" in this situation.

Don't get me wrong, I really like your setup! I am just concerned that by having more "configuration" options already at the file set level, we might cause beginners even more trouble than we already have.

Add a new setup to neorv32-setups and implement the custom Intel specific stuff there.

Absolutely! 👍 😃

[NikLeberg]

Don't get me wrong, I really like your setup! I am just concerned that by having more "configuration" options already at the file set level, we might cause beginners even more trouble than we already have.

Yes! I totally get it! 🙌 Keeping it simple is a very good reason against this entity-architecture separation.
I'll prepare only a neorv32-setups pr then. 🚂

To make it a bit more visible though, what do you think about adding something like this to the on_chip_debugger.adoc docs:

[NOTE]
Most FPGAs are programmed over a JTAG connection itself and support the use of it in user designs with instantiation of
platform-specific entities. So instead of two JTAG connections, one to program the FPGA and one to debug the core,
only one connection is needed. See the setups in [`neorv32-setups`](https://github.com/stnolting/neorv32-setups)
for example implementations.

I'll leave it up to you. 🙋‍♂️

[stnolting]

I'll prepare only a neorv32-setups pr then.

Awesome! Thank you very much! 👍

To make it a bit more visible though, what do you think about adding something like this to the on_chip_debugger.adoc docs:

Good idea! Do you want to do a PR? 😉

[agamez]

Hi!

I'm trying to follow some of the indications here to apply the same concept to Xilinx FPGAs. I'm having a lot of trouble, though, maybe because I'm also using the Digilent HS1 device, which I believe adds a little bit of complexity. It looks like I need to instantiate a BSCAN to JTAG converter (or maybe four, one per each USR? but how would I connect them?), but I haven't been able to have openOCD recognize the riscv core. I can't really provide any of the configurations I've tested because I've tried almost anything... so nothing I could provide would be very useful.

Do you guys have any indication on what should be the best way to proceed?

[stnolting]

Hey there!

I also had a closer look at the Xilinx-flavored approach. This is a little bit more complex. Basically, there a re two different approaches: tunneling using a single BSCAN module and replacement of the DTM's registers by individual BSCAN modules. I have experimented a little bit with the tunneling approach, but it is quite tricky (and badly documented).

This GH issue post provides pretty good resources: openhwgroup/core-v-mcu#117 (comment)