@nataliapc/mcp-openmsx 1.2.10 → 1.2.11

package/resources/book--the-msx-red-book/Introduction.md

@@ -0,0 +1,104 @@
+<a name="contents"></a>
+# Contents
+
+[Introduction](#introduction)
+
+1. [Programmable Peripheral Interface](#chapter_1)
+    + [PPI Port A (I/O Port A8H)](#ppi_port_a)
+    + [Expanders](#expanders)
+    + [PPI Port B (I/O Port A9H)](#ppi_port_b)
+    + [PPI Port C (I/O Port AAH)](#ppi_port_c)
+    + [PPI Mode Port (I/O Port ABH)](#ppi_mode_port)
+2. [Video Display Processor](#chapter_2)
+    + [Data Port (I/O Port 98H)](#data_port)
+    + [Command Port (I/O Port 99H)](#command_port)
+    + [Address Register](#address_register)
+    + [VDP Status Register](#vdp_status_register)
+    + [VDP Mode Registers](#vdp_mode_registers)
+    + [Mode Register 0](#mode_register_0)
+    + [Mode Register 1](#mode_register_1)
+    + [Mode Register 2](#mode_register_2)
+    + [Mode Register 3](#mode_register_3)
+    + [Mode Register 4](#mode_register_4)
+    + [Mode Register 5](#mode_register_5)
+    + [Mode Register 6](#mode_register_6)
+    + [Mode Register 7](#mode_register_7)
+    + [Screen Modes](#screen_modes)
+    + [40x24 Text Mode](#40x24_text_mode)
+    + [32x24 Text Mode](#32x24_text_mode)
+    + [Graphics Mode](#graphics_mode)
+    + [Multicolour Mode](#multicolour_mode)
+    + [Sprites](#sprites)
+3. [Programmable Sound Generator](#chapter_3)
+    + [Address Port (I/O port A0H)](#address_port)
+    + [Data Write Port (I/O port A1H)](#data_write_port)
+    + [Data Read Port (I/O port A2H)](#data_read_port)
+    + [Registers 0 and 1](#registers_0_and_1)
+    + [Registers 2 and 3](#registers_2_and_3)
+    + [Registers 4 and 5](#registers_4_and_5)
+    + [Register 6](#register_6)
+    + [Register 7](#register_7)
+    + [Register 8](#register_8)
+    + [Register 9](#register_9)
+    + [Register 10](#register_10)
+    + [Registers 11 and 12](#registers_11_and_12)
+    + [Register 13](#register_13)
+    + [Register 14](#register_14)
+    + [Register 15](#register_15)
+4. [ROM BIOS](#chapter_4)
+    + [Data Areas](#data_areas)
+    + [Terminology](#terminology)
+5. [ROM BASIC Interpreter](#chapter_5)
+6. [Memory Map](#chapter_6)
+    + [Workspace Area](#workspace_area)
+    + [The Hooks](#the_hooks)
+7. [Machine Code Programs](#chapter_7)
+    + [Keyboard Matrix](#keyboard_matrix)
+    + [40 Column Graphics Text](#40_column_graphics_text)
+    + [String Bubble Sort](#string_bubble_sort)
+    + [Graphics Screen Dump](#graphics_screen_dump)
+    + [Character Editor](#character_editor)
+
+Contents Copyright 1985 Avalon Software<br>
+Iver Lane, Cowley, Middx, UB8 2JD
+
+MSX is a trademark of Microsoft Corp.<br>
+Z80 is a trademark of Zilog Corp.<br>
+ACADEMY is trademark of Alfred.
+
+<br><br><br>
+
+<a name="introduction"></a>
+# Introduction
+
+## <a name="aims"></a>Aims
+
+This book is about MSX computers and how they work. For technical and commercial reasons MSX computer manufacturers only make a limited amount of information available to the end user about the design of their machines. Usually this will be a fairly detailed description of Microsoft MSX BASIC together with a broad outline of the system hardware. While this level of documentation is adequate for the casual user it will inevitably prove limiting to anyone engaged in more sophisticated programming.
+
+The aim of this book is to provide a description of the standard MSX hardware and software at a level of detail sufficient to satisfy that most demanding of users, the machine code programmer. It is not an introductory course on programming and is necessarily of a rather technical nature. It is assumed that you already possess, or intend to acquire by other means, an understanding of the Z80 Microprocessor at the machine code level. As there are so many general purpose books already in existence about the Z80 any description of its characteristics would simply duplicate widely available information.
+
+<a name="organization"></a>
+## Organization
+
+The MSX Standard specifies the following as the major functional components in any MSX computer:
+
+1. Zilog Z80 Microprocessor
+2. Intel 8255 Programmable Peripheral Interface
+3. Texas 9929 Video Display Processor
+4. General Instrument 8910 Programmable Sound Generator
+5. 32 KB MSX BASIC ROM
+6. 8 KB RAM minimum
+
+Although there are obviously a great many additional components involved in the design of an MSX computer they are all small-scale, non-programmable ones and therefore "invisible" to the user. Manufacturers generally have considerable freedom in the selection of these small-scale components. The programmable components cannot be varied and therefore all MSX machines are identical as far as the programmer is concerned.
+
+[Chapters 1](#chapter_1), [2](#chapter_2) and [3](#chapter_3) describe the operation of the Programmable Peripheral Interface, Video Display Processor and Programmable Sound Generator respectively. These three devices provide the interface between the Z80 and the peripheral hardware on a standard MSX machine. All occupy positions on the Z80 I/O (Input/Output) Bus.
+
+[Chapter 4](#chapter_4) covers the software contained in the first part of the MSX ROM. This section of the ROM is concerned with controlling the machine hardware at the fine detail level and is known as the ROM BIOS (Basic Input Output System). It is structured in such a way that most of the functions a machine code programmer requires, such as keyboard and video drivers, are readily available.
+
+[Chapter 5](#chapter_5) describes the software contained in the remainder of the ROM, the Microsoft MSX BASIC Interpreter. Although this is largely a text-driven program, and consequently of less use to the programmer, a close examination reveals many points not documented by manufacturers.
+
+[Chapter 6](#chapter_6) is concerned with the organization of system memory. Particular attention is paid to the Workspace Area, that section of RAM from F380H to FFFFH, as this is used as a scratchpad by the BIOS and the BASIC Interpreter and contains much information of use to any application program.
+
+[Chapter 7](#chapter_7) gives some examples of machine code programs that make use of ROM features to minimize design effort.
+
+It is believed that this book contains zero defects, if you know otherwise the author would be delighted to hear from you. This book is dedicated to the Walking Nightmare.

package/resources/book--the-msx-red-book/toc.json

@@ -4,9 +4,44 @@
     "external_url": "https://github.com/gseidler/The-MSX-Red-Book",
     "toc": [
         {
-            "title": "The MSX Red Book (full book)",
-            "uri": "msxdocs://book--the-msx-red-book/the_msx_red_book",
-            "description": "The MSX Red Book provides a detailed technical overview of MSX computers, focusing on hardware and software components. It is designed for advanced users, particularly machine code programmers, offering insights into the MSX standard and its programmable components."
+            "title": "Introduction",
+            "uri": "msxdocs://book--the-msx-red-book/Introduction",
+            "description": "The aim of this book is to provide a description of the standard MSX hardware and software at a level of detail sufficient to satisfy that most demanding of users, the machine code programmer."
+        },
+        {
+            "title": "Chapter1. Programmable Peripheral Interface",
+            "uri": "msxdocs://book--the-msx-red-book/Chapter1_Programmable_Peripheral_Interface",
+            "description": "Chapter1, Chapter2 and Chapter3 describe the operation of the Programmable Peripheral Interface, Video Display Processor and Programmable Sound Generator respectively. These three devices provide the interface between the Z80 and the peripheral hardware on a standard MSX machine. All occupy positions on the Z80 I/O (Input/Output) Bus."
+        },
+        {
+            "title": "Chapter2. Video Display Processor",
+            "uri": "msxdocs://book--the-msx-red-book/Chapter2_Video_Display_Processor",
+            "description": "Chapter1, Chapter2 and Chapter3 describe the operation of the Programmable Peripheral Interface, Video Display Processor and Programmable Sound Generator respectively. These three devices provide the interface between the Z80 and the peripheral hardware on a standard MSX machine. All occupy positions on the Z80 I/O (Input/Output) Bus."
+        },
+        {
+            "title": "Chapter3. Programmable Sound Generator",
+            "uri": "msxdocs://book--the-msx-red-book/Chapter3_Programmable_Sound_Generator",
+            "description": "Chapter1, Chapter2 and Chapter3 describe the operation of the Programmable Peripheral Interface, Video Display Processor and Programmable Sound Generator respectively. These three devices provide the interface between the Z80 and the peripheral hardware on a standard MSX machine. All occupy positions on the Z80 I/O (Input/Output) Bus."
+        },
+        {
+            "title": "Chapter4. ROM BIOS",
+            "uri": "msxdocs://book--the-msx-red-book/Chapter4_ROM_BIOS",
+            "description": "Chapter4 covers the software contained in the first part of the MSX ROM. This section of the ROM is concerned with controlling the machine hardware at the fine detail level and is known as the ROM BIOS (Basic Input Output System). It is structured in such a way that most of the functions a machine code programmer requires, such as keyboard and video drivers, are readily available."
+        },
+        {
+            "title": "Chapter5. ROM BASIC Interpreter",
+            "uri": "msxdocs://book--the-msx-red-book/Chapter5_ROM_BASIC_Interpreter",
+            "description": "Chapter5 describes the software contained in the remainder of the ROM, the Microsoft MSX BASIC Interpreter. Although this is largely a text-driven program, and consequently of less use to the programmer, a close examination reveals many points not documented by manufacturers."
+        },
+        {
+            "title": "Chapter6. Memory Map",
+            "uri": "msxdocs://book--the-msx-red-book/Chapter6_Memory_Map",
+            "description": "Chapter6 is concerned with the organization of system memory. Particular attention is paid to the Workspace Area, that section of RAM from F380H to FFFFH, as this is used as a scratchpad by the BIOS and the BASIC Interpreter and contains much information of use to any application program."
+        },
+        {
+            "title": "Chapter7. Machine Code Programs",
+            "uri": "msxdocs://book--the-msx-red-book/Chapter7_Machine_Code_Programs",
+            "description": "Chapter7 gives some examples of machine code programs that make use of ROM features to minimize design effort."
         }
     ]
 }

package/resources/processors/toc.json

@@ -15,10 +15,10 @@
             "description": "This comprehensive instruction set reference provides a complete tabular listing of all Z80 processor instructions plus R800-specific extensions (MULUB/MULUW multiplication instructions), including documented and undocumented opcodes with precise timing data for MSX systems. It details instruction timing across four scenarios (Z80, Z80+M1 waits, R800, R800+waits), hexadecimal opcodes, instruction sizes, and MSX-specific timing considerations including M1 wait states, memory access patterns, I/O timing, and R800 internal/external memory performance characteristics. Essential for MSX assembly programming, emulator development, performance optimization, cycle-accurate timing calculations, and understanding the behavioral differences between Z80 and R800 processors in MSX environments."
         },
         {
-            "title": "The Undocumented Z80 Documented",
+            "title": "Z80 Undocumented Opcodes",
             "uri": "msxdocs://processors/z80-undocumented",
-            "external_url": "http://bifi.msxnet.org/msxnet/tech/",
-            "description": "Provides a comprehensive technical reference for Z80 microprocessor instructions, focusing on both officially documented and undocumented instruction sets. It serves as an authoritative guide for Z80 assembly programming, particularly relevant for MSX computer development."
+            "external_url": "https://www.cpcwiki.eu/index.php/Z80_-_undocumented_opcodes",
+            "description": "Reference for Z80 undocumented opcodes, covering the SLL (CB prefix) shift instruction, access to the hidden 8-bit index sub-registers IXH, IXL, IYH, IYL via DD/FD prefixes, and duplicate/unofficial ED-prefix instructions. Useful for advanced Z80 assembly programming where extra registers or non-standard shifts provide performance benefits."
         }
     ]
 }

package/resources/processors/z80-undocumented.md

@@ -0,0 +1,141 @@
+# Z80 - undocumented opcodes
+
+The Z80 CPU contains several undocumented opcodes, which can be quite helpful sometimes. The most useful undocumented opcodes are probably these ones, which split up the 16bit index registers IX and IY in 8bit registers called IXL,IXH,IYL and IYH. 
+
+Please note, that many Z80 successors like the Z180 are NOT able to execute some of the following opcodes properly. 
+
+This is just an overview. Parts of this article have been copied from the ["The Undocumented Z80 Documented"](http://www.myquest.nl/z80undocumented/) originally by Sean Young and currently maintained by Jan Wilmans, which is one of the most comprehensive descriptions around. 
+
+## CB prefix
+
+Of the 247 opcodes that use the prefix &CB, the block &CB &30 to &CB &37 is undocumented officially. These commands shift the operand register left and set its lowest bit to 1.
+
+This is in contrast to `SRL` (Shift Right Logical), which shifts right and clears the highest bit. Some believe these opcodes were supposed to be Shift Left Logical but that the setting of the lowest bit represents a bug in the Z80, claiming this is why the opcodes are undocumented. Others call the opcodes `SLIA`, for Shift Left Inverted Arithmetic.
+
+Regardless of the story behind this operation, its effective result is `register = (register * 2) + 1`, something that does have its uses and has been employed in various programming contexts for that reason.
+
+```
+CB30 SLL B
+CB31 SLL C
+CB32 SLL D
+CB33 SLL E
+CB34 SLL H
+CB35 SLL L
+CB36 SLL (HL)
+CB37 SLL A
+```
+
+## DD and FD prefixes
+
+The &DD or &FD prefixes are documented as causing operations using the 16-bit register HL to instead work with either of the 16-bit indexing registers IX or IY; if the operations access a memory location (i.e. normally `LD A,(HL)`, etc.), the opcodes must additionally include an extra byte that specifies a signed displacement (-128 to +127) from IX/IY.
+
+However, Zilog have not documented the fact that these prefixes also affect opcodes that usually refer to the 8-bit components of HL, i.e. H and L. Thus, one gains access to the additional registers IXH, IXL, IYH, and IYL, for almost all commands that normally use H or L. It is even possible to do things like `LD IXH,IXL` (although you cannot combine IX and IY in the same instruction, for obvious reasons). These registers can be useful in routines that must process and/or store a lot of numbers. Thankfully, they are not as slow as their 16-bit counterparts: whereas access to (IX+d) is usually slower by 3 NOPs than the equivalent operation upon (HL), using the 8-bit components is (like `PUSH IX`, etc.) only 1 `NOP` slower, and this is only due to the need to parse the prefixing byte.
+
+```
+DB #DD:LD H,A --> LD IXH,A
+DB #FD:LD B,L --> LD B,IYL
+```
+
+> **Note:** These registers are called LX, LY, HX, and HY by WinAPE's debugger, although its assembler uses the names given above.
+
+## ED prefix
+
+There are a number of undocumented EDxx instructions, of which most are duplicates of documented instructions. Any instruction not listed has no effect (same behaviour as 2 `NOP` instructions). 
+
+The complete list except for the block instructions:
+
+```
+ED40 IN B,(C)       ED60 IN H,(C)
+ED41 OUT (C),B      ED61 OUT (C),H
+ED42 SBC HL,BC      ED62 SBC HL,HL
+ED43 LD (nn),BC     ED63 LD (nn),HL
+ED44 NEG            ED64 NEG *
+ED45 RETN           ED65 RETN *
+ED46 IM 0           ED66 IM 0 *
+ED47 LD I,A         ED67 RRD
+ED48 IN C,(C)       ED68 IN L,(C)
+ED49 OUT (C),C      ED69 OUT (C),L
+ED4A ADC HL,BC      ED6A ADC HL,HL
+ED4B LD BC,(nn)     ED6B LD HL,(nn)
+ED4C NEG *          ED6C NEG *
+ED4D RETI           ED6D RETN *
+ED4E IM 0 *         ED6E IM 0 *
+ED4F LD R,A         ED6F RLD
+ED50 IN D,(C)       ED70 IN (C) / IN F,(C) *
+ED51 OUT (C),D      ED71 OUT (C),0 *
+ED52 SBC HL,DE      ED72 SBC HL,SP
+ED53 LD (nn),DE     ED73 LD (nn),SP
+ED54 NEG *          ED74 NEG *
+ED55 RETN *         ED75 RETN *
+ED56 IM 1           ED76 IM 1 *
+ED57 LD A,I         ED77 NOP *
+ED58 IN E,(C)       ED78 IN A,(C)
+ED59 OUT (C),E      ED79 OUT (C),A
+ED5A ADC HL,DE      ED7A ADC HL,SP
+ED5B LD DE,(nn)     ED7B LD SP,(nn)
+ED5C NEG *          ED7C NEG *
+ED5D RETN *         ED7D RETN *
+ED5E IM 2           ED7E IM 2 *
+ED5F LD A,R         ED7F NOP *
+* = undocumented opcodes
+```
+
+## DDCB prefix
+
+The undocumented DDCB instructions store the result (if any) of the operation in one of the seven all-purpose registers, which one depends on the lower 3 bits of the last byte of the opcode (not operand, so not the offset). 
+```
+000 B
+001 C
+010 D
+011 E
+100 H
+101 L
+110 (none: documented opcode)
+111 A
+```
+The documented DDCB0106 is `RLC (IX+01h)`. So, clear the lower three bits (DDCB0100) and something is done to register B. The result of the `RLC` (which is stored in (IX+01h)) is now also stored in register B. Effectively, it does the following:
+```
+LD B,(IX+01h)
+RLC B
+LD (IX+01h),B
+```
+So you get double value for money. The result is stored in B and (IX+01h). The most common notation is: `RLC (IX+01h),B`
+
+I’ve once seen this notation: 
+```
+RLC (IX+01h)
+LD B,(IX+01h)
+```
+That’s not correct: B contains the rotated value, even if (IX+01h) points to ROM. The DDCB `SET` and `RES` instructions do the same thing as the shift/rotate instructions:
+```
+DDCB10C0    SET 0,(IX+10h),B
+DDCB10C1    SET 0,(IX+10h),C
+DDCB10C2    SET 0,(IX+10h),D
+DDCB10C3    SET 0,(IX+10h),E
+DDCB10C4    SET 0,(IX+10h),H
+DDCB10C5    SET 0,(IX+10h),L
+DDCB10C6    SET 0,(IX+10h) - documented instruction
+DDCB10C7    SET 0,(IX+10h),A
+```
+So for example with the last instruction, the value of (IX+10h) with bit 0 set is also stored in register A. 
+
+The DDCB `BIT` instructions do not store any value; they merely test a bit. That’s why the undocumented DDCB `BIT` instructions are no different from the official ones:
+```
+DDCB d 78   BIT 7,(IX+d)
+DDCB d 79   BIT 7,(IX+d)
+DDCB d 7A   BIT 7,(IX+d)
+DDCB d 7B   BIT 7,(IX+d)
+DDCB d 7C   BIT 7,(IX+d)
+DDCB d 7D   BIT 7,(IX+d)
+DDCB d 7E   BIT 7,(IX+d) - documented instruction
+DDCB d 7F   BIT 7,(IX+d)
+```
+
+## FDCB prefix
+
+Same as for the DDCB prefix, though IY is used instead of IX. 
+
+## Web links
+
+* ["The Undocumented Z80 Documented" by Sean Young Version 0.91, 18th September, 2005](http://www.myquest.nl/z80undocumented/z80-documented-v0.91.pdf) at [Jan Wilmans' Website](http://www.myquest.nl/z80undocumented/)
+* [Short information about the internal "MEMPTR" 16bit register of the Z80 and its influence on the F-Register)](http://www.grimware.org/lib/exe/fetch.php/documentations/devices/z80/z80.memptr.eng.txt)

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/.