Due date: See Class Webpage

Observe the Emory Honor Code when doing homeworks.

1. Purpose

This is your first assembler programming assignment and it is very easy to do. The difficulty of this assignment is: setting up the EGTAPI programming environment - espcially if you want to work from home.

Please start early, because when things don't work; you will need my help to set it up; and I may not be available late at night on the due day.

The purpose of this homework is primarily to allow you setting up and to get used to the EGTAPI (Emory Graphical Tool for Assembler Programming Instruction) system before the real project assignments are given, and introduce you to the EGTAPI programming environment.

The tutorial of the Emory Graphical Tool for Assembler Programming Instruction (EGTAPI) can be found here:

Documentation for Egtapi: click here .

I suggest you print a copy out and have it at hand when you do this assignment.

What is EGTAPI:

Running assembler programs requires the use of a debugger - such as gdb The gdb debugger is very hard to use.... To make it easier to use for students, we made a Graphical Front end called Egtapi (Emory Grapical Tool for Assembler Programming Instrcution)

You must install EGTAPI on your laptop first !

2. Install EGTAPI on your laptop

• Download and install EGTAPI from the following URL:

  http://www.cs.emory.edu/~egtapi/download.html

  After downloading the file, you must create a directory called (say) cs255 and extract the downloaded compressed archive into this cs255 directory in your laptop.

• After you have extracted the files, open a file browser and go into the cs255 folder.

  Click on the Egtapi icon to start EGTAPI.

3. Working on CS255 assembler assignments

• How you can work on CS255 assembler programming assignments:

  To work on your assembler program, you must use the EGTAPI tool Run EGTAPI on your laptop (and you can even work from home !) EGTAPI is also available on the workstations in the CS lab

• There are 2 ways that you can work on your assembler programming projects:

  You can work from anywhere with EGTAPI installed on your laptop: Install EGTAPI on your laptop (see above) and run it Log in and select a workstation from the list Through EGTAPI, you will be esentially working on a lab machine; but from anywhere !!! (We call this tele-commuting) Use a workstation in the CS Lab is: (note: this method is unavailable due to Covid-19) Go to the CS lab on the 3rd floor of the MSC building Login to some lab machine Open a terminal window In the terminal window: run EGTAPI using this command: /home/cs255001/bin/egtapi

4. Preparations

• To do this project, you must obtain a copy of the prepared files. Follow the instructions below to obtain a copy of the prepared files - which will be copied into your ~/cs255/pj4 directory on the MathCS system

• Start EGTAPI (on a lab machine or on your laptop).

  Login: click here After logging, you can use one of the following 2 methods to obtain the files. Method 1 is the easiest. Obtain the prepared files - easy method: Click on File Browser (top menu bar in EGTAPI) In the File Browser side bar, click on the Prepare tab. In the Egtapi Prepare pop up window, select: Section Number = 1 if you're in CS255-1 and Section Number = 2 if you're in CS255-2; and enter pj4 in the Project Code field. Then clcik the Prepare button (and close the Prepare window when done) The verify that it was successful, click Refresh in the EGTAPI File Browser window - you should see the pj4 folder. Obtain the prepared files - alternate method: Click on: Terminal in EGTAPI (for details, see: ) click here A 2-part window will open up at the bottom. The top part is an output window and the bottom part is an input window. Type in (or cut and paste) the following commands (one at a time) into the bottom (input) window: mkdir ~/cs255/pj4 For CS255-1 students: cp /home/cs255001/Handouts/pj4/* ~/cs255/pj4 For CS255-2 students: cp /home/cs255002/Handouts/pj4/* ~/cs255/pj4 ls ~/cs255/pj4 // You should see: pj4.s listed If you see pj4.s listed, you are good to go. Otherwise, repeat the above steps. If all else fails, seek help (instructor or TA) When you are good to go, click on Terminal to close the terminal.

5. The Skeleton Project File "pj4.s"

The assignment consists of 10 easy questions given inside the assembler program pj4,s that was copied into your project directory through the preparation step above.

You must edit the project file "pj4.s" and write the required assembler instructions in this program file.

How to edit the project file pj4.s file:

Read this write up: click here

The skeletal program has 10 sections, labeled as Q1, Q2, ..., Q10 where you put assembler instructions

---

• Advice:

  Do the project piece meal: Write the assembler instructions for question 1 at label Q1 Then compile and run the program pj4.s When Q1 is done, do Q2, and so on When you test the assembler instructions for a question, use the STEP button (for explanation of the menu buttons, see this webpage: click here ) When you want to skip over an already tested section of the project, use the RUN button --- it will skip to the code of next question (for explanation of breakpoint, see this webpage: click here )

  ---

• Assignment:

  These instructions are also given inside pj4.s Write the assembler instructions the each answer in the corresponding section of Q1, Q2, ..., Q10 in the pj4.s file. Q1: ans_i = 74; Q2: ans_s = 39; Q3: ans_b = -44; Q4: ans_i = x; Q5: ans_s = x; Q6: ans_b = x; Q7: ans_b = y; (Can you explain why ans_b != y ?) Q8: ans_s = y; (Can you explain why ans_s == y ?) Q9: ans_s = z; (Can you explain why ans_s != z ?) Q10: ans_i = y; Pre-defined variables used by the program: ans_b: byte ans_s: short ans_i: int x: -13 (byte variable) binary: 11110011 y: 2057 (short variable) binary: 00001000 00001001 z: 147463 (int variable) binary: 00000000 00000010 01000000 00000111

  Recall from the lecture(s) that:

  Byte type variables are one byte in length, Short type variables are two bytes, and Integer type variables are 4 bytes long.

  Warning:

  Be very careful and use the correct operand size in each assembler instruction. In other words: be careful when you load a value, make sure you used the correct ldr instruction: Use ldrsb when you load a byte value Use ldrsh when you load a short value Use ldr when you load a int value And be careful when you store a value, make sure you used the correct str instruction: Use strb when you store a byte value Use strh when you store a short value Use str when you store a int value

  There are some more helpful hints on testing your program in the next section !!!

6. Running/testing the program

The main purpose of this assignment is to get you familiarized with the m68000 system. So follow the following instruction carefully.

This is how you run your program assuming that you called your program file "pj4.s":

1. Edit your assignment program (pj4.s) according to the instructions above...

   You can complete 1 question at a time and compile and test the program.

2. After you're have finished writting some part of the assembler program, you can run the program as follows:

   First, assembler the program using EGTAPI. Read this webpage on how to assembler a single file project: http://www.mathcs.emory.edu/~cheung/Courses/255/Projects/Egtapi/doc2019/compile.html You need to select pj4.s and click Compile. When the compilation is completed successfully, it will produce a listing in file pj4.list and an executable file in pj4.arm. The listing file is not used in the execution, but it does contain interesting information about the placement of the variables in the memory (symbol table). If compilation is successful, you can execute the pj4.arm in EGTAPI Read this webpage on how to run a compiled program in EGTAPI: http://www.mathcs.emory.edu/~cheung/Courses/255/Projects/Egtapi/doc2019/load.html Basically, you select pj4.arm and click Select. If all is well, the program will stop at the breakpoint main. You will see this in the Breakpoint window: The label main is highlighted - indicating the program has stopped at the label main You will see the first instruction in your program in the Curr. Instr window. Now you are ready to test your program.

3. To test your program, press the Step key (right arrow with a bar).

   Effect:

   The Step will cause EGTAPI to execute the current assembler instruction and stop.

   Press Step a few more times to execute all the instructions that you have written to perform Question 1 of the assignment.

   If your program is correct, EGTAPI will:

   show ans_i = 74 in the "Variable Watch" window at the top in the right most column of the EGTAPI window

4. How to check for errors:

   Press the Step button repeatedly (but SLOWLY !) to check the execution of your program. While you are pressing the Step button, look at how the variables ans_b, ans_s and ans_i variables - specifically, look for the correct values moved in these variables in the "Variable Watch" window. Make sure the values are right (according to the questions in the project assignment).

5. Program end:

   EGTAPI will stop when it reaches the instruction at the Stop label. When EGTAPI reaches the Stop label, the Step (and other buttons) will no longer work. If you want to re-run the program, you can click on Reload. If your program is complete and correct, you can turn in the project.

6. If you found an error (i.e.: you detects that the value stored in some variable is incorrect), then you must correct your error:

   Edit your pj4.s file (Use EGTAPI, File Browser, select pj4.s and click Edit) Compile the program after you finish editing (and saving the file) (Click File Browser, select pj4.s and click Compile) Re-run the program. (Click Reload)

   If you discover more errors, just repeat the above steps until your program is error-free.

7. Turn in

Important note:

You must turn in your program to complete the assignment !!! You can turn in your work using EGTAPI

---

• Unlike other classes, in CS255, you must turn in your program pj4.s (electronically) by using the the following turnin procedure before the due date:

  1. Click on File Browser in EGTAPI 2. Select the assembler program file that you want to turn in 3. After selecting the file, click on Turnin The "Egtapi Turn-in" window will pop up 4. In the "Section Number" drop down tab: Select "1" if you are in Section 1 Select "2" if you are in Section 2 5. Enter "Project Code": pj4 6. Click the "Turn in" button 7. You will see the turn in result in the right most panel. Make sure that your see the message: "Program ... has been successfully turned in..."

  Alternately, you can turn in using EGTAPI Terminal:

  1. Open the EGTAPI Terminal (click on "Terminal") 2. Enter these command in the lower input area of the Terminal panel: (a) cd ~/cs255/pj4 (b) /home/cs255001/turnin pj4.s pj4 // If you're in section 1 or (b) /home/cs255002/turnin pj4.s pj4 // If you're in section 2

  If you want to see what you have turned in, then

  1. Open the EGTAPI Terminal (click on "Terminal") 2. Enter this command in the lower input area of the Terminal panel: /home/cs255001/turnin // If you're in section 1 or /home/cs255002/turnin // If you're in section 2

  ---

  ---

8. Extension request

• The easiest way to request an extension is using EGTAPI. See instructions in homework 1 handout write up: click here.

  However, you need to use pj4 as homework code to make extension for this homework/project.

• Alternately, you can request an extension for pj4, by executing the following command in EGTAPI's console:

  /home/cs255001/req-ext pj4 // IF you're in section 1 or: /home/cs255002/req-ext pj4 // IF you're in section 2

  You request will be successful if you have not exceeded the maximum number of "free" (no-questions-asked) requests allowed