diff --git a/man/gbz80.7 b/man/gbz80.7 index 819f59613..27f23c73d 100644 --- a/man/gbz80.7 +++ b/man/gbz80.7 @@ -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,7 +79,28 @@ and .Ad 0x38 Pc . .El .Sh INSTRUCTION OVERVIEW -.Ss 8-bit Arithmetic and Logic Instructions +.Ss Load instructions +.Bl -inset -compact +.It Sx LD r8,r8 +.It Sx LD r8,n8 +.It Sx LD r16,n16 +.It Sx LD [HL],r8 +.It Sx LD [HL],n8 +.It Sx LD r8,[HL] +.It Sx LD [r16],A +.It Sx LD [n16],A +.It Sx LDH [n16],A +.It Sx LDH [C],A +.It Sx LD A,[r16] +.It Sx LD A,[n16] +.It Sx LDH A,[n16] +.It Sx LDH A,[C] +.It Sx LD [HLI],A +.It Sx LD [HLD],A +.It Sx LD A,[HLI] +.It Sx LD A,[HLD] +.El +.Ss 8-bit arithmetic instructions .Bl -inset -compact .It Sx ADC A,r8 .It Sx ADC A,[HL] @@ -87,9 +108,6 @@ and .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 @@ -97,26 +115,33 @@ and .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 +.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 +.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] @@ -124,10 +149,8 @@ and .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 +.Ss Bit shift instructions .Bl -inset -compact .It Sx RL r8 .It Sx RL [HL] @@ -147,29 +170,10 @@ and .It Sx SRA [HL] .It Sx SRL r8 .It Sx SRL [HL] +.It Sx SWAP r8 +.It Sx SWAP [HL] .El -.Ss Load Instructions -.Bl -inset -compact -.It Sx LD r8,r8 -.It Sx LD r8,n8 -.It Sx LD r16,n16 -.It Sx LD [HL],r8 -.It Sx LD [HL],n8 -.It Sx LD r8,[HL] -.It Sx LD [r16],A -.It Sx LD [n16],A -.It Sx LDH [n16],A -.It Sx LDH [C],A -.It Sx LD A,[r16] -.It Sx LD A,[n16] -.It Sx LDH A,[n16] -.It Sx LDH A,[C] -.It Sx LD [HLI],A -.It Sx LD [HLD],A -.It Sx LD A,[HLI] -.It Sx LD A,[HLD] -.El -.Ss Jumps and Subroutines +.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 diff --git a/man/rgbasm.5 b/man/rgbasm.5 index 0f05007d6..463fb53d0 100644 --- a/man/rgbasm.5 +++ b/man/rgbasm.5 @@ -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 , diff --git a/man/rgbds.5 b/man/rgbds.5 index 710e02ebe..c41e9b969 100644 --- a/man/rgbds.5 +++ b/man/rgbds.5 @@ -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.