From: Jack Wolfard Date: Sat, 28 Aug 2021 03:42:55 +0000 (-0400) Subject: Update lab 0 instructions & scripts X-Git-Url: https://git.devinivas.org/?a=commitdiff_plain;h=2902e4a498b85e5ddadea8712b4974b50000ac98;p=cs3210-lab0.git Update lab 0 instructions & scripts --- diff --git a/instructions/autograder_instructions.md b/instructions/autograder_instructions.md deleted file mode 100644 index 92624e3..0000000 --- a/instructions/autograder_instructions.md +++ /dev/null @@ -1,211 +0,0 @@ -# Autograder Manual - -The purpose of this document is to outline the functionality, use, and rules of -the cs3210 autograder. - -In cs3210 this semester we will be using an interactive autograder to help -evaluate your lab solutions. The autograder will download your submissions from -[GaTech's GitHub](https://github.gatech.edu), and then run a series of tests on -your code, delivering the results to you as it runs (usually). - -The goal of the autograder is to help you ensure you've implemented the project -correctly, and have a good idea of the credit you will receive. It is not -intended for debugging your project, and will not deliver particularly useful -feedback (it will only tell you if you pass or fail a test, not what that test -was, or why you failed). - -## Autograder Policies - -The autograder is intended to help you throughout this course, and give you some -confidence as to where you stand with your lab submissions. However, the -autograder doesn't have infinite resources, and needs to ensure submissions are -kept safe. As a result, the autograder has several specific policies it will -require you to adhere to. - -### Feedback Submissions - -If students were to all submit their lab frequently (and last minute), the -autograder queue would become very long, potentially causing students to wait -many hours before their submission is graded, resulting in poor grades and late -submissions. This issue is caused by students attempting to use the autograder -as a last-minute debugging tool instead of its true intention -- an automatic -grading and feedback mechanism. To help alleviate this issue, the autograder -will only provide students with a limited amount of feedback per day by limiting -the number of submissions it provides feedback for. - -To be more precise, when you run the autograder with a feedback-enabled -submission, the autograder will tell you what test number it's running, if you -passed that test, then ultimately the total number of tests you've passed. This -will give you a good idea of how well your submission did. Once you've expended -all of your available feedback enabled submissions, the autograder will only -tell you that it has run your submission, and provide no graded feedback. - -The policy on feedback-enabled submissions is that students get one-per-day -(a day starts at midnight, and ends at midnight). These "feedbacks" cannot be -stockpiled (it goes away at midnight). However, we understand that sometimes -students are working hard and don't want to wait until the next day to submit, -so we provide 3 extra graded feedbacks per project, which the student may use at -any point in place of a non-feedback submission (e.g. at your 2nd+ submission -for that day). These extra feedbacks do not transition between projects. - -### Malicious Submissions - -All submissions to the autograder will be logged both locally (on the -autograder) and remotely (off the autograder), and may be audited. Any -unauthorized attempt to subvert the autograder, either by gaining control of the -autograder machine, exposing autograder testcases, or generally using the -autograder for any purpose other than its intended one (to grade your code), -will be considered a violation of Georgia Tech's honor code and will be -severely punished. The autograder has many safety checks and fail-safes in -place. Do not attempt to attack the autograder! - -### Autograder-Specific Requirements - -The autograder does place some specific restrictions on how you modify your -code and construct your labs. You may add any source files you like to the -bootloader, kernel, or user files, but the autograder will not respect any -changes to CMakeLists.txt (that would allow students to run arbitrary code). -Instead, you must specify any changes in the list within the Sources.cmake -directory. - -Additionally, the autograder will ignore any changes made to any of the scripts -run to create the kernel. The files the autograder will ignore or overwrite -includes: - -- CMakeLists.txt -- user/CMakeLists.txt -- kernel/CMakeLists.txt -- bootblock/CMakeLists.txt -- tools/CMakeLists.txt -- scripts/xv6-qemu -- tools/mkfs -- tools/cuth -- tools/printpcs -- tools/pr.pl -- tools/runoff -- tools/runoff1 -- tools/runoff.list -- tools/runoff.spec -- tools/show1 -- tools/spinp -- tools/toc.ftr -- tools/toc.hdr -- kernel/tools/mksym.sh -- kernel/tools/vectors.pl - -Furthermore, the autograder restricts the changes you are allowed to make to your -Sources.cmake (`kernel/Sources.cmake`, `user/Sources.cmake`, and -`bootblock/Sources.cmake`). You are only allowed to modify the lists present in -those files. - -You **may not** add any autograder generated files (e.g. anything in the `build` directory, -or any files generated by `cmake` to your git repository. Doing so will likely cause an autograder -error, wasting your submission. - -Finally, when the autograder runs your code, it will do so in Release mode (with -the option `-DCMAKE_BUILD_TYPE=Release`). Ensure your code works in Release -mode before submitting it to the autograder! - -### Misc Autograder Rules - -- You may only have one submission queued at a time (if you have a submission - queued, but not yet graded, the autograder will reject additional submission - requests until your submission is graded). -- You may not modify the transition interface between the bootblock and the kernel. - Doing so may cause the autograder to crash when booting your kernel. - - -## Autograder Use - -To use the autograder, visit the [autograder page][autograder], and click the -authenticate button. NOTE: You'll have to be logged into the campus VPN to access -it. This will bring you to a GitHub login page, where you will -give the autograder permission to know your identity and checkout your private -repositories. Once you've completed the authentication, you will be taken back -to the autograder, where the autograder will display the available labs. From -here the operation of the autograder should be mostly self-explanatory. We'll -outline a few important details about lab submission now. - -### Submission Confirmation - -Once you choose to submit your lab, the autograder will show you a confirmation -page, containing a series of information looking somewhat like this: - -``` -Grade request for lab: lab1 -Request has locked in timestamp: 06-23-2020 11:43 - -github commit hash to be graded: d6f55858a1945baaf1e1925eddbf8fe29dc3fe14 -Your request will do the following: -Original Due Date (before late days): 09-02-2020 23:59 -Previous Due Date (after previously applied late days): 09-02-2020 23:59 -New Due Date (after late days applied for this request): 09-02-2020 23:59 -Late Days applied for this request: 0 -Late Penalty (if you're out of late days): 0% -Late Days remaining: 3 - -Feedback Given: True -Extra Feedback Used: False -Extra Feedback Remaining (after submission): 0 - -You have 5 minutes to confirm this submission, afterwards a resubmission is -required. -Continue with this submission? (resources will only be used after confirm) -``` - -Here is a quick breakdown of the fields in this confirmation message: -- **Grade request for lab** -- What lab are we grading? -- **Request has locked in timestamp** -- If you hit confirm within the next 5 - minutes, this is the timestamp that will be used for the purposes of grading - your lab (and determining late-ness). -- **github commit hash to be graded** -- This is the GitHub hash that will be - checked out and graded by the autograder. Ensure it matches the hash you've - last commited and pushed to your GitHub repository (e.g. with `git log`). -- **Original Due Date** -- If you were to never use late-days on this lab, when - would it be due? -- **Previous Due Date** -- Before this submission, what was your due date (any - late days you've used as a part of prior submissions will be reflected here)? -- **New Due Date** -- After this submission, this is your new due date (after - late day application). -- **Late Days applied...** -- The number of late-days that will be used as a - part of this request (remember, you only get 3 for the entire semester). -- **Late Penalty** -- What penalty to your score will you get from this - submission due to it being late? -- **Late Days Remaining** -- The number of late days you have remaining for the - semester (after any late days in this request are used) -- **Feedback Given** -- Will this request give you feedback? -- **Extra Feedback Used** -- Will this request use one of your extra feedbacks? - (you get 3 per lab) -- **Extra Feedback Remaining** -- How many extra feedbacks will you have after this - submission? - - -### Group Creation - -The autograder allows creation of groups. By default every student is in their own -group, with their own repositories. Starting from lab2, if students wish to partner -with another student, the autograder will support this behavior. To create a group -and get a github repository for your group please do the following: - -1. Decide on a `group_name`. This name must be alpha-numeric (only using characters `[a-zA-Z0-9]`). -2. Have one partner generate an autograder key (NOTE: this key only lasts for 5 minutes) - - To do so, log into the autograder and click the "Get Group Key" button. - - The displayed screen will have a unique key -3. Have the other partner create the group: - - Select the "Create Group" button - - Enter your group name in the "Group Name" box - - Enter your *partner's* key in the Partner Key box - - Press "Create Group" - -Once this process is completed the autograder will begin to make your group. It will -create a new github repository for you and your partner called `cs3210-spring2021/-xv6-public.git`. -Both you and your partner will have write accesses to this repository, and all future -autograder submissions for either of you will come from this repository. - -**NOTES**: Once you join a group, you cannot leave or form a new group without informing -the instructional staff (we'll help you with that process). Groups are intended to last -the semester, however we understand that sometimes its best not to stay in your group. To -discourage group hopping we don't enable creating switching groups (once you've entered your first group) -by default, but we will allow you to switch groups if needed. - -[autograder]:https://cs3210-autograder.cc.gatech.edu/index.html diff --git a/instructions/lab0.md b/instructions/lab0.md index bd3afbd..765c24e 100644 --- a/instructions/lab0.md +++ b/instructions/lab0.md @@ -5,28 +5,40 @@ gained with xv6, particularly the boot process (which you'll be modifying in lab 1), as well as to gain some familiarity with the tools we'll be using as a part of this course. -This is the only lab where you will submit answers to questions, in prose.  All -other labs will be autograded, and based on code. +This is the only lab where you will submit answers to questions through Canvas. +All other labs will be autograded. -For this lab, you will submit your answers to the canvas Lab0 assignment as a -txt, md, or pdf file by the due date and time given in the schedule. +## Requirements +In order to interface w/ our scripts, you must be able to run Bash and Docker. +Our recommendation for Windows users is to use WSL with Docker. Further help +can be provided through Piazza or Office Hours for getting this setup. + +- Docker +- Bash +- Git ## Downloading, Compiling, and Running xv6 +Start by checking out the xv6 repository on your local machine. + +```bash +git clone git@github.gatech.edu/cs3210-fall2021/xv6.git +cd xv6 +``` -Start by checking out your xv6 repository. The following line will clone your -code into cs3210\_lab: +Next, launch the docker instance for the class using the provided script. ```bash -git clone git@github.gatech.edu/cs3210-spring2021/-xv6-public.git cs3210_lab +./scripts/docker.sh --pull # download the image from DockerHub +./scripts/docker.sh # run container and mount the pwd as /xv6 ``` -Now, build your repository.  We recommend building within a separate build -directory: +Now that you're inside the docker instance, build your repository. We recommend +building within a separate build directory: ```bash -cd cs3210_lab +cd /xv6 mkdir build cd build cmake .. -DCMAKE_BUILD_TYPE=Debug @@ -35,18 +47,6 @@ make This will build and install the kernel. -**NOTE:** Depending on the state of your VM installation, you may have to install -some programs, such as gcc, make, cmake, to actually build the kernel. Install -any missing programs as follows -```bash -sudo apt install -``` - -If you have a new installation, we recommend installing at least: -```bash -sudo apt install gcc build-essential cmake qemu libvirt-dev -``` - Once make complete successfully you can try to boot the kernel by running our xv6-qemu script (from within your build directory): @@ -54,7 +54,7 @@ running our xv6-qemu script (from within your build directory): ./xv6-qemu ``` -This should launch xv6 and take you to a prompt. You can view avaialble files +This should launch xv6 and take you to a prompt. You can view available files with `ls`. You can close qemu by pressing CTRL-a followed by x. ## Observing behaviors with gdb @@ -67,18 +67,19 @@ launcher script, please launch the xv6 launcher with gdb enabled: ``` This should pause qemu from launching, and wait for a gdb session to attach. -Now, in a separate terminal, launch gdb from your build directory: +Now, we can connect to our Docker container in a separate terminal and launch +gdb from the build directory: + ```bash -cd +./scripts/docker.sh --attach +cd /xv6/build gdb ``` -**NOTE:** gdb may give you an error. Please follow the instructions they give -you to enable gdb to use our `.gdbinit` script to connect to qemu. - Once this is complete, it should take you to a gdb console, with the initial BIOS `ljmp` instruction from the x86 machine's reset vector: -``` + +```x86 ljmp $0xf000,$0xe05b ``` @@ -88,20 +89,20 @@ address. Look up real-mode addressing, what is the linear address to which it is jumping? (this question is ungraded) Find the address of \_start, the entry point of the kernel: -``` + +```bash $ nm kernel/kernel | grep _start 8010b50c D _binary_entryother_start 8010b4e0 D _binary_initcode_start 0010000c T _start ``` - The kernel address is at 0010000c. Open gdb in the same directory, set a breakpoint and run to \_start as in the following: -``` +```bash $ gdb ... The target architecture is assumed to be i8086 @@ -131,9 +132,9 @@ Look at the registers and stack: The stack grows from higher addresses to lower in x86, so items pushed on the stack will be at higher addresses the earlier they were pushed on. -## Graded Questions: +## Graded Questions -Answer the following: +Answer the following on Canvas: 1. What address is the start (first pushed element) of the stack? @@ -161,7 +162,7 @@ where eip is set to 0x10000c. What happens to the stack as a result of that call? Look at the bootmain C code and compare it to the bootblock.asm assembly code. -## Extra (not graded): +## Extra (not graded) For thought: (let us know if you play with it!): Most modern OSs boot using a firmware standard called UEFI instead of the older standard BIOS. Bootloaders @@ -174,4 +175,3 @@ firmware load such as OVMF, and QEMU, show using gdb that you can reach the kernel entry point. What did you have to change to get this working? (You may use the 64-bit architecture qemu for this to avoid having to compile OVMF 32-bit.) - diff --git a/scripts/docker.sh b/scripts/docker.sh index e6f6608..1f958f5 100755 --- a/scripts/docker.sh +++ b/scripts/docker.sh @@ -1 +1,50 @@ -docker run --rm -it --name="xv6" -v ${PWD}/:/xv6 -w="/xv6" jackwolfard/cs3210:latest +#!/usr/bin/env bash + +function usage() { + cat < /dev/null && pwd)" +cd "${SCRIPT_DIR}/.." +ROOT_DIR="$(pwd)" + +PULL=false +ATTACH=false + +for arg in "$@"; do + case $arg in + --pull) + PULL=true + shift + ;; + --attach) + ATTACH=true + shift + ;; + -h | --help) + usage # run usage function on help + ;; + *) + usage # run usage function if wrong argument provided + ;; + esac +done + +if [[ $PULL == true ]]; then + echo "Pulling latest image from DockerHub" + docker pull jackwolfard/cs3210:latest +elif [[ $ATTACH == true ]]; then + echo "Attaching to container" + docker exec -it xv6 bash +else + echo "Starting xv6 container" + docker run --rm -it --name="xv6" -v ${ROOT_DIR}/:/xv6 -w="/xv6" jackwolfard/cs3210:latest +fi