@nataliapc/mcp-openmsx 1.2.10 → 1.2.12

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)