Skip to content

content: fix factual errors in chapters 2-7 - #97

Open
dajiaohuang wants to merge 2 commits into
0xAX:masterfrom
dajiaohuang:content/fix-factual-errors
Open

dajiaohuang wants to merge 2 commits into
0xAX:masterfrom
dajiaohuang:content/fix-factual-errors

Conversation

@dajiaohuang

@dajiaohuang dajiaohuang commented Oct 19, 2026 •

Copy link
Copy Markdown

Fixes several objective factual errors in the course text. All changed files are Markdown and are covered by the repository's CC BY-NC-SA 4.0 license; no example sources were modified.

Changes proposed in this pull request:

  • content/asm_2.md: the comment next to mov ecx, 4 referred to an exc register. It now says ecx.
  • content/asm_3.md: the function-argument list gave r10 for the fourth argument. The System V AMD64 ABI passes the fourth integer/pointer argument in rcx (the same chapter's example and chapters 2 and 7 already use ecx/rcx for function calls). Also, pop without an operand is not a valid epilogue after push rbp; it now restores rbp with pop rbp.
  • content/asm_4.md: not takes one operand and inverts its bits; the "result is stored in the first operand" sentence applies to and, or, and xor. The prose also called the lodsb instruction loadsb.
  • content/asm_5.md: the single-line macro example said define argc instead of %define argc. The REPX example said it expands to pmulhuw m0, m7 ..., but the macro and the shown invocation expand to psrlw m0, 8, psrlw m1, 8, and so on.
  • content/asm_6.md: CMPSS predicate 7 is the ordered predicate ("neither operand is NaN"), not "both operands are NaN". The paragraph also said a floating-point comparison's result is controlled by rflags; unlike an integer cmp, cmpss writes its result to the destination register.
  • content/asm_7.md: msg is "hello, world!\n", i.e. 14 bytes, which matches mov rdx, 14 and the comments in the other chapters.
  • CONTRIBUTORS.md: added dajiaohuang, as requested by CONTRIBUTING.md.

Checks performed:

  • Assembled the corrected NASM snippets and the chapter 5 single-line macro example with NASM 2.16.03.
  • Confirmed the REPX expansion with nasm -E (psrlw m0, 8 ...).
  • Confirmed the fourth function argument register against the System V AMD64 ABI and GCC 13.3 -O0 output (movl %ecx, -16(%rbp) for the fourth parameter).
  • Confirmed CMPSS predicate 7 semantics against Intel's CMPSS documentation (pseudo-op VCMPORDSS / ORD_Q).
  • Counted the greeting length (14 bytes).

No example programs were changed, so the examples workflow is unaffected.

- asm_2: name the ecx register in the compiler output comment
- asm_3: pass the fourth function argument in rcx and restore rbp in the epilogue
- asm_4: not takes one operand; name the lodsb instruction correctly
- asm_5: use the %define directive and show the actual REPX expansion
- asm_6: correct the CMPSS ordered predicate and the comparison result location
- asm_7: the greeting including the newline is 14 bytes

@0xAX 0xAX left a comment

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@dajiaohuang thank you for your PR! I've left two minor comments

Comment thread content/asm_6.md
| 5 | >= |
| 6 | > |
| 7 | Checks that both operands are [Nan](https://en.wikipedia.org/wiki/NaN) |
| 7 | Checks that neither operand is [NaN](https://en.wikipedia.org/wiki/NaN) |

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@dajiaohuang good catch. This table on the line 3 also has Nan, can you please update it to NaN as well

Comment thread content/asm_6.md
### Floating-point control instructions

As we already know, the main goal of these instructions is to manage the control flow of our programs. For integer comparisons, we used the `cmp` instruction. However, this instruction does not work with floating-point values, even though the result of the comparison is controlled by the same `rflags` registers that we saw in the [Data manipulation](./asm_4.md#control-transfer-instructions) chapter. The general instruction to compare floating-point numbers is `cmpss`. Instead of setting the value of the flag based on the result comparison, the instruction stores the result of the comparison in the destination register.
As we already know, the main goal of these instructions is to manage the control flow of our programs. For integer comparisons, we used the `cmp` instruction. However, this instruction does not work with floating-point values: unlike an integer comparison, whose result is recorded in the `rflags` register, a floating-point comparison stores its result in the destination register. The general instruction to compare floating-point numbers is `cmpss`. Instead of setting the value of the flag based on the result comparison, the instruction stores the result of the comparison in the destination register.

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This paragraph now doubles information about the storing the result of the comparison in the destination register.

Maybe something like this:

As we already know, the main goal of these instructions is to manage the control flow of our programs. For integer comparisons, we used the cmp instruction from the Data manipulation chapter. However, this instruction does not work with floating-point values. To compare floating-point numbers, we can use the cmpss instruction. Unlike cmp, this instruction does not set any flags. Instead, it stores the result of the comparison in the destination register.

@0xAX
0xAX self-requested a review October 19, 2026 19:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants