Observed
The header comment of src/multiplyTwoNumbers.asm states the calling contract (lines 2-3):
; pre execution we have num1 in R1 and num2 in R2
; return is R0
README.md states the same thing: "A simple program in LC3 Assembly that multiplies the R1 and R2 registers and stores the result in R0." The GitHub repository description repeats it verbatim.
The TESTCODE: block (lines 7-11) then unconditionally destroys both documented inputs:
TESTCODE:
AND R1, R1, #0
AND R2, R2, #0
ADD R1, R1, #5 ; store five in R1
ADD R2, R2, #6 ; store six in R2
Both operand registers are cleared and reloaded with 5 and 6 before MULTIPLY: is reached. Any caller-supplied values are discarded.
Impact
As committed, the program can only ever compute 5 x 6. The documented interface and the implemented behavior describe two different programs, and all three documentation sources of truth are on the same side of that disagreement.
Resolution is a design decision, not a defect fix
Two readings are available and they are mutually exclusive:
- The documentation is authoritative.
TESTCODE: is scaffolding and should be removed or made conditional, leaving a callable routine driven from a simulator. This changes the program from "assemble and run" to "assemble and drive", which is a real usability loss for a teaching exercise a student is meant to execute immediately.
- The code is authoritative. The program is a self-contained demonstration that multiplies 5 by 6, and the header comment, the README sentence, and the repository description should be reworded to say so.
Which reading is intended is the owner's call. This issue is filed to record the disagreement, not to resolve it. Note that the repository description is not a tracked file and would need to be edited through repository settings.
This issue body was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).
drafted by Claude on behalf of Daniel Stephenson
Observed
The header comment of
src/multiplyTwoNumbers.asmstates the calling contract (lines 2-3):README.mdstates the same thing: "A simple program in LC3 Assembly that multiplies the R1 and R2 registers and stores the result in R0." The GitHub repository description repeats it verbatim.The
TESTCODE:block (lines 7-11) then unconditionally destroys both documented inputs:Both operand registers are cleared and reloaded with 5 and 6 before
MULTIPLY:is reached. Any caller-supplied values are discarded.Impact
As committed, the program can only ever compute 5 x 6. The documented interface and the implemented behavior describe two different programs, and all three documentation sources of truth are on the same side of that disagreement.
Resolution is a design decision, not a defect fix
Two readings are available and they are mutually exclusive:
TESTCODE:is scaffolding and should be removed or made conditional, leaving a callable routine driven from a simulator. This changes the program from "assemble and run" to "assemble and drive", which is a real usability loss for a teaching exercise a student is meant to execute immediately.Which reading is intended is the owner's call. This issue is filed to record the disagreement, not to resolve it. Note that the repository description is not a tracked file and would need to be edited through repository settings.
This issue body was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).
drafted by Claude on behalf of Daniel Stephenson