From: rs <> Date: Sat, 28 Jun 2025 04:53:56 +0000 (-0500) Subject: Add documentation in nexys2 library X-Git-Url: https://git.the-white-hart.net/?a=commitdiff_plain;h=4131df3f00ad6400c84b1c0c47653d04bb71c29f;p=vhdl Add documentation in nexys2 library --- diff --git a/libraries/nexys2/epp_wb.vhd b/libraries/nexys2/epp_wb.vhd index a854496..a0596c0 100644 --- a/libraries/nexys2/epp_wb.vhd +++ b/libraries/nexys2/epp_wb.vhd @@ -1,3 +1,30 @@ +-------------------------------------------------------------------------------- +-- epp_wb - Digilent EPP to Wishbone bridge +-- +-- Connects to a Digilent EPP bus (one of Digilent's USB interface methods) and +-- converts EPP transactions into Wishbone bus transactions. +-------------------------------------------------------------------------------- +-- WISHBONE DATASHEET +-- +-- Wishbone specification used: Rev B.3 +-- Interface type: master +-- Port size: 8-bit +-- Operand sizes: 8-bit +-- Endianness: undefined (port size same as granularity) +-- Data transfer sequence: undefined +-- Clock constraints: none +-- Signals: +-- * rst_i +-- * clk_i +-- * cyc_o +-- * stb_o +-- * we_o +-- * ack_i +-- * adr_o (8-bit) +-- * dat_i (8-bit) +-- * dat_o (8-bit) +-------------------------------------------------------------------------------- + library ieee; use ieee.std_logic_1164.all; @@ -14,13 +41,13 @@ entity epp_wb is -- Wishbone bus signals rst_i: in std_logic; clk_i: in std_logic; - adr_o: out std_logic_vector(7 downto 0); - dat_i: in std_logic_vector(7 downto 0); - dat_o: out std_logic_vector(7 downto 0); cyc_o: out std_logic; stb_o: out std_logic; we_o: out std_logic; - ack_i: in std_logic + ack_i: in std_logic; + adr_o: out std_logic_vector(7 downto 0); + dat_i: in std_logic_vector(7 downto 0); + dat_o: out std_logic_vector(7 downto 0) ); end epp_wb; diff --git a/libraries/nexys2/host_ctrl.vhd b/libraries/nexys2/host_ctrl.vhd index 5839450..954af7e 100644 --- a/libraries/nexys2/host_ctrl.vhd +++ b/libraries/nexys2/host_ctrl.vhd @@ -1,14 +1,185 @@ -------------------------------------------------------------------------------- --- Registers: +-- host_ctrl - Generic host control interface for Nexys2 board -- --- 0: CTRL --- 1: MBOX_FLAGS --- 2: MBOX_VALUE --- 3: SW(R)/LED(W) --- 4: SSEG0 --- 5: SSEG1 --- 6: SSEG2 --- 7: SSEG3 +-- Drop-in module that rovides host computer access to onboard memory, switches, +-- LEDs, and signalling to any other device programmed to the FPGA +-------------------------------------------------------------------------------- +-- Registers (Host EPP interface): +-- +-- +---+---+---+---+---+---+---+---+ +-- | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +-- +---+---+---+---+---+---+---+---+ +-- 0x0 |RST|MEM| | CTRL +-- +---+---+-----------------------+ +-- 0x1 | MBOX_FLAGS(W1S) | +-- +-------------------------------+ +-- 0x2 | MBOX_VALUE | +-- +-------------------------------+ +-- 0x3 | SW(R)/LED(W) | +-- +-------------------------------+ +-- 0x4 | SSEG0 | +-- +-------------------------------+ +-- 0x5 | SSEG1 | +-- +-------------------------------+ +-- 0x6 | SSEG2 | +-- +-------------------------------+ +-- 0x7 | SSEG3 | +-- +---+---+---+---+---+---+---+---+ +-- 0x8 |FLS|FLS| | | |RAM|RAM|AUT| MEM_CTRL +-- |RST|CS | | | |CS |CRE|CNT| +-- +---+---+---+---+---+---+---+---+ +-- 0x9 | ADDR_L | (BIT 0 IGNORED) +-- +-------------------------------+ +-- 0xa | ADDR_M | +-- +-------------------------------+ +-- 0xb | ADDR_H | +-- +-------------------------------+ +-- 0xc | DATA_L | (TRANSFER TRIGGER) +-- +-------------------------------+ +-- 0xd | DATA_H | +-- +-------------------------------+ +-- 0xe | (RESERVED) | +-- +-------------------------------+ +-- 0xf | (RESERVED) | +-- +-------------------------------+ +-- +-- CTRL +-- Read-only +-- RST - Active-high reset signal to device +-- MEM - 1: Host computer controls onboard memory over USB-EPP interface +-- 0: Device controls onboard memory +-- +-- MBOX_FLAGS +-- Write-one-to-clear +-- Eight independant signalling bits from the host computer to the device, +-- intended for use as interrupt signals +-- +-- MBOX_VALUE +-- Eight-bit value readable and writable by both host and device, intended for +-- small data transfers and signalling between host and device +-- +-- SW(R)/LED(W) +-- Readable and writable by both host and device +-- Reads return the current positions of the switches on the Nexys2 board +-- Writes set the state of the LEDs above the switches on the Nexys2 board +-- +-- SSEGn +-- Readable and writable by both host and device +-- SSEG0 is the right-most (least-significant) seven-segment display +-- SSEG3 is the left-most (most-significant) seven-segment display +-- Values are active-low (segment is turned on when written to 0) +-- Bit to segment mapping: +-- (0) +-- ------ +-- | | +-- (5)| |(1) +-- | (6) | +-- ------ +-- | | +-- (4)| |(2) +-- | | +-- ------ o(7) +-- (3) +-- +-- MEM_CTRL +-- FLS_RST - Wired to the onboard flash reset signal, active low +-- FLS_CS - When clear, transfers go to the onboard flash +-- RAM_CS - When clear, transfers go to the onboard RAM +-- RAM_CRE - Wired to the onboard RAM's CRE signal, active high +-- AUT_CNT - Address auto-count, when set, increments addr by 2 each transaction +-- Behavior when both FLS_CS and RAM_CS are clear is undefined +-- +-- ADDR_L/M/H +-- 24-bit address used for the memory transaction, treated as a byte-address, +-- ADDR_L(0) is ignored +-- +-- DATA_L/H +-- 16-bit value read from or written to memory +-- Reads/writes to DATA_L trigger a transaction: +-- - For reads, read DATA_L first then DATA_H +-- - For writes, write DATA_H first then DATA_L +-- +-------------------------------------------------------------------------------- +-- Registers (Device Wishbone interface): +-- +-- +---+---+---+---+---+---+---+---+ +-- | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +-- +---+---+---+---+---+---+---+---+ +-- 0 |RST|MEM| | CTRL(RO) +-- +---+---+-----------------------+ +-- 1 | MBOX_FLAGS(W1C) | +-- +-------------------------------+ +-- 2 | MBOX_VALUE | +-- +-------------------------------+ +-- 3 | SW(R)/LED(W) | +-- +-------------------------------+ +-- 4 | SSEG0 | +-- +-------------------------------+ +-- 5 | SSEG1 | +-- +-------------------------------+ +-- 6 | SSEG2 | +-- +-------------------------------+ +-- 7 | SSEG3 | +-- +-------------------------------+ +-- +-- CTRL +-- Read-only +-- RST - Active-high reset signal to device +-- MEM - 1: Host computer controls onboard memory over USB-EPP interface +-- 0: Device controls onboard memory +-- +-- MBOX_FLAGS +-- Write-one-to-clear +-- Eight independant signalling bits from the host computer to the device, +-- intended for use as interrupt signals +-- +-- MBOX_VALUE +-- Eight-bit value readable and writable by both host and device, intended for +-- small data transfers and signalling between host and device +-- +-- SW(R)/LED(W) +-- Readable and writable by both host and device +-- Reads return the current positions of the switches on the Nexys2 board +-- Writes set the state of the LEDs above the switches on the Nexys2 board +-- +-- SSEGn +-- Readable and writable by both host and device +-- SSEG0 is the right-most (least-significant) seven-segment display +-- SSEG3 is the left-most (most-significant) seven-segment display +-- Values are active-low (segment is turned on when written to 0) +-- Bit to segment mapping: +-- (0) +-- ------ +-- | | +-- (5)| |(1) +-- | (6) | +-- ------ +-- | | +-- (4)| |(2) +-- | | +-- ------ o(7) +-- (3) +-- +-------------------------------------------------------------------------------- +-- WISHBONE DATASHEET +-- +-- Wishbone specification used: Rev B.3 +-- Interface type: device +-- Port size: 8-bit +-- Operand sizes: 8-bit +-- Endianness: undefined (port size same as granularity) +-- Data transfer sequence: undefined +-- Clock constraints: none +-- Signals: +-- * rst_i +-- * clk_i +-- * d_cyc_i (CYC_I) +-- * d_stb_i (STB_I) +-- * d_we_i (WE_I) +-- * d_ack_o (ACK_O) +-- * d_adr_i (ADR_I, 3-bit) +-- * d_dat_i (DAT_I, 8-bit) +-- * d_dat_o (DAT_O, 8-bit) -------------------------------------------------------------------------------- library ieee; diff --git a/libraries/nexys2/host_regs.vhd b/libraries/nexys2/host_regs.vhd index 8ea6e6d..ab56e95 100644 --- a/libraries/nexys2/host_regs.vhd +++ b/libraries/nexys2/host_regs.vhd @@ -1,3 +1,49 @@ +-------------------------------------------------------------------------------- +-- host_regs - host control register file for Nexys2 +-- +-- Intended to be used by "host_ctrl" entity +-------------------------------------------------------------------------------- +-- WISHBONE DATASHEET (Host-side) +-- +-- Wishbone specification used: Rev B.3 +-- Interface type: device +-- Port size: 8-bit +-- Operand sizes: 8-bit +-- Endianness: undefined (port size same as granularity) +-- Data transfer sequence: undefined +-- Clock constraints: none +-- Signals: +-- * rst_i +-- * clk_i +-- * h_cyc_i (CYC_I) +-- * h_stb_i (STB_I) +-- * h_we_i (WE_I) +-- * h_ack_o (ACK_O) +-- * h_adr_i (ADR_I, 3-bit) +-- * h_dat_i (DAT_I, 8-bit) +-- * h_dat_o (DAT_O, 8-bit) +-------------------------------------------------------------------------------- +-- WISHBONE DATASHEET (Device-side) +-- +-- Wishbone specification used: Rev B.3 +-- Interface type: device +-- Port size: 8-bit +-- Operand sizes: 8-bit +-- Endianness: undefined (port size same as granularity) +-- Data transfer sequence: undefined +-- Clock constraints: none +-- Signals: +-- * rst_i +-- * clk_i +-- * d_cyc_i (CYC_I) +-- * d_stb_i (STB_I) +-- * d_we_i (WE_I) +-- * d_ack_o (ACK_O) +-- * d_adr_i (ADR_I, 3-bit) +-- * d_dat_i (DAT_I, 8-bit) +-- * d_dat_o (DAT_O, 8-bit) +-------------------------------------------------------------------------------- + library ieee; use ieee.std_logic_1164.all; use ieee.numeric_std.all; diff --git a/libraries/nexys2/mem_mux.vhd b/libraries/nexys2/mem_mux.vhd index acde130..cadc020 100644 --- a/libraries/nexys2/mem_mux.vhd +++ b/libraries/nexys2/mem_mux.vhd @@ -1,3 +1,9 @@ +-------------------------------------------------------------------------------- +-- mem_mux - multiplexer for access to Nexys2 onboard memory +-- +-- Intended to be used by "host_ctrl" entity +-------------------------------------------------------------------------------- + library ieee; use ieee.std_logic_1164.all; diff --git a/libraries/nexys2/mem_wb8_0.vhd b/libraries/nexys2/mem_wb8_0.vhd index 45d9003..a08602f 100644 --- a/libraries/nexys2/mem_wb8_0.vhd +++ b/libraries/nexys2/mem_wb8_0.vhd @@ -1,3 +1,30 @@ +-------------------------------------------------------------------------------- +-- mem_wb8_0 - Simple, non-caching 8-bit interface to Nexys2 onboard memory +-- +-- When adr_i(24) is clear, accesses go to flash +-- When adr_i(24) is set, accesses go to RAM +-------------------------------------------------------------------------------- +-- WISHBONE DATASHEET +-- +-- Wishbone specification used: Rev B.3 +-- Interface type: device +-- Port size: 8-bit +-- Operand sizes: 8-bit +-- Endianness: undefined (port size same as granularity) +-- Data transfer sequence: undefined +-- Clock constraints: none +-- Signals: +-- * rst_i +-- * clk_i +-- * cyc_i +-- * stb_i +-- * we_i +-- * ack_o +-- * adr_i (25-bit) +-- * dat_i (8-bit) +-- * dat_o (8-bit) +-------------------------------------------------------------------------------- + library ieee; use ieee.std_logic_1164.all; use ieee.std_logic_misc.all; diff --git a/libraries/nexys2/mem_wb_basic.vhd b/libraries/nexys2/mem_wb_basic.vhd index cb9531b..aec169d 100644 --- a/libraries/nexys2/mem_wb_basic.vhd +++ b/libraries/nexys2/mem_wb_basic.vhd @@ -1,4 +1,6 @@ -------------------------------------------------------------------------------- +-- mem_wb_basic - Wishbone-bus interface for out-of-band memory programming +-------------------------------------------------------------------------------- -- Registers: -- -- +---+---+---+---+---+---+---+---+ @@ -23,7 +25,26 @@ -- +-------------------------------+ -- -------------------------------------------------------------------------------- - +-- WISHBONE DATASHEET +-- +-- Wishbone specification used: Rev B.3 +-- Interface type: device +-- Port size: 8-bit +-- Operand sizes: 8-bit +-- Endianness: undefined (port size same as granularity) +-- Data transfer sequence: undefined +-- Clock constraints: none +-- Signals: +-- * rst_i +-- * clk_i +-- * cyc_i +-- * stb_i +-- * we_i +-- * ack_o +-- * adr_i (3-bit) +-- * dat_i (8-bit) +-- * dat_o (8-bit) +-------------------------------------------------------------------------------- library ieee; use ieee.std_logic_1164.all; @@ -127,7 +148,7 @@ begin begin if rising_edge(clk_i) then if rst_i = '1' then - ctrl_reg <= "11001000"; + ctrl_reg <= "11000100"; addr_reg <= (others => '0'); data_reg <= (others => '0'); cur_state_reg <= S_READY; diff --git a/libraries/nexys2/seven_seg_hex.vhd b/libraries/nexys2/seven_seg_hex.vhd index 04b2c77..426a841 100644 --- a/libraries/nexys2/seven_seg_hex.vhd +++ b/libraries/nexys2/seven_seg_hex.vhd @@ -1,3 +1,7 @@ +-------------------------------------------------------------------------------- +-- seven_seg_hex - maps 4-bit binary values to seven-segment display +-------------------------------------------------------------------------------- + library ieee; use ieee.std_logic_1164.all; use ieee.numeric_std.all; diff --git a/libraries/nexys2/seven_seg_mux.vhd b/libraries/nexys2/seven_seg_mux.vhd index cddb127..c2d56cd 100644 --- a/libraries/nexys2/seven_seg_mux.vhd +++ b/libraries/nexys2/seven_seg_mux.vhd @@ -1,3 +1,7 @@ +-------------------------------------------------------------------------------- +-- seven_seg_mux - drives a multiplexed seven-segment display with four elements +-------------------------------------------------------------------------------- + library ieee; use ieee.std_logic_1164.all; use ieee.numeric_std.all; diff --git a/libraries/nexys2/wishbone_debugger.vhd b/libraries/nexys2/wishbone_debugger.vhd index baa5751..67b0a6c 100644 --- a/libraries/nexys2/wishbone_debugger.vhd +++ b/libraries/nexys2/wishbone_debugger.vhd @@ -1,5 +1,5 @@ -------------------------------------------------------------------------------- --- Nexys2 Manual Wishbone Bus Master +-- wishbone-debugger - Nexys2 Manual Wishbone Bus Master -- -- The purpose is to provide a ready-made harness to manually test and debug -- Wishbone bus devices by hand on a Nexys2 board @@ -37,6 +37,26 @@ -- -- The LEDs on the Nexys2 board are left available for flags put out by the DUT -------------------------------------------------------------------------------- +-- WISHBONE DATASHEET +-- +-- Wishbone specification used: Rev B.3 +-- Interface type: master +-- Port size: 8-bit +-- Operand sizes: 8-bit +-- Endianness: undefined (port size same as granularity) +-- Data transfer sequence: undefined +-- Clock constraints: none +-- Signals: +-- * rst_i +-- * clk_i +-- * cyc_o +-- * stb_o +-- * we_o +-- * ack_i +-- * adr_o (8-bit) +-- * dat_i (8-bit) +-- * dat_o (8-bit) +-------------------------------------------------------------------------------- library ieee; use ieee.std_logic_1164.all;