docs/layouts/shortcodes/instruction.md

{{- /* instruction - Standardized instruction reference card, following the layout used in the Patt & Patel textbook: mnemonic title, short description, assembler formats, encoding diagram, high-level operation, and usage examples.

@param {string} mnemonic Instruction mnemonic(s), comma-separated if more than one (e.g. "ADD" or "JSR, JSRR"). @param {string} short Short two-to-three word description (e.g. "Addition"). @param {string} formats Assembler format(s). Use a backtick-quoted string for multiple lines. @param {string} encoding Filename of the encoding diagram @param {string} encoding-dark Optional dark mode variant of the encoding diagram. If set, encoding is only shown in light mode and this is shown in dark mode. @param {string} encoding-bits Optional accessible bit-level breakdown of the encoding, for screen readers and crawlers. Use lines of "bits:value:meaning", one per row. Separate multiple variants with a line containing only "---". @param {string} operation High-level operation, typically pseudo-C. Use a backtick-quoted string for multiple lines. @param {string} examples Usage examples in LC-2 assembly. Use a backtick-quoted string for multiple lines.

@example {{% instruction mnemonic="ADD" short="Addition"

formats=ADD DR, SR1, SR2 ADD DR, SR1, imm5

encoding="add.drawio.png" encoding-dark="add-dark.drawio.png"

operation=`if (bit[5] == 0) { DR = SR1 + SR2; } else { DR = SR1 + SEXT(imm5); }

setcc(DR);`

examples=ADD R2, R3, R4 ; R2 ← R3 + R4 ADD R2, R3, #7 ; R2 ← R3 + 7

%}} If bit [5] is 0, the second-source operand is obtained from SR2. If bit [5] is 1, the second-source operand is obtained by sign-extending the imm5 field to 16 bits. In both cases, the second source operand is added to the contents of SR1, and the result stored in DR. The condition codes are set, based on whether the result is negative, zero, or positive. {{% /instruction %}}

*/ -}}

{{- $mnemonic := .Get "mnemonic" -}} {{- $short := .Get "short" -}} {{- $formats := .Get "formats" -}} {{- $encoding := .Get "encoding" -}} {{- $encodingDark := .Get "encoding-dark" -}} {{- $encodingBits := .Get "encoding-bits" -}} {{- $operation := .Get "operation" -}} {{- $examples := .Get "examples" -}} {{- $description := .Inner -}}

{{ $mnemonic }}

{{ $mnemonic }}

{{ $short }}

Assembler Formats

{{ $formats }}

Encoding

{{ if $encodingDark }} {{ else }} {{ end }}

{{ if $encodingBits }} {{ $variants := (split $encodingBits "---") }} {{ $html := printf "<div id="%s-encoding-table" class="hx:sr-only">" ($mnemonic | lower) }} {{ range $variantIndex, $variant := $variants }} {{ $html = print $html "" }} {{ $html = print $html (printf "" $mnemonic (cond (gt (len $variants) 1) (printf ", variant %d" (add $variantIndex 1)) "")) }} {{ $html = print $html "" }} {{ $html = print $html "" }} {{ range (split (trim $variant "\n") "\n") }} {{ $parts := split . "|" }} {{ $html = print $html (printf "" (index $parts 0) (index $parts 1) (index $parts 2)) }} {{ end }} {{ $html = print $html "

%s encoding%s

Bits	Value	Meaning
%s	%s	%s

" }} {{ end }} {{ $html = print $html "

" }} {{ $html | safeHTML }} {{ end }}

Operation

{{ $operation }}

Description

{{ $description }}

Examples

{{ $examples }}