UNIX SPRING2026 EOCE

The End of Course Experience (eoce) satisfies the fourth discrete grading component of the course. It is meant to evaluate your knowledge and understanding gained through the semester.

Unlike the regular weekly projects, the purpose of which is to promote a learning and understanding of the concepts of the course, this EoCE is meant more as a demonstration of your proficiency in understanding and utilizing the concepts and skills obtained, showing me how productive you can be with the experiences gained.

RULES

Presented within will be various activities evaluating your knowledge and experience gained this semester. In places where you are able, the more you write (ie comment) and explain topics the better the chance you will have of receiving full credit (and alternatively, the more credit you will receive should something defer correctness).

Unless otherwise specified, the components on this experience are open resource with the exception of other individuals. In that respect, it is CLOSED PERSON. This means you are not to communicate with other people (either in the class or otherwise), in real life or electronically. Use your own knowledge, use your own skills, and use your own ability to access the allowed resources to aid you in coming up with your well thought out responses to each activity.

You are allowed, and expected, to seek clarification on any activity by asking me. But the aim here is to evaluate what you have learned, so do not expect tutoring. Any help should be prompted by a well-asked question. The better and more informed your questions, the better my responses MAY be. In many ways, I designed this EoCE premised on each and every one of you interacting with me through the asking of informed questions. Those that do not take advantage of asking such calibre of questions and instead end up struggling, please know that you're doing this wrong. But also know that, the aim here is for you to accomplish the various tasks through your own understanding of the task and concepts at hand, and not to outsource your thinking and remembering to others.

You are to all of the available items. Submission is to be as a submitted archive to the usual and appropriate places: the 'pctF' project submitted via its usual process, the other items will be part of the eoce project that you would have grabited.

To maximize any credit received (or to minimize points lost), optimize your submission for an organized and easy-to-read presentation of information that conforms with each section's stated guidelines. In the case of programs or scripts written, ensure that you are following proper and consistent commenting/documentation and indentation practices. Use well-named variables (at least 4 symbols long), and be mindful of how your particular files submitted will appear on a reasonably-sized terminal (most of my terminals are 80-90 characters wide), should that be the contextually relevant destination of output.

The EoCE is worth 26 points of your overall grade (projects (52) + participation (13) + notes (13) + eoce (26) = 104), representing a distinct fourth category within the grading policy of the course (Projects, Journal, Participation, and EoCE).

FINALS WEEK AVAILABILITY

While some classes are allocated a specific meeting time during finals week, I make all such times available should you be free and have questions. As such, finals week in CHM123 will look something like this:

  • Tuesday, May 12th, 2026 from 08:00AM-11:00AM
  • Wednesday, May 13th, 2026 from 02:30PM-05:30PM
  • Thursday, May 14th, 2026 from 11:15AM-02:15PM

Do note, the discord remains available for questions, and there is no need for you to be physically present at a given time during finals week. These are merely resources available to you should you wish to utilize them in the appropriate manners they are available to be used.

CONTENT

SCRIPT TO COLLATE VIRCON32 DEBUG DATA

In the game/ folder, you will find the code for a sample Vircon32 game cartridge, which can be built by running the Make.sh script.

If you look in the obj/ directory after building the cartridge, you will notice, in addition to the usual .asm, .vtex and .vbin files, you will see two files ending in .debug:

  • .asm.debug
  • .vbin.debug

These files contain debugging outputs tracing program logic through the various layers (C code, assembly code).

If you look in these .debug files (they are text files!), you will see things according to the following formats:

# game.asm.debug is the C compiler debug output
obj/game.asm,2904,game.c,73,main
obj/game.asm,2907,game.c,79
obj/game.asm,2909,game.c,80

Where each line is started off with the assembly file name, followed by the line of the assembly file. Then, the originating C file. Finally, the line in the C file that corresponds with the line in the assembly file.

So, we can see here that line 82 in game.c corresponds with line 2913 in game.asm.

Next, we have the other debug file:

# game.vbin.debug
0x20000DC9,obj/game.asm,2904,__function_main
0x20000DCA,obj/game.asm,2905
0x20000DCB,obj/game.asm,2906
0x20000DCD,obj/game.asm,2907
0x20000DCF,obj/game.asm,2908
0x20000DD1,obj/game.asm,2909

Here we have each line start with the memory address/offset, then the assembly file, finally the line of the assembly file.

This file shows the mapping of the assembly file to corresponding machine code.

Your task for this section is to write a bash script that will take as input the game.asm.debug and game.vbin.debug files, parse through them, and produce an output file game.debug.out that is organized as follows:

offset:asmfile line #:asmfile:Cfile line #:C file:base64-encoded processed line from C file

If there is no direct match between the C and offset (it will be the case where one line in the C file corresponds to multiple lines in assembly and machine code, or some aspect of the C file manifests differently in assembly, such as for loop), simply omit the line. There should be no empty fields in thie resulting file.

Also, eliminate any tabs, omit comments, and squeeze multiple spaces in a sequence into just one. If there is any leading or trailing whitespace on the line, filter it out. Same with newlines.

Once you have the processed line of C code, encode it in base64 and place it in that final field of your output text file.

So, using the two example snippets above, your script should produce the following output:

0x20000DC9:2904:obj/game.asm:73:game.c:dm9pZCBtYWluICgp
0x20000DCD:2907:obj/game.asm:79:game.c:aW50IGZyZXEgPSAyMDAwOw==
0x20000DD1:2909:obj/game.asm:80:game.c:aW50IGluZGV4ID0gMDs=
0x20000DD5:2911:obj/game.asm:81:game.c:aW50IHNjb3JlID0gMDs=
0x20000DD9:2913:obj/game.asm:82:game.c:aW50IHRpbWVyID0gMDs=
0x20000DDD:2915:obj/game.asm:83:game.c:aW50IERpcmVjdGlvblggPSAwOw==

The processed line 73 of game.c is: void main (), base64 encoded it is dm9pZCBtYWluICgpCgp

The processed line 79 of game.c is: int freq = 2000;, base64 encoded it is aW50IGZyZXEgPSAyMDAwOw==

The processed line 80 of game.c is: int index = 0;, base64 encoded it is aW50IGluZGV4ID0gMDs=

Your script should be able to produce this output when given any two .debug files (you should even be able to test it against your fwg0 program).

Be sure your script is well commented, consistently aligned and indented, and functions without warning or error.

BINARY HACKING

Taking the collated debug data from the previous section, our task now is to add it into the binary data of an assembled Vircon32 VBIN data file. You will want to write a script to automate this process.

Take the assembled game.vbin and take note of its size. Also, using various hex viewing tools like xxd(1), note the value in bytes 8-11- this should correspond with the amount of data in the file after the header, in units of 32-bit words (ie groups of 4 bytes). Verify this value with the data in the file to ensure you can read the count correctly.

Note that this data may be represented in little endian byte ordering, which means you'll need to switch it back to the big endian we're used to reading. You'll want to confirm the endianness before proceeding.

Little endian: DD CC BB AA Big endian: AA BB CC DD

We will need to generate binary data from our text data. This can be done with the provided encode.c file. It contains a C program that will decode the base64 encoded data from the previous step, and will output data in its binary form. This can then be appended to the VBIN file, one entry at a time.

However, some additional hacking will need to be done. One, we want to add in a unique heading that can be used to distinguish our handiwork from the rest of the machine code data. We will want to first add in a "V32-TEXT" header, then follow it with our lines of data, which should take the following form:

  • first word (4 bytes) of data: the number of offsets present
  • the sequence of 4 byte offsets
  • after the sequence of offsets has concluded:
  • 4 bytes for storing the length of the line of the C file
  • the line from the C file

Take note of the total size (in 32-bit words) of data you have appended to the VBIN file (header included). You will need to update the data size word in the VBIN file (bytes 8-11, in the same endian format as it started).

To do this, you will want to take a look at the dd(1) command, which is an incredibly powerful data manipulation tool.

Once you accomplish these modifications, proceed with the building of the cartridge. Upon getting a .v32 file, once again check it out with a hex viewer (xxd(1)) and verify that the "V32-TEXT" section and associated data is present within the produced cartridge.

Add your scripts into the Make.sh build script, so that this process happens automatically when that script is run.

There is an encode.c C program that will facilitate in transacting data into binary form, and can decode the base64-encoded data. You will want to make use of it to assist you.

REVERSE ENGINEER AND DOCUMENT A SCRIPT

Reference and modify the files in the revE/ directory.

Here you will find a script, stripping of proper formatting and comments; it performs a task that you must figure out and document (in the form of comments), as you also restore proper indentation.

Note that the files in their current form, while they perform an operation, are not in the proper form needed for submission (namely, laying out in an organized, easy-to-read, consistently indented, and well-commented fashion; that is something you may need to figure out).

What is going on here? Both on a global (what functionality the script, when properly invoked, provides) and also more local (what are particular operations within the script doing to aid in performing the overall process).

In your finished, submitted product, no line in the script should span longer than 90 characters. This includes both script logic and your comments.

  • with the exception of "then" and "do" statements, no other commands can be separated by semi-colons

  • if there are any naming manipulations needed on the script, create them as symbolic links against the main script.

  • submit with the rest of the eoce, by running "make submit" in the base directory.

The resultant script MUST be well-organized, easy-to-read, consistently indented visually showing the encapsulated levels of logic, and be thoroughly commented to explain each significant step of the process.

PCTF

Your task here is a familiar one: a letter division, just as we've encountered all semester. Only, this one is of the solve4 variety (ie not only do you have to solve for the key and provide a written step-by-step solution, but you also have to solve for the quotient and the remainder).

Additionally, the puzzle difficulty has been increased to 'hard', which should provide more of a challenge than the 'medium'-rated puzzles you've had prior.

Be sure to submit the appropriately-named and formatted files persuant to stated pctX project specifications (especially where a solve4-category puzzle is concerned).

SUBMISSION

The DEADLINE FOR SUBMISSION of this EoCE is 11:59:59pm EDT (that's 23:59:59 in 24-hour time) Thursday, May 14th, 2026. This is the ultimate deadline for any and all coursework. There is no "late", only "too late". Don't be that person, not with this.

I would highly recommend not waiting until the last moment (or even the last week) to start on this. It has been released weeks in advance, with the intention that you chip away at it a little bit at a time, over the course of weeks.

As with the projects and other deliverables this semester, you can submit early (and worthwhile, early submissions or extra work can receive up to 7 bonus points (applicable to the EoCE grading component)), and also submit as many times as you desire. Note that when you submit, that resets the timestamp from which I will evaluate any early submission bonus points or on-time eligibility.

Eligibility of any received bonus points on the EoCE are ultimately up to my decision: if you have genuinely put forth just and honest effort that is worthy of this undertaking, you will likely receive any eligible bonus points as described. If you are more calculating and avoiding of work in your EoCE efforts, I reserve the right not to grant any bonus points.

Also, if I notice any cases of rule violations (people overhelping each other instead of letting each individual complete the EoCE on their own accord and ability), you risk forfeiting any/all bonus points or even any credit for the section(s) that you violated the rules on.

Additionally:

  • Solutions not abiding by spirit of project will be subject to a 50% overall deduction
  • Solutions not utilizing descriptive why and how comments will be subject to a 50% overall deduction
  • Solutions not utilizing indentation to promote scope and clarity will be subject to a 50% overall deduction
  • Solutions not organized and easy to read are subject to a 50% overall deduction

Good luck!