haas/spring2026/unix/eoce/EoCE.md
... ...
@@ -0,0 +1,328 @@
1
+# COMPORG SPRING2026 EOCE
2
+
3
+The End of Course Experience (eoce) satisfies the fourth discrete grading
4
+component of the course. It is meant to evaluate your knowledge and
5
+understanding gained through the semester.
6
+
7
+Unlike the regular weekly projects, the purpose of which is to promote a
8
+learning and understanding of the concepts of the course, this EoCE is
9
+meant more as a demonstration of your proficiency in understanding and
10
+utilizing the concepts and skills obtained, showing me how productive you
11
+can be with the experiences gained.
12
+
13
+## RULES
14
+
15
+Presented within will be various activities evaluating your knowledge and
16
+experience gained this semester. In places where you are able, the more
17
+you write (ie comment) and explain topics the better the chance you will
18
+have of receiving full credit (and alternatively, the more credit you
19
+will receive should something defer correctness).
20
+
21
+Unless otherwise specified, the components on this experience are open
22
+resource with the exception of other individuals. In that respect, it
23
+is **CLOSED PERSON**. This means you are not to communicate with
24
+other people (either in the class or otherwise), in real life or
25
+electronically. Use your own knowledge, use your own skills, and use your
26
+own ability to access the allowed resources to aid you in coming up with
27
+your well thought out responses to each activity.
28
+
29
+You are allowed, and expected, to seek clarification on any activity by
30
+asking me. But the aim here is to evaluate what you have learned, so do
31
+not expect tutoring. Any help should be prompted by a well-asked
32
+question. The better and more informed your questions, the better my
33
+responses MAY be. In many ways, I designed this EoCE premised on each and
34
+every one of you interacting with me through the asking of informed
35
+questions. Those that do not take advantage of asking such calibre of
36
+questions and instead end up struggling, please know that you're doing
37
+this wrong. But also know that, the aim here is for you to accomplish the
38
+various tasks through your own understanding of the task and concepts at
39
+hand, and not to outsource your thinking and remembering to others.
40
+
41
+You are to all of the available items. Submission is to be as a submitted
42
+archive to the usual and appropriate places: the 'pctF' project submitted
43
+via its usual process, the other items will be part of the `eoce` project
44
+that you would have `grabit`ed.
45
+
46
+To maximize any credit received (or to minimize points lost), optimize
47
+your submission for an organized and easy-to-read presentation of
48
+information that conforms with each section's stated guidelines. In the
49
+case of programs or scripts written, ensure that you are following proper
50
+and consistent commenting/documentation and indentation practices. Use
51
+well-named variables (at least 4 symbols long), and be mindful of how
52
+your particular files submitted will appear on a reasonably-sized
53
+terminal (most of my terminals are 80-90 characters wide), should that be
54
+the contextually relevant destination of output.
55
+
56
+The EoCE is worth 26 points of your overall grade (projects (52) +
57
+participation (13) + notes (13) + eoce (26) = 104), representing a
58
+distinct fourth category within the grading policy of the course
59
+(Projects, Journal, Participation, and EoCE).
60
+
61
+### FINALS WEEK AVAILABILITY
62
+
63
+While some classes are allocated a specific meeting time during finals
64
+week, I make all such times available should you be free and have
65
+questions. As such, finals week in **CHM123** will look something like
66
+this:
67
+
68
+ * Tuesday, May 12th, 2026 from 08:00AM-11:00AM
69
+ * Wednesday, May 13th, 2026 from 02:30PM-05:30PM
70
+ * Thursday, May 14th, 2026 from 11:15AM-02:15PM
71
+
72
+Do note, the discord remains available for questions, and there is no
73
+need for you to be physically present at a given time during finals week.
74
+These are merely resources available to you should you wish to utilize
75
+them in the appropriate manners they are available to be used.
76
+
77
+## CONTENT
78
+
79
+### SCRIPT TO COLLATE VIRCON32 DEBUG DATA
80
+
81
+In the `game/` folder, you will find the code for a sample Vircon32 game
82
+cartridge, which can be built by running the `Make.sh` script.
83
+
84
+If you look in the `obj/` directory after building the cartridge, you
85
+will notice, in addition to the usual `.asm`, `.vtex` and `.vbin` files,
86
+you will see two files ending in `.debug`:
87
+
88
+ * `.asm.debug`
89
+ * `.vbin.debug`
90
+
91
+These files contain debugging outputs tracing program logic through the
92
+various layers (C code, assembly code).
93
+
94
+If you look in these `.debug` files (they are text files!), you will see
95
+things according to the following formats:
96
+
97
+```
98
+# game.asm.debug is the C compiler debug output
99
+obj/game.asm,2904,game.c,73,main
100
+obj/game.asm,2907,game.c,79
101
+obj/game.asm,2909,game.c,80
102
+```
103
+
104
+Where each line is started off with the assembly file name, followed by
105
+the line of the assembly file. Then, the originating C file. Finally, the
106
+line in the C file that corresponds with the line in the assembly file.
107
+
108
+So, we can see here that line `82` in `game.c` corresponds with line
109
+`2913` in `game.asm`.
110
+
111
+Next, we have the other debug file:
112
+
113
+```
114
+# game.vbin.debug
115
+0x20000DC9,obj/game.asm,2904,__function_main
116
+0x20000DCA,obj/game.asm,2905
117
+0x20000DCB,obj/game.asm,2906
118
+0x20000DCD,obj/game.asm,2907
119
+0x20000DCF,obj/game.asm,2908
120
+0x20000DD1,obj/game.asm,2909
121
+```
122
+
123
+Here we have each line start with the memory address/offset, then the
124
+assembly file, finally the line of the assembly file.
125
+
126
+This file shows the mapping of the assembly file to corresponding machine
127
+code.
128
+
129
+Your task for this section is to write a bash script that will take as
130
+input the `game.asm.debug` and `game.vbin.debug` files, parse through
131
+them, and produce an output file `game.debug.out` that is organized as
132
+follows:
133
+
134
+```
135
+offset:asmfile line #:asmfile:Cfile line #:C file:base64-encoded processed line from C file
136
+```
137
+
138
+If there is no direct match between the C and offset (it will be the case
139
+where one line in the C file corresponds to multiple lines in assembly
140
+and machine code, or some aspect of the C file manifests differently in
141
+assembly, such as for loop), simply omit the line. There should be no
142
+empty fields in thie resulting file.
143
+
144
+Also, eliminate any tabs, omit comments, and squeeze multiple spaces in a
145
+sequence into just one. If there is any leading or trailing whitespace on
146
+the line, filter it out. Same with newlines.
147
+
148
+Once you have the processed line of C code, encode it in base64 and place
149
+it in that final field of your output text file.
150
+
151
+So, using the two example snippets above, your script should produce the
152
+following output:
153
+
154
+```
155
+0x20000DC9:2904:obj/game.asm:73:game.c:dm9pZCBtYWluICgp
156
+0x20000DCD:2907:obj/game.asm:79:game.c:aW50IGZyZXEgPSAyMDAwOw==
157
+0x20000DD1:2909:obj/game.asm:80:game.c:aW50IGluZGV4ID0gMDs=
158
+0x20000DD5:2911:obj/game.asm:81:game.c:aW50IHNjb3JlID0gMDs=
159
+0x20000DD9:2913:obj/game.asm:82:game.c:aW50IHRpbWVyID0gMDs=
160
+0x20000DDD:2915:obj/game.asm:83:game.c:aW50IERpcmVjdGlvblggPSAwOw==
161
+```
162
+
163
+The processed line 73 of `game.c` is: `void main ()`, base64 encoded it
164
+is `dm9pZCBtYWluICgpCgp`
165
+
166
+The processed line 79 of `game.c` is: `int freq = 2000;`, base64 encoded
167
+it is `aW50IGZyZXEgPSAyMDAwOw==`
168
+
169
+The processed line 80 of `game.c` is: `int index = 0;`, base64 encoded it
170
+is `aW50IGluZGV4ID0gMDs=`
171
+
172
+Your script should be able to produce this output when given any two
173
+`.debug` files (you should even be able to test it against your `fwg0`
174
+program).
175
+
176
+Be sure your script is well commented, consistently aligned and indented,
177
+and functions without warning or error.
178
+
179
+### BINARY HACKING
180
+
181
+Taking the collated debug data from the previous section, our task now is
182
+to add it into the binary data of an assembled Vircon32 VBIN data file.
183
+You will want to write a script to automate this process.
184
+
185
+Take the assembled `game.vbin` and take note of its size. Also, using
186
+various hex viewing tools like `xxd`(1), note the value in bytes 8-11-
187
+this should correspond with the amount of data in the file after the
188
+header, in units of 32-bit words (ie groups of 4 bytes). Verify this
189
+value with the data in the file to ensure you can read the count
190
+correctly.
191
+
192
+Note that this data may be represented in little endian byte ordering,
193
+which means you'll need to switch it back to the big endian we're used to
194
+reading. You'll want to confirm the endianness before proceeding.
195
+
196
+Little endian: `DD CC BB AA`
197
+Big endian: `AA BB CC DD`
198
+
199
+We will need to generate binary data from our text data. This can be done
200
+with the provided `encode.c` file. It contains a C program that will
201
+decode the base64 encoded data from the previous step, and will output
202
+data in its binary form. This can then be appended to the VBIN file, one
203
+entry at a time.
204
+
205
+However, some additional hacking will need to be done. One, we want to
206
+add in a unique heading that can be used to distinguish our handiwork
207
+from the rest of the machine code data. We will want to first add in a
208
+"V32-TEXT" header, then follow it with our lines of data, which should
209
+take the following form:
210
+
211
+ * first word (4 bytes) of data: the number of offsets present
212
+ * the sequence of 4 byte offsets
213
+ * after the sequence of offsets has concluded:
214
+ * 4 bytes for storing the length of the line of the C file
215
+ * the line from the C file
216
+
217
+Take note of the total size (in 32-bit words) of data you have appended
218
+to the VBIN file (header included). You will need to update the data size
219
+word in the VBIN file (bytes 8-11, **in the same endian format as it
220
+started**).
221
+
222
+To do this, you will want to take a look at the `dd`(1) command, which is
223
+an incredibly powerful data manipulation tool.
224
+
225
+Once you accomplish these modifications, proceed with the building of the
226
+cartridge. Upon getting a `.v32` file, once again check it out with a hex
227
+viewer (`xxd`(1)) and verify that the "V32-TEXT" section and associated
228
+data is present within the produced cartridge.
229
+
230
+Add your scripts into the `Make.sh` build script, so that this process
231
+happens automatically when that script is run.
232
+
233
+There is an `encode.c` C program that will facilitate in transacting data
234
+into binary form, and can decode the base64-encoded data. You will want
235
+to make use of it to assist you.
236
+
237
+### REVERSE ENGINEER AND DOCUMENT A SCRIPT
238
+
239
+Reference and modify the files in the `revE/` directory.
240
+
241
+Here you will find a script, stripping of proper formatting and comments;
242
+it performs a task that you must figure out and document (in the form of
243
+comments), as you also restore proper indentation.
244
+
245
+Note that the files in their current form, while they perform an
246
+operation, are not in the proper form needed for submission (namely,
247
+laying out in an organized, easy-to-read, consistently indented, and
248
+well-commented fashion; that is something you may need to figure out).
249
+
250
+What is going on here? Both on a global (what functionality the script,
251
+when properly invoked, provides) and also more local (what are particular
252
+operations within the script doing to aid in performing the overall
253
+process).
254
+
255
+In your finished, submitted product, no line in the script should span
256
+longer than 90 characters. This includes both script logic and your
257
+comments.
258
+
259
+ * with the exception of "then" and "do" statements, no other commands
260
+ can be separated by semi-colons
261
+
262
+ * if there are any naming manipulations needed on the script, create
263
+ them as symbolic links against the main script.
264
+
265
+ * submit with the rest of the `eoce`, by running "make submit" in the
266
+ base directory.
267
+
268
+The resultant script MUST be well-organized, easy-to-read, consistently
269
+indented visually showing the encapsulated levels of logic, and be
270
+thoroughly commented to explain each significant step of the process.
271
+
272
+### PCTF
273
+
274
+Your task here is a familiar one: a letter division, just as we've
275
+encountered all semester. Only, this one is of the solve4 variety (ie not
276
+only do you have to solve for the key and provide a written step-by-step
277
+solution, but you also have to solve for the quotient and the remainder).
278
+
279
+Additionally, the puzzle difficulty has been increased to 'hard', which
280
+should provide more of a challenge than the 'medium'-rated puzzles you've
281
+had prior.
282
+
283
+Be sure to submit the appropriately-named and formatted files persuant to
284
+stated pctX project specifications (especially where a solve4-category
285
+puzzle is concerned).
286
+
287
+## SUBMISSION
288
+
289
+The DEADLINE FOR SUBMISSION of this EoCE is 11:59:59pm EDT (that's
290
+23:59:59 in 24-hour time) Thursday, May 14th, 2026. This is the ultimate
291
+deadline for any and all coursework. There is no "late", only "too late".
292
+Don't be that person, not with this.
293
+
294
+I would highly recommend not waiting until the last moment (or even the
295
+last week) to start on this. It has been released weeks in advance, with
296
+the intention that you chip away at it a little bit at a time, over the
297
+course of weeks.
298
+
299
+As with the projects and other deliverables this semester, you can submit
300
+early (and worthwhile, early submissions or extra work can receive up to
301
+7 bonus points (applicable to the EoCE grading component)), and also
302
+submit as many times as you desire. Note that when you submit, that
303
+resets the timestamp from which I will evaluate any early submission
304
+bonus points or on-time eligibility.
305
+
306
+Eligibility of any received bonus points on the EoCE are ultimately up to
307
+my decision: if you have genuinely put forth just and honest effort that
308
+is worthy of this undertaking, you will likely receive any eligible bonus
309
+points as described. If you are more calculating and avoiding of work in
310
+your EoCE efforts, I reserve the right not to grant any bonus points.
311
+
312
+Also, if I notice any cases of rule violations (people overhelping each
313
+other instead of letting each individual complete the EoCE on their own
314
+accord and ability), you risk forfeiting any/all bonus points or even any
315
+credit for the section(s) that you violated the rules on.
316
+
317
+Additionally:
318
+
319
+ * Solutions not abiding by spirit of project will be subject to a 50%
320
+ overall deduction
321
+ * Solutions not utilizing descriptive why and how comments will be
322
+ subject to a 50% overall deduction
323
+ * Solutions not utilizing indentation to promote scope and clarity will
324
+ be subject to a 50% overall deduction
325
+ * Solutions not organized and easy to read are subject to a 50% overall
326
+ deduction
327
+
328
+Good luck!