Add documentation in nexys2 library

diff --git a/libraries/nexys2/epp_wb.vhd b/libraries/nexys2/epp_wb.vhd
index a8544961456ff038747b1a3189187055a9bd9403..a0596c0b9515d2bbc9809fe0323fc3aaafde9fe4 100644 (file)
--- 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 583945072764e054b98d6b8020003add69986faa..954af7eeb0a618105621985b236cb87b0fef4b1b 100644 (file)
--- 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 8ea6e6d6198ceb5ab958f898bd8b89d2c20b6540..ab56e95b81a8dfc6fba12947c59b3241da5e888f 100644 (file)
--- 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 acde1301a9f656218b1302ec38fb173e7c4d68ac..cadc0200086e20695d7cfb7fb44d96171e4387e8 100644 (file)
--- 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 45d900368ee07cd877f4d969b89ed36acc16d973..a08602f909c128b2e2fd119da40a5fe9ac64dbd2 100644 (file)
--- 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 cb9531b837e6053dcfc167f83e1bfd0f06a8a895..aec169d4fab89e463e42dfe97b9e5cb8498798ba 100644 (file)
--- 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 04b2c77ba796e648e4b9af3e1a04f803153643de..426a84193fb6822b286cd9628e49b13435422ff5 100644 (file)
--- 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 cddb12750e4718da7d2d09bf0216f307c0dacc9c..c2d56cd1c0a8b19e3bbee8b8803ae94ecb530f98 100644 (file)
--- 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 baa57514985433651241942a0adc0f551f5e9aa5..67b0a6cb2610a1336c6885cfcaa21be75153f586 100644 (file)
--- 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;