diff options
Diffstat (limited to 'man')
| -rw-r--r-- | man/ahoy.1 | 148 | ||||
| -rw-r--r-- | man/c8asm.1 | 65 | ||||
| -rw-r--r-- | man/c8asm.5 | 399 | ||||
| -rw-r--r-- | man/c8dump.1 | 58 |
4 files changed, 670 insertions, 0 deletions
diff --git a/man/ahoy.1 b/man/ahoy.1 new file mode 100644 index 0000000..4b0895b --- /dev/null +++ b/man/ahoy.1 @@ -0,0 +1,148 @@ +.Dd 25 February, 2024 +.Dt AHOY 1 +.Os Ahoy 1.0.0 +.Sh NAME +.Nm ahoy +.Nd emulate CHIP-8 games +.Sh SYNOPSIS +.Nm +.Op Fl S +.Op Fl c Ar "clock speed" +.Op Fl s Ar seed +.Op Fl v Ar volume +.Op Ar file +.Nm +.Fl h +.Sh DESCRIPTION +.Nm +is a graphical emulator for the CHIP-8 virtual console. +When invoked +.Nm +attempts to run the ROM specified by +.Ar file . +If no such argument is provided or the special filename +.Sq \- +is provided, +the ROM is read from the standard input. +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Fl c , Fl Fl clock\-speed Ns = Ns Ar speed +Specify the clock-speed of the emulator. +The provided clock-speed must be a non-negative integer and defaults to +700 Hz. +.It Fl h , Fl Fl help +Display help information by opening this manual page. +.It Fl s , Fl Fl seed Ns = Ns Ar seed +Specify the seed for the random-number-generator. +The provided seed must be non-negative integer. +.It Fl S , Fl Fl scan\-lines +Start the emulator with scanlines enabled. +.It Fl v , Fl Fl volume Ns = Ns Ar volume +Specify the volume level of the emulator. +The provided volume must be non-negative integer and defaults to 3000 if +not provided. +.El +.Pp +.Ss Default Keybindings +As of the current installed release of +.Nm , +there exists no functionality yet to configure keybindings. +.Pp +The default keybindings are as follows: +.Pp +.Bl -tag -compact -width <space> +.It 1 +the keypad’s +.Sq 1 +key +.It 2 +the keypad’s +.Sq 2 +key +.It 3 +the keypad’s +.Sq 3 +key +.It 4 +the keypad’s +.Sq C +key +.It q +the keypad’s +.Sq 4 +key +.It w +the keypad’s +.Sq 5 +key +.It e +the keypad’s +.Sq 6 +key +.It r +the keypad’s +.Sq D +key +.It a +the keypad’s +.Sq 7 +key +.It s +the keypad’s +.Sq 8 +key +.It d +the keypad’s +.Sq 9 +key +.It f +the keypad’s +.Sq E +key +.It z +the keypad’s +.Sq A +key +.It x +the keypad’s +.Sq 0 +key +.It c +the keypad’s +.Sq B +key +.It v +the keypad’s +.Sq F +key +.It Aq space +(un)pause the emulator +.It p +pause the emulator +.It = +increase volume by 500 +.It \- +decrease volume by 500 +.It . +increase the clock speed by 10 Hz +.It , +decrease the clock speed by 10 Hz +.El +.Sh EXIT STATUS +.Ex -std +.Sh EXAMPLES +Play a CHIP-8 game: +.Pp +.Dl $ ahoy maze.bin +.Pp +Test the output of the +.Xr c8asm 1 +assembler: +.Pp +.Dl $ c8asm tag.s | ahoy +.Sh SEE ALSO +.Xr c8asm 1 , +.Xr c8dump 1 +.Sh AUTHORS +.An Thomas Voss Aq Mt mail@thomasvoss.com diff --git a/man/c8asm.1 b/man/c8asm.1 new file mode 100644 index 0000000..b126c68 --- /dev/null +++ b/man/c8asm.1 @@ -0,0 +1,65 @@ +.Dd 26 February, 2024 +.Dt U8ASM 1 +.Os Ahoy 1.0.0 +.Sh NAME +.Nm c8asm +.Nd assemble CHIP-8 binaries +.Sh SYNOPSIS +.Nm +.Op Ar +.Nm +.Fl h +.Sh DESCRIPTION +The +.Nm +utility reads +.Xr c8asm 5 +source code files provided as command-line arguments and writes the +corresponding binary to the standard output. +If no command-line arguments are provided or the special +.Sq \- +filename is given, +input is read from the standard input. +.Pp +The assembler is extremely barebones, with no notion of a preprocessor. +If metaprogramming is desired you might consider using a macro-processor +such as +.Xr m4 1 +or +.Xr cpp 1 . +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Fl h , Fl Fl help +Display help information by opening this manual page. +.El +.Sh EXIT STATUS +.Ex -std +.Sh EXAMPLES +Assemble a binary: +.Pp +.Dl $ c8asm celeste.s >celeste.bin +.Pp +Preprocess source files using the +.Xr m4 1 +macro processor and then assemble them: +.Pp +.Dl $ m4 setup.s main-loop.s | c8asm >dragster.bin +.Pp +In the above example, local labels will end up being global to the entire +program as a result of +.Ic m4 +concatenating the files. +An alternative solution using process substitution +.Pq if your shell supports it +is as follows: +.Pp +.Dl c8asm <(setup.s) <(main-loop.s) >dragster.bin +.Sh SEE ALSO +.Xr ahoy 1 , +.Xr c8dump 1 , +.Xr cpp 1 , +.Xr m4 1 , +.Xr c8asm 5 +.Sh AUTHORS +.An Thomas Voss Aq Mt mail@thomasvoss.com 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 diff --git a/man/c8dump.1 b/man/c8dump.1 new file mode 100644 index 0000000..d79f723 --- /dev/null +++ b/man/c8dump.1 @@ -0,0 +1,58 @@ +.Dd 26 February, 2024 +.Dt U8DUMP 1 +.Os Ahoy 1.0.0 +.Sh NAME +.Nm c8dump +.Nd disassemble CHIP-8 binaries +.Sh SYNOPSIS +.Nm +.Op Ar +.Nm +.Fl h +.Sh DESCRIPTION +The +.Nm +utility disassembles CHIP-8 binaries into the assembly dialect understood +by the +.Xr c8asm 1 +assembler. +It reads the binaries provided as command-line arguments and writes the +corresponding assembly code to the standard output. +If no command-line arguments are provided or the special +.Sq \- +filename is given, +input is read from the standard input. +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Fl h , Fl Fl help +Display help information by opening this manual page. +.El +.Pp +As a result of the CHIP-8 binary format it is quite common that sprite +data and other sequences of byte-literals will be translated by +.Nm +into instructions. +As a minimal reproducable example, the following sprite data would get +disassembled into a +.Ql stor v0 . +.Pp +.Dl sprite: db 0xF0 0x55 +.Sh EXIT STATUS +.Ex -std +.Sh EXAMPLES +Disassemble a binary: +.Pp +.Dl $ c8dump space-invaders.bin +.Pp +Disassemble output from the +.Xr c8asm 1 +assembler: +.Pp +.Dl $ c8asm tetris.s | c8dump +.Sh SEE ALSO +.Xr ahoy 1 , +.Xr c8asm 1 , +.Xr c8asm 5 +.Sh AUTHORS +.An Thomas Voss Aq Mt mail@thomasvoss.com |