diff options
Diffstat (limited to 'man/c8asm.5')
| -rw-r--r-- | man/c8asm.5 | 399 |
1 files changed, 399 insertions, 0 deletions
diff --git a/man/c8asm.5 b/man/c8asm.5 new file mode 100644 index 0000000..67d6697 --- /dev/null +++ b/man/c8asm.5 @@ -0,0 +1,399 @@ +.Dd 26 February, 2024 +.Dt U8ASM 5 +.Os Ahoy 1.0.0 +.Sh NAME +.Nm c8asm +.Nd the c8 assembly dialect +.Sh DESCRIPTION +The +.Nm +assembly dialect is the language understood by the +.Xr c8asm 1 +assembler. +It is a small language consisting of only the few instructions and syntax +elements described in this manual. +A basic program to display the number 69 followed by an exclamation-mark +on the screen may look as follows: +.Bd -literal -offset indent +; Draw the sprite for ‘6’ +ld v2 6 +hex v2 +drw v0 v1 5 + +; Draw the sprite for ‘9’ +ld v2 9 +hex v2 +add v0 5 ; Offset the X position by 5 +drw v0 v1 5 + +ld i exclamation_sprite +add v0 5 +drw v0 v1 5 + +; Infinite loop +loop: + jp loop + +exclamation_sprite: + db 0b1000'0000 + db 0b1000'0000 + db 0b1000'0000 + db 0b0000'0000 + db 0b1000'0000 +.Ed +.Sh LANGUAGE SYNTAX +.Ss Encoding +All +.Nm +documents must be UTF-8 encoded. +No other encodings are valid. +.Ss Whitespace +Syntax elements are often separated by whitespace. +When mentioned in this document, +.Sq whitespace +refers to all Unicode codepoints with the property Pattern_White_Space. +.Ss Case +Unlike most assembly dialects, +.Nm +is case-sensitive. +This means that the labels +.Ql .foo +and +.Ql .FOO +are not interchangeable and neither are the instructions +.Ql add +and +.Ql ADD . +.Ss Labels +Labels are a way to assign names to a particular memory address. +They’re useful for referencing locations of sprites, +or instructions to jump to. +.Pp +A label is composed of a Unicode codepoint with the property XID_Start, +followed by zero-or-more Unicode codepoints with the property +XID_Continue. +In simple terms this means labels follow the same syntax rules as most +modern programming languages. +As an extension to the Unicode specification labels may also begin with +an underscore +.Pq Sq _ . +.Pp +All labels must be terminated by any amount of whitespace and a colon +.Pq Sq \&: . +.Pp +By default labels are globally scoped. +This means that if you define the label +.Ql foo , +you’ll be able to reference that label from any file in your project. +To define a label local to the current file you can prefix it with a +period. +.Ss Instructions +The following is a list of available instructions in +.Nm , +and a description of their behavior. +.Pp +The following terms are used in this section: +.Pp +.Bl -tag -compact -width "nibble, byte, and addr" +.It vx and vy +arbitrary v-registers +.Pq see: Sx Registers +.It nibble, byte, and addr +4-, 8-, and 12-bit integer literals +.It dt, st, i, and v0 +the dt, st, i, and v0 registers +.El +.Pp +The instructions are as follows: +.Pp +.Bl -tag -width Ds +.It Ic add Ar i Ar vx , Ic add Ar vx Ar byte +Add the values of the first- and second oprands and store the result in +the first oprand. +.It Ic add Ar vx Ar vy +Add the values of +.Ar vx +and +.Ar vy +and store the result in +.Ar vx. +If the result is greater than 255 then +.Ar vf +is set to 1, +otherwise 0. +.It Ic and Ar vx Ar vy +Perform a bitwise-AND of +.Ar vx +and +.Ar vy +and store the result in +.Ar vx . +.It Ic bcd Ar vx +Store the hundreds-, tens-, and ones-digit of the BCD representation of +the value in +.Ar vx +to the memory addresses stored in +.Va i , +.Va i+1 , +and +.Va i+2 . +.It Ic call Ar addr +Push the current address to the top of the callstack and set the +instruction pointer to +.Ar addr . +.It Ic cls +Clear the display. +.It Ic db Ar byte ... +Insert the byte arguments literally into the assembled binary. +.It Ic drw Ar vx Ar vy Ar nibble +Draw the sprite pointed to by the +.Va i +register at the position +.Pq Va vx , Va vy +with a height of +.Ar nibble . +.It Ic hex Ar vx +Set the +.Va i +register to the address of the hexadecimal sprite corresponding to the +value of +.Ar vx . +.It Ic jp Ar addr +Set the instruction pointer to +.Ar addr . +.It Ic jp Ar v0 Ar addr +Set the instruction pointer to +.Ar v0 ++ +.Ar addr . +.It Ic ld Ar dt Ar vx , Ic ld Ar i Ar addr , Ic ld Ar st Ar vx , Ic ld Ar vx Ar byte , Ic ld Ar vx Ar dt , Ic ld Ar vx Ar vy +Store the value of the second oprand into the first oprand. +.It Ic ld Ar vx Ar k +Block until the user presses a key, +and store the value of the key pressed into +.Ar vx . +.It Ic or Ar vx Ar vy +Perform a bitwise-OR of +.Ar vx +and +.Ar vy +and store the result in +.Ar vx . +.It Ic ret +Pop an address off the top of the callstack and set the instruction +pointer to that location. +.It Ic rnd Ar vx Ar byte +Set +.Ar vx +to the bitwise-AND of a randomly-generated byte and the given +.Ar byte . +.It Ic rstr Ar vx +Reads data starting at the memory address stored in the +.Va i +register into the registers +.Va v0 +though to +.Ar vx +inclusive. +.Pp +The +.Va i +register is incremented by +.Ar x . +.It Ic se Ar vx Ar byte , Ic se Ar vx Ar vy +Skip the next instruction if the two oprands are equal. +.It Ic shl Ar vx +Left-shift +.Ar vx +by 1 and store the result in +.Ar vx . +If the most-significant-byte of +.Ar vx +was 1 +.Va vf +is set to 1 +otherwise 0. +.It Ic shr Ar vx +Right-shift +.Ar vx +by 1 and store the result in +.Ar vx . +If the least-significant-byte of +.Ar vx +was 1 +.Va vf +is set to 1 +otherwise 0. +.It Ic sknp Ar vx +Skip the next instruction if the key with the value of +.Ar vx +is not pressed. +.It Ic skp Ar vx +Skip the next instruction if the key with the value of +.Ar vx +is pressed. +.It Ic sne Ar vx Ar byte , Ic sne Ar vx Ar vy +Skip the next instruction if the two oprands are not equal. +.It Ic stor Ar vx +Stores the values of the registers +.Va v0 +through +.Ar vx +inclusive starting at the memory address stored in the +.Va i +register. +.Pp +The +.Va i +register is incremented by +.Ar x . +.It Ic subn Ar vx Ar vy +Subtract +.Ar vx +from +.Ar vy +and store the result in +.Ar vx . +If +.Ar vy +was greater than +.Ar vx +then +.Va vf +is set to 1 otherwise 0. +.It Ic sub Ar vx Ar vy +Subtract +.Ar vy +from +.Ar vx +and store the result in +.Ar vx . +If +.Ar vx +was greater than +.Ar vy +then +.Va vf +is set to 1 otherwise 0. +.It Ic sys Ar addr +Jump to a machine-code routine at the address +.Ar addr . +.Pp +Most interpreters completely ignore this instruction. +.It Ic xor Ar vx Ar vy +Perform a bitwise-XOR of +.Ar vx +and +.Ar vy +and store the result in +.Ar vx . +.El +.Ss Registers +The following registers are available for use in +.Nm +programs: +.TS +box; +c | c +l | r. +Name Size (Bits) +_ +v0–vf 8 +i 16 +dt 8 +st 8 +.TE +.Pp +The +.Va v0 Ns – Ns Va ve +registers are general-purpose registers intended for use by the +programmer. +The +.Va vf +register is also a general-purpose register but is overriden by various +instructions which utilize it as a flags register. +.Pp +The +.Va i +register is intended to be used to store 12-bit memory addresses. +.Pp +The +.Va dt +and +.Va st +registers are special registers. +When non-zero they are decremented by 1 at a rate of 60 Hz. +Additionally, when the +.Va st +register is non-zero, +a monotone beep is played. +.Ss Integer Literals +The +.Nm +language supports non-negative binary-, octal-, decimal-, and hexadecimal +integer literals. +Integer literals are prefixed by a literal +.Sq 0 +and a lowercase base-specifier, +but this prefix is optional for base-10 integers. +The base-specifiers are as follows: +.Pp +.Bl -tag -compact -width Ds +.It b +binary +.It o +octal +.It d +decimal +.It x +hexadecimal +.El +.Pp +The following table shows how different numbers can be represented in +different bases: +.Pp +.TS +box; +c | c | c | c +r | r | r | r. +Binary Octal Decimal Hexadecimal +_ +0b01100000 0o140 96 0x60 +0b00010011 0o023 19 0x13 +0b01111111 0o177 127 0x7F +0b00111010 0o072 58 0x3A +.TE +.Pp +An apostrophe +.Pq Sq \(aq +can also be included anywhere in an integer literal +.Em after +the base-specifier as a digit-separator, +such as in +.Ql 0b1011\(aq1001 . +.Ss Strings +Strings are composed of an opening- and closing double quote +.Pq Sq \(dq +with zero-or-more bytes between them. +Strings can only be used as an argument to the +.Ql db +instruction and they expand to a sequence of bytes representing their +contents. +.Pp +The following two lines are equivalent: +.Bd -literal -offset indent +db "foo" +db 0x66 0x6F 0x6F +.Ed +.Sh SEE ALSO +.Xr ahoy 1 , +.Xr c8asm 1 , +.Xr c8dump 1 +.Rs +.%A Thomas P. Greene +.%D 30th August, 1997 +.%R Cowgod’s Chip-8 Technical Reference +.%U http://devernay.free.fr/hacks/chip8/C8TECH10.HTM +.Re +.Sh AUTHORS +.An Thomas Voss Aq Mt mail@thomasvoss.com |