@nataliapc/mcp-openmsx 1.1.15 → 1.2.3

package/resources/msx-dos/MSX-DOS_File_extensions.md

@@ -0,0 +1,154 @@
+# Filename extensions used on MSX
+
+|Extension|Description|Environment|
+|:-:|:--|:--|
+|ACC|Creator accompaniment data files||
+|AGL|Sony Auto Graphic Loader files - see Sony HBI-V1 Video Digitizer cartridge||
+|ARC|File(s) compressed in ARC format by System Enhancement Associates (SEA). Tools to extract are UNARC.COM (v1.6) and UNP.COM (v1.0 by Pierre Gielen).<br>The Unarchiver can be used to extract from this file. There are macOS and Windows/Linux versions.|MSX-DOS|
+|ARC|File(s) compressed in Russian ARC format, incompatible with SEA's ARC format. Tools to extract are XARC.COM (v1.01) and ARCDE.COM (v1.03).|MSX-DOS|
+|ARJ|File(s) compressed in ARJ format. Tool to extract are UNARC.COM (v1.10) and UNP.COM (v1.0 by Pierre Gielen).|MSX-DOS|
+|APT|Studio FM pattern data file||
+|ASC|Plain text (ASCII format) that can contain a BASIC program or data.|BASIC / Text editor|
+|ASN|Assignment files for MIDI Blaster||
+|BAS|BASIC program listing tokenized. These files can be executed from MSX-DOS with the BASIC name.bas command.|BASIC|
+|BAT|Batch files (plain text) interpreted by MSX-DOS.|MSX-DOS|
+|BGM|MuSICA binary music file. MuSICA is a software developed by ASCII to create music on 17 voices with PSG, FM and Konami's SCC.<br>We can use also the BGM player by (YMD)A or KINROU5 (by Masarun), an alternative driver to play the BGMs.|MuSICA driver, MSX-MUSIC, SCC, PSG|
+|BGM|MSX-FAN music file. Not to be confused with MuSICA files. Songs in this format were contained in all their disk magazines, and later a specific player was released that even supported playback on MIDI.|MSPLAY(OPLL) / MSP(MIDI interface), MSX-DOS2|
+|BGM|Bloadable MSX-MUSIC file created by the BIT2BGM.COM utility of Uwe Schröder that converts Synth Saurus musical files.|BGM.BIN driver, BASIC|
+|BIN|Binary file created with the BASIC BSAVE instruction. Loads with BLOAD. The header have a length of 7 bytes (FEh + Start address + End address + execution address). It can contain machine language and data.<br>Many of these files can be executed from MSX-DOS with BINLOAD.COM (by MSX-Park) or BINLDR.COM (by gdx).|BASIC|
+|BMP|Image file format native to Microsoft Windows. Best viewed with Deca BMP v1.25, aka DBMP.COM|MSX-DOS|
+|BOK|MSX-View Picture book.|MSX View|
+|BTM|Batch files supported by MSX-DOS 2 v.2.40 or later.|MSX-DOS 2|
+|CAS|BIOS level cassette image for emulators, needs a separate tool to run or write to cassette. SofaCas allows to convert software on tape to CAS file and also play it using a homemade cable PC sound output to MSX cassette input. On MSX turbo R, we can use TRCAS (by Martos) to run CAS played by SofaCas.|MSX emulator / SofaCas|
+|CH1|File created by Sony Character Editor||
+|CMP|Compressed screen 5 image, including palette, created with DD-Graph.|Dot Designer's Graph (aka DD-Graph)|
+|CMP|Compressed image, including palette, created with GIOS.|GIOS, aka Graphical Input/Output System|
+|COM|Command containing a binary executable under MSX-DOS, CP/M or SymbOS<br>Can be also an executable file compressed with POPCOM.COM (v1.0 by Perpermint-Star).|MSX-DOS, CP/M, SymbOS|
+|CPM|.COM file renamed to .CPM, either to be used in some CPM emulators, or to be able to workaround GMail's nanny protection against executable files. Just rename those back to .COM to be able to run them.|MSX-DOS, CP/M|
+|DAT|File with data for Sony Animation Editor||
+|DAT|Synthesizer configuration file for MIDI Blaster||
+|DRM|File for the drums editor of the First Rate Music Hall tracker.||
+|DSK|Disk image for emulators, needs a separate tool to run or write to normal disk.<br>Can be launched on real MSX with SofaRunit or using Nextor's EMUFILE command.|MSX-DOS, Nextor|
+|DUA|Music-BOX dual data file (melody + sample)||
+|EDI|File for the song editor of the First Rate Music Hall tracker.||
+|EMx|Disk image for the floppy disk emulator (HDDEMU.COM) for MSX turbo R by Tsuyoshi. Internal structure is same as in DSK-files. Protected disks have additional information stored to files with HED-extension.|MSX-DOS|
+|EVA|Video file in EVA format.|Video player|
+|EVG|Yamaha SFG-05 event data file||
+|EXE|Executable in SymbOS|SymbOS|
+|FM|MSX-MUSIC BASIC file.|BASIC|
+|FMP|MSX-MUSIC BASIC file.|BASIC|
+|FMS|Synth Saurus sound file|Synth Saurus|
+|FNT|Font file for the Scroll Power utility.||
+|G9B|Library graphic format for GFX-9000.||
+|GEx|x=5, 7 or 8. Synonym for .SCx, so check its description.|Image player|
+|GEN|Plain text that contain Z80 assembly source code, used with GEN80 compiler|MSX-DOS|
+|GIF|Graphics Interchange Format. They can be viewed with GIFI.COM (by Kakami Hiroyuki) and converted in MSX format with ENGIF.COM (v1.2 by Pierre Gielen) - See also SHOWEM.COM (by Steven van Loef) and GIFDUMP.COM (by Francesco Duranti)|MSX-DOS|
+|GLx|Graph Saurus shape image file. Synonym to SHx, so check its description.|Graph Saurus, BASIC|
+|GR5|Graphic file for Sony Animation Editor||
+|GRA|Image file in QLD format. The viewer BLS.COM (v3.0a by SEIGA & FRS) supports it. Requires a complementary .RGB file that contains the palette.|MSX-DOS|
+|GRP|Synonym for .SC2. See the .SCx file description.<br>Can also be a compressed image for Graph Saurus.|BASIC / Graph Saurus|
+|GZ|File compressed in GZIP format by PC gzipers. Tool to extract is GUNZIP.COM.|MSX-DOS|
+|HLP|MSX-DOS 2 help file (plain text)|MSX-DOS 2|
+|INS|File for the instruments editor of the First Rate Music Hall tracker.||
+|IPS|Patch for file. Needs IPS patcher.|MSX-DOS|
+|ISH|Binary-to-text converted file encoded and decodable by Ish available from MSX・FAN disk #1.	|MSX-DOS|
+|JPG|Compressed image file in format JPEG. Some viewers can show image up to 1024x1024: JPD.COM (v0.23 by APi), JLD.COM (v1.11 by SEIGA). JPEG file can be produced on MSX from SCREEN 12 images with JSV.COM (v0.1 by SEIGA).|MSX-DOS 2|
+|KSS|MSX music file that contains also player code. Use KSSPLAY.COM (by NYYRIKKI) to play it.|MSX-DOS|
+|LDR|Tokenized Basic file usually BASIC program LoaDeR used to load and run a program consisting of several BAS files.|BASIC|
+|LHA|File(s) compressed in LHA format. Tools to create a LHA archive are LHPACK.COM (v1.03 by H.Saito) or LHA.COM (v1.05a by Kyouju). Tools to extract are PMM.COM (v1.20 by Iita), LHARC.COM and LHEXT.COM (v1.33 by Kyouju).<br>The Unarchiver can be used to extract from this file. There are macOS and Windows/Linux versions.|MSX-DOS|
+|LPF|Loop file for the Scroll Power utility.||
+|LZH|Synonym for LHA.|MSX-DOS|
+|MAG|Maki-chan V2 image file also extensively used on PC-9801 and Sharp X68000. Best viewed with Deca MAG v1.25, aka DMAG.COM. The v1.25a patched to support the MSX2 can be downloaded here.|MSX-DOS|
+|MAX|Synonym for MAG.|MSX-DOS|
+|MBK|Samplekit file for the music tracker MoonBlaster.||
+|MBM|Music file for the music tracker MoonBlaster.||
+|MBS|Sample file for the music tracker MoonBlaster.||
+|MBV|Voice file for the music tracker MoonBlaster.||
+|MBW|Wave song for the music tracker MoonBlaster.|MoonSound|
+|MCM|Micro Cabin music file. Played by MCDRV.EXE|MSX-DOS|
+|MDT|MSX Music-System music data file||
+|MDX|Music file in a format designed for Sharp X68000. These files can be played by MPX2.COM (when driver installed with MXDRV.COM). Optional PDX files are PCM samples. Require the YAMAHA SFG-01/05 cartridge or the MFP PCM cartridge.|MSX-DOS 2, MDX Driver, 256kB~ of RAM|
+|MEG|Plain text that contain Z80 assembly MegaAssembler source code. Extension also used for Mega-Rom images.|MSX-DOS|
+|MEL|Music-BOX melody data file||
+|MFM|FM song for MoonBlaster.|MoonSound|
+|MGS|Music file in format developed by AIN. Played by MGSEL.COM (when driver installed with MGSDRV.COM).|MSX-DOS 2, MGS driver, YM-2413/OPLL, SCC|
+|MID|Standard MIDI file (can be played using MIDI-interface or MoonSound software)|Various|
+|MIF|Compressed image file.|Various|
+|MIO|MIODRV Music file. Played by MIODRV Player.||
+|MKI|Maki-chan V1 image file maintly used on Sharp X68000. Viewable with BLS.COM (v3.0a by SEIGA & FRS)|MSX-DOS|
+|MOD|Amiga MOD file (can be played on MSX turbo R or MoonSound)|MSX-DOS|
+|MP3|MPEG Audio Layer III file. MP3s can be played with Sunrise MP3 player, MPX Cartridge r1.1 by Junsoft or SE-ONE by TMT logic.||
+|MPK|Music Player K-kaz song. Require WAMPK Player|MSX-DOS|
+|MSx|Synth Saurus score file|Synth Saurus|
+|MSD|MuSICA source music file (MML). We can also use KINROU4 (by Masarun), an alternative compiler.|MSX-DOS|
+|MSQ|File created by Sony Realtime Keyboard Recorder||
+|MUE|HAL Music Editor MUE music file. There's a patch to add mouse support here.|Cartridge|
+|MUS|FAC Soundtracker music file||
+|MUS|MGSDRV source MML file. Needs to be compiled to a MGS file with MGSC.COM. OTOH, MGSCR.COM can decompile MGS files back to the MUS source.|MSX-DOS2|
+|MUS|Studio FM music file (not recommended)||
+|MWK|MoonSound Wave sample kit||
+|MWM|MoonBlaster for MoonSound Wave song||
+|OPX|OPLL driver music format||
+|OTO|File created by Sony Musical PSG Keyboard||
+|PAC|Dump of SRAM contents (save games) of PAC or FM-PAC cartridge.||
+|PAT|Studio FM pattern file||
+|PCM|Sound sample file for MSX turbo R.||
+|PCK|Packaged file for First Rate Music Hall tracker. Includes 4 songs with all instruments and drums data.||
+|PCT|Dynamic Publisher page files.|Dynamic Publisher|
+|PDT|File created by Sony Raku Raku Animation Editor||
+|PDX|Optional PCM sample file used with an MDX file. You can play a PDX with PDXLOAD.COM by AIN. See also MDX extension.|MSX-DOS 2, MDX Driver, 256kB~ of RAM|
+|PI|Yanagisawa's PI. A Japanese 16 color image format used on PC-98 and X68000. Viewable on the MSX with PI.COM v0.07|MSX-DOS2|
+|PIC|SCREEN8 binary image. Synonym for .SC8, so check the .SCx description.|Philips Video Graph, Matsushita Video Graphics|
+|PIC|Yanagisawa's PIC: A Japanese multi-platform image format with support for 16, 256 colors, 32768 or 65536 colors. Used on X68000, PC-98VA, FM-Towns, macOS classic and MSX2. Viewable on the MSX with BLS.COM (v3.0a by SEIGA & FRS)|MSX-DOS|
+|PLx|Indexed Palette file in Raw format.<br>The Graph Saurus version (contains 8 sets of palettes with two bytes by color in RG 0B format). It's a companion for the respective .SRx or GLx files, so the respective pair must always be copied together.<br>There's also the single palette version, that is a companion file for .SHx images to customize their colors.<br>In both cases, it's never used for SCREEN8 and SCREEN12 images since these modes have no indexed palette support for the background.|Graph Saurus, BASIC|
+|PMA|File(s) compressed in PMARC format. Tools to create an archive are PMARC.COM, PMARC2.COM (v2.0 by Sybex) and UNP.COM (v1.0 by Pierre Gielen). Tools to extract are PMM.COM (v1.20 by Iita), PMEXE.COM (v2.0) and PMEXT.COM (v2.22). PMEXT has been ported on Windows (v1.21 by Yoshihiko Mino).<br>TheUnarchiver can be used to extract from this file. There are macOS and Windows/Linux versions.|CP/M, MSX-DOS|
+|PRO|Music file for Pro-Tracker (by Tyfoon Soft).|BASIC|
+|PSG|PSG Sampler sample file.|PSG soundchip|
+|Q4|XLD4 is an image file for the PC-98. Viewable on the MSX with XLD4.COM by SEIGA.|MSX-DOS2|
+|Q4D|Text file with a description for the respective XLD4 image file. Encoded in Shift-JIS.|MSX-DOS2|
+|RDT|MSX Music-System rhythm data file||
+|RLT|Music Creator real time data files||
+|ROM|Raw ROM image dump. Used by ROM loaders or emulators.|MSX-DOS / MSX emulator|
+|RTM|Synth Saurus rhythm file|Synth Saurus|
+|S1x|Contains the odd lines of an interlace image. For more info, see the SCx file.||
+|S3M|See MOD file.||
+|SAM|Music-BOX sample data file (used as drumkit file in Music Creator)||
+SBM<br>SBK<br>SBP|Music data for SCC and PSG soundchips.|SCC-Blaffer NT, SCC, PSG|
+|SBS|Instruments data for SCC and PSG soundchips.|SCC-Blaffer NT, SCC, PSG|
+|SCx|Standard MSX-BASIC BLOAD image format, where 'x' is the screen mode, ranging from 0 to 8, A, B or C. It can optionally have a companion .S1x file that will contain the extra interlaced lines to double the vertical resolution.<br>It's the most common image format used on the MSX, used by the BASIC and many image editors. It can be viewed with BLS.COM (v3.0a by SEIGA & FRS).|BASIC|
+|SCR|Screen-2 image created with Graphos III. It's an executable file with a loader that produces an effect. Loadable on MSX-BASIC with BLOAD"file",R.|Graphos III, BASIC|
+|SCR|Compressed image (screen 5 to 8) created with Graphics Editor Halos from Halnote, Handy scanner software, Graphic Studio Pro, etc. (HAL Laboratory/Sony)||
+|SDT|MSX Music-System sound data file (= voice data)||
+|SDT|SCMD Music file for MSX made a MML compiler for Windows. The player is SC.COM.|MSX-DOS|
+|SEE|Sound Effect data. (Shareware by Fuzzy Logic)|Sound Effect Editor, PSG soundchip|
+|SEQ|Music Creator sequence data files||
+|SFM|Studio FM music file||
+|SHx|Standard MSX-BASIC COPY image format, where 'x' is the screen mode, ranging from 5 to 8, A, B or C. It can optionally have a companion .PLx file containing one or 8 palettes to customize the colors.<br>It's the 2nd most common image format used on the MSX, used by the BASIC and many image editors. It can be viewed with BLS.COM (v3.0a by SEIGA & FRS).|BASIC|
+|SMx|FAC Soundtracker sample file||
+|SMP|Sample file for Covox/SIMPL or MSX turbo R||
+|SNG|Music file for the music editor SCC-Musixx by Tyfoon Soft.|BASIC, SCC soundchip|
+|SPx|File created by Sony sprite editors||
+|SPT|Music Creator step time data files||
+|SPT|Text file for the Scroll Power utility.||
+|SRx|Graph Saurus Image file. Requires the respective .PLx file. Can be optionally compressed with run-lenght. Uncompressed files can be loaded on MSX-BASIC with a BLOAD"FILE.SRx",S, but the external palette will have to be loaded with OPEN#1. (length: 0~6A00h/0D400h). Both compressed and uncompressed versions can also be viewed with BLS.COM (v3.0a by SEIGA & FRS).|Graph Saurus|
+|STP|Dynamic Publisher stamp files. Contains an image that can be loaded on a page (.STP). Synonym for .GL6, so see the .GLx description.|Dynamic Publisher, BASIC|
+|TIx|Graph Saurus tile file.|Graph Saurus|
+|TSR|Terminate and Stay Resident programs to be used with MemMan 2.0 and higher.|MemMan|
+|TXT|Plain text file generaly coded in ASCII, Ank or Shift-JIS.|Text editor / viewer|
+|VCD|Voice file for the MSX Voice Recorder (HAL Laboratory)||
+|VCD|MuSICA voice file|MuSICA driver|
+|VGM|Music file that supports many sound chips, playable by VGMPLAY.COM (by Laurens Holst)|MSX-DOS|
+|VOC|Music Creator voice data files||
+|VOC|Studio FM voice data file||
+|VOG|Yamaha SFG-05 voice data file||
+|WAV|Sound sample file. Can be played with the MPX Cartridge r1.1 by Junsoft.||
+|WB|Assembler Project file. For the The WBASS2 Z80 Assembler.||
+|XM|See MOD file.||
+|XPC|Rom Patch file for EXECROM.COM (A&L Software). EXECROM patches the Rom on the fly.|MSX-DOS|
+|ZIP|File(s) compressed in ZIP format by PC zipers. The best tool to extract is SUZ.COM (v1.3 by Loutrax).|MSX-DOS|
+|ﾃｷｽ|Japanese transliteration of TXT used in Disc Station.|Text editor / viewer|
+|ﾃﾞﾀ|Japanese transliteration of DAT used in Disc Station.||
+|ﾄﾞｸ|Japanese transliteration of DOC used with text files in Disc Station.|Text editor / viewer|
+|ﾊﾞｽ|Japanese transliteration of BAS used in Disc Station and several other disks. A file with this extension is usually an Easter egg that has to be executed independently.|BASIC|
+|ﾊﾞｯ|Japanese transliteration of BAT used in Disc Station.|MSX-DOS|
+|ﾋﾞﾝ|Japanese transliteration of BIN used in Disc Station.||

package/resources/msx-dos/toc.json

@@ -13,6 +13,19 @@
             "uri": "msxdocs://msx-dos/MSX-DOS_2_Function_Specifications",
             "external_url": "https://map.grauw.nl/resources/dos2_functioncalls.php",
             "description": "This document provides a comprehensive specification of MSX-DOS 2 function calls (version 2.20), detailing over 90 system functions accessible via two calling methods: CALL 00005h for MSX-DOS environment programs and CALL 0F37Dh for disk BASIC programs. The functions are categorized by compatibility level (CPM for CP/M 2.2 compatibility, MSX1 for MSX-DOS version 1 compatibility, and NEW for MSX-DOS 2 exclusive features) and cover essential system operations including file management (FCB and file handle based), directory operations, disk I/O, console I/O, memory management, process control, and device handling. Each function is thoroughly documented with parameters, return values, error conditions, and implementation details, making this an indispensable reference for MSX software development, system programming, and understanding the MSX-DOS operating system interface for both legacy compatibility and modern MSX development workflows."
+        },
+        {
+            "title": "MSX-DOS 2 Environment Variables",
+            "uri": "msxdocs://msx-dos/MSX-DOS_2_Environment_Variables",
+            "external_url": "https://www.msx.org/wiki/MSX-DOS_2_Environment_Variables",
+            "description": "This document provides a detailed overview of the environment variables used in MSX-DOS 2, including their purpose, default values, and how they can be modified. It covers variables such as PATH, which defines the search path for executable files; PROMPT, which sets the command prompt appearance; and others that control system behavior and configuration. The document serves as a reference for developers and users to understand how to customize their MSX-DOS 2 environment for optimal performance and usability."
+        },
+        {
+            "title": "MSX-DOS File extensions",
+            "uri": "msxdocs://msx-dos/MSX-DOS_File_extensions",
+            "external_url": "https://www.msx.org/wiki/File_extensions_used_on_MSX",
+            "description": "This document provides a comprehensive list of file extensions used in the MSX-DOS operating system, detailing their specific purposes and associations. It includes extensions for various types of files such as executable programs (.COM, .BAS), data files (.DAT, .TXT), and system files (.SYS, .CFG). Each extension is explained with its typical usage context."
         }
+
     ]
 }

package/resources/msx-unapi/toc.json

@@ -10,12 +10,12 @@
         },
         {
             "title": "MSX-UNAPI specification 1.1",
-            "uri": "msxdocs://msx-unapi/MSX_UNAPI_specification_1.1",
+            "uri": "msxdocs://msx-unapi/MSX_UNAPI_specification_1_1",
             "description": "The full core specification document, covering all the details on how to design an API, how to implement it, and how to discover and consume it from a client application."
         },
         {
             "title": "Ethernet UNAPI specification",
-            "uri": "msxdocs://msx-unapi/Ethernet_UNAPI_specification_1.1",
+            "uri": "msxdocs://msx-unapi/Ethernet_UNAPI_specification_1_1",
             "description": "The specification of an API for Ethernet cards. This describes an UNAPI compliant API specification for Ethernet hardware for MSX computers."
         },
         {

package/resources/others/keyboard_matrices.md

@@ -0,0 +1,243 @@
+# Keyboard matrices
+
+The key matrix is a matrix of 11x8 bits in which the currently pressed keys on the keyboard are indicated. This document contains an overview of all the available keymatrices, since they can be slightly to very different for different types of MSX computers. Also it discusses several oddities about using the keyboard matrix on MSX, and how to read it.
+
+## The keyboard version value
+
+There is a keyboard version information value at bits 0-3 of address #002C in the BIOS, of which the values can be:
+
+|Value|Keyboard version|
+|:-:|---|
+|0|Japanese|
+|1|International (QWERTY/other)|
+|2|French (AZERTY)|
+|3|English|
+|4|German (DIN)|
+|6|Spanish / Argentinian|
+
+However, this value isn't really useful to determine which key matrix layout you have to use. Daniel Caetano reported having encountered several MSX computers where this was the case:
+
+- The problem resides in the fact the relation line/column -> ASCII is NOT default. It seems to be different on several machines, even if they are from the same country and have similar keyboard. The result is: in some computers, the keys act as expected (when you press the "A" key, the A appears on the screen). But on other computers, when you press the "A" key, something different appears (say, an "8" is shown).
+- Before someone asks me, I know the byte 0x002C of ROM tells me the keyboard type. But this means nothing. On computers with the same value for this byte, the answer of the key matrix was different one from another. )^=
+
+Anyways, I think – and Daniel agreed with me on this – that at least rows 6-10 are pretty much equal on all MSX models (though many have no num pads), since they are used very often in games and people would notice immediately that certain games had their keyboard layout all mixed up. But the other rows are not. Anyways, take care, and if you're not sure you can always just use the BIOS routines for it.
+
+So what is the keyboard version byte useful for then?? It doesn't indicate the matrix layout, but it does indicate the layout as it is presented to the user. So it might be somewhat useful if you need to determine where which keys are located on the keyboard. For example if you want to use the AWSD keys as a secondary set of 'cursor keys' for a 2nd player, it would be interesting to know whether the player used a standard QWERTY keyboard or an AZERTY one (in which case the game should respond to the QZSD keys instead). But, in practice this isn't all there is to the story either. As you can see on the picture of the Russian keyboard below, the key layout isn't at all like QWERTY, but still that particular MSX's BIOS indicates the layout as '1' (international). Grmbl, they should have defined a 5th (Russian JCUKEN) layout! Or at least an 'Other' setting, instead of putting it under International.
+
+## Japanese layouts
+
+Similar to the QWERY vs. AZERTY layouts on roman keyboards, Japanese computers also have two kinds of kana key mappings, where the characters are located at different places. One is called the JIS-layout, the other the ANSI-layout. In JIS, the Japanese kana characters are ordered like our QWERTY keyboards – all mixed up, presumably ordered to make the most freqently used characters easily accessible (or was it to prevent typing errors... well, never mind that). The ANSI layout in the contrary is ordered very logically, like a hypothetical roman ABCDEF keyboard.
+
+I find it easiest to visually distinguish between the two by looking at the location of the very recognizable 'no' (の) character. On a JIS keyboard, it is among the letters, at the K. On an ANSI keyboard, it's on the numbers row, at the 0. Note by the way that some keyboards show katakana characters instead of hiragana (such as the Sanyo Wavy 70FD), so there you need to look for a 'no' written as ノ. Must be very uncomfortable by the way, having two majorly different keyboard layouts. Ahwell.
+
+It seems the most common computers use JIS, the turboR computers for example, but there are also quite a few which use ANSI. Fortunately, you do not have to guess about this. Bit 6 of PSG port A (register 14, read-only) indicates which of the layouts you should use. A 1 means the keyboard is JIS, a 0 means it is ANSI.
+
+|PSG Register|Description|
+|---|---|
+|14|bit 6: Keyboard layout (1=JIS, 0=ANSI)|
+
+## Key Ghosting
+
+There is a limitation in most if not all MSX keyboards, which causes the effect known as 'key ghosting'. This means that sometimes the matrix indicates a key you didn't actually press as being pressed. If you for example try pressing SHIFT+S+X, there is a good chance that it will cause F1 to get 'pressed' aswell. Likewise, C+D+SPACE will also cause HOME to be pressed. The cause for this does not lay in a flaw in the MSX hardware, but rather in the keyboard itself. One could strongly reduce the happening of key ghosting by adding a series of diodes to the keyboard, however for some reason most, if not all, MSX manufacturers decided not to do so. Probably because it would require a fair number of added diodes :).
+
+I'll now try to explain why this effect occurs. Let's start off with presenting you the following part of the (international) keyboard matrix layout, and please note that the highlighted keys are in the same two columns:
+
+||bit 7|bit 6|bit 5|bit 4|bit 3|bit 2|bit 1|bit 0|
+|---|---|---|---|---|---|---|---|---|
+|**row 5**|Z|Y|X|W|V|U|T|S|
+|**row 6**|F3|F2|F1|CODE|CAPS|GRAPH|CTRL|SHIFT|
+
+First off, some explanation about how a common MSX keyboard works. The keyboard has 11 row wires inside, and depending on the value in the row select register it will put power on one of the ten wires. To each of these ten wires, their 8 corresponding keys are connected. Furthermore, there are also 8 column wires in the keyboard, these connect all keys in the same column. Now, if for example row 6 is selected, and SHIFT is pressed, the switch below it will connect row wire 6 with column wire 0, and power will start to flow, which is detected and is put into the row read register as a 0.
+
+So far, all is fine. However part of the problem starts to occur if you press the S key aswell (or any key connected to the same column wire). In that case, power flows from the row 6 wire through the SHIFT key into the column 0 wire, but then it will also flow from the column 0 wire through the S key into the row 5 wire! So far no real problems yet, as setting row 6 will still result in a 11111110 value in the row read register (meaning SHIFT is pressed), and setting row 5 will do so likewise (meaning S is pressed).
+
+Now imagine that you press the X key aswell. Remember that power is also flowing through row wire number 5, even though row 6 is selected, through the SHIFT and the S keys. If the X key is pressed, it connects the row 5 wire with the column 5 wire, resulting in both column wires 0 and 5 having power on them, and the value 11011110 will be put into the row read register. With the row select register set to 6, this will show up as both SHIFT and F1 being pressed, even though F1 is actually not.
+
+Had there been diodes on the column wires between X / F1 and S / SHIFT then this would not have happened, because then power cannot flow from the SHIFT key to the F1 key through the row 5 wire like that. So if you'd add diodes between all keys on the column wires (that'll be 80 of them, to be precise :)), you would have partial protection against this. The most annoying cases of key ghosting (being typing MSX in capitals and typing CD<space>) would not occur anymore. However it is not complete protection, consider the SHIFT+F1+S scenario for example, it would still ghost the X key. This can be prevented by adding diodes between all keys on the row wires aswell (total diode count is now 157), however even then key ghosting can still occur (try SHIFT+F1+X). So complete protection against this can only be achieved by giving each key a separate wire, which means a much more complex board and controller.
+
+The effect can also be countered in software. By not updating the key matrix in the system area when there are ghosted keys in it, the 'flawed' key combination resulting in a key being ghosted will not be passed through to the underlying program. As key ghosting will only occur if 3 or more keys are being pressed, a fairly simple approach would be to skip the key matrix update if that is the case. However, it is not a very user-friendly approach. The current version of Meridian (at the time of writing) does this, and when typing text in capitals the delay between the actual key press and the key being detected is very annoying. A better approach would be to detect a 'critical' key combination, where a 1st key lies in the same row as a 2nd key, and at the same time that 2nd key is in the same column as a 3rd key. Only in that case key ghosting will occur, and then you can skip the matrix update. If the key matrix is read out into the system memory like that, the nasty effects will be gone, and the only effect it will show is that in some cases a key press is detected a little later than usual.
+
+This still won't allow the SHIFT+S+X combination to be pressed (for that you'd really need a hardware solution), however if you type the phrase 'MSX' a bit fast, and haven't released the S key before you press the X key (which happens to me all the time), at least it will properly write down MSX and not add color 15,4,4' because the F1 key is ghosted.
+
+## Reading the key matrix
+
+The key matrix can be read out through the PPI (part of the MSX engine):
+
+|Port range|Description|
+|---|---|
+|#AA|bits 0-3: Row select|
+|#A9 (read)|Row read (inverted)|
+
+```assembler
+    in a,(#AA)
+    and #F0         ; only change bits 0-3
+    or b            ; take row number from B
+    out (#AA),a
+    in a,(#A9)      ; read row into A
+```
+
+However in general it is much easier to just read out the NEWKEY memory area at #FBE5-#FBEF which the BIOS interrupt routine (or your own interrupt routine) updates. Personally I like to refer to NEWKEY with "keys". Please note that the keyboard matrix is inverted – a 0 means the key is pressed, while a 1 means it isn't. Remember that a lot of keyboards haven't got a numpad, so don't use them for vital controls, or create an alternative (like Konami did in the headhunter game in SD Snatcher).
+
+In the following example I will show you how to read out the space key its status. The space key is located in bit 0 of row 8:
+
+```assembler
+keys: EQU #FBE5
+
+;
+; Check whether space is pressed
+;
+Main_ReadKeys:
+    ld a,(keys+8)   ; space
+    bit 0,a
+    jp z,spacepressed
+
+    ...
+
+    ret
+```
+
+The key readout itself is pretty trivial, however as you can see, I have put the key readout routines in a subroutine. It is good practice to do this because then the key handlers will in effect be called as subroutines so they can quite with a RET instead of having to manually JP back to the mainloop afterwards... [Go To Statement Considered Harmful](http://www.acm.org/classics/oct95/), eh ;). Actually the real objection against it in this case is that it introduces redundant code (being the "JP main" at the end of each keyhandler), which is bad; if you change something like for example the spot of the main routine which has to be jumped to, all those keyhandler exit jumps need to be changed and it is easy to forget one.
+
+Finally, a small Basic program which you can use for keyboard matrix testing purposes:
+
+```basic
+10 DEFINT A-Z:K=&HFBE5:CLS
+20 FOR I=0 TO 10:PRINT RIGHT$("0000000"+BIN$(PEEK(K+I)),8):NEXT
+30 PRINT CHR$(11):GOTO 20
+```
+
+## The key matrix layouts
+
+(this list is still incomplete)
+
+Two things: first of all, to display some key matrices you might need some fonts supporting Japanese characters and symbols, if you don't have them already. Such as MS Gothic (in Japanese Language support) or Arial Unicode MS (comes with MS Office). The other thing is that if there are two characters in a cell, the first is the basic character, and the second is with SHIFT pressed.
+
+### International key matrix
+
+||bit 7|bit 6|bit 5|bit 4|bit 3|bit 2|bit 1|bit 0|
+|---|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|
+|row 0|7 &|6 ^|5 %|4 $|3 #|2 @|1 !|0 )|
+|row 1|; :|] }|[ {|\ ¦|= +|- _|9 (|8 *|
+|row 2|B|A|DEAD|/ ?|. >|, <|` ~|' "|
+|row 3|J|I|H|G|F|E|D|C|
+|row 4|R|Q|P|O|N|M|L|K|
+|row 5|Z|Y|X|W|V|U|T|S|
+|row 6|F3|F2|F1|CODE|CAPS|GRAPH|CTRL|SHIFT|
+|row 7|RET|SELECT|BS|STOP|TAB|ESC|F5|F4|
+|row 8|→|↓|↑|←|DEL|INS|HOME|SPACE|
+|row 9|NUM4|NUM3|NUM2|NUM1|NUM0|NUM/|NUM+|NUM*|
+|row 10|NUM.|NUM,|NUM-|NUM9|NUM8|NUM7|NUM6|NUM5|
+
+Note: DEAD is the dead key with the accents \`, ´, ^ and ¨. If you press it nothing will happen, but if you press a vowel next, it will put the selected accent above it (example: àáâä). You can pick one of the accents by pressing the dead key alone or in combination with SHIFT, CODE and CODE+SHIFT.
+
+### Japanese key matrix
+
+||bit 7|bit 6|bit 5|bit 4|bit 3|bit 2|bit 1|bit 0|
+|---|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|
+|row 0|7 '|6 &|5 %|4 $|3 #|2 "|1 !|0|
+|row 1|; +|[ {|@ `|¥ ||^ ~|- =|9 )|8 (|
+|row 2|B|A|  _|/ ?|. >|, <|] }|: *|
+|row 3|J|I|H|G|F|E|D|C|
+|row 4|R|Q|P|O|N|M|L|K|
+|row 5|Z|Y|X|W|V|U|T|S|
+|row 6|F3|F2|F1|かな¹|CAPS|GRAPH|CTRL|SHIFT|
+|row 7|RET|SELECT|BS|STOP|TAB|ESC|F5|F4|
+|row 8|→|↓|↑|←|DEL|INS|HOME|SPACE|
+|row 9|NUM4|NUM3|NUM2|NUM1|NUM0|NUM/|NUM+|NUM*|
+|row 10|NUM.|NUM,|NUM-|NUM9|NUM8|NUM7|NUM6|NUM5|
+|row 11²|||||No||Yes||
+Notes:
+
+¹ かな is Japanese writing for KANA. Unlike CODE, it is a toggle.  
+² Used by Panasonic turboR, FS-A1WX and FS-A1WSX.
+
+As said, Japanese computers have two kinds of kana key layouts, JIS and ANSI. Amongst others the Panasonic FS-A1FX and Sanyo Wavy 70FD have the JIS-layout:
+
+|JIS-layout|bit 7|bit 6|bit 5|bit 4|bit 3|bit 2|bit 1|bit 0|
+|---|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|
+|row 0|や ゃ|お ぉ|え ぇ|う ぅ|あ ぁ|ふ|め|わ を|
+|row 1|れ|゜ ｢|゛|ー|へ|ほ|よ ょ|ゆ ゅ|
+|row 2|こ|ち|ろ|め ･|る ｡|ね ､|む ｣|け|
+|row 3|ま|に|く|き|は|い ぃ|し|そ|
+|row 4|す|た|せ|ら|み|も|り|の|
+|row 5|つ っ|ん|さ|て|ひ|な|か|と|
+
+The ANSI-layout is used by for example Panasonic FS-A1 computers:
+
+|ANSI-layout|bit 7|bit 6|bit 5|bit 4|bit 3|bit 2|bit 1|bit 0|
+|---|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|
+|row 0|に|な|お ぉ|え ぇ|う ぅ|い ぃ|あ ぁ|の|
+|row 1|も|ろ ｢|れ|る|り|ら|ね|ぬ|
+|row 2|と|さ|ん ･|を ｡|わ ､|よ ょ|゜ ｣|゛ ー|
+|row 3|み|ふ|ま|そ|せ|く|す|つ っ|
+|row 4|け|か|ほ|へ|や ゃ|ゆ ゅ|め|む|
+|row 5|た|は|ち|き|て|ひ|こ|し|
+
+These are the mappings for the key combinations with GRAPH:
+
+|GRAPH|bit 7|bit 6|bit 5|bit 4|bit 3|bit 2|bit 1|bit 0|
+|---|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|
+|row 0|土|金|木|水|火|月|日|万|
+|row 1|♣|○||円||─|千|百|
+|row 2|┘||♦|♠|大|小|●|♥|
+|row 3||│|時|┤|┼|┌|├|└|
+|row 4|┬||π|||分|中||
+|row 5||年|╳||┴||┐|秒|
+
+Note: with GRAPH you can enter a couple of common Japanese characters; GRAPH-Y for 'year', GRAPH-S for 'second', and similarly 'hour' and 'minute'. The characters at GRAPH-1 to 7 are the days of the week, and GRAPH-8, 9 and 0 have the characters for 100, 1000 and 10000. GRAPH-\< has the character for 'small', \> has 'big' and GRAPH-L which is physically more or less inbetween \< and \> has the kanji for 'middle'. And finally, GRAPH-¥ is the Yen kanji, and GRAPH-P is Pi.
+
+### Pioneer PX-7 key matrix
+
+The Pioneer MSX with laser-disc player has no num-pad, but does have some extra special-purpose keys. Thanks to Sean Young and Manuel Bilderbeek for the info.
+
+||bit 7|bit 6|bit 5|bit 4|bit 3|bit 2|bit 1|bit 0|
+|---|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|
+|row 9||||||super-impose|video|computer|
+
+### UK key matrix
+
+||bit 7|bit 6|bit 5|bit 4|bit 3|bit 2|bit 1|bit 0|
+|---|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|
+|row 2|B|A|£|/|.|,|`|'|
+
+All other rows and the CODE- and GRAPH- matrices are equal to the International layout.
+
+### Spanish / Argentinian key matrix
+
+As found in the Talent TPC 310. Thanks go to Flyguille!
+
+||bit 7|bit 6|bit 5|bit 4|bit 3|bit 2|bit 1|bit 0|
+|---|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|
+|row 1|ñ Ñ|] }|[ {|\ ¦|= +|- _|9 (|8 *|
+|row 2|B|A|DEAD|/ ?|. >|, <|; :|' "|
+
+All other rows are equal to the International layout.
+
+Note: On the Talent TPC 310 you can also enter characters by holding the CTRL key while entering a character number, similar to the ALT + num pad numbers functionality on Windows PCs.
+
+### Russian key matrix
+
+As found in the Yamaha YIS805R and YIS503R. Thanks go to Stanislav Borutsky!
+
+||bit 7|bit 6|bit 5|bit 4|bit 3|bit 2|bit 1|bit 0|
+|---|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|
+|row 0|& 6|% 5|¤ 4|# 3|" 2|! 1|+ ;|) 9|
+|row 1|V Ж|* :|H Х|- ^ Ъ|= _|$ 0|( 8|' 7|
+|row 2|I И|F Ф|? /|< ,|@ Ю|B Б|> .|\ Э|
+|row 3|O О|[ { Ш|R Р|P П|A А|U У|W В|S С|
+|row 4|K К|J Й|Z З|] } Щ|T Т|X Ь|D Д|L Л|
+|row 5|Q Я|N Н|| ~ Ч|C Ц|M М|G Г|E Е|Y Ы|
+|row 6|F3|F2|F1|РУС|CAPS|GRAPH|CTRL|SHIFT|
+|row 7|RET|SELECT|BS|STOP|TAB|ESC|F5|F4|
+|row 8|→|↓|↑|←|DEL|INS|HOME|SPACE|
+|row 9|NUM4|NUM3|NUM2|NUM1|NUM0|NUM/|NUM+|NUM*|
+|row 10|NUM.|NUM,|NUM-|NUM9|NUM8|NUM7|NUM6|NUM5|
+
+Note: РУС works like the Japanese かな (KANA) key, it is a toggle.
+
+And here is a photograph of the Russian keyboard:
+![MSX Russian keyboard](https://map.grauw.nl/articles/keymatrix/yamaha_russian_keyboard.jpg)
+
+## Source
+
+https://map.grauw.nl/articles/keymatrix.php

package/resources/others/toc.json

@@ -6,6 +6,12 @@
             "title": "MemMan v2.32 TSR Development Kit",
             "uri": "https://map.grauw.nl/resources/tsrdev_en.php",
             "description": "Development kit documentation for MemMan 2.32 TSR (Terminate and Stay Resident) programs on MSX2 systems. Covers new XTsrCall function (61), improved memory allocation with DOS2 RAMdisk support, enhanced Info function (50) for direct entry addresses, enlarged internal stack (240 bytes), and direct function calling methods to improve TSR program performance by bypassing EXTBIO hook overhead."
+        },
+        {
+            "title": "Keyboard matrices",
+            "uri": "msxdocs://others/keyboard_matrices",
+            "external_url": "https://map.grauw.nl/articles/keymatrix.php",
+            "description": "Comprehensive guide to MSX keyboard matrix layouts covering the 11x8 bit key matrix structure, keyboard version detection from BIOS address #002C, differences between Japanese, International, French, German, and Spanish keyboard layouts. Discusses keyboard matrix reading techniques and compatibility issues across different MSX computer models, with special focus on rows 6-10 standardization."
         }
     ]
 }

package/resources/programming/asm_callbios.md

@@ -0,0 +1,79 @@
+# Calling the BIOS from MSX-DOS
+
+In the MSX-DOS environment there is no special entry for calling the MSX BIOS, however you can simply use an interslot call to reach it.
+
+You can use this method to call the BIOS:
+
+```assembly
+CALSLT:      EQU    #001C
+EXPTBL:      EQU    #FCC1
+
+Call_Slot:   ld     iy,(EXPTBL-1)       ;BIOS slot in iyh
+             ld     ix,nnnn             ;address of BIOS routine
+             call   CALSLT              ;interslot call
+```
+
+## The SUBROM
+
+You can’t call the SUBROM from MSX-DOS as you would normally, the reason for this is that both EXTROM and CALSLT use the IX register to pass parameters. Calling directly to the SUBROM doesn’t work either, because using an interslot call to call the SUBROM is not allowed per the MSX2 standard. The reason for this, according to Alex Wulms in MCM 48, is that some DiskROMs couldn’t handle the the SUBROM being in page 0.
+
+The official means to call the SUBROM from MSX-DOS is by using the following routine, provided by ASCII:
+
+```assembly
+; CALSUB
+;
+; In: IX = address of routine in MSX2 SUBROM
+;     AF, HL, DE, BC = parameters for the routine
+;
+; Out: AF, HL, DE, BC = depending on the routine
+;
+; Changes: IX, IY, AF', BC', DE', HL'
+;
+; Call MSX2 subrom from MSXDOS. Should work with all versions of MSXDOS.
+;
+; Notice: NMI hook will be changed. This should pose no problem as NMI is
+; not supported on the MSX at all.
+;
+CALSLT:  EQU    #001C
+NMI:     EQU    #0066
+EXTROM:  EQU    #015f
+EXPTBL:  EQU    #fcc1
+H_NMI:   EQU    #fdd6
+;
+CALSUB:  exx
+         ex     af,af'       ; store all registers
+         ld     hl,EXTROM
+         push   hl
+         ld     hl,#C300
+         push   hl           ; push NOP ; JP EXTROM
+         push   ix
+         ld     hl,#21DD
+         push   hl           ; push LD IX,<entry>
+         ld     hl,#3333
+         push   hl           ; push INC SP; INC SP
+         ld     hl,0
+         add    hl,sp        ; HL = offset of routine
+         ld     a,#C3
+         ld     (H_NMI),a
+         ld     (H_NMI+1),hl ; JP <routine> in NMI hook
+         ex     af,af'
+         exx                 ; restore all registers
+         ld     ix,NMI
+         ld     iy,(EXPTBL-1)
+         call   CALLSLT      ; call NMI-hook via NMI entry in ROMBIOS
+                             ; NMI-hook will call SUBROM
+         exx
+         ex     af,af'       ; store all returned registers
+         ld     hl,10
+         add    hl,sp
+         ld     sp,hl        ; remove routine from stack
+         ex     af,af'
+         exx                 ; restore all returned registers
+         ret
+```
+
+~Grauw
+
+## Source
+
+https://map.grauw.nl/sources/callbios.php

package/resources/programming/asm_docopy.md

@@ -0,0 +1,115 @@
+# DoCopy
+
+The first time I wrote a routine to send a command to the VDP, it was the routine DoCopy, by Stefan Boer, published in Sunrise Special. Later on, as my programming skills improved I step by step improved the routine. Now, this is pretty much the end result, as fast as I could think of. Well, actually, when I really want to do a lot of copies, I usually use an even faster variant, with a faster response time. More about that after the first docopy routine.
+
+```assembly
+;
+; Fast DoCopy, by Grauw
+; In:  HL = pointer to 15-byte VDP command data
+; Out: HL = updated
+;
+DoCopy:
+    ld a,32
+    di
+    out (#99),a
+    ld a,17+128
+    out (#99),a
+    ld c,#9B
+VDPready:
+    ld a,2
+    di
+    out (#99),a     ; select s#2
+    ld a,15+128
+    out (#99),a
+    in a,(#99)
+    rra
+    ld  a,0         ; back to s#0, enable ints
+    out (#99),a
+    ld a,15+128
+    ei
+    out (#99),a     ; loop if vdp not ready (CE)
+    jp c,VDPready
+    outi            ; 15x OUTI
+    outi            ; (faster than OTIR)
+    outi
+    outi
+    outi
+    outi
+    outi
+    outi
+    outi
+    outi
+    outi
+    outi
+    outi
+    outi
+    outi
+    ret
+```
+
+I sometimes find this useful too, a separate routine to wait for the VDP to finish its current command.
+
+```assembly
+;
+; This lil' routine waits until the VDP is done copying.
+;
+VDP_Ready:
+    ld a,2
+    di
+    out (#99),a     ; select s#2
+    ld a,15+128
+    out (#99),a
+    in a,(#99)
+    rra
+    ld a,0          ; back to s#0, enable ints
+    out (#99),a
+    ld a,15+128
+    ei
+    out (#99),a     ; loop if vdp not ready (CE)
+    jp c,VDPready
+    ret
+```
+
+And now, the faster variant of this routine. This one doesn’t switch between status register 0 and status register 2 anymore, which greatly improves the response time, very useful when you need to execute lots and lots of VDP commands consecutively. I believe Cas Cremer’s Core Dump w.i.p. gave me the idea. In any case, this one does not switch status registers anymore, however that will require status register 2 to be set all the time. Fortunately this is not much of a problem when you have your own interrupt handler set-up.
+
+```assembly
+;
+; Faster again!!! DoCopy, by Grauw
+; In:  HL = pointer to 15-byte VDP command data
+; Out: HL = updated
+;
+DoCopy:
+    ld a,32
+    di
+    out (#99),a
+    ld a,17+128
+    ei
+    out (#99),a
+    ld c,#9B
+VDPready:
+    in a,(#99)      ; loop if vdp not ready (CE)
+    rra
+    jp c,VDPready
+    outi            ; 15x OUTI
+    outi            ; (faster than OTIR)
+    outi
+    outi
+    outi
+    outi
+    outi
+    outi
+    outi
+    outi
+    outi
+    outi
+    outi
+    outi
+    outi
+    ret
+```
+
+~Grauw
+
+## Source
+
+https://map.grauw.nl/sources/docopy.php