@nataliapc/mcp-openmsx 1.2.10 → 1.2.12

package/resources/programming/toc.json

@@ -32,6 +32,12 @@
             "external_url": "https://map.grauw.nl/articles/mult_div_shifts.php",
             "description": "Comprehensive guide to optimized mathematical operations in Z80 assembly for MSX. Covers fast multiplication and division techniques using bit shifts, generic multiplication routines, division algorithms, and square root calculations. Essential for performance-critical MSX programming where the Z80 lacks built-in multiplication instructions."
         },
+        {
+            "title": "[ASM] Develop a program in a cartridge ROM",
+            "uri": "msxdocs://programming/asm_develop_a_program_in_cartridge_rom",
+            "external_url": "https://www.msx.org/wiki/Develop_a_program_in_cartridge_ROM",
+            "description": "Complete guide to writing MSX ROM cartridge programs in assembly. Covers the 16-byte ROM header structure (INIT, STATEMENT, DEVICE, TEXT), creating ROMs with and without mapper (up to 128KB with ASCII 16k mapper), disk support methods, RAM search and allocation, and practical examples for Glass, Sjasm, tniASM and Zasm assemblers."
+        },
         {
             "title": "[ASM] Get slot ID of any page",
             "uri": "msxdocs://programming/asm_getslot",

package/resources/sdcc/1_Introduction.md

@@ -0,0 +1,199 @@
+# SDCC Compiler User Guide
+
+SDCC LatexCommand input filename "sdcc_version" literal "true"  
+$Date:: 2024-01-29 $  
+$Revision: 14650 $
+
+The above strings enclosed in $ are automatically updated by Subversion
+
+LatexCommand tableofcontents
+
+## Introduction
+
+### About SDCC
+
+**SDCC** (*S* mall *D* evice *CC* ompiler) is free open source, retargettable, optimizing standard (ANSI C89 / ISO C90, ISO C99, ISO C11 / ISO C17) C compiler suite originally written by **Sandeep Dutta** designed for 8 bit Microprocessors. The current version targets Intel MCS-51 based Microprocessors (8031, 8032, 8051, 8052, mcs51 CPU, etc.), Dallas DS80C390 variants, NXP (formerly Freescale/Motorola) HC08 based (HC08, S08), Zilog Z80 based MCUs (Z80, Z180, eZ80 in Z80 mode, SM83, Rabbit 2000/3000, Rabbit 3000A, Toshiba TLCS-90, Zilog eZ80 in Z80 mode, ASCII R800), STMicroelectronics STM8, Padauk PDK14 and PDK15. It can be retargeted for other microprocessors; support for Padauk PDK13 and MOS6502 is under development, whereas Microchip PIC is currently unmaintained. The entire source code for the compiler is distributed under GPL. SDCC uses a modified version of sdas (sdasgb, sdas6808, sdas8051, sdasz80) & sdld, free open source retargetable assembler & linker. SDCC has extensive language extensions suitable for utilizing various microcontrollers and underlying hardware effectively.
+You might also want to have a look at the wiki https://sourceforge.net/p/sdcc/wiki/.
+
+In addition to the MCU specific optimizations SDCC also does a host of standard optimizations like:
+
+- global sub expression elimination,
+- loop optimizations (loop invariant, strength reduction of induction variables and loop reversing),
+- constant folding & propagation,
+- copy propagation,
+- dead code elimination
+- jump tables for *switch* statements.
+For the back-end SDCC uses a global register allocation scheme which should be well suited for other 8 bit MCUs.
+
+The peep hole optimizer uses a rule based substitution mechanism which is MCU independent.
+
+Supported data-types are:
+
+| type | width | default | signed range | unsigned range |
+| --- | --- | --- | --- | --- |
+| _Bool / bool | 8 bits, 1 byte | unsigned | - | 0, 1 |
+| char | 8 bits, 1 byte | unsigned | -128, +127 | 0, +255 |
+| short | 16 bits, 2 bytes | signed | -32.768, +32.767 | 0, +65.535 |
+| int | 16 bits, 2 bytes | signed | -32.768, +32.767 | 0, +65.535 |
+| long | 32 bits, 4 bytes | signed | -2.147.483.648, +2.147.483.647 | 0, +4.294.967.295 |
+| long long status open Incomplete support in the pic14 and pic16 backends. | 64 bits, 8 bytes | signed | | |
+| _BitInt status open Incomplete support in the pic14 and pic16 backends. | 8 to 64 bits, 1 to 8 bytes | | | |
+| float | 4 bytes similar to IEEE 754 | signed | | 1.175494351E-38, 3.402823466E+38 |
+| pointer | 1, 2, 3 or 4 bytes | generic | | |
+| __bit status open Only supported in the mcs51, ds390, ds400 backends. | 1 bit | unsigned | - | 0, 1 |
+| __bit status open Only supported in the mcs51, ds390, ds400 backends. | 1 bit | unsigned | - | 0, 1 |
+
+The compiler also allows *inline assembler code* to be embedded anywhere in a function. In addition, routines developed in assembly can also be called.
+
+SDCC also provides an option (--cyclomatic) to report the relative complexity of a function. These functions can then be further optimized, or hand coded in assembly if needed.
+
+SDCC also comes with a companion source level debugger SDCDB. The debugger currently uses ucSim, a free open source simulator for 8051 and other micro-controllers.
+
+The latest SDCC version can be downloaded from http://sdcc.sourceforge.net/snap.php. *Please note: the compiler will probably always be some steps ahead of this documentation *** Status of documentation Obviously this has pros and cons.
+
+### SDCC Suite Licenses
+
+SDCC suite is a collection of several components derived from different sources with different licenses:
+
+- executables:
+- sdcc compiler:
+sdcc compiler is licensed under the GPLv2 (GPLv3 might apply depending on the libraries used when building).
+The code or object files generated by SDCC suite are not licensed, so they can be used in FLOSS or proprietary (closed source) applications.
+- sdcpp preprocessor:
+derived from GCC cpp preprocessor http://gcc.gnu.org/; GPLv3 license
+- sdas assemblers and sdld linker:
+derived from ASXXXX https://shop-pdp.net/ashtml/; GPLv3 license
+- SDCC run-time libraries:
+The great majority of SDCC run-time libraries are licensed under the GPLv2+LE which allows linking of SDCC run-time libraries with proprietary (closed source) applications.
+A possible exception are pic device libraries and header files which are generated from Microchip header (.inc) and linker script (.lkr) files. Microchip requires that "The header files should state that they are only to be used with authentic Microchip devices" which makes them incompatible with the GPL, if Microchip has any copyright in them (which might depend on local copyright laws). Pic device libraries and header files are located at non-free/lib and non-free/include directories respectively. SDCC should be run with the **--** use-non-free **range none pageformat default --use-non-free** command line option in order to include non-free header files and libraries.
+- sdbinutils utilities (sdar, sdranlib, sdnm, sdobjcopy):
+derived from GNU Binutils http://www.gnu.org/software/binutils/; GPLv3 license
+- ucsim simulators:
+GPLv2 license
+- sdcdb debugger:
+GPLv2 license
+- gcc-test regression tests:
+derived from gcc-testsuite; no license explicitely specified, but since it is a part of GCC is probably GPLv3 licensed
+- packihx:
+public domain
+- makebin:
+zlib/libpng License
+- pic libraries in device/non-free:
+Microchip Technology Inc. claims to have copyrights on this, and their term are non-free. However, a more common opinion is that Microchip Technology Inc. is just claiming a copyright on uncopyrightable facts.
+- libraries:
+- dbuf library:
+zlib/libpng License
+- Boost C++ libraries:
+ http://www.boost.org/; Boost Software License 1.0 (BSL-1.0)
+Links to licenses:
+
+- GPLv2 license: http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
+- LGPLv2.1 license: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html
+- GPLv3 license: http://www.gnu.org/licenses/gpl.html
+- zlib/libpng License: http://www.opensource.org/licenses/Zlib
+- Boost Software License 1.0 (BSL-1.0): http://www.opensource.org/licenses/BSL-1.0
+
+### Documentation
+
+This documentation is maintained using a free open source word processor (\SpecialChar LyX) http://www.lyx.org/.
+
+### Typographic conventions
+
+Throughout this manual, we will use the following convention. Commands you have to type in are printed in **"sans serif"**. Code samples are printed in typewriter font. Interesting items and new terms are printed in *italic.
+
+### Compatibility with previous versions
+
+Newer versions have usually numerous bug fixes compared with the previous version. But we also sometimes introduce some incompatibilities with older versions. Not just for the fun of it, but to make the compiler more stable, efficient and Standard-compliance (see section Standard-Compliance for Standard-Compliance). This is a list of such changes. It would be fine to add to each item, in which version was it changed.
+
+- short is now equivalent to int (16 bits), it used to be equivalent to char (8 bits) which is not ANSI compliant. To maintain compatibility, old programs could be compiled using the --short-is-8bits command line option (option removed after the 3.6.0 release).
+- the default directory for gcc-builds where include, library and documentation files are stored is now in /usr/local/share.
+- char type parameters to vararg, va arg functions are casted to int unless explicitly casted and neither of the **--std-c90, --std-c99, --std-c11 or --std-c23** command line options is used, e.g.:
+`char a=3;
+printf ("%d %c\ n", a, (char)a);
+`
+will push a as an int and as a char resp if none of the above command line options are not defined,
+will push a as two ints if none of the above command line option is defined.
+- pointer type parameters to vararg, va arg functions are casted to generic pointers on Harvard architectures (e.g. mcs51, ds390) unless explicitly casted and neither of the **--std-c90, --std-c99, --std-c11** or **--std-c23** command line options is used.
+- option --regextend has been removed.
+- option --noregparms has been removed.
+- option --stack-after-data has been removed.
+- __bit range none pageformat default bit and __sbit range none pageformat default sbit types now consistently behave like the C99 _Bool type with respect to type conversion range none pageformat default type conversion range none pageformat default type promotion. The most common incompatibility resulting from this change is related to bit toggling range none pageformat default Bit toggling idioms, e.g.:
+__bit b;
+b = ~ range none pageformat default ~ Operator b; /* equivalent to b=1 instead of toggling b */
+b =!b; /* toggles b */
+In previous versions, both forms would have toggled the bit.
+- in older versions, the preprocessor was always called with **--std-c99 range none pageformat default --std-c99** regardless of the **--std-xxx** setting. This is no longer true, and can cause compilation failures on code built with **--std-c90 range none pageformat default --std-c90** but using c99 preprocessor features, such as one-line (//) comments
+- in versions older than 2.8.4 the pic16 *printf() and printf_tiny() library functions supported undocumented and not standard compliant 'b' binary format specifier ("%b", "%hb" and "%lb"). The 'b' specifier is now disabled by default. It can be enabled by defining BINARY_SPECIFIER macro in files device/lib/pic16/libc/stdio/vfprintf.c and device/lib/pic16/libc/stdio/printf_tiny.c and recompiling the library.
+- in versions older then 2.8.5 the unnamed bit-field structure members participated in initialization, which is not conforming with ISO/IEC 9899:1999 standard (see section Section 6.7.8 Initialization, clause 9)
+
+Old behaviour, before version 2.8.5:
+```c
+struct {
+  int a: 2;
+  char: 2;
+  int b: 2;
+} s = {1, 2, 3};
+/* s.a = 1, s.b = 3 */
+```
+New behaviour:
+```c
+struct {
+  int a: 2;
+  char: 2;
+  int b: 2;
+} s = {1, 2};
+/* s.a = 1, s.b = 2 */
+```
+- In 2.9.0 libraries included in SDCC packages, are in ar format. See section Using sdar to Create and Manage Libraries.
+- In 3.0.0 targets for xa51 and avr are disabled by default.
+- In 3.0.0 sdldgb and sdldz80 don't support generation of Game Boy binary image format. The makebin utility can be used to convert Intel Hex format to Game Boy binary image format.
+- In 3.0.0 sdldgb and sdldz80 don't support generation of rrgb (Game Boy simulator) map file and no$gmb symbol file formats. The as2gbmap utility can be used to convert sdld map format to rrgb and no$gmb file formats.
+- In 3.1.0 asranlib utility was renamed to sdranlib.
+- In 3.1.0 pic14 target, structured access to SFR via is deprecated and replaced by. It will be obsoleted (removed) in one of next SDCC releases. See section Naming of special function registers.
+- sdar archive managing utility and sdnm utilities were introduced in version 3.2.0. sdar, sdranlib and sdnm are derived from GNU Binutils package.
+- In 3.2.0 the sdcclib utility is deprecated. Sdar utility should be used to create SDCC object file archives. Sdcclib utility will become obsolete in one of next SDCC releases and will be removed from SDCC packages.
+- In 3.2.0 special SDCC keywords which are not preceded by a double underscore are obsoleted (removed). See section Standard-Compliance Standard-Compliance.
+- In 3.2.0 compiler macro definitions not starting with double underscore characters are deprecated if `--std-cXX` command line option is defined. They have been obsoleted (removed) after the 3.4.0 release (except for the macro SDCC, which has been removed after the 3.6.0 release (and brought back for mcs51 for the 3.7.0 release)).
+- In 3.2.0 new compiler macros for processor definition were introduced for pic14 and pic16 targets:`-D__SDCC_PIC16XXXX` and `-D__SDCC_PIC18FXXX` respectively. The pic16 macro definition `-D__18fXXX` is deprecated. It was obsoleted (removed) after the 3.4.0 release.
+- In 3.2.0 pragma config for pic16 target was introduced. See section Pragmas
+- In 3.2.0 new inline assembler format `__asm__ (" inline_assembler_code");` as an addition to `__asm... __endasem;` format introduced. See section Inline Assembler Code
+- sdobjcopy utility was introduced in version 3.3.0. It is derived from GNU Binutils package.
+- Before 3.4.0 release, intrinsic named address spaces were called" storage classes" in this manual.
+- In 3.6.0, the default for char changed from signed to unsigned.
+- In 3.7.0, the prototype for putchar() changed from `void putchar(char)` to `int putchar(int)`.
+- In 3.7.0 mcs51 and ds390 got a full _Bool/bool type, separate from __bit.
+- In 3.7.0, the option **`--nojtbound`** and the corresponding pragma have been deprecated.
+- In 3.7.0, the prototype for `getchar()`changed from `char getchar(void)` to `int getchar(void)`.
+- In 3.8.6, the deprecated sdcclib was removed.
+- In 4.0.3, _itoa, _uitoa, _ltoa, _ultoa were renamed to __itoa, __uitoa, __ltoa, __ultoa.
+- In 4.1.1, typeof.h has been removed.
+- In 4.1.3, support for **`--oldralloc`** has been removed for the z80-related backends.
+- In 4.1.10, the default calling convention switched from `__sdccall(0)` to `__sdccall(1)` for stm8 and gbz80.
+- In 4.1.10, support for **`--profile`** has been removed for gbz80.
+- In 4.1.11, the minimum Z80N Core version for the z80n port has been raised from 1.0 to 2.0.
+- In 4.1.12, the default calling convention switched from `__sdccall(0)` to `__sdccall(1)` for z80, z180 and z80n.
+- In 4.1.12, support for **`--profile`** has been removed for z80, z180, z80n.
+- In 4.1.13, support for **`--profile`** has been removed.
+- In 4.1.14, the gbz80 port was renamed to sm83.
+- In 4.2.3, support for non-parenthesized arguments to `__using` and `__interrupt` was dropped.
+- In 4.2.3, support for non-parenthesized arguments to __at that are not constants was dropped.
+- In 4.2.4, the placement of `__at` in declarations was restricted.
+- In 4.2.6, bool is chosen as the underlying integer type for enumerations with just two values.
+- In 4.2.9, support for **`--pedantic-parse-number`** and #pragma pedantic_parse_numer was dropped.
+- In 4.2.9, support for #pragma sdcc_hash was dropped, necessitating a wrapper macro for literal" #" characters in macro bodies.
+- In 4.2.9, support for arguments to -MMD was dropped. The output file can be specified via -MF instead.
+- In 4.2.10, `_sdcc_external_startup` was renamed to `__sdcc_external_startup` and support for it was added to further ports.
+- In 4.2.13, for the sm83 port, `__sfr` addresses need to be specified using the full 16-bit address.
+- In 4.2.14, byte order in output from the %p specifier of printf()-family functions was corrected for big-endian platforms (stm8, hc08, s08, mos6502) to match uintptr_t.
+- In 4.3.1, `__builtin_rlc`, `__builtin_rrc` and `__builtin_swap` were replaced by `__builtin_rot`.
+- In 4.3.6, support for **`--parms-in-bank1`** was removed from the mcs51 port.
+- In 4.4.1, the address width in.rel files was increased from 24 bits to 32 bits for the z80 (and related) ports.
+- In 4.5.2, the C23 standard library bit and byte utilities (stdbit.h) more closely follow the final ISO C23 standard instead of the 2022 C2X draft.
+
+### System Requirements
+
+What do you need before you start installation of SDCC? A computer, and a desire to compute. The preferred method of installation is to compile SDCC from source using GNU GCC and make. For Windows some pre-compiled binary distributions are available for your convenience. You should have some experience with command line tools and compiler use.
+
+### Other Resources
+
+The SDCC home page at http://sdcc.sourceforge.net/ is a great place to find distribution sets. You can also find links to the user mailing lists that offer help or discuss SDCC with other SDCC users. Web links to other SDCC related sites can also be found here. This document can be found in the doc directory of the source package. The latest snapshot build version of this document in pdf format is available at http://sdcc.sourceforge.net/doc/sdccman.pdf. Some of the other tools (simulator and assembler) included with SDCC contain their own documentation and can be found in the source distribution. If you want the latest unreleased software, the complete source package is available directly from Subversion on http://sourceforge.net/p/sdcc/code/8805/tree/trunk/sdcc/.