diff --git a/presets/verilog/7segment.v b/presets/verilog/7segment.v index f05e36a8..684a0661 100644 --- a/presets/verilog/7segment.v +++ b/presets/verilog/7segment.v @@ -2,6 +2,11 @@ `include "hvsync_generator.v" /* +seven_segment_decoder - Decodes a digit into 7 segments. + +segments_to_bitmap - Encodes a 7-segment bitmask into + a 5x5 bitmap. + Segment bit indices: 6666 diff --git a/presets/verilog/ball_absolute.v b/presets/verilog/ball_absolute.v index 60573577..e2cf3cbe 100644 --- a/presets/verilog/ball_absolute.v +++ b/presets/verilog/ball_absolute.v @@ -1,6 +1,10 @@ `include "hvsync_generator.v" +/* +A bouncing ball using absolute coordinates. +*/ + module ball_absolute_top(clk, reset, hsync, vsync, rgb); input clk; diff --git a/presets/verilog/ball_paddle.v b/presets/verilog/ball_paddle.v index 87b7a0f1..c74300e6 100644 --- a/presets/verilog/ball_paddle.v +++ b/presets/verilog/ball_paddle.v @@ -3,6 +3,10 @@ `include "digits10.v" `include "scoreboard.v" +/* +A brick-smashing ball-and-paddle game. +*/ + module ball_paddle_top(clk, reset, hpaddle, hsync, vsync, rgb); input clk; diff --git a/presets/verilog/ball_slip_counter.v b/presets/verilog/ball_slip_counter.v index 0082b86d..dae9dfad 100644 --- a/presets/verilog/ball_slip_counter.v +++ b/presets/verilog/ball_slip_counter.v @@ -1,6 +1,11 @@ `include "hvsync_generator.v" +/* +A bouncing ball using the "slipping counter" method, as +used in Pong, Computer Space, and other early arcade games. +*/ + module ball_slip_counter_top(clk, reset, hsync, vsync, rgb); input clk; diff --git a/presets/verilog/clock_divider.v b/presets/verilog/clock_divider.v index 12f4a83a..b1f4b56f 100644 --- a/presets/verilog/clock_divider.v +++ b/presets/verilog/clock_divider.v @@ -1,4 +1,9 @@ +/* +A clock divider in Verilog, using both the cascading +flip-flop method and the counter method. +*/ + module clock_divider( input clk, input reset, diff --git a/presets/verilog/cpu_platform.v b/presets/verilog/cpu_platform.v index 92f3b8e8..a4c5ee78 100644 --- a/presets/verilog/cpu_platform.v +++ b/presets/verilog/cpu_platform.v @@ -8,6 +8,18 @@ `include "sound_generator.v" `include "cpu16.v" +/* +A full video game console, with the following components: + + 64 kilobytes (32,678 16-bit words) of RAM + 16-bit CPU running at 4.857 MHz + 32x30 tile graphics with 256 x 8 tile ROM + 32 16x16 sprites per frame with sprite ROM + 16 colors (two per tile, one per sprite) + Two game controllers (four direction switches, two buttons) + One paddle/analog stick controller +*/ + module cpu_platform(clk, reset, hsync, vsync, hpaddle, vpaddle, switches_p1, switches_p2, diff --git a/presets/verilog/digits10.v b/presets/verilog/digits10.v index 7a9768b8..aa12829f 100644 --- a/presets/verilog/digits10.v +++ b/presets/verilog/digits10.v @@ -4,6 +4,15 @@ `include "hvsync_generator.v" +/* +ROM module with 5x5 bitmaps for the digits 0-9. + +digits10_case - Uses the case statement. +digits10_array - Uses an array and initial block. + +These two modules are functionally equivalent. +*/ + // module for 10-digit bitmap ROM module digits10_case(digit, yofs, bits); diff --git a/presets/verilog/hvsync_generator.v b/presets/verilog/hvsync_generator.v index 175145af..24587616 100644 --- a/presets/verilog/hvsync_generator.v +++ b/presets/verilog/hvsync_generator.v @@ -2,6 +2,13 @@ `ifndef HVSYNC_GENERATOR_H `define HVSYNC_GENERATOR_H +/* +Video sync generator, used to drive a simulated CRT. +To use: +- Wire the hsync and vsync signals to top level outputs +- Add a 3-bit (or more) "rgb" output to the top level +*/ + module hvsync_generator(clk, reset, hsync, vsync, display_on, hpos, vpos); input clk; diff --git a/presets/verilog/lfsr.v b/presets/verilog/lfsr.v index fd2e7129..c2f97ebb 100644 --- a/presets/verilog/lfsr.v +++ b/presets/verilog/lfsr.v @@ -2,6 +2,10 @@ `ifndef LFSR_V `define LFSR_V +/* +Configurable Linear Feedback Shift Register. +*/ + module LFSR(clk, reset, enable, lfsr); parameter TAPS = 8'b11101; // bitmask for taps diff --git a/presets/verilog/paddles.v b/presets/verilog/paddles.v index 3202f1fe..d2019775 100644 --- a/presets/verilog/paddles.v +++ b/presets/verilog/paddles.v @@ -1,6 +1,10 @@ `include "hvsync_generator.v" +/* +Paddle demonstration. +*/ + module paddles_top(clk, reset, hsync, vsync, hpaddle, vpaddle, rgb); input clk, reset; diff --git a/presets/verilog/racing_game.v b/presets/verilog/racing_game.v index 168be4de..e1a57444 100644 --- a/presets/verilog/racing_game.v +++ b/presets/verilog/racing_game.v @@ -3,6 +3,11 @@ `include "sprite_bitmap.v" `include "sprite_renderer.v" +/* +A simple racing game with two sprites and a scrolling playfield. +This version does not use a CPU; all logic is straight Verilog. +*/ + module racing_game_top(clk, hsync, vsync, rgb, hpaddle, vpaddle); input clk; diff --git a/presets/verilog/racing_game_cpu.v b/presets/verilog/racing_game_cpu.v index 046a8851..6aa64f9e 100644 --- a/presets/verilog/racing_game_cpu.v +++ b/presets/verilog/racing_game_cpu.v @@ -4,6 +4,11 @@ `include "sprite_renderer.v" `include "cpu8.v" +/* +A simple racing game with two sprites and a scrolling playfield. +This version uses the 8-bit CPU. +*/ + // uncomment to see scope view //`define DEBUG diff --git a/presets/verilog/ram.v b/presets/verilog/ram.v index 43441151..093b3d7c 100644 --- a/presets/verilog/ram.v +++ b/presets/verilog/ram.v @@ -2,6 +2,17 @@ `ifndef RAM_H `define RAM_H +/* +RAM_sync - Synchronous RAM module. +RAM_async - Asynchronous RAM module. +RAM_async_tristate - Async RAM module with bidirectional data bus. + +Module parameters: + +A - number of address bits (default = 10) +D - number of data bits (default = 8) +*/ + module RAM_sync(clk, addr, din, dout, we); parameter A = 10; // # of address bits diff --git a/presets/verilog/ram1.v b/presets/verilog/ram1.v index 2f76b00e..b732eba7 100644 --- a/presets/verilog/ram1.v +++ b/presets/verilog/ram1.v @@ -3,6 +3,10 @@ `include "digits10.v" `include "ram.v" +/* +Displays a grid of digits on the CRT using a RAM module. +*/ + module test_ram1_top(clk, reset, hsync, vsync, rgb); input clk, reset; diff --git a/presets/verilog/scoreboard.v b/presets/verilog/scoreboard.v index cda8c499..1fdef21a 100644 --- a/presets/verilog/scoreboard.v +++ b/presets/verilog/scoreboard.v @@ -5,6 +5,11 @@ `include "hvsync_generator.v" `include "digits10.v" +/* +player_stats - Holds two-digit score and one-digit lives counter. +scoreboard_generator - Outputs video signal with score/lives digits. +*/ + module player_stats(reset, score0, score1, lives, incscore, declives); input reset; diff --git a/presets/verilog/sound_generator.v b/presets/verilog/sound_generator.v index 1cd34eef..2e25fc58 100644 --- a/presets/verilog/sound_generator.v +++ b/presets/verilog/sound_generator.v @@ -2,6 +2,13 @@ `include "hvsync_generator.v" `include "lfsr.v" +/* +Sound generator module. +This module has a square-wave oscillator (VCO) which can +be modulated by a low-frequency oscillator (LFO) and also +mixed with a LFSR noise source. +*/ + module sound_generator(clk, reset, spkr, lfo_freq,noise_freq, vco_freq, vco_select, noise_select, lfo_shift, mixer); diff --git a/presets/verilog/sprite_bitmap.v b/presets/verilog/sprite_bitmap.v index d0327b10..5c503e6c 100644 --- a/presets/verilog/sprite_bitmap.v +++ b/presets/verilog/sprite_bitmap.v @@ -4,6 +4,13 @@ `include "hvsync_generator.v" +/* +Simple sprite renderer example. + +car_bitmap - ROM for a car sprite. +sprite_bitmap_top - Example sprite rendering module. +*/ + module car_bitmap(yofs, bits); input [3:0] yofs; diff --git a/presets/verilog/sprite_renderer.v b/presets/verilog/sprite_renderer.v index 9a1d702d..5e6a85fc 100644 --- a/presets/verilog/sprite_renderer.v +++ b/presets/verilog/sprite_renderer.v @@ -1,10 +1,14 @@ - + `ifndef SPRITE_RENDERER_H `define SPRITE_RENDERER_H `include "hvsync_generator.v" `include "sprite_bitmap.v" +/* +Displays a 16x16 sprite (8 bits mirrored left/right). +*/ + module sprite_renderer(clk, vstart, load, hstart, rom_addr, rom_bits, gfx, in_progress); diff --git a/presets/verilog/sprite_rotation.v b/presets/verilog/sprite_rotation.v index 30a6e3d4..5c645716 100644 --- a/presets/verilog/sprite_rotation.v +++ b/presets/verilog/sprite_rotation.v @@ -4,6 +4,12 @@ `include "hvsync_generator.v" +/* +tank_bitmap - ROM for tank bitmaps (5 different rotations) +sprite_renderer2 - Displays a 16x16 sprite. +tank_controller - Handles display and movement for one tank. +*/ + module tank_bitmap(addr, bits); input [7:0] addr; diff --git a/presets/verilog/sprite_scanline_renderer.v b/presets/verilog/sprite_scanline_renderer.v index 944de44a..32fd0269 100644 --- a/presets/verilog/sprite_scanline_renderer.v +++ b/presets/verilog/sprite_scanline_renderer.v @@ -2,6 +2,13 @@ `include "hvsync_generator.v" `include "ram.v" +/* +sprite_scanline_renderer - Module that renders multiple + sprites whose attributes are fetched from shared RAM, + and whose bitmaps are stored in ROM. Made to be paired + with the FEMTO-16 CPU. +*/ + module example_bitmap_rom(addr, data); input [15:0] addr; diff --git a/presets/verilog/starfield.v b/presets/verilog/starfield.v index d63491d0..d0ab4f30 100644 --- a/presets/verilog/starfield.v +++ b/presets/verilog/starfield.v @@ -2,6 +2,10 @@ `include "hvsync_generator.v" `include "lfsr.v" +/* +Scrolling starfield generator using a period (2^16-1) LFSR. +*/ + module starfield_top(clk, reset, hsync, vsync, rgb); input clk, reset; diff --git a/presets/verilog/switches.v b/presets/verilog/switches.v index 26a50159..ed45067b 100644 --- a/presets/verilog/switches.v +++ b/presets/verilog/switches.v @@ -1,7 +1,9 @@ - + `include "hvsync_generator.v" /* +Switch test program. + Player 1 Keys: arrow keys + space + shift Player 2 Keys: A/D/W/S + Z + X */ diff --git a/presets/verilog/tank.v b/presets/verilog/tank.v index b4f878d1..001e962d 100644 --- a/presets/verilog/tank.v +++ b/presets/verilog/tank.v @@ -3,6 +3,15 @@ `include "digits10.v" `include "sprite_rotation.v" +/* +Tank game. + +minefield - Displays the minefield. +playfield - Displays the playfield maze. +tank_game_top - Runs the tank game, using two tank_controller + modules. +*/ + module minefield(hpos, vpos, mine_gfx); input [8:0] hpos; diff --git a/presets/verilog/test_hvsync.v b/presets/verilog/test_hvsync.v index 2c938c90..a3445ce8 100644 --- a/presets/verilog/test_hvsync.v +++ b/presets/verilog/test_hvsync.v @@ -1,6 +1,10 @@ `include "hvsync_generator.v" +/* +A simple test pattern using the hvsync_generator module. +*/ + module test_hvsync_top(clk, reset, hsync, vsync, rgb); input clk, reset; diff --git a/presets/verilog/tile_renderer.v b/presets/verilog/tile_renderer.v index 6d5b65cf..8a09de12 100644 --- a/presets/verilog/tile_renderer.v +++ b/presets/verilog/tile_renderer.v @@ -3,6 +3,11 @@ `include "font_cp437_8x8.v" `include "ram.v" +/* +Displays a 32x30 grid of 8x8 tiles, whose attributes are + fetched from RAM, and whose bitmap patterns are in ROM. +*/ + module tile_renderer(clk, reset, hpos, vpos, rgb, ram_addr, ram_read, ram_busy,