Documentation, step 1
authorMalte S. Stretz <mss@apache.org>
Sun, 17 May 2009 14:30:18 +0000 (16:30 +0200)
committerMalte S. Stretz <mss@apache.org>
Sun, 17 May 2009 14:30:18 +0000 (16:30 +0200)
bos2k9.vhd
fhw_spi/spi_counter_e.vhd
fhw_spi/spi_engine_e.vhd
fhw_spi/spi_master.vhd
fhw_spi/spi_shifter_e.vhd
fhw_spi/spi_starter_e.vhd
fhw_spi_t/spi_counter_t.vhd
fhw_spi_t/spi_master_all_t.vhd
fhw_spi_t/spi_master_t.vhd
fhw_spi_t/spi_shifter_t.vhd
fhw_spi_t/spi_starter_t.vhd

index 5469a5e..66bcf86 100644 (file)
@@ -25,7 +25,7 @@ architecture board of bos2k9 is
 
   component spi_master 
     generic(
-      clk_div    : positive := 100;
+      clk_div    : positive := 8;
       data_width : positive := data_width;
       spi_mode   : integer range 0 to 3 := 0);
     port(
index 5ec3d1c..13f8775 100644 (file)
@@ -1,8 +1,24 @@
+-----------------------------------------------------------------------
+-- Copyright (c) 2009 Malte S. Stretz <http://msquadrat.de> 
+--
+-- This is a helper entity implementing a counter. It is driven by
+-- `clock` on the edge specified by the generic `edge` (low means
+-- falling edge, high means rising). `reset` is active high.
+--
+-- While `enable` is high, it counts the number of ticks given via the
+-- generic `count`. When reached, `done` is high for exactly one
+-- `clock` (even if `enable` goes low).
+--
+-- It is possible to override and reset the counter by driving
+-- `override` high; `done` is high while `override` is high.
+-----------------------------------------------------------------------
+-- This entity is part of the following library:
+-- pragma library fhw_spi
+library fhw_spi;
+
 library ieee;
 use ieee.std_logic_1164.all;
 
------------------------------------------------------------------------
-
 entity spi_counter_e is
   generic(
     count : positive;
index 690e15d..6b79b9d 100644 (file)
@@ -1,9 +1,34 @@
+-----------------------------------------------------------------------
+-- Copyright (c) 2009 Malte S. Stretz <http://msquadrat.de> 
+--
+-- This is a helper entity implementing the main logic (including the
+-- state machine) of the SPI master. It is driven by `clock` on the
+-- rising edge but it is assumed that the `trigger` wired in by the
+-- parent entity is driven on the falling edge to avoid timing issues.
+-- `reset` is active high.
+--
+-- When `trigger` is high, data is latched or shifted, ie. `trigger`
+-- must run at the double rate of the needed frequency.
+--
+-- Once both the data and the state machine is finished, `done` does
+-- high for a single `clock`.
+--
+-- The meaning of the generics `data_width`, `spi_cpol` and `spi_cpha`
+-- are explained in the parent entity. `spi_in` is MISO, `spi_out` MOSI
+-- and `spi_clock` SCK. `data_in` is the parallel input, `data_out` the
+-- output and the same constraints as described in the parent entity
+-- apply.
+--
+-- This entity might be folded into the parent entity one day.
+-----------------------------------------------------------------------
+-- This entity is part of the following library:
+-- pragma library fhw_spi
+library fhw_spi;
+
 library ieee;
 use ieee.std_logic_1164.all;
 use ieee.numeric_std.all;
 
------------------------------------------------------------------------
-
 entity spi_engine_e is
   generic(
     data_width : positive;
index c574cdb..9717cc3 100644 (file)
@@ -1,13 +1,53 @@
+-----------------------------------------------------------------------
+-- Copyright (c) 2009 Malte S. Stretz <http://msquadrat.de> 
+--
+-- This SPI master processes the serial 4-wire full duplex bus-protocol
+-- called SPI (Serial Peripheral Interface), also known as Microwire.
+-- The four lines used by SPI are called MISO (Master In Slave Out,
+-- input `miso`), MOSI (Master Out Slave In, output `mosi`), SCK
+-- (Serial ClocK, output `sck`) and SS (Slave Select, low active, can
+-- be derived from the `busy` line).
+--
+-- SPI can operate with varying frame sizes which can be specified
+-- via the generic `data_width`, defaulting to eigth bit. The two
+-- bit wide generic `spi_mode` is for compatibility to devices which 
+-- do not use the default mode 0; the low bit is also known as CPHA
+-- (Clock PHAse), the high bit as CPOL (Clock POLarity). When CPHA is
+-- set, the first SCK edge is ignored; when CPOL is set, the polarity
+-- of the SCK is inverted (ie. SCK is low active).
+-- 
+-- The maximum speed of the SPI bus depends on the maximum speed of 
+-- both master and slave and can be changed via the generic `clk_div`
+-- which must be even and greater or equal than six.
+--
+-- For more information and details on SPI see
+--   http://en.wikipedia.org/wiki/Serial_Peripheral_Interface_Bus
+--
+-- This entity is synchronized on the rising edge of the clock `clk`
+-- and the reset line `rst` is high active.
+-- 
+-- It is idle until `start` goes high. Data to be transmitted over SPI
+-- must be stable on `txd` at that point and be held stable for one
+-- `clk` cycle afterwards. Then, next data can be prepared.
+
+-- While data is shifted, the `busy` line is high and `start` is
+-- ignored. Even if `start` stays high all the time, `busy` will go
+-- low for one `clk` cycle when all data is shifted out to signal a
+-- stable output on `rxd`. The state of the latter is undefined (ie.
+-- not stable) while `busy` is high.
+-----------------------------------------------------------------------
+-- This entity is part of the following library:
+-- pragma library fhw_spi
+library fhw_spi;
+
 library ieee;
 use ieee.std_logic_1164.all;
 use ieee.numeric_std.all;
 
------------------------------------------------------------------------
-
 entity spi_master is
   generic(
-    clk_div    : positive := 10;
-    data_width : positive :=  8;
+    clk_div    : positive := 6;
+    data_width : positive := 8;
     spi_mode   : integer range 0 to 3 := 0);
   port(
     clk : in  std_logic;
@@ -33,7 +73,7 @@ architecture rtl of spi_master is
   
   component spi_counter_e
     generic(
-      count : positive := clk_div / 2; -- TODO: odd clk_div? TODO: min: 6
+      count : positive := clk_div / 2;
       edge  : std_logic := '0');
     port(
       clock  : in  std_logic;
@@ -92,6 +132,9 @@ architecture rtl of spi_master is
   signal spi_out_s   : std_logic;
   signal spi_clock_s : std_logic;
 begin
+  assert clk_div >= 6      report "clk_div can not be lower than 6" severity error;
+  assert clk_div mod 2 = 0 report "clk_div will be rounded down to the next even value" severity warning;
+
   clock_s <= clk;
   reset_s <= rst;
   
index 7ecc9ae..a25d5d4 100644 (file)
@@ -1,8 +1,23 @@
+-----------------------------------------------------------------------
+-- Copyright (c) 2009 Malte S. Stretz <http://msquadrat.de> 
+--
+-- This is a helper entity implementing a shift register. It is driven
+-- by `clock` on the rising edge. As it doesn't have a reset line, the
+-- initial state is undefined but can be preset parallely by `preload`
+-- while `load` is high.
+--
+-- While `enable` is high, each `clock` the `data` is shifted left and
+-- the lowest bit is filled up with `input`. Data is NOT shifted out
+-- into `output` but discared; `output` is simply wired to the top
+-- `data` bit.
+-----------------------------------------------------------------------
+-- This entity is part of the following library:
+-- pragma library fhw_spi
+library fhw_spi;
+
 library ieee;
 use ieee.std_logic_1164.all;
 
------------------------------------------------------------------------
-
 entity spi_shifter_e is
   generic(
     data_width : positive);
index 83173d3..6a3b566 100644 (file)
@@ -1,8 +1,20 @@
+-----------------------------------------------------------------------
+-- Copyright (c) 2009 Malte S. Stretz <http://msquadrat.de> 
+--
+-- This is a helper entity which manages the busy line, wired to the
+-- output `status`. It will go high once `start` was seen high and
+-- stay like this until `stop` occurs. The latter overrides the line.
+--
+-- It is driven by `clock` on the rising edge and `reset` is active
+-- high.
+-----------------------------------------------------------------------
+-- This entity is part of the following library:
+-- pragma library fhw_spi
+library fhw_spi;
+
 library ieee;
 use ieee.std_logic_1164.all;
 
------------------------------------------------------------------------
-
 entity spi_starter_e is
   port(
     clock   : in  std_logic;
index e480c20..99ed3b2 100644 (file)
@@ -1,10 +1,14 @@
-library ieee;
-use ieee.std_logic_1164.all;
-
+-----------------------------------------------------------------------
+-- Copyright (c) 2009 Malte S. Stretz <http://msquadrat.de> 
+-----------------------------------------------------------------------
+-- This entity is part of the following library:
+-- pragma library fhw_spi_t
+library fhw_spi_t;
 library fhw_spi;
 use fhw_spi.all;
 
------------------------------------------------------------------------
+library ieee;
+use ieee.std_logic_1164.all;
 
 entity spi_counter_t is
   generic(
index b6e0309..c6ba125 100644 (file)
@@ -1,3 +1,10 @@
+-----------------------------------------------------------------------
+-- Copyright (c) 2009 Malte S. Stretz <http://msquadrat.de> 
+-----------------------------------------------------------------------
+-- This entity is part of the following library:
+-- pragma library fhw_spi_t
+library fhw_spi_t;
+
 library ieee;
 use ieee.std_logic_1164.all;
 use ieee.numeric_std.all;
index a737695..bac07b6 100644 (file)
@@ -1,10 +1,16 @@
+-----------------------------------------------------------------------
+-- Copyright (c) 2009 Malte S. Stretz <http://msquadrat.de> 
+-----------------------------------------------------------------------
+-- This entity is part of the following library:
+-- pragma library fhw_spi_t
+library fhw_spi_t;
+library fhw_spi;
+use fhw_spi.all;
+
 library ieee;
 use ieee.std_logic_1164.all;
 use ieee.numeric_std.all;
 
-library fhw_spi;
-use fhw_spi.all;
-
 -----------------------------------------------------------------------
 
 entity spi_master_t is
@@ -80,7 +86,6 @@ begin
     start_s <= '1';
     
     wait until rising_edge(clock_s); test_s <= test_s + 1;
-    start_s <= '0';
     
     wait until rising_edge(clock_s); test_s <= test_s + 1;
     txd_s  <= (others => 'U');
@@ -93,9 +98,14 @@ begin
     
       wait until rising_edge(clock_s); test_s <= test_s + 1;
       txd_s  <= txd_s xor txd_pattern;
-    
+      
       wait until falling_edge(busy_s); test_s <= test_s + 1;
-      start_s <= '1';
+    
+      -- while busy_s = '1' loop
+        -- wait until rising_edge(clock_s);
+      -- end loop;
+      -- test_s <= test_s + 1;
+      -- start_s <= '1';
     
       wait until rising_edge(clock_s); test_s <= test_s + 1;
       start_s <= '0';
@@ -104,6 +114,7 @@ begin
       txd_s  <= (others => 'U');
     end loop;
     
+    start_s <= '0';
     wait;
   end process;
   
@@ -144,7 +155,7 @@ begin
     
     assert simo_s = data_v      report "neq:txd";
     assert rxd_s  = rxd_pattern report "neq:rxd";
-    wait until rising_edge(clock_s);
+    wait until falling_edge(clock_s);
   end process;
   
   reset : process
index 8794ae6..1043f2e 100644 (file)
@@ -1,10 +1,14 @@
-library ieee;
-use ieee.std_logic_1164.all;
-
+-----------------------------------------------------------------------
+-- Copyright (c) 2009 Malte S. Stretz <http://msquadrat.de> 
+-----------------------------------------------------------------------
+-- This entity is part of the following library:
+-- pragma library fhw_spi_t
+library fhw_spi_t;
 library fhw_spi;
 use fhw_spi.all;
 
------------------------------------------------------------------------
+library ieee;
+use ieee.std_logic_1164.all;
 
 entity spi_shifter_t is
   generic(
index f8779c9..2401a7f 100644 (file)
@@ -1,10 +1,14 @@
-library ieee;
-use ieee.std_logic_1164.all;
-
+-----------------------------------------------------------------------
+-- Copyright (c) 2009 Malte S. Stretz <http://msquadrat.de> 
+-----------------------------------------------------------------------
+-- This entity is part of the following library:
+-- pragma library fhw_spi_t
+library fhw_spi_t;
 library fhw_spi;
 use fhw_spi.all;
 
------------------------------------------------------------------------
+library ieee;
+use ieee.std_logic_1164.all;
 
 entity spi_starter_t is
   generic(