4  Lab 1 Assignment

4.1 Steps To Prepare for Doing Lab 1

Caution

This part is only for students at NCKU.

After accepting Lab 1 on the GitHub Classroom, you should have your own repository which contains the code template for lab 1. Please clone the owned repository into your docker development environment under the path /home/ubuntu/workspace.

$ git clone <link_to_your_own_repo>
$ cd <your_folder>
$ git submodule update --init --recursive
$ pre-commit install

4.2 How to Start to Write Codes?

In most cases, the only file you must modify is src/core.c. More precisely, you should complte the missing parts of the two functions Core_decode() and Core_execute().

4.3 After Completing Coding

After finishing the implementation of the ISS, you can now compile it and run the unit tests. There are a few steps to do to run unit tests:

  1. Compile the unit tests itself

    $ cd riscv-tests/isa
$ make -j
# go back to root path of lab-1
$ cd ../..

  2. Compile the ISS you implement

    $ mkdir build && cd build   
$ cmake ..
$ make -j

    Build the ISS

  3. Execute ctest to run all the 37 instruction unit tests

    Caution

    Please make sure that you are inside the folder build.

    $ ctest

    Run CTest

Besides, you can run the command below if you want to run a specific test case (e.g., runs ADD instruction only):

$ ctest -R "add\$"

Furthermore, you can also run tests in the unit of a opcode-type (e.g., runs OP-IMM opcode-type instructions only):

$ ctest -R "^OPIMM_[a-z]+"

As the minimal requirement, you should pass the 37 unit tests for instructions we implement in the ISS.

Note

The expressions add\$ and ^OPIMM_[a-z]+ are related to regular expression and escape character. If you are interested in regular expression, you can use the website regex101 to test and verify the regex patterns you write.

4.4 What You Must Do To Complete The Assignment?

There are two parts you must complete in the assignment:

  1. The program part (i.e., the ISS) — 80% of scores
  2. Assignment Report — 20% of scores

In the program part, the score is further divided into two parts:

  1. ISS compilation test
    • You can get 10% of scores if your ISS can be compiled without any error
  2. Instruction unit tests with riscv-tests
    • TA divides the 37 instruction unit tests into 9 parts according to the opcode map, and the division of scores is related to the number of instructions for each opcode-type.
      • OP, (15 pts)
      • OP-IMM (15 pts)
      • LOAD (8 pts)
      • STORE (8 pts)
      • BRANCH (8 pts)
      • JAL (4 pts)
      • JALR (4 pts)
      • LUI (4 pts)
      • AUIPC (4 pts)
    • You will get 70 pts if you pass all the 9 groups of test mentioned above.

4.5 How to Turn in Your Assignment Report

You should see a file called report.md inside your homework repository. Please complete the report in plcae, commit it, and push the commit to your remote repository on GitHub.