Assignment Requirements for EE/CSE 371

Effective technical communication is a particularly critical skill once you graduate. This can take the form of writing research grants and papers, writing documentation for your work, teaching, or making presentations to your collaborators, managers, clients, or venture capitalists.

371 employs multiple forms of technical communication: lab demos, lab reports, homework, and code commenting. Lab demos allow you to practice verbal communication, while homework, lab reports, and code allow you to practice written communication.

The assignment documents (lab reports and homework), in particular, serve a couple of roles:

1. Communicate to us that you learned and/or achieved what we wanted you to, and
2. Create a persistent digital artifact that you can refer back to in the future.

But just having a digital artifact is insufficient if you can't understand it! Along those lines, it is very important that your work is properly explained, including using good style in your SystemVerilog code. Having good style while you are writing code will also make debugging a lot easier!

In order to balance the importance of technical communication with the other work in this course, we only ask that the requirements laid out by the rest of this page are met.

• Lab reports and homework must be submitted as a single PDF file.
  1. You can print directly to PDF from Office products (like Microsoft Word) and combine multiple PDF files into one using Adobe Acrobat or online websites.
  2. Any materials generated by hand can be included by scanning or importing a photo.
  3. Any materials generated digitally can be imported or included via screenshot.
• SystemVerilog HDL files should be submitted separately and do not need to be included in your lab report and homework PDFs.
• Lab reports and homework should begin with (1) your name(s), (2) your student ID number(s) (e.g., 1234567), and (3) the assignment number (e.g., Lab 2, Homework 3).
• Everything included in your lab reports should be comprehensible, properly labeled, and explained. Someone who hasn't taken this class should be able to understand at a high level what you did and why just by reading your document.
• Homework will also involve explanations at times, but the formatting and detail requirements will be much laxer, as these are intended to be opportunities to practice with the course material.

The goals of the lab demos are a chance to (1) show off your project live, (2) practice verbal communication, and (3) check in with the course staff and get some immediate feedback.

• The lab demos are not intended to be a secretive assessment; you should have a general idea of how you did by the end of every demo.
• If you worked with a partner, both partners must be present for the lab demo and are expected to both provide responses during the demo.

Demonstrating Your Project

Depending on the lab, you may not be asked to demo every task. Pay special attention to the notes at the end of each lab spec to see generally what will be asked of you.

To show proper behavior of your system, you should already have some input sequences in mind (hint: refer back to your testbenches). For some labs, the TAs may ask you to demonstrate specific input combinations or behaviors, but these won't always be provided ahead of time.

Demo Questions

After the demonstration portion, the TA will ask you 1-2 questions about the lab. The demo questions generally fall into one of the following categories:

1. A review question based on lecture material related to the lab.
2. Describe some piece of your design.
3. Talk through a tweak to your design.

These are not intended to be a grilling (i.e., this is not an interview). These are more about your ability to talk about your design and design process. The TA may follow up with clarifying questions or feedback about your responses.

Not all of the following requirements will apply to every lab, but this outline and the rubrics at the end of the lab specifications are intended to act guides to your lab report writing and the lab report grading. If ever in doubt, please post any questions you have on the course discussion board.

Lab reports should include the following three main sections:

1. Design Procedure
   • Give a brief description of how you approached the tasks in this lab.
   • Include diagrams of your system design. This will always include a block diagram of your overall system but can also include finite state machine (FSM) and algorithmic state machine (ASM/ASMD) diagrams, depending on the lab.
   • For each major component of your system, (1) highlight important features and (2) discuss how and why you implemented it the way that you did.
     • Include snippets of important pieces of code, if helpful to your discussion.
2. Results
   • Give a brief overview of the finished project, highlighting any differences compared to what was asked for and decisions you made that were not specified.
   • Include screenshots of your ModelSim results for important modules and clearly describe what was tested and how the screenshots verify/demonstrate the desired behavior.
     • If you are using a provided module or reusing a module from a previous lab, you do not need to verify its behavior, but you should mention where it came from.
   • Include a screenshot of the "Flow Summary" from your Compilation Report for your final Task. No explanation needed.
3. Experience Report
   • Give any positive or negative feedback you have on the lab. What was your implementation experience like?
   • Describe any significant issues you encountered while completing the lab and how you overcame them (or "I did not encounter any significant issues in this lab").
   • Include any tips and/or tricks that you discovered while completing the lab – these tips may prove useful to you in future labs!
   • Your lab report should end with your estimated total time (in hours) to complete the lab.
     • This includes reading, planning, design, coding, debugging, testing, etc.

Your overall goal is to make your code easy to read and understand, particularly without having to dissect or even read every line of code. This will be helpful for others (and future you) to figure out what your code does, or is supposed to do, and how different parts of your code fit together.

• Choose meaningful and descriptive names for modules, parameters, wires, regs, logics, etc. If you do use vague names, make sure that there are comments that clarify their purpose.
• The contents of each block of code (e.g., always, initial, for, module) should use an extra level of indentation.
  • begin can be on the same line as the start of the block or on the next line at the same indentation level.
  • Each end or endmodule should include a comment indicating which block it closes.
• Each module needs to have a block comment in front of it that:
  • Describes its overall function,
  • Briefly explains the module ports, including their bit-widths, and
  • Mentions any connections to other modules.
• Every major "chunk" of code (e.g., blocks of code such as always_comb/always_ff, collections of assign statements) should have a comment explaining its purpose.
• Any unclear, messy, or complex lines of code should have an explanatory comment.

Example Code Styling and Commentary

• Lines 1-3: Each module should have a comment mentioning all inputs and outputs, as well as the bit-width of each (these are not necessary for DE1_SoC). The comment should also describe the module's functionality and other important notes.
• Line 9: Every submodule instantiation should have a comment explaining its role and the port connections, particularly if this module type is instantiated more than once.
• Line 12: Large sections of code, including always_comb blocks, always_ff blocks, and multiple assign statements in a row should have a comment explaining their purpose and behavior.
• Line 20: Closing comment for modules should be the module name. Closing comment for long blocks can just be the block name (e.g., always_ff). These comments make visually scanning your code much easier.

Homework coding problems are opportunities to practice writing, testing, and debugging SystemVerilog code in the context of recent course material; these programs will NOT be run on hardware. Homework write-ups are more informal than lab reports, and we will often use autograders to check the quality of your coding instead of requiring screenshots of simulation results and explanations. However, the autograders are known to be pretty brittle, due to the limitations of autograding simulation results and the tension of using them in a class about design.

After submitting your homework files to Gradescope, (1) add any group members that you worked with to your submission, and then (2) wait for the autograder to finish executing so you can check for any issues (e.g., the autograder will notify you if you forget to submit any required files).

• If the autograder "failed to execute properly," "timed out," or "terminated with 'Killed'," please make a private Ed post and include a link to your submission as soon as possible so we can investigate.
• However, if your submission fails for reasons that amount to either (1) not following the directions (e.g., misnamed module) or (2) not testing your code (e.g., bad syntax), very little leniency, if any, will be given.

Tips to Avoid Penalties and Issues

• Use provided starter code — These are typically module skeletons that will provide module and port names to use/follow and may define intermediate signals. Don't change the provided lines of code unless you are specifically asked to do so (other than "to-do" comments).
• Double- and triple-check the problem statement — There may be bullet points that dictate the names of signals or states to use (be especially careful with capitalization!).
• Use a sane clock period — Remember that it's arbitrary time units in simulation! No need to make your period unnecessarily long and risk running into a simulation time out (though we'll see how to specify the precision of simulated time later in the class). A clock period on the order of 20-50 arbitrary time units is usually sufficient.
• Actually compile and simulate your code — Non-compiling code will automatically receive a 0. Submitting untested code means you are missing out on one of the main purposes of the homework, which will likely also hurt you on the labs (in debugging time and/or points).
  • The autograders expect to find the system task $stop; at the end of your test bench, which is necessary to actually view your simulation in ModelSim (otherwise the simulation ends/terminates automatically).