Assignment: Zero

Assignment Manifest

Each CS 240 assignment starts with an assignment manifest describing Due dates, the honor code Policy for collaboration and submissions, how to find starter Code, how to Submit your work, and a list of topics that are good Reference.

In this assignment, please ignore the Code and Submit lines above until directed explicitly. For this assignment, learning how to acquire starter code is part of the assignment itself. In future assignments, they serve as quick reminders of standard steps, with links to the full documentation.

(Orange boxes mark key information or warnings.)

Contents

Overview

This assignment is a joint lecture/lab assignment with a few tasks/goals:

Notes:

  • This is an individual assignment, meaning each student will submit their own work. Critically, each student should complete all of the tool and setup steps in their own account. We will rely on this going forward.
  • Since this is a practice assignment, you are encouraged to collaborate on ideas or troubleshooting with other students or work together, even though you will each submit your own work.
  • The tools will be new to most of you. It is expected that you may need some support in figuring them out. Please post questions or visit help hours if you get stuck.
  • Compared to the assignments that will follow, this one involves more tool setup and tool learning, less concept thinking, and fewer points.
  • You can do Tasks 1 and 3 in any order. But in order to write/submit answers to Task 2 you must first complete Task 1.

Task 1: Set Up Accounts and Tools

Please complete these tasks in order to set up your computer and CS account for access to CS 240 tools.

Connect to the CS GNU/Linux computing environment.

Since CS 240 studies low-level concepts, you need to use the computing environment we have prepared to avoid incompatibilities between the different low-level details in different computing environments. While the concepts are general, concrete low-level details differ among real systems. These real differences can cause obvious or subtle problems if doing CS 240 assignment work in a different environment.

You will see the following reminder of this fact in assignments:

CS 240 code assignments require a CS 240 GNU/Linux computing environment.

CS 240 code assignments are designed, tested, and graded in the CS 240 GNU/Linux computing environment, since low-level system details matter in this course. We guarantee support (help with provided tools) and consistency (our grading and your testing use the same environment) only for work in a CS 240 GNU/Linux computing environment.

You can complete the setup steps for this assignment and access the CS 240 GNU/Linux computing environment either locally in the SCI L037 CS Systems Lab or remotely on your own computer.

Local Access

During software-focused lab exercises or some drop-in hours in the SCI L037 CS Systems Lab, you will use the CS GNU/Linux environment directly on the lab machines. When on a lab machine, you do not need to use a remote extension or SSH manually.

Most of the lab machines in the SCI L037 CS Systems Lab run GNU/Linux (Rocky). Some can also run Windows.

  • During the first few labs of the course, you will use a digital logic simulator that runs in Windows. Use your Wellesley username/password to log in.
  • For this assignment and all other code parts of the course, you will use software tools in GNU/Linux. These computers are labeled Rocky (the specific variant of Linux installed). Use your CS username/password to log in.

If you encounter a SCI L037 CS Systems Lab machine that is running Windows, follow these steps to switch to Rocky GNU/Linux:

  1. Reboot the machine.
  2. Wait for the “Lenovo” logo to appear on the screen.
  3. Press the F12 key repeatedly until the scree changes to a menu.
  4. The UEFI boot menu will come up and give you a choice of Rocky or Windows. Select Rocky.
  5. Select Rocky again on the next screen if given the option.

Remote Access

If you wish to work outside the lab, you will connect remotely to the same CS GNU/Linux environment.

Configure your CS account to use CS 240 software tools.

These tasks will get you started using the command-line interface through a terminal.

At the text prompt in the terminal, type the following command exactly and hit return/enter to run it:

source /home/cs240/live/env/init/account.sh

This is a one-time setup step that configures your CS account permanently1 to find CS 240 tools. Regardless of whether you connected locally or remotely, you do not need to repeat it later.

Again do the following steps just once this semester.

  1. Authenticate your account with CodeTub for access to hosted repositories by running the command:

    $ cs240 auth -i s24

    This command will prompt for your human name, CS username, and password. It may take a moment to complete.

  2. Create a directory where you will store CS 240 assignments: cs240-repos is a great choice. Make sure to take note of where you created this directory (we suggest doing it in your home directory, which you can get to by running cd ~ first).

    $ mkdir cs240-repos

Learn some terminal basics.

CS 240 requires (but does not assume you have) some basic terminal skills. This section gives a quick warm-up on the command line with the CS GNU/Linux machines. You can skip it if you are already comfortable with the terminal/command line.

(This part is adapted from past CS 240 lab activities by Jean Herbst.)

An operating system is the software which manages and controls all other applications and resources on a computer. The computers we use in CS 240 use the GNU/Linux operating system, which combines the Linux kernel (the operating system core) with the GNU operating system utilities.

For many CS 240 tasks, you will enter text commands directly at a prompt in a terminal window, rather than selecting options with a mouse through a graphical interface. A terminal is a session that can receive and send input and output for command-line programs. A shell is a program that is used for controlling and running programs interactively via a terminal. Sometimes the two terms are used interchangeably, though they are technically distinct.

Continue using the terminal you already have open.

For each of the following steps, try the specified command and consider any questions listed. You do not need to submit answers to these questions anywhere..

Commands:

  1. pwd: Print the working directory (the directory you are currently where you are currently working). The shell always works in one directory at a time. Your command prompt may also show this information.

  2. ls: List the files and subdirectories in your working directory.
    • How do you know whether the items listed are files or subdirectories?

  3. ls -a: Are there any files which begin with a .?

  4. man ls: Check the manual for all the different options for using the ls command. Type SPACE to advance one page, q to exit.

  5. mkdir my-dir: Make a new directory called my-dir

  6. cd my-dir: Change your working directory to the new directory.

  7. echo YOURNAME: (Replace YOURNAME with your name.) Echo your name to the screen.

  8. echo YOURNAME > test1.txt: Echo your name again, but this time redirect the output into a new file named test1.txt.

  9. List the contents of the directory to see whether the new file was created or not. Then, use two different commands to display its contents to the screen (without an editor):

    • ls
    • less test1.txt (Page down with SPACE, exit with q.)
    • cat test1.txt
  10. Check out additional reference (from CS 304, ignore drop) or other reference on the tools page as needed.

Learn Git basics for CS 240.

CS 240 uses the Git version control system to help manage assignment code. We do not assume you have used Git before. Even if you have used Git, there are some aspects of our workflow that will be new to you. You can skip this part if you are already comfortable with Git.

Optional: complete the Git for Code Assignments tutorial, starting at Concepts. Continue through First Steps and Solo Basics, then stop just before Team Basics. You do not need to submit anything for this component.

Task 2: Make Nothing from Something

Prerequisites

Before working on this task, you must first:

  • Have some familiarity with basic concepts from the Data as Bits topic. If you are a little stuck on this part, that is not a problem. It is a low stakes exercise.

In the ideal case, you should also:

  • Complete the Task 1 account and tool setup above before this task; and
  • Create your zero repository by going to your cs240-repos directory and running this command in your CS terminal: cs240 start zero --solo.

However, before you attend Lab 2, we expect you to complete 4 bit puzzle functions from Assignment Zero Task 2 (zero_xor, zero_and_not, zero_or_not, and zero_plus_not). Although these functions are quick to define, completing the setup in Task 1 can take a long time, and we don’t want that to stand in the way of defining the four functions before lab.

For this reason, we’re providing you with an easier way to solve and test the 4 bit puzzle functions:

  1. Open this online C compiler in a new browser tab/window. We’ll often use this browser-based compiler as a quick way to write and execute C code during the course
  2. Use this code to completely replace the default code in the online C compiler.
  3. Modify the definitions of the 4 functions zero_xor, zero_and_not, zero_or_not, and zero_plus_not until pressing the Run button shows that all tests are passed.

Note that you’ll also still need to flesh out the definitions of these 4 functions in the zero.c file in Task 2, but that can wait until after Lab 2 if you don’t have time to complete it before Lab 2.

Overview

In this part, you will do some brief C programming with bitwise operators in the file zero.c in your zero repository. The goal is to write several functions that take any byte value as an argument, and, no matter what that byte value is, return the zero byte, 0x00. Of course this is trivial! Just return 0x00;!

To make the task a little more interesting, we prohibit you from using any operations except a small handful. As an example, the zero_minus function must use only the MINUS operator, -, and the parameter, x. (return and semicolon are also allowed and necessary.) No other C features are permitted, not even literal number values like 0 or 0x00.

Example

/**
 * EXAMPLE: zero_minus
 *
 * Goal: take an unknown byte value `x` and return the byte value 0x00
 * no matter what `x` is.
 *
 * The body of the function may use only `return`, `;`, `x`,
 * and the MINUS operator `-`.
 *
 * No other C features are allowed.
 */
byte zero_minus(byte x) {
  return x - x;
}

This function returns the zero byte (0x00) no matter what x it is given.

For simplicity, we use the type byte (instead of the actual more verbose C type unsigned char) to describe a 1-byte value in the range 0x00 to 0xff. Note: byte is not a standard C type name. Comments in zero.c explain its definition.

Task Specification

Your task is to replace the bodies of several more functions defined in the zero.c file that should behave just like zero_minus but with different restrictions:

  • zero_xor uses only bitwise XOR (^).
  • zero_and_not uses only bitwise AND (&) and bitwise NOT (~).

  • zero_or_not uses only bitwise OR (|) and bitwise NOT (~).

  • zero_plus_not uses only integer addition (+) and bitwise NOT (~).

Any of these functions may use their parameter, x, as many times as needed, and as many parentheses as needed.

Hint: The simplest solutions are all quite short and easily fit on one line.

Compiling and Testing

The main function in the file zero_test.c tests the behavior of these zero-producing functions on all possible byte argument values. An incorrect return value from any function causes the program to print an error message.

Before we can run the testing code or any program based on our zero.c code, we must compile the source code of the program to produce a binary executable. The source code files contain C-language code stored as human-readable text. An executable is a file containing machine instructions encoded in binary. The compiler translates from human-readable C code to machine readable executable code. Once we have an executable, we can run it as many times as we like.

Compiling an Executable from Source Code

To compile your puzzle solutions from zero.c with the test harness in zero_test.c and produce a binary executable with testing code, run the command make. This command uses compilation recipes in the Makefile to produce an executable called zero.bin. If your code compiles successfully, the session will look like this:

$ make
gcc -std=c99 -O0 -g zero.c zero_test.c -o zero.bin

If you have not changed zero.c since the last time you compiled, you will see:

$ make
make: 'zero.bin' is up to date.

Any other output indicates an error. Read the error message to determine how to proceed.

Running an Executable

Now that the executable zero.bin has been compiled, we can run it with the command ./zero.bin. Before you have made changes, expect to see:

$ ./zero.bin 
Testing zero_minus... all tests passed!
Testing zero_xor... at least one test failed.
  zero_xor(0x01) returned 0x01
  [Skipping remaining tests for zero_xor]
Testing zero_and_not... at least one test failed.
  zero_and_not(0x01) returned 0x01
  [Skipping remaining tests for zero_and_not]
Testing zero_or_not... at least one test failed.
  zero_or_not(0x01) returned 0x01
  [Skipping remaining tests for zero_or_not]
Testing zero_plus_not... at least one test failed.
  zero_plus_not(0x01) returned 0x01
  [Skipping remaining tests for zero_plus_not]

The provided puzzle functions after zero_minus do not work; you need to change them so they do.

Compilation is not Interpretation

Notice that this model of implementing a program by compilation (translation to machine code) is different than the model of interpration (running the source code directly), which may be more familiar from languages like Python. Under compilation:

  • The source code file and the executable file are separate files.
  • The source code cannot be run directly. The hardware processor does not understand the source code. Only the executable can be run.
  • The executable does not contain the source code and cannot be edited; it contains binary machine code that the hardware processor understands.
  • The executable is produced or updated only by explicitly compiling the source code.
  • If the programmer edits the source code file after compiling, the executable does not automatically change. Running the executable runs the executable that was last compiled (before the change). The programmer must first compile the updated source code to create an updated executable if they wish to run the updated program.

Every time you change zero.c and want to run the tests again, you must run make to (re-)compile the executable before running it. If you do not, you will be running an old executable that was compiled from an older version of your zero.c file. To help avoid forgetting to compile, you may wish to run the make test recipe, which compiles the executable if needed and runs it.

$ make test
gcc -std=c99 -O0 -g zero.c zero_test.c -o zero.bin
./zero.bin
Testing zero_minus... all tests passed!
Testing zero_xor... at least one test failed.
  zero_xor(0x01) returned 0x01
  [Skipping remaining tests for zero_xor]
Testing zero_and_not... at least one test failed.
  zero_and_not(0x01) returned 0x01
  [Skipping remaining tests for zero_and_not]
Testing zero_or_not... at least one test failed.
  zero_or_not(0x01) returned 0x01
  [Skipping remaining tests for zero_or_not]
Testing zero_plus_not... at least one test failed.
  zero_plus_not(0x01) returned 0x01
  [Skipping remaining tests for zero_plus_not]
make: *** [Makefile:43: test] Error 4

Task 3: Review Course Mechanics

Read the About page (syllabus) and other course info such as the course tools page, then answer the following questions.

  1. What should you do if you can’t finish an assignment before the deadline?
  2. Is it ever acceptable to view another student’s code? If so, under what circumstances?
  3. Is it acceptable for two individuals to write a full code solution together on a whiteboard or shared document, then immediately type it up in their individual assignment submissions?
  4. When is it acceptable for one individual student to offer another individual student help understanding an error message?
  5. Give an example of when it is not acceptable to discuss high-level strategies for part of an assignment with another student.
  6. Why should you run CS 240 code on the CS GNU/Linux environment (remotely through VSCode/SSH from your computer or directly in the SCI L037 CS Systems Lab) instead of installing a C compiler and working with code directly on your own computer?
  7. What is one good next step if compiling or running your code raises an error you do not understand?

You can answer these questions before completing any other parts of this assignment. However, to submit answers, you must first complete the account and tool setup.

Submit your answers to this part in the file course.txt in your zero repository. If you haven’t created your zero repository yet, run this command in your CS terminal: cs240 start zero --solo

Submission

You will use the standard code assignment submission process for your answers about course mechanics and zero.c.

Submit: The course staff will collect your work directly from your hosted repository. To submit your work:

  1. Test your zero.c source code file one last time. Make sure that, at a minimum, submitted source code is free of syntax errors and any other static errors (such as static type errors or name/scope errors). In other words: the code does not need to complete the correct computation when invoked, but it must be a valid program. We will not grade files that do not pass this bar.

  2. Verify that you have answered all the questions in courses.txt.

  3. Use git status to see which files need to be added and committed. For instance, the following example shows that zero.c and courses.txt need to be added and committed. If you see other changed files that you do not expect, you can just ignore them: in the next step, you only need to add the files you want to submit.

    [gdome@tempest zero] git status
On branch main
Your branch is up to date with 'origin/main'.
   
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        modified:   course.txt
        modified:   zero.c

no changes added to commit (use "git add" and/or "git commit -a")

  4. Make sure you have committed your latest changes. (Replace FILES with the files you changed and MESSAGE with your commit message.)

    $ git add FILES
$ git commit -m "MESSAGE"

    For example:

    [gdome@tempest zero] git add course.txt zero.c
[gdome@tempest zero] git commit -m "answer questions in course.txt and completed all functions in zero.c"
[main aa41bff] answer questions in course.txt and completed all functions in zero.c
2 files changed, 3 insertions(+), 1 deletion(-)

  5. Run the command cs240 sign to sign your work and respond to any assignment survey questions.

    $ cs240 sign

  6. Push your signature and your latest local commits to the hosted repository.

    $ git push

Confirm: All local changes have been submitted if the output of git status shows both:

  • Your branch is up to date with 'origin/main', meaning all local commits have been pushed
  • nothing to commit, meaning all local changes have been committed

Resubmit: If you realize you need to change something later, just repeat the above process.

Grading

This assignment is graded out of a total of 10 possible points for completing all tasks. Parts with submitted answers may be graded for correctness.

  1. If you prefer to use the CS 240 tools only in the current shell session, then run the command source /home/cs240/live/env/init/session.sh instead; run this command in each shell session where you want to use the CS 240 tools. If you need to remove the permanent account configuration, edit ~/.bash_profile to remove the lines marked as related to CS 240. ↩