Merge branch 'master' of https://gitlab.justprojects.de/hochschule/de2-115-fpga-pong

README.md

@@ -1,3 +1,5 @@
 # DE2-115-FPGA-Pong
 
-Pong game on Altera FPGA as exercise in Hardware-/Software-Codesign
+Pong game on Altera FPGA as exercise in Hardware-/Software-Codesign
+
+![](images/graph.png)

myfirst_niosii.vhd

@@ -4,42 +4,75 @@ use IEEE.numeric_std.ALL;
 use IEEE.STD_LOGIC_UNSIGNED.ALL;
 
 
+-- top level entity myfirst_niosii
+
 entity myfirst_niosii is port (
-		clk: in std_logic;
-		rst: in std_logic;
-		pio_led: out std_logic_vector(31 downto 0);
-		buttons: in std_logic_vector(7 downto 0);
-		matrix_rows: out std_logic_vector(11 downto 0);
-		matrix_cols: out std_logic_vector(7 downto 0);
-	   lcd_16207_ext_RS             : out   std_logic;                                        -- RS
-	   lcd_16207_ext_RW             : out   std_logic;                                        -- RW
-	   lcd_16207_ext_data           : inout std_logic_vector(7 downto 0)  := (others => 'X'); -- data
-	   lcd_16207_ext_E              : out   std_logic 
+	clk: in std_logic;																																		  -- 50 MHz
+	rst: in std_logic;																																			-- rst switch
+	pio_led: out std_logic_vector(31 downto 0);																							-- LEDs of dev board
+	buttons: in std_logic_vector(7 downto 0);																								-- push buttons
+	matrix_rows: out std_logic_vector(11 downto 0);																					-- LED row driver, active high
+	matrix_cols: out std_logic_vector(7 downto 0);																					-- LED colunm driver, active high
+	lcd_16207_ext_RS             : out   std_logic;                                         -- RS
+	lcd_16207_ext_RW             : out   std_logic;                                         -- RW
+	lcd_16207_ext_data           : inout std_logic_vector(7 downto 0)  := (others => 'X');  -- data
+	lcd_16207_ext_E              : out   std_logic 
 );
-type matrix_t is array(integer range 0 to 7) of std_logic_vector(11 downto 0);
+
+	-- the state of the LEDs is stored in a 7 x 12 bit matrix
+	-- the outer index represents the coulumn ID and the std_logic index represents the row ID
+	type matrix_t is array(integer range 0 to 7) of std_logic_vector(11 downto 0);
+
 end myfirst_niosii;
 
 architecture behav of myfirst_niosii is
+
+	-- noisII CPU IP wrapper
 	component nios2_uc is port (
-		clk_clk                 	  : in    std_logic                     := 'X';  				-- clk
-		reset_reset_n           	  : in    std_logic                     := 'X';  				-- reset_n
+		clk_clk                 	   : in    std_logic                     := 'X';  				   -- clk
+		reset_reset_n           	   : in    std_logic                     := 'X';  				   -- reset_n
 		lcd_16207_ext_RS             : out   std_logic;                                        -- RS
 		lcd_16207_ext_RW             : out   std_logic;                                        -- RW
 		lcd_16207_ext_data           : inout std_logic_vector(7 downto 0)  := (others => 'X'); -- data
 		lcd_16207_ext_E              : out   std_logic;                                        -- E
-		pio_led_ext_conn_export 	  : out   std_logic_vector(31 downto 0);         				-- export
-		pio_button_ext_conn_export   : in    std_logic_vector(7 downto 0)  := (others => 'X'); -- export
-		pio_matrix_ext_conn_export   : out   std_logic_vector(19 downto 0)                     -- export
-  
+		pio_led_ext_conn_export 	   : out   std_logic_vector(31 downto 0);         				   -- dev board LEDs
+		pio_button_ext_conn_export   : in    std_logic_vector(7 downto 0)  := (others => 'X'); -- dev board buttons
+
+		pio_matrix_ext_conn_export   : out   std_logic_vector(19 downto 0)                     -- matrix instruction
+		-- matrix instruction contains three parts:
+		-- 20   16   12   8    4    0
+		--   XXXX CCCC RRRR RRRR RRRR
+		-- 
+		-- X: 19 downto 16:  unused
+		-- C: 15 downto 12:  column number
+		-- R: 11 downto  0:  row data
+		--
+		-- column number:
+		--  0000: don't set anythhing
+		--  0001: set column 0 to row data
+		--  0010: set column 1 to row data 
+		--  0011: set column 2 to row data 
+		--  ...
 	);
 	end component nios2_uc;
 
+	-- signals for debouncing
+	-- previous button state
 	signal button_states: std_logic_vector(7 downto 0);
+
+	-- button polling clock: 50Mhz / 2**20 = 47.7 Hz
 	signal button_timer: integer range 0 to 2**20-1 := 0;
 
+  -- matrix multiplexing clock: 
+	-- 50Mhz / 2**20 = 1526 Hz = 1 / 0.66 ms per column
+	-- 1526 Hz / 8 = 190 Hz matrix refresh rate
 	signal matrix_timer: integer range 0 to 2**15-1 := 0;
-	signal matrix_col_index: integer range 0 to 8 := 0;
+
+	-- column index signal
+	signal matrix_col_index: integer range 0 to 7 := 0;
+	-- matrix signal
 	signal matrix_s: matrix_t;
+	-- matrix instruction signal
 	signal pio_matrix_s: std_logic_vector(19 downto 0);
 
 begin
@@ -54,9 +87,9 @@ begin
 	);
 
 
-
+	-- copies the row data according to instructions from CPU
 	matrix_set: process(clk, rst)
-	variable col_id : integer range 0 to 8;
+		variable col_id : integer range 0 to 8;
 	begin
 		if rst = '0' then
 			matrix_s <= (
@@ -77,9 +110,8 @@ begin
 		end if;
 	end process;
 
-	
+	-- copies rows from matrix_s to the outputs
 	matrix_multiplex: process(clk, rst)
-
 	begin
 		if rst = '0' then
 			matrix_rows <= "111111111111";
@@ -87,6 +119,9 @@ begin
 			matrix_timer <= 0;
 			matrix_col_index <= 0;
 		elsif rising_edge(clk) then
+
+			-- set outputs to zero at timer overflow
+			-- avoids ghosting of display
 			if matrix_timer = 2**15-1 then
 				matrix_timer <= 0;
 				if matrix_col_index = 7 then
@@ -97,17 +132,22 @@ begin
 				
 				matrix_cols <= (others => '0');
 				matrix_rows <= (others => '0');
+
+			-- write actual data only 50MHz / 2**11 = 1 / 0.04 ms after setting outputs to zero
 			elsif matrix_timer = 2**11-1 then
 				matrix_cols(matrix_col_index) <= '1';
 				matrix_rows <= matrix_s(matrix_col_index);
 				matrix_timer <= matrix_timer + 1;
+
+			-- else do nothing
 			else
 				matrix_timer <= matrix_timer + 1;
 			end if;
 		end if;
 	end process;
 
-
+	-- this process polls the buttons at 47.7 Hz
+	-- edge detection is done in software
 	button_debounce: process(clk, rst)	
 	begin
 		if rst = '0' then
@@ -115,16 +155,16 @@ begin
 		elsif rising_edge(clk) then
 			if button_timer = 2**20-1 then
 				button_timer <= 0;
+
+				-- update button states
 				for id in 0 to 7 loop
-					if buttons(id) = not button_states(id) then
-						button_states(id) <= buttons(id);
-						
-					end if;
+					button_states(id) <= buttons(id);
 				end loop;
 			else
 				button_timer <= button_timer + 1;
 			end if;
 		end if;
 	end process;
+
 end behav;
 

software/Pong_Code/Display.h

@@ -19,15 +19,15 @@
  * Each row on the screen is represented by one field of the array.
  * The Integer filling the field convertet to binary state wich pixels are active
  * Exp.:
- *										 __					      __
- *										|  1,0,0,0,0,0,0,0,0,0,0,0  |
- *										|  1,0,0,0,0,0,0,0,0,0,0,0  |
- *										|  1,0,0,0,0,0,0,0,0,0,0,0  |
+ *																			 __					              __
+ *																			|  1,0,0,0,0,0,0,0,0,0,0,0  |
+ *																			|  1,0,0,0,0,0,0,0,0,0,0,0  |
+ *																			|  1,0,0,0,0,0,0,0,0,0,0,0  |
  *	 [2048,2048,2048,64,0,1,1,1]   ==> 	|  0,0,0,0,0,1,0,0,0,0,0,0  | 
- *										|  0,0,0,0,0,0,0,0,0,0,0,0  |
- *										|  0,0,0,0,0,0,0,0,0,0,0,1  |
- *										|  0,0,0,0,0,0,0,0,0,0,0,1  |
- *										|__0,0,0,0,0,0,0,0,0,0,0,1__|
+ *																			|  0,0,0,0,0,0,0,0,0,0,0,0  |
+ *																			|  0,0,0,0,0,0,0,0,0,0,0,1  |
+ *																			|  0,0,0,0,0,0,0,0,0,0,0,1  |
+ *																			|__0,0,0,0,0,0,0,0,0,0,0,1__|
  *
  * 1-> pixel light up
  * 0-> pixel is dark

software/Pong_Code/Main.c

@@ -17,8 +17,8 @@
 */
 #define LEFT_UP_BUTTON 1
 #define LEFT_DOWN_BUTTON 0
-#define RIGTH_UP_BUTTON 3
-#define RIGTH_DOWN_BUTTON 2
+#define RIGHT_UP_BUTTON 3
+#define RIGHT_DOWN_BUTTON 2
 
 #define MIN(a,b) (((a)<(b))?(a):(b))
 #define MAX(a,b) (((a)>(b))?(a):(b))
@@ -30,7 +30,7 @@ struct Paddle right_paddle;
 /*
  * restes everything to default.
  * both paddles on highes position, with a length of 3.
- * ball in the middle, start moving up-rigth.
+ * ball in the middle, start moving up-right.
 */
 void reset_pos() {
 	ball.x = COLS/2 - 1;
@@ -48,7 +48,7 @@ void reset_pos() {
  * first read input registers and calculate new paddelpositions depending on the pressed buttons.
  * 
  * second calculate the new position of the ball depending on its current position and velocity.
- * If Ball hits left or rigth border calculate if the ball hits a paddle or strike a goal.
+ * If Ball hits left or right border calculate if the ball hits a paddle or strike a goal.
  * Goal 	-> restart the game
  * Paddle 	-> bounce ball back
  * 
@@ -74,10 +74,10 @@ void game() {
 			printf("%f\n",left_paddle.y);
 		}
 
-		if (buttons & (1<<RIGTH_UP_BUTTON)){
+		if (buttons & (1<<RIGHT_UP_BUTTON)){
 			right_paddle.y = MAX(right_paddle.y - (10 * TICK), 0);
 		}
-		if (buttons & (1<<RIGTH_DOWN_BUTTON)){
+		if (buttons & (1<<RIGHT_DOWN_BUTTON)){
 			right_paddle.y = MIN(right_paddle.y + (10 * TICK), ROWS - (right_paddle.length));
 		}
 
@@ -98,11 +98,11 @@ void game() {
 				ball.vel_x = - ball.vel_x;
 			} else {
 				printf("ballx: %f, ball y: %f\n",ball.x,ball.y);
-				printf("rigth player lost\n");
+				printf("right player lost\n");
 				reset_pos();
 			}
 		}
-		// check for rigth border
+		// check for right border
 		if (ball.x >= COLS - 2){
 			if (round(ball.y) >= round(right_paddle.y) && round(ball.y) <= (round(right_paddle.y) + right_paddle.length -1)){
 				ball.vel_x = - ball.vel_x;
@@ -142,7 +142,7 @@ void game() {
 
 /*
  * function to output a test picture. used to verify the VHDL implementation.
- * Will turn on one pixel after another starting with row 1 on the rigth side
+ * Will turn on one pixel after another starting with row 1 on the right side
  * Will also print on console if one of the game buttons is pressed.
 */
 void test_picture() {
@@ -160,11 +160,11 @@ void test_picture() {
 					printf("left button down");
 				}
 
-				if (buttons & (1<<RIGTH_UP_BUTTON)){
-					printf("rigth button up");
+				if (buttons & (1<<RIGHT_UP_BUTTON)){
+					printf("right button up");
 				}
-				if (buttons & (1<<RIGTH_DOWN_BUTTON)){
-					printf("rigth button down");
+				if (buttons & (1<<RIGHT_DOWN_BUTTON)){
+					printf("right button down");
 				}
 				printf("\n");
 				set_pixel(j,i);