ECE 4514 Digital Design II 24 January 2019 - GITHUB 5:00 PM Outline Today we will continue discussing the 'heartbeat' example: - simulation - hardware synthesis We will also discuss a version control environment called 'GitHub.' And we will clarify how it's used in this class. Key ideas of Lecture 1. a/ Digital hardware design = Applications, Methods, Tools b/ Digital Hardware Design Converting Behavior into Structure using a Method while meeting Constraints c/ Top-down and Bottom-up design d/ Schematics vs HDL 5:05 PM Heartbeat design - Running LED of 10 lights with a 100ms step time - Implemented on FPGA with a 50MHz clock module heartbeatde1soc( input CLOCK2_50, input CLOCK3_50, input CLOCK4_50, input CLOCK_50, input [3:0] KEY, output [9:0] LEDR ); reg [ 9:0] ledr_reg; reg [23:0] count_reg; wire tick; always @(posedge CLOCK_50) if (KEY[0] == 1'b0) begin ledr_reg <= 10'b1; count_reg <= 24'd0; end else begin count_reg <= tick ? 24'd0 : count_reg + 24'd1; ledr_reg <= tick ? {ledr_reg[8:0], ledr_reg[9]} : ledr_reg; end assign tick = (count_reg == 24'd5000000); assign LEDR = ledr_reg; endmodule - This example shows both synchronous always @(posedge CLOCK_50) register update and combinational logic (assign) - We will see several other 'standard' mechanisms to capture register update and combinational logic - RTL Design = REGISTER TRANSFER LEVEL Design = you can think of the operation of this design as a sequence of register transfers. In this case, there are two concurrent transfers: a/ count_reg updating itself (with incremented value) b/ ledr_reg updating itself (with shifted value) 5:10 PM Simulation To check the correctness of an HDL design, we will make use of an HDL simulator. An HDL simulator is a program the reads on HDL (Verilog) and proceeds at simulating the activities of the hardware. HDL simulation can also simulate concurrency and parallelism but making use of _simulated_time_ (as opposed to real time). By keeping the simulated time constant, the HDL simulator makes it appear as if multiple activities are happening at the same time. We will discuss the construction of a typical HDL simulator (including Verilog) next week. For today, we will build a testbench that exercises the module above. A testbench is an HDL program that can be simulated together with the application; the testbench will drive inputs and capture outputs. The testbench can display the outputs, or show them in a timing diagram. The testbench can also (be designed to) verify for the correctness of the outcome. +------------------------------------------+ | testbench | | +----------------+ | | stimuli -->| DUT |-> record | | +----------------+ | +------------------------------------------+ A testbench typically encapsulates the application as a lower level module called DUT (Device Under Test). The testbench then applies inputs and records the output. The testbench for the heartbeat design starts a clock signal running at a 20ns period, and then 'presses' the reset button. Here is the Verilog: `timescale 1ns/ 1ns module heartbeatde1soctb; reg CLOCK_50; reg CLOCK2_50; reg CLOCK3_50; reg CLOCK4_50; wire [9:0] LEDR; reg [3:0] KEY; heartbeatde1soc dut(CLOCK2_50, CLOCK3_50, CLOCK4_50, CLOCK_50, KEY, LEDR); always #10 CLOCK_50 <= ~CLOCK_50; initial begin $monitor("t=%8d LEDR=%10b", $time, LEDR); CLOCK_50 <= 0; CLOCK2_50 <= 0; CLOCK3_50 <= 0; CLOCK4_50 <= 0; KEY <= 4'hf; #500 KEY[0] <= 0; #1000 KEY[0] <= 1; end endmodule Questions: - How do we know that this program simulates a clock of 20ns? * timescale * #10 in an always block - Draw the clock and the activities of the key? time 0 10 20 ... 500 510 ... 1500 1510 1520 ... CLOCK_50 0 1 0 0 1 0 1 0 ... KEY[0] 1 1 1 0 0 1 1 1 ... count_reg X X X X 0 0 1 1 - What is $monitor doing? Print the line (similar to $display) each time it detects a change in any of the values it is printing. So $monitor("t=%8d LEDR=%10b", $time, LEDR); prints every change on LEDR. 5:20 Command Line Simulation To simulate a Verilog file, we use Modelsim. Modelsim can be run on the command line or using a graphical interface. Let's start with the command line. To simulate Verilog code, it first has to be compiled in an intermediate object code format, similar to a C program. The Verilog object code is collected in a working directory, which is managed by the Verilog simulator. Before we can simulate Verilog code, we have to complete the following tasks. 1. Prepare the working directory (vlib command) 2. Compile each Verilog file (vlog command) To prepare the heartbeat example, we therefore issue the following commands: ================================================== vlib work vlog heartbeatde1soc.v vlog heartbeatde1soctb.v ================================================== The order of compilation is not essential. Each time you make a change to a Verilog file, you have to re-run the vlog command on that file. If a Verilog file has a syntax error, you need to fix the error and re-run the vlog command. To run a Verilog program, you use the vsim command. vsim can start a GUI or else remain on the command line ================================================== vsim -c heartbeatde1soctb ================================================== ================================================== vsim heartbeatde1soctb ================================================== 5:30 Synthesis To implement a Verilog file on the de1soc kit, you have to: 1/ synthesize the Verilog into a bitstream 2/ download the bitstream onto the FPGA The synthesizing process includes several different steps: a. 'Map': convert Verilog code into a netlist of FPGA building blocks b. 'Fit': Assign the FPGA building blocks to locations on the FPGA fabric Route the connections of the netlist into the FPGA routing network c. 'Assemble': Convert the placed and routed netlist into a bitstream There is a single command line that can run all these steps for you. Again, we can run the tools both in a GUI or else on the command line. The key outcome of these tools are the synthesis reports such as: - Warnings regarding the quality of the input (Verilog) - The number of FPGA building blocks used (registers, LUTs, RAMs, ..) - The speed of the design (maximum clock frequency) - ... We will study those reports in detail throughout the course. The following are important inputs for the heartbeatde1soc project: - heartbeatde1soc.v - Verilog file - heartbeatde1soc.qsf - Pin constraint file - heartbeatde1soc.sdc - Clock constraint file ('Synopsys Design Constraints') You will receive the qsf, sdc files for every project. However, it's good to understand their purpose. - The pin constraint file explains how the PORTS of the top-level Verilog module connect to the PINS of the FPGA. For example, KEY[0] in the Verilog is allocated to pin AA14 of the FPGA. The designers of the DE1SoC kit have implemented their PCB such that, on that pin number, a switch is connected. In the qsf file, you will find the following lines: set_location_assignment PIN_AA14 -to KEY[0] set_instance_assignment -name IO_STANDARD "3.3-V LVTTL" -to KEY[0] See DE1SoC schematic sheet 3 and sheet 20 - The sdc file defines the timing constraints for pins, as well as the clocks: For example, for CLOCK_50, it says: create_clock -period 20.000ns [get_ports CLOCK_50] The synthesis tools use these guidelines. The command line that will create a bitstream from the Verilog is: ================================================== quartus_sh --flow compile heartbeatde1soc ================================================== Sample output: Info: Command: quartus_map --read_settings_files=on --write_settings_files=off heartbeatde1soc -c heartbeatde1soc Info: Command: quartus_fit --read_settings_files=off --write_settings_files=off heartbeatde1soc -c heartbeatde1soc Info: Command: quartus_asm --read_settings_files=off --write_settings_files=off heartbeatde1soc -c heartbeatde1soc The result of the synthesis process is dumped into report files. We will study those in detail later: heartbeatde1soc.flow.rpt Overall flow report heartbeatde1soc.map.rpt Results of mapping step heartbeatde1soc.fit.rpt Results of fitting step heartbeatde1soc.asm.rpt Results of assembly step heartbeatde1soc.sta.rpt Results of static timing analysis The tools can generate additional output besides the basic report files above. The resulting bitstream is an 'sof' file: The command line that will download the bitstream into a connected DE1SoC board is: ================================================== quartus_pgm -m jtag -o "p;heartbeatde1soc.sof@2" ================================================== 5:45 git and GitHub Git is a version control system. We will run all our Homework as git repositories. We will make use of 'GitHub Classroom' (The following shows overlap with a lecture I do in ECE 2534, I apologize if you have heard this before). The heart of a version control system is the REPOSITORY. It's a database that can remember multiple versions of a file. The repository does not have to be stored on your laptop - it could be anywhere (e.g., on a server in the cloud). So the situation looks as follows: REPOSITORY (in the cloud, or on your laptop) | +--- heartbeatde1soc.v (initial version, monday) +--- heartbeatde1soc.v (version 2, thursday 8AM) +--- heartbeatde1soc.v (version 3, thursday 5PM) +--- heartbeatde1soc.v (version 4, saturday noon) Laptop Disk: | +--- heartbeatde1soc.v (latest version, after saturday noon) If you start working on a file, then you would download a copy that the most current version from the version control system. That is called CHECKING OUT a file. When you update the version control system with a day's work, thereby creating a new version, you are CHECKING IN a file. Checking in a file automatically creates a new version (and a new delta). Checking out a file, and checking in a file is transparent to the user. The version control system will figure out the differences between each version, and store them efficiently in the repository. Moreover, the version control system will be able to reconstruct precisely the version you would like. 5:50 git and GitHub.com Version control is an old idea, and many different systems offer version control. We are using a modern version control system called git. GIT is a DISTRIBUTED version control system. In such an approach, it is allowed to have multiple copies of the version repository. There's one master repository, but before you check out a file, you will first download a copy of the entire repository. So, you have all versions of every file in the repository locally available. GIT uses some specific terminology to express the various operations. -----------> ---------> CLONE CLONE MASTER LOCAL local REPOSITORY -----------> REPOSITORY <--------- directory PULL COMMIT <----------- PUSH GITHUB.COM YOUR COMPUTER YOUR COMPUTER When you load the first copy from the master repository, you are CLONING it. This creates a local copy of the repository, and at the same time also CHECKS OUT the latest version of every file. When you wish to CHECK IN a change to a file, you will COMMIT the file into the local repository. However, COMMIT is different from checking in a single file, since it applies to ALL files that belong to the repository at the same time. So if you make changes to 5 different files, then committing your file-set would CHECK IN every file that has changed. Sooner or later, you will want to make the master repository consistent with the local repository. To do that, you have to PUSH the local repository to the master repository. This will back-annotate every change you made across every version of every file. Finally, there is PULL. Often, you will have multiple people working on the same master repository. Or, you may store multiple copies of the local repository, one for each of your computers. In that case, there may be changes in the master repository made from different local repositories. To make a local repository consistent with all the latest changes on the master repository, you would PULL the master repository into the local repository. 6:00 git organization and permissions All of the repositories on GitHub for this called will be on https://github.com/vt-ece4514-s19. On GitHub, a collection of repositories is called an ORGANIZATION. All the TA's and instructors for this class are owners of this organization. That means that they can access everything. In this course, we will work with GitHub in two different ways. (a) We use git to distribute the examples we discuss in class. (b) We use git to distribute assignments and collect your solution. The repositories for (a) are public and can be accessed by everyone. The repositories for (b) are private. They are accessible by you (a single student), the TA's and the instructors. The examples in the class (a) are PUBLIC repositories. Everyone can access them. Furthermore, everybody will check out the same repository and work with it, since changes do not have to be uploaded on GitHub. Of course, on your laptop, you can make any change you want (locally). The assignments (b) are PRIVATE repositories. When you create a repository, it can be accessed only by you and by the TA's and instructors. So, even though these repositories are stored in the same organization, you cannot see the repositories for your peers. Demonstration of operations on repositories. - You will need a git client to download files from GitHub. I use Git for Windows (https://git-scm.com/) for in-class examples, but there are plenty of options (TurtoiseGit, Sublime Merge, ...) Select and use one to your liking. - You will need an account on GitHub IMPORTANT: We will need to know the link between your GitHub account ID and your VTID to accurately grade your projects. We will allow you to establish this connection for the first homework. Follow the instructions with the assignment to make sure your work is graded correctly. Starting from an empty directory ================================================ # download the example git clone https://github.com/vt-ece4514-s19/heartbeatde1soc # other operations here: # compile it ... # quartus_sh --flow compile heartbeatde1soc # download it to the board ... # quartus_pgm -m jtag -o "p;heartbeatde1soc.sof@2" # make a change to a Verilog file, e.g., heartbeatde1soctb.v # then, commit the change git add heartbeatde1soctb.v # check if it will be uploaded git status # check it into the local repository git commit -m 'changes' # upload it to GitHub git push # add a new file, e.g., comment.txt git add comment.txt # send it back to GitHub git status git commit -m 'more changes' git push # remove comment.txt again git rm comment.txt # and remove it from local and remote (GitHub) repository git status git commit -m 'cleanup' git push +------------------------------------------------------------------ | IMPORTANT TO REMEMBER: | for homework submission deadlines, we will use the time of your | last push to GitHub as the turn-in time. Thus it is essential | to ensure that you update the github.com repository as the FINAL | step in your homework assignment +------------------------------------------------------------------ 6:10 Exploring further Version control is an exciting and essential concept for anyone working with design files (e.g., not only software but also schematics, documents, PCB designs, etc.). There is a wealth of information on working with git and version control. Also, there are many concepts in version control that we did not discuss: branches, for example. You will be able to complete labs and homework using the information given in this lecture. If you would like to explore further: - Git Book: https://git-scm.com/book/en/v2 - Git tutorial: https://try.github.io/levels/1/challenges/1 6:15 COMING UP - Homework 1 will be posted later today (1/24). You have one week to solve it. The homework is an assignment on Verilog coding and Verilog simulation Use Piazza for questions - Next week, we do a recap on Finite State Machine Design