gbdev/rgbds
1
0
Fork 0
mirror of https://github.com/gbdev/rgbds.git synced 2025-11-20 18:22:07 +00:00
Code Issues Packages Projects Releases Wiki Activity

Clean up some man pages (#1547)

Browse Source
This commit is contained in:
Sylvie
2024-10-22 13:07:09 -04:00
committed by GitHub
parent 4c495c31d9
commit f048cbbb11
3 changed files with 203 additions and 192 deletions
Download Patch File Download Diff File Expand all files Collapse all files

227
man/gbz80.7
View File

@@ -11,7 +11,7 @@ This is the list of opcodes supported by
.Xr rgbasm 1 ,
including a short description, the number of bytes needed to encode them and the number of CPU cycles at 1MHz (or 2MHz in GBC dual speed mode) needed to complete them.
.Pp
Note: All arithmetic/logic instructions that use register
Note: All arithmetic and logic instructions that use register
.Sy A
as a destination can omit the destination, since it is assumed to be register
.Sy A
@@ -79,76 +79,7 @@ and
.Ad 0x38 Pc .
.El
.Sh INSTRUCTION OVERVIEW
.Ss 8-bit Arithmetic and Logic Instructions
.Bl -inset -compact
.It Sx ADC A,r8
.It Sx ADC A,[HL]
.It Sx ADC A,n8
.It Sx ADD A,r8
.It Sx ADD A,[HL]
.It Sx ADD A,n8
.It Sx AND A,r8
.It Sx AND A,[HL]
.It Sx AND A,n8
.It Sx CP A,r8
.It Sx CP A,[HL]
.It Sx CP A,n8
.It Sx DEC r8
.It Sx DEC [HL]
.It Sx INC r8
.It Sx INC [HL]
.It Sx OR A,r8
.It Sx OR A,[HL]
.It Sx OR A,n8
.It Sx SBC A,r8
.It Sx SBC A,[HL]
.It Sx SBC A,n8
.It Sx SUB A,r8
.It Sx SUB A,[HL]
.It Sx SUB A,n8
.It Sx XOR A,r8
.It Sx XOR A,[HL]
.It Sx XOR A,n8
.El
.Ss 16-bit Arithmetic Instructions
.Bl -inset -compact
.It Sx ADD HL,r16
.It Sx DEC r16
.It Sx INC r16
.El
.Ss Bit Operations Instructions
.Bl -inset -compact
.It Sx BIT u3,r8
.It Sx BIT u3,[HL]
.It Sx RES u3,r8
.It Sx RES u3,[HL]
.It Sx SET u3,r8
.It Sx SET u3,[HL]
.It Sx SWAP r8
.It Sx SWAP [HL]
.El
.Ss Bit Shift Instructions
.Bl -inset -compact
.It Sx RL r8
.It Sx RL [HL]
.It Sx RLA
.It Sx RLC r8
.It Sx RLC [HL]
.It Sx RLCA
.It Sx RR r8
.It Sx RR [HL]
.It Sx RRA
.It Sx RRC r8
.It Sx RRC [HL]
.It Sx RRCA
.It Sx SLA r8
.It Sx SLA [HL]
.It Sx SRA r8
.It Sx SRA [HL]
.It Sx SRL r8
.It Sx SRL [HL]
.El
.Ss Load Instructions
.Ss Load instructions
.Bl -inset -compact
.It Sx LD r8,r8
.It Sx LD r8,n8
@@ -169,7 +100,80 @@ and
.It Sx LD A,[HLI]
.It Sx LD A,[HLD]
.El
.Ss Jumps and Subroutines
.Ss 8-bit arithmetic instructions
.Bl -inset -compact
.It Sx ADC A,r8
.It Sx ADC A,[HL]
.It Sx ADC A,n8
.It Sx ADD A,r8
.It Sx ADD A,[HL]
.It Sx ADD A,n8
.It Sx CP A,r8
.It Sx CP A,[HL]
.It Sx CP A,n8
.It Sx DEC r8
.It Sx DEC [HL]
.It Sx INC r8
.It Sx INC [HL]
.It Sx SBC A,r8
.It Sx SBC A,[HL]
.It Sx SBC A,n8
.It Sx SUB A,r8
.It Sx SUB A,[HL]
.It Sx SUB A,n8
.El
.Ss 16-bit arithmetic instructions
.Bl -inset -compact
.It Sx ADD HL,r16
.It Sx DEC r16
.It Sx INC r16
.El
.Ss Bitwise logic instructions
.Bl -inset -compact
.It Sx AND A,r8
.It Sx AND A,[HL]
.It Sx AND A,n8
.It Sx CPL
.It Sx OR A,r8
.It Sx OR A,[HL]
.It Sx OR A,n8
.It Sx XOR A,r8
.It Sx XOR A,[HL]
.It Sx XOR A,n8
.El
.Ss Bit flag instructions
.Bl -inset -compact
.It Sx BIT u3,r8
.It Sx BIT u3,[HL]
.It Sx RES u3,r8
.It Sx RES u3,[HL]
.It Sx SET u3,r8
.It Sx SET u3,[HL]
.El
.Ss Bit shift instructions
.Bl -inset -compact
.It Sx RL r8
.It Sx RL [HL]
.It Sx RLA
.It Sx RLC r8
.It Sx RLC [HL]
.It Sx RLCA
.It Sx RR r8
.It Sx RR [HL]
.It Sx RRA
.It Sx RRC r8
.It Sx RRC [HL]
.It Sx RRCA
.It Sx SLA r8
.It Sx SLA [HL]
.It Sx SRA r8
.It Sx SRA [HL]
.It Sx SRL r8
.It Sx SRL [HL]
.It Sx SWAP r8
.It Sx SWAP [HL]
.El
.Ss Jumps and subroutine instructions
.Bl -inset -compact
.It Sx CALL n16
.It Sx CALL cc,n16
@@ -183,7 +187,12 @@ and
.It Sx RETI
.It Sx RST vec
.El
.Ss Stack Operations Instructions
.Ss Carry flag instructions
.Bl -inset -compact
.It Sx CCF
.It Sx SCF
.El
.Ss Stack manipulation instructions
.Bl -inset -compact
.It Sx ADD HL,SP
.It Sx ADD SP,e8
@@ -198,16 +207,16 @@ and
.It Sx PUSH AF
.It Sx PUSH r16
.El
.Ss Miscellaneous Instructions
.Ss Interrupt-related instructions
.Bl -inset -compact
.It Sx CCF
.It Sx CPL
.It Sx DAA
.It Sx DI
.It Sx EI
.It Sx HALT
.El
.Ss Miscellaneous instructions
.Bl -inset -compact
.It Sx DAA
.It Sx NOP
.It Sx SCF
.It Sx STOP
.El
.Sh INSTRUCTION REFERENCE
@@ -222,7 +231,7 @@ Cycles: 1
Bytes: 1
.Pp
Flags:
.Bl -hang -compact
.Bl -tag -width Ds
.It Sy Z
Set if result is 0.
.It Sy N
@@ -267,7 +276,7 @@ Cycles: 1
Bytes: 1
.Pp
Flags:
.Bl -hang -compact
.Bl -tag -width Ds
.It Sy Z
Set if result is 0.
.It Sy N
@@ -312,7 +321,7 @@ Cycles: 2
Bytes: 1
.Pp
Flags:
.Bl -hang -compact
.Bl -tag -width Ds
.It Sy N
0
.It Sy H
@@ -343,7 +352,7 @@ Cycles: 4
Bytes: 2
.Pp
Flags:
.Bl -hang -compact
.Bl -tag -width Ds
.It Sy Z
0
.It Sy N
@@ -364,7 +373,7 @@ Cycles: 1
Bytes: 1
.Pp
Flags:
.Bl -hang -compact
.Bl -tag -width Ds
.It Sy Z
Set if result is 0.
.It Sy N
@@ -410,7 +419,7 @@ Cycles: 2
Bytes: 2
.Pp
Flags:
.Bl -hang -compact
.Bl -tag -width Ds
.It Sy Z
Set if the selected bit is 0.
.It Sy N
@@ -466,7 +475,7 @@ Cycles: 1
Bytes: 1
.Pp
Flags:
.Bl -hang -compact
.Bl -tag -width Ds
.It Sy N
0
.It Sy H
@@ -487,7 +496,7 @@ Cycles: 1
Bytes: 1
.Pp
Flags:
.Bl -hang -compact
.Bl -tag -width Ds
.It Sy Z
Set if result is 0.
.It Sy N
@@ -538,7 +547,7 @@ Cycles: 1
Bytes: 1
.Pp
Flags:
.Bl -hang -compact
.Bl -tag -width Ds
.It Sy N
1
.It Sy H
@@ -552,7 +561,7 @@ Cycles: 1
Bytes: 1
.Pp
Flags:
.Bl -hang -compact
.Bl -tag -width Ds
.It Sy Z
Set if result is 0.
.It Sy H
@@ -570,7 +579,7 @@ Cycles: 1
Bytes: 1
.Pp
Flags:
.Bl -hang -compact
.Bl -tag -width Ds
.It Sy Z
Set if result is 0.
.It Sy N
@@ -682,7 +691,7 @@ Cycles: 1
Bytes: 1
.Pp
Flags:
.Bl -hang -compact
.Bl -tag -width Ds
.It Sy Z
Set if result is 0.
.It Sy N
@@ -1090,7 +1099,7 @@ Cycles: 3
Bytes: 2
.Pp
Flags:
.Bl -hang -compact
.Bl -tag -width Ds
.It Sy Z
0
.It Sy N
@@ -1132,7 +1141,7 @@ Cycles: 1
Bytes: 1
.Pp
Flags:
.Bl -hang -compact
.Bl -tag -width Ds
.It Sy Z
Set if result is 0.
.It Sy N
@@ -1189,7 +1198,7 @@ Cycles: 3
Bytes: 1
.Pp
Flags:
.Bl -hang -compact
.Bl -tag -width Ds
.It Sy Z
Set from bit 7 of the popped low byte.
.It Sy N
@@ -1339,7 +1348,7 @@ Cycles: 2
Bytes: 2
.Pp
Flags:
.Bl -hang -compact
.Bl -tag -width Ds
.It Sy Z
Set if result is 0.
.It Sy N
@@ -1382,7 +1391,7 @@ Cycles: 1
Bytes: 1
.Pp
Flags:
.Bl -hang -compact
.Bl -tag -width Ds
.It Sy Z
0
.It Sy N
@@ -1408,7 +1417,7 @@ Cycles: 2
Bytes: 2
.Pp
Flags:
.Bl -hang -compact
.Bl -tag -width Ds
.It Sy Z
Set if result is 0.
.It Sy N
@@ -1451,7 +1460,7 @@ Cycles: 1
Bytes: 1
.Pp
Flags:
.Bl -hang -compact
.Bl -tag -width Ds
.It Sy Z
0
.It Sy N
@@ -1477,7 +1486,7 @@ Cycles: 2
Bytes: 2
.Pp
Flags:
.Bl -hang -compact
.Bl -tag -width Ds
.It Sy Z
Set if result is 0.
.It Sy N
@@ -1520,7 +1529,7 @@ Cycles: 1
Bytes: 1
.Pp
Flags:
.Bl -hang -compact
.Bl -tag -width Ds
.It Sy Z
0
.It Sy N
@@ -1546,7 +1555,7 @@ Cycles: 2
Bytes: 2
.Pp
Flags:
.Bl -hang -compact
.Bl -tag -width Ds
.It Sy Z
Set if result is 0.
.It Sy N
@@ -1589,7 +1598,7 @@ Cycles: 1
Bytes: 1
.Pp
Flags:
.Bl -hang -compact
.Bl -tag -width Ds
.It Sy Z
0
.It Sy N
@@ -1623,7 +1632,7 @@ Cycles: 1
Bytes: 1
.Pp
Flags:
.Bl -hang -compact
.Bl -tag -width Ds
.It Sy Z
Set if result is 0.
.It Sy N
@@ -1669,7 +1678,7 @@ Cycles: 1
Bytes: 1
.Pp
Flags:
.Bl -hang -compact
.Bl -tag -width Ds
.It Sy N
0
.It Sy H
@@ -1717,7 +1726,7 @@ Cycles: 2
Bytes: 2
.Pp
Flags:
.Bl -hang -compact
.Bl -tag -width Ds
.It Sy Z
Set if result is 0.
.It Sy N
@@ -1757,7 +1766,7 @@ Cycles: 2
Bytes: 2
.Pp
Flags:
.Bl -hang -compact
.Bl -tag -width Ds
.It Sy Z
Set if result is 0.
.It Sy N
@@ -1797,7 +1806,7 @@ Cycles: 2
Bytes: 2
.Pp
Flags:
.Bl -hang -compact
.Bl -tag -width Ds
.It Sy Z
Set if result is 0.
.It Sy N
@@ -1842,7 +1851,7 @@ Cycles: 1
Bytes: 1
.Pp
Flags:
.Bl -hang -compact
.Bl -tag -width Ds
.It Sy Z
Set if result is 0.
.It Sy N
@@ -1889,7 +1898,7 @@ Cycles: 2
Bytes: 2
.Pp
Flags:
.Bl -hang -compact
.Bl -tag -width Ds
.It Sy Z
Set if result is 0.
.It Sy N
@@ -1921,7 +1930,7 @@ Cycles: 1
Bytes: 1
.Pp
Flags:
.Bl -hang -compact
.Bl -tag -width Ds
.It Sy Z
Set if result is 0.
.It Sy N

162
man/rgbasm.5
View File

@@ -253,7 +253,7 @@ Although, for these examples,
.Ic STRFMT
would be more appropriate; see
.Sx String expressions
further below.
below.
.Sh EXPRESSIONS
An expression can be composed of many things.
Numeric expressions are always evaluated using signed 32-bit math.
@@ -267,7 +267,7 @@ This is generally always the case, unless a label is involved, as explained in t
section.
However, some operators can be constant even with non-constant operands, as explained in
.Sx Operators
further below.
below.
.Pp
The instructions in the macro-language generally require constant expressions.
.Ss Numeric formats
@@ -968,12 +968,14 @@ block before performing its own function.
.Ic LOAD
blocks can use the
.Ic UNION
modifier as described below, but not the
modifier as described in
.Sx Unionized sections
below, but not the
.Ic FRAGMENT
modifier.
.Ss Unionized sections
When you're tight on RAM, you may want to define overlapping static memory allocations, as explained in the
.Sx Unions
.Sx Allocating overlapping spaces in RAM
section.
However, a
.Ic UNION
@@ -1014,7 +1016,7 @@ or
.El
.Pp
Different declarations of the same unionized section are not appended, but instead overlaid on top of each other, just like
.Sx Unions .
.Sx Allocating overlapping spaces in RAM .
Similarly, the size of an unionized section is the largest of all its declarations.
.Ss Section fragments
Section fragments are sections with a small twist: when several of the same name are encountered, they are concatenated instead of producing an error.
@@ -1137,7 +1139,7 @@ otherwise, it is said to be
.Dq exported ,
explained in
.Sx Exporting and importing symbols
further below).
below).
More than one dot in label names is not allowed.
.Pp
For convenience, local labels can use a shorthand syntax: when a symbol name starting with a dot is found (for example, inside an expression, or when declaring a label), then the current
@@ -1567,47 +1569,6 @@ environment variable if that is defined as a UNIX timestamp.
Refer to the spec at
.Lk https://reproducible-builds.org/docs/source-date-epoch/ reproducible-builds.org .
.Sh DEFINING DATA
.Ss Statically allocating space in RAM
.Ic DS
statically allocates a number of empty bytes.
This is the preferred method of allocating space in a RAM section.
You can also use
.Ic DB , DW
and
.Ic DL
without any arguments instead (see
.Sx Defining constant data in ROM
below).
.Bd -literal -offset indent
DS 42 ;\ Allocates 42 bytes
.Ed
.Pp
Empty space in RAM sections will not be initialized.
In ROM sections, it will be filled with the value passed to the
.Fl p
command-line option, except when using overlays with
.Fl O .
.Pp
Instead of an exact number of bytes, you can specify
.Ic ALIGN Ns Bq Ar align , offset
to allocate however many bytes are required to align the subsequent data.
Thus,
.Sq Ic DS ALIGN Ns Bo Ar align , offset Bc , No ...
is equivalent to
.Sq Ic DS Ar n , No ...
followed by
.Sq Ic ALIGN Ns Bq Ar align , offset ,
where
.Ar n
is the minimum value needed to satisfy the
.Ic ALIGN
constraint (see
.Sx Requesting alignment
below).
Note that
.Ic ALIGN Ns Bq Ar align
is a shorthand for
.Ic ALIGN Ns Bq Ar align , No 0 .
.Ss Defining constant data in ROM
.Ic DB
defines a list of bytes that will be stored in the final image.
@@ -1674,7 +1635,7 @@ can be used in a
/
.Ic SRAM
section.
.Ss Including binary files
.Ss Including binary data files
You probably have some graphics, level data, etc. you'd like to include.
Use
.Ic INCBIN
@@ -1698,7 +1659,48 @@ INCBIN "data.bin", 78, 256
.Pp
The length argument is optional.
If only the start position is specified, the bytes from the start position until the end of the file will be included.
.Ss Unions
.Ss Statically allocating space in RAM
.Ic DS
statically allocates a number of empty bytes.
This is the preferred method of allocating space in a RAM section.
You can also use
.Ic DB , DW
and
.Ic DL
without any arguments instead (see
.Sx Defining constant data in ROM
below).
.Bd -literal -offset indent
DS 42 ;\ Allocates 42 bytes
.Ed
.Pp
Empty space in RAM sections will not be initialized.
In ROM sections, it will be filled with the value passed to the
.Fl p
command-line option, except when using overlays with
.Fl O .
.Pp
Instead of an exact number of bytes, you can specify
.Ic ALIGN Ns Bq Ar align , offset
to allocate however many bytes are required to align the subsequent data.
Thus,
.Sq Ic DS ALIGN Ns Bo Ar align , offset Bc , No ...
is equivalent to
.Sq Ic DS Ar n , No ...
followed by
.Sq Ic ALIGN Ns Bq Ar align , offset ,
where
.Ar n
is the minimum value needed to satisfy the
.Ic ALIGN
constraint (see
.Sx Requesting alignment
below).
Note that
.Ic ALIGN Ns Bq Ar align
is a shorthand for
.Ic ALIGN Ns Bq Ar align , No 0 .
.Ss Allocating overlapping spaces in RAM
Unions allow multiple static memory allocations to overlap, like unions in C.
This does not increase the amount of memory available, but allows re-using the same memory region for different purposes.
.Pp
@@ -1759,6 +1761,37 @@ Unions may be used in any section, but they may only contain space-allocating di
.Ic DS
(see
.Sx Statically allocating space in RAM ) .
.Ss Requesting alignment
While
.Ic ALIGN
as presented in
.Sx SECTIONS
is often useful as-is, sometimes you instead want a particular piece of data (or code) in the middle of the section to be aligned.
This is made easier through the use of mid-section
.Ic ALIGN Ar align , offset .
It will retroactively alter the section's attributes to ensure that the location the
.Ic ALIGN
directive is at, has its
.Ar align
lower bits equal to
.Ar offset .
.Pp
If the constraint cannot be met (for example because the section is fixed at an incompatible address), an error is produced.
Note that
.Ic ALIGN Ar align
is a shorthand for
.Ic ALIGN Ar align , No 0 .
.Pp
There may be times when you don't just want to specify an alignment constraint at the current location, but also skip ahead until the constraint can be satisfied.
In that case, you can use
.Ic DS ALIGN Ns Bq Ar align , offset
to allocate however many bytes are required to align the subsequent data.
.Pp
If the constraint cannot be met by skipping any amount of space, an error is produced.
Note that
.Ic ALIGN Ns Bq Ar align
is a shorthand for
.Ic ALIGN Ns Bq Ar align , No 0 .
.Sh THE MACRO LANGUAGE
.Ss Invoking macros
A macro is invoked by using its name at the beginning of a line, like a directive, followed by any comma-separated arguments.
@@ -2320,37 +2353,6 @@ PUSHO b.X, g.oOX
DW `..ooOOXX
POPO
.Ed
.Ss Requesting alignment
While
.Ic ALIGN
as presented in
.Sx SECTIONS
is often useful as-is, sometimes you instead want a particular piece of data (or code) in the middle of the section to be aligned.
This is made easier through the use of mid-section
.Ic ALIGN Ar align , offset .
It will alter the section's attributes to ensure that the location the
.Ic ALIGN
directive is at, has its
.Ar align
lower bits equal to
.Ar offset .
.Pp
If the constraint cannot be met (for example because the section is fixed at an incompatible address), an error is produced.
Note that
.Ic ALIGN Ar align
is a shorthand for
.Ic ALIGN Ar align , No 0 .
.Pp
There may be times when you don't just want to specify an alignment constraint at the current location, but also skip ahead until the constraint can be satisfied.
In that case, you can use
.Ic DS ALIGN Ns Bq Ar align , offset
to allocate however many bytes are required to align the subsequent data.
.Pp
If the constraint cannot be met by skipping any amount of space, an error is produced.
Note that
.Ic ALIGN Ns Bq Ar align
is a shorthand for
.Ic ALIGN Ns Bq Ar align , No 0 .
.Sh SEE ALSO
.Xr rgbasm 1 ,
.Xr rgblink 1 ,

6
man/rgbds.5
View File

@@ -254,7 +254,7 @@ Size of the
below.
.It Cm BYTE Ar RPNExpr Ns Bq RPNSize
The patch's value, encoded as a RPN expression
.Pq see Sx RPN EXPRESSIONS .
.Pq see Sx RPN expressions .
.El
.It Cm ENDR
.El
@@ -294,14 +294,14 @@ Size of the
below.
.It Cm BYTE Ar RPNExpr Ns Bq RPNSize
The patch's value, encoded as a RPN expression
.Pq see Sx RPN EXPRESSIONS .
.Pq see Sx RPN expressions .
.It Cm STRING Ar Message
The message displayed if the expression evaluates to a non-zero value.
If empty, a generic message is displayed instead.
.El
.It Cm ENDR
.El
.Ss RPN EXPRESSIONS
.Ss RPN expressions
Expressions in the object file are stored as RPN, or
.Dq Reverse Polish Notation ,
which is a notation that allows computing arbitrary expressions with just a simple stack.