Lab 1: Linux Setup

When you're done with this lab you will have done the following things:

Install Git on WSL2
Set up your Linux for running ARM assembly.
Practice basic Linux command lines.
(Optional) Fix a broken image by hacking the raw binary file

The last (optional) item does not have to do with Linux, so can be done even if you are having issues that delay the setup of your WSL2.

Part 1: Git on Linux

Goals of this section:

Launch Linux in WSL2.
Install and practice Git

If you haven't yet, please complete the prelab.

Stage 1: Launch WSL2

Open your Windows Terminal. Ideally, you want to pin this app to the taskbar as we will frequently use it in this class. For example, my taskbar looks like this

drawing

When open Windows Terminal, by default, it will open the PowerShell, which is not the thing we need. Instead, you want to find the "v" icon (drop down menu) to open Ubuntu in a new tab, as shown below.

drawing

Once selecting the "Ubuntu-20.04" option, you can launch the Ubuntu Linux virtual machine and go to the command line environment, i.e., shell. The command line prompt will be like this:

username@hostname: ~ $

username will be your username on your Windows account. And the hostname is the device name generated by WSL2, which can vary based on your machine. The part after the $ sign is the input space where you can type in command lines.

Special Note:

Since this course was originally designed to use Raspberry Pi as the Linux machine, the command prompt in the later instructions (for all labs and homework) will show as

pi@username-pi: ~ $

This is just the username and hostname used on Pi. So simply ignore the username and hostname in the prompt and use the command lines given (the part after the "$") on WSL2.

Also, in all the places we mention Pi in later labs/homework/exams, it refers to your Linux in WSL2.

Now it's time to play around Linux with a terminal. For the rest of this lab, you're going to use a number of linux commands. Here's a quick reference for some of them:

cd <dir>: change directory. For example, cd foo is like opening the folder "foo" and going inside. cd .. goes back up a directory.
ls: show a list of the files in the current directory
cat <file>: display the contents of a file.

Also, in order to run things as an administrator (for example, to install programs), you need to use a command called sudo. This temporarily turns you into an admin called root. Try it!

pi@username-pi ~ $ whoami
pi
pi@username-pi ~ $ sudo whoami
root

Stage 2: Install a command-line web browser

Since your sole access to the Linux is via command line, lets install a browser that works in a text-only environment! To do this, we will use apt.

pi@username-pi: ~ $ sudo apt install links

It will ask you if it's ok to install stuff. Type "y" and hit enter.

Once it's installed, launch it and see if you can view the course website! (Hint: hit the "ESC" key to show menus and "q" to quit).

pi@username-pi ~ $ links http://www.rose-hulman.edu/class/csse/csse132/

SHOW YOUR INSTRUCTOR

Now is a great time to print out the instructor verification sheet and show your instructor.

Stage 3: Install Git

Next, you need to install the git client so you can get your lab and homework materials. Use apt to install it!

pi@username-pi ~ $ sudo apt install git

NOTE: your Linux may already have Git installed. If it does, running this command will result in a message such as:

git is already the newest version

Stage 4: Use Git

Clone your class repository

Clone your repository using a command like this, replacing <username> with your RHIT username. NOTE: <username> appears twice; replace it both times. Use the git clone command:

git clone ssh://<username>@gitter.csse.rose-hulman.edu:/srv/git_repos/2122c-csse132-<username>

Use your RHIT password when asked for a password.
NOTE: GIT may ask you if you want to accept a key. Choose "yes".

Once it's checked out, use the cd command to go into the directory, and the ls command to show your repository's contents. HINT: you can type part of the command (like "cd 1819" and then hit tab to auto-complete the directory).

pi@username-pi ~ $ cd 2122c-csse132-username/
pi@username-pi ~/2122c-csse132-username $ ls
lab01
pi@username-pi ~/2122c-csse132-username $

Configure Git

Next, you will have to tell Git your username and email address. Use the git config command to do this.

git config --global user.name "YOUR NAME"

(replace "YOUR NAME" with your name)

git config --global user.email youremail@rose-hulman.edu

(replace "youremail@rose-hulman.edu" with your Rose email address).

Create and push a new file.

Use the cd command to go into the lab01 folder. Once you're in there, create a new file called "itworks.txt":

type nano itworks.txt to create the file and edit it using nano.
Put your name in the file, and write a fact about yourself (for example, "I like cats").
Save the file in nano (hold the Ctrl key and type the letter O)
Exit nano (hold The Ctrl key and type the letter X)

Now that you've got the file, commit it to your git repository. First, pull any change from the server:

git pull

Then, you need to tell git about the file:

git add itworks.txt

Commit your changes:

git commit -m "added new file in lab 1"

Once it verifies your commit, it's time to upload your new file to the server.

git push

You've committed your first git file with your raspberry pi! Good job!

SHOW YOUR INSTRUCTOR

Check this item off the Instructor Verification Sheet.

Part 2: Get Linux Ready for ARM Assembly

Install Toolchain and QEMU

Run the following command in order to install necessary libs and packages.

Update system.

  sudo apt update -y && sudo apt upgrade -y

Install the ARM cross-compile tools.

  sudo apt install gcc-arm-linux-gnueabihf binutils-arm-linux-gnueabihf binutils-arm-linux-gnueabihf-dbg

Install the emulator (QEMU) to run ARM.

  sudo apt install qemu-user qemu-user-static gcc-aarch64-linux-gnu binutils-aarch64-linux-gnu binutils-aarch64-linux-gnu-dbg build-essential

Compile and Run an ARM program

In Linux, navigate to the hello_ARM folder under lab01 folder under your git repo. This can be done with the following command:

 username@hostname ~ $ cd  2122c-csse132-username/lab01/hello_ARM

Using ls command, you can check the files under this directory:

username@hostname ~/2122c-csse132-username/lab01/hello_ARM $ ls
Makefile hello.s

Then type make to compile the ARM source code. Usually, you will see output like this

username@hostname ~/2122c-csse132-username/lab01/hello_ARM $ make
arm-linux-gnueabihf-as  hello.s -o hello.o
arm-linux-gnueabihf-ld -static hello.o -o hello

Now you can run the executable file by typing make run. Your setup is successful if you can see the message below:

Hello, ARM32!
If you see this message, your ARM env setup is successful!!

SHOW YOUR INSTRUCTOR

Check this item off the Instructor Verification Sheet.

Part 3: Learning and Practicing Linux Command lines

Open a web browser and go to the bandit instruction page using the link below:

http://overthewire.org/wargames/bandit/

Follow the instructions and get into level 5. After finishing each level, save the password on your computer (maybe in notepad). You will need this info later.

SHOW YOUR INSTRUCTOR

Check this item off the Instructor Verification Sheet.

Part 4: Fix an Image (Optional)

This part is done on your laptop, not the Pi. You will want to first clone your CSSE132 Git repo to some directory of your choice on your laptop. Hint: use Git Bash and follow analogous steps as you did when cloning the Git repo on your Pi.

In this part, you will need to tweak the data of an image file to help fix a broken image. To modify the raw data of a file, you need special tools to do that. Frhed is a free binary file editor available on Windows. Follow the link below to download the tool:

Frhed Download Link

Usage:

Launch the tool: Type its name FrHed in the Windows search bar and click to open
Open a file: Inside the tool, click on File tab on the top left corner and open any file you want.
Edit data: Use arrow keys (or mouse) to navigate to the hex number you want to edit, and type the desire hex number. To save the change, press Ctrl + s.

Wrong Format

PNG defines a certain format that a picture file has to follow. If a picture does not strictly follow this format, computers can not recognize it correctly, and thus fail to open it as a picture. This is what happened for this picture.

To fix it, you need to first understand the format specs of PNG. Check the PNG Format Specs page and particularly focus on the File Header section.

Now, open the lab01_broken_pic.png under the lab01 folder in your repo, and inspect the header (the few bytes at the beginning) to see if it matches the format specs in the Wiki page. Fix the incorrect byte.

If you successfully correct the header, the picture can be opened as a picture to view.

Wrong Size

When opening the picture, you will see extra white space below the picture. That's because the size specified in the file is not correct, specifically the height is too big. (You can find the size information by right clicking the file -> Properties -> Details Tab.)

Check again the PNG Format Specs to find the bytes that define the height.

Hint: After the header, comes a series of chunks, each of which conveys certain information about the image. The height is defined in the IHDR chunk, the very first chunk of the file.

Once you find the bytes that define the height, change it from 666 to 410. First, convert these two numbers to hex and then edit the bytes accordingly.

If you did that, your image file should be broken again. If it is not broken, it is just because the software ignores the error.

Fix the CRC

The reason it should break is because the software should notice we edited (corrupted) the file so it should consider the file is not safe. The way the computer detects this problem is to use certain bytes in the file to calculate a validation code, called CRC (cyclic redundancy checksum). It will compare the computed result with the checksum stored in the file. If the result doesn't match, it knows the file is corrupted. In our case, the CRC for the IHDR chunk is not correct given the modified height info. To find the the CRC, pay attention to the "offset" shown at the bottom left corner of the app: the CRC's first byte is at the offset/address 0x1D.

We need to re-calculate the CRC. Once we know which bytes we need to use to generate the new CRC, we can simply use this website CRC calculator to calculate new CRC. Based on the specs, we know the CRC for this chunk is calculated over the chunk type and chunk data (Hint: from offset 0xc to 0x1c). So, type those bytes into the website and choose CRC32 to calculate the new CRC. Then change the CRC in this chunk.

Once you have done that, you should be able to open the file correctly with the proper size.

Finishing the Lab

Submit any electronic files you create to git (using git add <file> for each file, then git commit and git push.). (Probably you already did that for this lab)
To make sure your git submission has successfully reached the server, a quick way to check is using the following command: git log --stat -1
Make sure you see your latest commit (e.g., adding test.txt) appears in the output. Also, double-check if the first line of the log message includes origin/master in the parentheses. If not, try to git push again.
Submit the instructor verification sheet in hard copy.