Finally some inline documentation. master 3_rs232
authorMalte S. Stretz <mss@apache.org>
Sat, 29 Aug 2009 12:06:20 +0000 (14:06 +0200)
committerMalte S. Stretz <mss@apache.org>
Sat, 29 Aug 2009 12:06:20 +0000 (14:06 +0200)
bos2k9.vhd
fhw_rs232/rs232_globals_p.vhd
fhw_rs232/rs232_recv.vhd
fhw_rs232/rs232_send.vhd
fhw_rs232/rs232_uart.vhd
fhw_rs232_t/rs232_globals_parity_t.vhd
fhw_rs232_t/rs232_send_t.vhd

index ac58024..8e7f6cf 100644 (file)
 --  * `SD_CMD` is the SPI MOSI.
 --  * `SD_DAT3` is the SPI CS.
 --  * `SD_CLK` is the SPI SCK.
+--  * `UART_RXD` is the serial input.
+--  * `UART_TXD` is the serial output.
 --
 -- LEDG(0) should be always on and represents a powered system. The 
 -- `reset` is wired to `SW(17)`, so the switch should be off when these
 -- system is started.  Once `reset` is off (ie. the switch on), the card
--- can be initialized (and later reset) by pressing `KEY(0)`.  Once
+-- is initialized as soon as it is inserted.  Whe n this is successful,
 -- LEDG(2) is led, the system is ready to read a block; if an error 
 -- occurs, LEDG(1) is switched on instead.
 --
 -- board tend to break, this cannot be ensured but a longer press 
 -- doesn't break anything.
 --
--- The currently via SW(8) to SW(15) selected byte is displayed on the
--- LEDs LEDR(0) to LEDR(7).
---
--- Because only eight address bits are wired, only half the block can 
--- be displayed.  Both this and the above limitation doesn't matter as 
--- this is a test setup only.
+-- The whole block is output via `UART_TXD`.
 --
 -- For debugging purposes, the SPI bus is also wired to the LEDs 
 -- LEDG(7) to LEDG(4). 
@@ -231,8 +228,14 @@ begin
     sd_address_s(std_logic_block_address_t'high downto std_logic_byte_t'high + 1) <= (others => '0');
     sd_address_s(std_logic_byte_t'range) <= byte_sw1_s;
     
+    -- Make sure we can't accidently start another read action while 
+    -- something else is still going on.
     sd_start_s <= read_btn_s and sd_ready_s and not pumping_s;
-  
+    
+    -- Magic wiring between the `sd_host` and the timeout/poll counter:
+    -- The counter will trigger the `init` port each `init_ticks_c` 
+    -- but once the `sd_host` is initialized, the `ready` line will 
+    -- keep the counter via the `clr` line at zero.
     sd_io : sd_host port map(
       clk => clock_s,
       rst => reset_s,
index 85b9fa8..9336c4c 100644 (file)
@@ -1,7 +1,7 @@
 -----------------------------------------------------------------------
 -- Copyright (c) 2009 Malte S. Stretz <http://msquadrat.de> 
 --
--- TODO
+-- Some helper stuff for the UART implementation.
 -- 
 -----------------------------------------------------------------------
 -- This entity is part of the following library:
@@ -14,6 +14,8 @@ use ieee.numeric_std.all;
 
 package rs232_globals_p is
   
+  -- Calculate the parity for the `word`, `even` or not `even` 
+  -- (ie. odd).
   function get_parity(
     word : std_logic_vector;
     even : std_logic) return std_logic;
index 73ec208..a30f0e3 100644 (file)
@@ -1,7 +1,7 @@
 -----------------------------------------------------------------------
 -- Copyright (c) 2009 Malte S. Stretz <http://msquadrat.de> 
 --
--- TODO
+-- TODO: This receiver doesn't have any implementation.
 -- 
 -----------------------------------------------------------------------
 -- This entity is part of the following library:
index 4a83543..b421d48 100644 (file)
@@ -1,8 +1,19 @@
 -----------------------------------------------------------------------
 -- Copyright (c) 2009 Malte S. Stretz <http://msquadrat.de> 
 --
--- TODO
--- 
+-- This is the sending part of a RS232 UART.  The speed is specified
+-- by the `clock_divider` and the frame format by `data_width` (number
+-- of data bits per frame) `parity_enabled` and `parity_type` (`0` 
+-- being odd parity, `1` even).  When no parity is used, the sender
+-- will generate two stop bits.  The latter may change in the future.
+-- The `clock_divider` should not be lower than 4.
+--
+-- The data applied to `txd` is sent as soon as the shift trigger `txn`
+-- is high for one clock.  While data is shifted out via `tx`, the busy
+-- flag `txb` is high.
+--
+-- The data at the `txd` input has to be stable while `txb` is high.
+--
 -----------------------------------------------------------------------
 -- This entity is part of the following library:
 -- pragma library fhw_rs232
index ef8cf35..04847f6 100644 (file)
@@ -1,7 +1,8 @@
  -----------------------------------------------------------------------
 -- Copyright (c) 2009 Malte S. Stretz <http://msquadrat.de> 
 --
--- TODO
+-- TODO: This is an incomplete UART implementation, only including a 
+-- sender.  See `rs232_send` for details.
 -- 
 -----------------------------------------------------------------------
 -- This entity is part of the following library:
index 71c677d..7f2b8bf 100644 (file)
@@ -22,6 +22,8 @@ entity rs232_globals_parity_t is
 end rs232_globals_parity_t;
 
 architecture test of rs232_globals_parity_t is
+  -- The first parameter is the `word` to calculate the parities (both 
+  -- even and odd) of, the second is the `expect`ed value for even parity.
   procedure t(
     word   : in std_logic_vector;
     expect : in std_logic) is
@@ -33,23 +35,31 @@ architecture test of rs232_globals_parity_t is
     e_p_v := get_parity(word, '1'); assert e_p_v = e_e_v report "wrong E parity for " & str(word) & ": " & str(e_p_v) & " != " & str(e_e_v);
   end t;
 begin
-  t("0", '0');
-  t("1", '1');
-  
-  t("00", '0');
-  t("01", '1');
-  t("10", '1');
-  t("11", '0');
-  
-  t("000", '0');
-  t("001", '1');
-  t("010", '1');
-  t("011", '0');
-  t("100", '1');
-  t("101", '0');
-  t("110", '0');
-  t("111", '1');
-  
+  -- We'll test the parity for 1, 2, 3 and 4 bit words.  That includes
+  -- the shortest possible word lengths with even and odd number of
+  -- digits and the next two lengths.  Everything else doesn't make a 
+  -- difference.
+
+  -- word - expected
+  -------------------
+  -- 1 bit
+  t("0",    '0');
+  t("1",    '1');
+  -- 2 bit
+  t("00",   '0');
+  t("01",   '1');
+  t("10",   '1');
+  t("11",   '0');
+  -- 3 bit
+  t("000",  '0');
+  t("001",  '1');
+  t("010",  '1');
+  t("011",  '0');
+  t("100",  '1');
+  t("101",  '0');
+  t("110",  '0');
+  t("111",  '1');
+  -- 4 bit
   t("0000", '0');
   t("0001", '1');
   t("0010", '1');
index 3a8fd83..48913b8 100644 (file)
@@ -1,7 +1,12 @@
 -----------------------------------------------------------------------
 -- Copyright (c) 2009 Malte S. Stretz <http://msquadrat.de> 
 --
--- Testing the RS232 sending unit.
+-- Testing the RS232 sending unit in all possible combinations with
+-- one byte long words (ie. 8e1, 8o1, and 8n1 which is actually 8n2).
+--
+-- There are two processes, one sending data while the other collects
+-- the output and checks for correctnes.
+--
 -----------------------------------------------------------------------
 -- This entity is part of the following library:
 -- pragma library fhw_rs232_t
@@ -24,6 +29,8 @@ entity rs232_send_t is
 end rs232_send_t;
 
 architecture test of rs232_send_t is
+  -- Use a low, but not too low clock divider so we can still read the
+  -- output while not entering any border cases.
   constant div_c : positive := 4;
   subtype std_logic_byte_t is std_logic_vector(7 downto 0);
   component rs232_send is
@@ -45,6 +52,8 @@ architecture test of rs232_send_t is
    signal clock_s : std_logic;
    signal reset_s : std_logic;
    
+   -- A bunch of signals for all the combinations of input and output
+   -- signals.  Name format: port_format_io
    signal tx_8n1_o_s  : std_logic;
    signal txd_8n1_o_s : std_logic_byte_t;
    signal txd_8n1_i_s : std_logic_byte_t;
@@ -64,13 +73,16 @@ architecture test of rs232_send_t is
    signal busy_s : std_logic;
    
 begin
+  -- Three possible combinations of frame format.
   tx_8n1 : rs232_send generic map(div_c, 8, '0', '0') port map(clock_s, reset_s, tx_8n1_o_s, txd_8n1_i_s, txn_8n1_i_s, txb_8n1_o_s);
   tx_8o1 : rs232_send generic map(div_c, 8, '1', '0') port map(clock_s, reset_s, tx_8o1_o_s, txd_8o1_i_s, txn_8o1_i_s, txb_8o1_o_s);
   tx_8e1 : rs232_send generic map(div_c, 8, '1', '1') port map(clock_s, reset_s, tx_8e1_o_s, txd_8e1_i_s, txn_8e1_i_s, txb_8e1_o_s);
   
+  -- The current test is busy until the last entity finished.
   busy_s <= txb_8n1_o_s or txb_8o1_o_s or txb_8e1_o_s;
   
   stimulus : process
+    -- Send an arbitrary `word` through the entities.
     procedure send(
        word : in std_logic_byte_t) is
     begin
@@ -86,6 +98,7 @@ begin
   begin
     wait until falling_edge(reset_s);
     
+    -- Four test pattern should be enough.
     send("01000111");
     send("10010010");
     send("11111111");
@@ -97,26 +110,32 @@ begin
   verify : process
     variable wait_v : natural;
   begin
+    -- Nothing happened yet.
     txd_8n1_o_s <= (others => '-');
     txd_8o1_o_s <= (others => '-');
     txd_8e1_o_s <= (others => '-');
+    -- Wait for the start bit.
     wait until falling_edge(tx_8n1_o_s);
     txd_8n1_o_s <= (others => 'U');
     txd_8o1_o_s <= (others => 'U');
     txd_8e1_o_s <= (others => 'U');
+    -- Sync
     for i in div_c downto 1 loop
       wait until rising_edge(clock_s);
     end loop;
+    -- Read eight bit.
     for i in 0 to 7 loop
       txd_8n1_o_s(i) <= tx_8n1_o_s;
       txd_8o1_o_s(i) <= tx_8o1_o_s;
       txd_8e1_o_s(i) <= tx_8e1_o_s;
+      -- Sync
       for t in div_c downto 1 loop
         wait until rising_edge(clock_s);
       end loop;
 
       wait until rising_edge(clock_s);
     end loop;
+    -- Compare input and output.
     assert txd_8n1_o_s = txd_8n1_i_s report "data mismatch 8n1: got: " & str(txd_8n1_o_s) & " exp: " & str(txd_8n1_i_s);
     assert txd_8o1_o_s = txd_8n1_i_s report "data mismatch 8o1: got: " & str(txd_8o1_o_s) & " exp: " & str(txd_8o1_i_s);
     assert txd_8e1_o_s = txd_8n1_i_s report "data mismatch 8e1: got: " & str(txd_8e1_o_s) & " exp: " & str(txd_8e1_i_s);