the10thwiz/cc65
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge branch 'master' into seglist

Browse Source
This commit is contained in:
Bob Andrews
2025-07-10 20:48:28 +02:00
committed by GitHub
parent 3ae514921c ce6e322046
commit d8b4013f3c
226 changed files with 2847 additions and 2118 deletions
Download Patch File Download Diff File Expand all files Collapse all files

117
doc/ca65.sgml
View File

@@ -107,6 +107,7 @@ Short options:
Long options:
--auto-import Mark unresolved symbols as import
--bin-include-dir dir Set a search path for binary includes
--color [on|auto|off] Color diagnostics (default: auto)
--cpu type Set cpu type
--create-dep name Create a make dependency file
--create-full-dep name Create a full make dependency file
@@ -120,6 +121,7 @@ Long options:
--listing name Create a listing file if assembly was ok
--list-bytes n Maximum number of bytes per listing line
--memory-model model Set the memory model
--no-utf8 Disable use of UTF-8 in diagnostics
--pagelength n Set the page length for the listing
--relax-checks Disables some error checks
--segment-list Generate segment offsets in listing
@@ -148,6 +150,14 @@ Here is a description of all the command line options:
name="search paths">.
<label id="option--color">
<tag><tt>--color</tt></tag>
This option controls if the assembler will use colors when printing
diagnostics. The default is "auto" which will enable colors if the output
goes to a terminal (not to a file).
<label id="option--cpu">
<tag><tt>--cpu type</tt></tag>
@@ -261,6 +271,14 @@ Here is a description of all the command line options:
huge.
<label id="option--no-utf8">
<tag><tt>--no-utf8</tt></tag>
Disable the use of UTF-8 characters in diagnostics. This might be necessary
if auto detection fails or if the output is captured for processing with a
tool that is not UTF-8 capable.
<label id="option-o">
<tag><tt>-o name</tt></tag>
@@ -920,6 +938,7 @@ See the description of the <tt><ref id=".PROC" name=".PROC"></tt>
directive for more information.
<label id=cheap-locals>
<sect1>Cheap local labels<p>
Cheap local labels are defined like standard labels, but the name of the
@@ -1435,38 +1454,6 @@ constant is defined:
CPU_ISET_M740
</verb></tscreen>
<!-- Sorry but explaining these with the changes from #2751 is too cringy for
me - must be done by someone else. The remainder is from the old
".macpack cpu" section"
The value read from the <tt/<ref id=".CPU" name=".CPU">/ pseudo variable may
be checked with <tt/<ref id="operators" name=".BITAND">/ to determine if the
currently enabled CPU supports a specific instruction set. For example the
65C02 supports all instructions of the 65SC02 CPU, so it has the
<tt/CPU_ISET_65SC02/ bit set in addition to its native <tt/CPU_ISET_65C02/
bit. Using
<tscreen><verb>
.if (.cpu .bitand CPU_ISET_65SC02)
lda (c_sp)
.else
ldy #$00
lda (c_sp),y
.endif
</verb></tscreen>
it is possible to determine if the
<tscreen><verb>
lda (c_sp)
</verb></tscreen>
instruction is supported, which is the case for the 65SC02, 65C02 and 65816
CPUs (the latter two are upwards compatible to the 65SC02).
see section <ref id="6502-mode" name="6502 format"> and following.
-->
<tt/.CPU/ may be used to replace the .IFPxx pseudo instructions or to
construct even more complex expressions.
@@ -1484,8 +1471,43 @@ see section <ref id="6502-mode" name="6502 format"> and following.
.endif
</verb></tscreen>
See also: <tt><ref id=".CAP" name=".CAP"></tt>
<bf>The dilemma:</bf>
The original design of this feature was made under the assumption, that any
"higher" CPU will support the entire instruction set of the "lower" CPU. For
example: the WDC W65C02 supports all instructions of the 65C02, which again
support all instructions of the 65SC02. Unfortunately this is not true for all
CMOS CPUs - when the 65CE02 was made, some instructions were changed, and a new
addressingmode was added. As a result all CPUS after (and including) 65CE02
are no more (source code) compatible with all instructions originally introduced
by the 65SC02.
Because of this, the .CPU function and the ISET* macros were repurposed to
indicate <em>groups of instructions</em> only, ie only the set of instructions
that was added by that particular CPU. In the value returned by .CPU only the
bits will be set, that refer to the groups of instructions that are completely
supported by that CPU.
The advantage of this is, that the mechanism keeps working for all new CPUs
added. The inevitable disadvantage is that you now have to know exactly which
CPU added which instructions (look <htmlurl url="cpus.html" name="here"> for reference).
<tscreen><verb>
.if (.cpu .bitand CPU_ISET_65SC02)
; This will be assembled for the W65C02, 65C02, 65SC02, 65816, HUC6820
lda (c_sp)
.elseif (.cpu .bitand CPU_ISET_65CE02)
; This will be assembled for the 65CE02, 4510, 45GS02
ldz #$00
lda (c_sp),z
.else
ldy #$00
lda (c_sp),y
.endif
</verb></tscreen>
See also: <tt><ref id=".CAP" name=".CAP"></tt>, which is a similar mechanism,
but without the problem outlined above.
<sect1><tt>.ISIZE</tt><label id=".ISIZE"><p>
@@ -3753,20 +3775,23 @@ See: <tt><ref id=".ASCIIZ" name=".ASCIIZ"></tt>,<tt><ref id=".BYTE" name=".BYTE"
<sect1><tt>.LOCAL</tt><label id=".LOCAL"><p>
This command may only be used inside a macro definition. It declares a
list of identifiers as local to the macro expansion.
This command may only be used inside a macro definition. It declares a list
of identifiers as local to the macro expansion. The identifers may be
standard identifiers or cheap local identifiers depending on the planed use.
A problem when using macros are labels: Since they don't change their name,
you get a "duplicate symbol" error if the macro is expanded the second time.
Labels declared with <tt><ref id=".LOCAL" name=".LOCAL"></tt> have their
name mapped to an internal unique name (<tt/___ABCD__/) with each macro
name replaced by an internally generated unique name for each macro
invocation.
Some other assemblers start a new lexical block inside a macro expansion.
This has some drawbacks however, since that will not allow <em/any/ symbol
to be visible outside a macro, a feature that is sometimes useful. The
<tt><ref id=".LOCAL" name=".LOCAL"></tt> command is in my eyes a better way
to address the problem.
Please note that while the generated names are unique and guaranteed to not
clash with any user generated names, they are still regular symbols and
added to the current scope. This means that a local macro label will start a
new scope for cheap locals whenever the macro is expanded. To avoid that,
you may also use a <ref id="cheap-locals" name="cheap local symbol"> for the
name. In this case the assembler will generate unique cheap local
identifiers instead of standard ones.
You get an error when using <tt><ref id=".LOCAL" name=".LOCAL"></tt> outside
a macro.
@@ -3805,7 +3830,6 @@ See: <tt><ref id=".ASCIIZ" name=".ASCIIZ"></tt>,<tt><ref id=".BYTE" name=".BYTE"
<tscreen><verb>
atari Defines the scrcode macro.
cbm Defines the scrcode macro.
cpu Defines constants for the .CPU variable.
generic Defines generic macros like add, sub, and blt.
longbranch Defines conditional long-jump macros.
</verb></tscreen>
@@ -5119,6 +5143,7 @@ For better orthogonality, the assembler defines similar symbols as the
compiler, depending on the target system selected:
<itemize>
<item><tt/__AGAT__/ - Target system is <tt/agat/
<item><tt/__APPLE2__/ - Target system is <tt/apple2/ or <tt/apple2enh/
<item><tt/__APPLE2ENH__/ - Target system is <tt/apple2enh/
<item><tt/__ATARI2600__/ - Target system is <tt/atari2600/
@@ -5131,23 +5156,31 @@ compiler, depending on the target system selected:
<item><tt/__C128__/ - Target system is <tt/c128/
<item><tt/__C16__/ - Target system is <tt/c16/ or <tt/plus4/
<item><tt/__C64__/ - Target system is <tt/c64/
<item><tt/__C65__/ - Target system is <tt/c65/
<item><tt/__CBM__/ - Target is a Commodore or Commodore-alike system
<item><tt/__CBM510__/ - Target system is <tt/cbm510/
<item><tt/__CBM610__/ - Target system is <tt/cbm610/
<item><tt/__CREATIVISION__/ - Target system is <tt/creativision/
<item><tt/__CX16__/ - Target system is <tt/cx16/
<item><tt/__GAMATE__/ - Target system is <tt/gamate/
<item><tt/__GEOS__/ - Target is a GEOS system
<item><tt/__GEOS_APPLE__/ - Target system is <tt/geos-apple/
<item><tt/__GEOS_CBM__/ - Target system is <tt/geos-cbm/
<item><tt/__KIM1__/ - Target system is <tt/kim1/
<item><tt/__LUNIX__/ - Target system is <tt/lunix/
<item><tt/__LYNX__/ - Target system is <tt/lynx/
<item><tt/__MEGA65__/ - Target system is <tt/mega65/
<item><tt/__NES__/ - Target system is <tt/nes/
<item><tt/__OSIC1P__/ - Target system is <tt/osic1p/
<item><tt/__PCE__/ - Target system is <tt/pce/
<item><tt/__PET__/ - Target system is <tt/pet/
<item><tt/__PLUS4__/ - Target system is <tt/plus4/
<item><tt/__RP6502__/ - Target system is <tt/rp6502/
<item><tt/__SIM6502__/ - Target system is <tt/sim6502/
<item><tt/__SIM65C02__/ - Target system is <tt/sim65c02/
<item><tt/__SUPERVISION__/ - Target system is <tt/supervision/
<item><tt/__SYM1__/ - Target system is <tt/sym1/
<item><tt/__TELESTRAT__/ - Target system is <tt/telestrat/
<item><tt/__VIC20__/ - Target system is <tt/vic20/
</itemize>

59
doc/cc65.sgml
View File

@@ -641,7 +641,7 @@ Here is a description of all the command line options:
<item>pce (PC engine)
<item>pet (all CBM PET systems except the 2001)
<item>plus4
<item>p6502
<item>rp6502
<item>sim6502
<item>sim65c02
<item>supervision
@@ -1112,6 +1112,10 @@ This cc65 version has some extensions to the ISO C standard.
The compiler defines several macros at startup:
<descrip>
<tag><tt>__AGAT__</tt></tag>
This macro is defined if the target is the Agat (-t agat).
<tag><tt>__APPLE2__</tt></tag>
This macro is defined if the target is the Apple ][ (-t apple2) or the enhanced Apple //e (-t apple2enh).
@@ -1122,11 +1126,15 @@ The compiler defines several macros at startup:
<tag><tt>__ATARI2600__</tt></tag>
This macro is defined if the target is the Atari 2600 game console.
This macro is defined if the target is the Atari 2600 game console (-t atari2600).
<tag><tt>__ATARI5200__</tt></tag>
This macro is defined if the target is the Atari 5200 game console.
This macro is defined if the target is the Atari 5200 game console (-t atari5200).
<tag><tt>__ATARI7800__</tt></tag>
This macro is defined if the target is the Atari 7800 game console (-t atari7800).
<tag><tt>__ATARI__</tt></tag>
@@ -1140,6 +1148,10 @@ The compiler defines several macros at startup:
This macro is defined if the target is the Oric Atmos (-t atmos).
<tag><tt>__BBC__</tt></tag>
This macro is defined if the target is the BBC (-t bbc).
<tag><tt>__C128__</tt></tag>
This macro is defined if the target is the Commodore 128 (-t c128).
@@ -1152,6 +1164,10 @@ The compiler defines several macros at startup:
This macro is defined if the target is the Commodore 64 (-t c64).
<tag><tt>__C65__</tt></tag>
This macro is defined if the target is the Commodore 65 (-t c65).
<tag><tt>__CBM__</tt></tag>
This macro is defined if the target system is one of the CBM targets.
@@ -1196,10 +1212,8 @@ The compiler defines several macros at startup:
<label id="macro-CPU">
<tag><tt>__CPU__</tt></tag>
This macro contains a bitset that allows to check if a specific instruction
set is supported. For example, the 65C02 CPU supports all instructions of the
65SC02. So testing for the instruction set of the 65SC02 using the following
check will succeed for both CPUs (and also for the 65816 and HUC6280).
This macro contains a bitset that allows to check if a specific group of
instructions is supported.
<tscreen><verb>
#if (__CPU__ & __CPU_ISET_65SC02__)
@@ -1212,6 +1226,13 @@ The compiler defines several macros at startup:
given, but can be changed using the <tt/<ref id="option--cpu" name="--cpu">/
command line option.
Note that, since the different CMOS instruction sets are not orthogonal, the
following test macros only test for the group of instructions <bf>added</bf>
by this particular CPU.
see <htmlurl url="ca65.html#.CPU" name=".CPU"> for details on the ISET*
dilemma.
<tag><tt>__CPU_4510__</tt></tag>
This macro is defined if the code is compiled for a 4510 CPU.
@@ -1321,6 +1342,10 @@ The compiler defines several macros at startup:
<tt/<ref id="macro-CPU" name="__CPU__">/ macro for the instruction set
of the W65C02 CPU.
<tag><tt>__CREATIVISION__</tt></tag>
This macro is defined if the target is the VTech Creativision game console (-t creativision).
<tag><tt>__CX16__</tt></tag>
This macro is defined if the target is the Commander X16 (-t cx16).
@@ -1339,6 +1364,10 @@ The compiler defines several macros at startup:
This macro expands to a string containing the name of the C source file.
<tag><tt>__GAMATE__</tt></tag>
This macro is defined if the target is the Gamate handheld (-t gamate).
<tag><tt>__GEOS__</tt></tag>
This macro is defined if you are compiling for one of the GEOS systems.
@@ -1351,6 +1380,10 @@ The compiler defines several macros at startup:
This macro is defined if you are compiling for the GEOS 64/128 system (-t geos-cbm).
<tag><tt>__KIM1__</tt></tag>
This macro is defined if the target is the KIM-1 (-t kmi1).
<tag><tt>__LINE__</tt></tag>
This macro expands to the current line number.
@@ -1363,6 +1396,10 @@ The compiler defines several macros at startup:
This macro is defined if the target is the Atari Lynx (-t lynx).
<tag><tt>__MEGA65__</tt></tag>
This macro is defined if the target is the Mega 65 (-t mega65).
<tag><tt>__NES__</tt></tag>
This macro is defined if the target is the Nintendo Entertainment System (-t nes).
@@ -1388,6 +1425,10 @@ The compiler defines several macros at startup:
This macro is defined if the target is the Ohio Scientific Challenger 1P
(-t osic1p).
<tag><tt>__PCE__</tt></tag>
This macro is defined if the target is the PC Engine game console (-t pce).
<tag><tt>__PET__</tt></tag>
This macro is defined if the target is the PET family of computers (-t pet).
@@ -1396,6 +1437,10 @@ The compiler defines several macros at startup:
This macro is defined if the target is the Commodore Plus/4 (-t plus4).
<tag><tt>__RP6502__</tt></tag>
This macro is defined if the target is the Picocomputer 6502 (-t rp6502).
<tag><tt>__SIM6502__</tt></tag>
This macro is defined if the target is sim65 in 6502 mode (-t sim6502).

31
doc/funcref.sgml
View File

@@ -785,6 +785,7 @@ communication, see also <tt>testcode/lib/ser-test.c</tt>.
<item><ref id="strcpy" name="strcpy">
<item><ref id="strcspn" name="strcspn">
<item><ref id="strdup" name="strdup">
<item><ref id="strndup" name="strndup">
<item><ref id="strerror" name="strerror">
<item><ref id="stricmp" name="stricmp">
<item><ref id="strlen" name="strlen">
@@ -5621,6 +5622,7 @@ be used in presence of a prototype.
<ref id="free" name="free">,
<ref id="realloc" name="realloc">,
<ref id="strdup" name="strdup">
<ref id="strndup" name="strndup">
<tag/Example/None.
</descrip>
</quote>
@@ -7774,6 +7776,35 @@ be used in presence of a prototype.
<tag/See also/
<ref id="free" name="free">,
<ref id="malloc" name="malloc">
<ref id="strndup" name="strndup">
<tag/Example/None.
</descrip>
</quote>
<sect1>strndup<label id="strndup"><p>
<quote>
<descrip>
<tag/Function/Allocate a copy of a string on the heap, of a given maximum length.
<tag/Header/<tt/<ref id="string.h" name="string.h">/
<tag/Declaration/<tt/char* __fastcall__ strndup (const char* s, size_t maxlen);/
<tag/Description/<tt/strndup/ allocates a memory block on the heap, big enough
to hold a copy of <tt/s/ including the terminating zero. If the allocation
fails, <tt/NULL/ is returned, otherwise <tt/s/ is copied into the allocated
memory block, maxlen characters are kept, and a pointer to the block is returned.
<tag/Notes/<itemize>
<item>The function is only available as fastcall function, so it may only
be used in presence of a prototype.
<item>It is up to the caller to free the allocated memory block.
</itemize>
<tag/Availability/ISO 9899
<tag/See also/
<ref id="free" name="free">,
<ref id="malloc" name="malloc">
<ref id="strndup" name="strndup">
<tag/Example/None.
</descrip>
</quote>