@nataliapc/mcp-openmsx 1.1.5 → 1.1.8

package/resources/book--msx2-technical-handbook/MSX_Kun_BASIC_Compiler.md

@@ -0,0 +1,220 @@
+# MSX-BASIC-KUN (BASIC COMPILER)
+
+  by J.Suzuki 1989
+
+  this document & samples by Sho Endo
+
+  translate to english by LASP
+  
+  this text file typed without changes by Nestor Soriano
+
+MSX-BASIC-KUN is an incredible BASIC compiler. It will compile a BASIC program on memory in few seconds and execute it 15 to 100 times faster!! It can compile most of the statements and functions of MSX-BASIC and can handle strings and floating numbers. Once you see it, you'd feel you'd never need to learn the Z-80 machine language. Real time games, C.G., demo programs can be written by the ease of BASIC for machine language speed.
+
+
+<p>&nbsp;</p>
+
+## 1. Settings & General knowledge
+
+This compiler is sold in Japan as a cartridge for 4500 yen. You just set it in a slot to use it. Also, you can found this compiler in MSX2+ Sanyo machines, in ROM.
+
+Now you are in BASIC mode as usual, except that two commands are available:
+
+```
+CALL RUN
+CALL TURBO ON/OFF
+```
+
+"CALL" can be written as "_" (underscore). I will use that from now on.
+
+`_RUN` is the command to compile and execute the entire program on memory. If it finds an error it will stop and yield the message.
+
+`_TURBO ON` is the statement to define the beginning of the turbo block.
+`_TURBO OFF` is the end of the block.
+
+The turbo block is the part of the program you want to execute fast. When the entire program contains some uncompilable statements, you can define the block to be compiled using this set.
+
+EXAMPLE
+
+```
+    100 SCREEN 8:DEFINT A-Z
+    110 BLOAD"PICTURE",S
+    120 _TURBO ON
+    130 FOR X=0 TO 255
+    140 LINE(X,0)-(X,211),0
+    150 NEXT X
+    160 _TURBO OFF
+    170 GOTO 170
+```
+
+This program cannot be `_RUN`, because the `BLOAD` is one of the commands that cannot be compiled. If you `RUN` this, the part lines 130 through 150 will be executed fast.
+
+As `_RUN"FILE"` is not supported, you have to add `_TURBO ON` and `_TURBO OFF` at the beginning and the end if you want to `RUN"FILE"` and have the effect.
+
+```
+    100 FOR I=0 TO 999
+    110 ...
+    .
+    .
+    .
+    890 'END OF THE PROGRAM
+```
+
+So, this can be `_RUN` or add `10 _TURBO ON` and `900 _TURBO OFF` and `RUN"FILE"`.
+
+If you `_RUN` a program containing `_TURBO ON/OFF` it will be an error.
+
+`_TURBO ON/OFF` can not be written in a multi-statement lines.
+
+`_TURBO ON/OFF` can not be nested. But you may have many closed blocks in a program.
+
+Variables and arrays are handled differently in and outside of the blocks. Once you are out of the block, variables and arrays used in the block are lost. Only, the integer types can be defined as common.
+
+```
+    100 DEFINT A-Z:DIM C(2),D(2)
+    110 A=1:B=2:C(0)=3:D(0)=4
+    120 _TURBO ON(A,C())
+    130 DIM D(2)
+    140 PRINT A,B,C(0),D(0)
+    150 A=5:B=6:C(0)=7:D(0)=8
+    160 _TURBO OFF
+    170 PRINT A,B,C(0),D(0)
+
+    RUN
+      1 0 3 0
+      5 2 7 4
+    Ok
+```
+
+Floating numbers used by the compiler is a special format 3-byte value. Its accuracy is about 4.5 digits. Double precision is not available.
+
+An array must be declared by a constant in the beginning.
+
+This compiler works on the BASIC program on the RAM and creates the objects and variables on the left RAM. So there is a limit of the size of the source program about 10K. Big arrays, string variables (each uses 256 byte), `CLEAR ???,&H????` will make the situation tighter as you can imagine. The compiled objects can not be saved as independent programs.
+
+Interrupts available, such as `KEY(1) ON, OFF` etc. But it will decrease the efficiency of the executed object's size & speed.
+
+Some statements may not work correctly.
+
+```
+    100 GOTO 130
+    110 A=3/2
+    120 END
+    130 DEFINT A-Z
+    140 GOTO 110
+```
+
+If you `RUN` this, A is 1. If you `_RUN` this, A is 1.5. `DEF???` will be effective when encountered during the execution in the case of interpreter, while it depends on the order of line number in the other case.
+
+A little complicated string operation may cause easily a "String formula too complex" error. As this compiler has only one level of stack for it. Break a long string formula into multiple small ones, if so.
+
+If you `_RUN` an endless program, you can not stop it. Make a part to check keyboards.
+
+```
+    100 GOTO 100 'Reset or power off to stop
+
+    100 IF INKEY$="" THEN 100
+    110 END
+```        
+is better.
+
+
+<p>&nbsp;</p>
+
+## 2. Difference from MSX-BASIC interpreter
+
+List of statements, commands and functions that can not be compiled.
+
+AUTO, BASE, BLOAD, BSAVE, CALL, CDBL, CINT, CLEAR, CLOAD, CLOAD?, CLOSE, CONT, CSAVE, CSNG, CVD, CVI, CVS, DEFFN, DELETE, DRAW, DSKF, EOF, ERASE, ERL, ERR, ERROR, EQV, FIELD, FILES, FPOS, FRE, GET, IMP, INPUT#, KEY LIST, LFILES, LINEINPUT#, LIST, LLIST, LOAD, LOC, LOF, LPRINT USING, LSET, MAXFILES, MERGE, MOTOR, MKD$, MKI$, MKS$, NAME, NEW, ON ERROR GOTO, ON INTERVAL GOSUB (due to a bug), OPEN, PLAY, PRINT#, PRINT USING, PUT KANJI, RENUM, RESUME, RSET, SAVE, SPC, TAB, TRON, TROFF, WIDTH.
+
+List of those with limits.
+
+* **CIRCLE**: Start, end angles and aspect ratio can't be specified.
+* **COPY**: Only graphic COPY is available.
+* **DEFDBL**: Same as DEFSNG.
+* **DIM**: Must come first in the program or in the turbo block.
+* **INPUT**: Can handle only one variable at the time.
+* **KEY**: ON KEY GOSUB, KEY(n) ON/OFF only.
+* **LOCATE**: x,y must be given in as a set. No cursor switch parameter.
+* **NEXT**: Variable names after the NEXT can not be omitted.
+* **ON**: ON STOP GOSUB, ON INTERVAL GOSUB not available.
+* **PRINT**: Commas work in a different way. No wrapping for digits.
+* **PUT**: PUT SPRITE only.
+* **RUN**: Variables won't be initialized.
+* **SCREEN**: Screen mode and sprite size only.
+* **SET**: SET PAGE only.
+* **STOP**: Same as END.
+* **USR**: Parameter type must be integer only.
+* **VARPTR**: File number can not be given as the parameter.
+
+Otherwise there is no significant difference.
+
+In general, I/O commands & functions, and editing commands can not be compiled. Of course they are available in the direct mode, and outside of the turbo block. You can edit, debug and save a program in MSX-BASIC and execute it by _RUN.
+
+If you want to use `PRINT#` to write characters on `GRP:`, use it outside of turbo block. Otherwise study the sample, "PRINT.TRB".
+
+If you want to use PLAY, use BGM compiler, and get the sound by `USR(n)`.
+
+
+<p>&nbsp;</p>
+
+## 3. New features added
+
+3 special commands are available by starting a remark line with some specific characters.
+
+#### \#I
+Stands for INLINE. You can write a short machine-language routine.
+
+```
+    100 DEFINT A-Z
+    110 K=1
+    120 '#I &H2A,K
+    130 '#I &HF3,&HCD,@150,&HFB
+    140 END
+    150 'SUB
+    160 RETURN
+```
+
+120 means `LD HL,(K); K must be a simple variable of integer type.`
+130 means 
+
+```
+    DI
+    CALL @150 ;Be careful, this line won't be RENUMed.
+    EI
+```
+
+#### #C
+Stands for CLIP. In the screen modes 5 through 8 (except for `PAINT`, and `CIRCL`E), this will be set clipping on and off.
+
+````
+    10 SCREEN 8
+    20 '#C-
+    30 LINE(0,0)-(255,255) 'Y CLIPPED
+    40 IF INKEY$="" THEN 40
+    50 '#C+
+    60 LINE(0,0)-(255,255) 'NOT CLIPPED
+    70 IF INKEY$="" THEN 70
+````
+
+#### #N
+Check if NEXT overflows.
+
+```
+    10 FOR I%=0 TO &H7FFF
+    20 NEXT I%
+```
+
+This program will end up in a "Overflow error" in MSX-BASIC. And if _RUN, it will be an endless loop. If #N+ is specififed, it will end normally. This code will decrease the efficiency of the object, too. Better not use unless it's really necessary. To clear, specify #N-.
+
+
+<p>&nbsp;</p>
+
+**NOTE**: In MSX-2+ Sanyo you can found a new command:
+
+```
+    CALL BC
+```
+
+This command turn on the BASIC COMPILER options.
+
+

package/resources/book--msx2-technical-handbook/toc.json

@@ -0,0 +1,82 @@
+{
+    "title": "MSX2 Technical Handbook",
+    "description": "The MSX2 Technical Handbook is the (almost) full reference of the MSX2 system as published by ASCII Corporation in 1987. It includes detailed information about the MSX system, BASIC, MSX-DOS, VDP and display screen, BIOS access to peripherals, and more.",
+    "external_url": "https://github.com/Konamiman/MSX2-Technical-Handbook",
+    "toc": [
+        {
+            "title": "Chapter 1: MSX system overview",
+            "uri": "msxdocs://book--msx2-technical-handbook/Chapter1__MSX_System_Overview",
+            "description": "Provides a detailed comparison between MSX1 and MSX2, highlighting enhanced features such as improved graphics, higher resolution, expanded memory (RAM and VRAM), and new hardware components like the V9938 VDP and battery-powered clock. It explains the MSX2's compatibility with MSX1 software and peripherals, its standardized interfaces, and its dual software environments: BASIC mode and DOS mode. The chapter includes technical tables, diagrams, and memory maps to describe the system's architecture, addressing, and hardware/software integration."
+        },
+        {
+            "title": "Chapter 2: BASIC",
+            "uri": "msxdocs://book--msx2-technical-handbook/Chapter2__BASIC",
+            "description": "Details the enhancements in MSX BASIC version 2.0, including new instructions, modifications to screen modes, color specifications, graphics, VDP access, sprites, RAM disk operations, and timer features. It explains the internal structure of BASIC, linking with assembly language programs, and advanced features like creating new commands and handling interrupts. The chapter provides technical tables, examples, and diagrams to describe the syntax, functionality, and memory management of BASIC programs. It also includes notes on software development, error codes, and compatibility considerations for MSX systems."
+        },
+        {
+            "title": "Chapter 3: MSX-DOS",
+            "uri": "msxdocs://book--msx2-technical-handbook/Chapter3__MSX-DOS",
+            "description": "Describes MSX-DOS, a disk operating system for MSX computers, derived from MS-DOS and compatible with CP/M applications. It covers MSX-DOS features, such as file-level compatibility with MS-DOS, support for up to eight disk drives, and flexible file management. The chapter explains basic operations, internal and external commands, batch file usage, and system calls for disk and file access. It includes technical details on disk structure, file control blocks (FCB), logical sectors, and random/sequential file access methods. This information is essential for developing software that interacts with MSX-DOS."
+        },
+        {
+            "title": "Chapter 4: VDP and display screen (sections 1 to 5)",
+            "uri": "msxdocs://book--msx2-technical-handbook/Chapter4a__VDP_and_Display_Screen",
+            "description": "Provides detailed information about the V9938 video display processor (VDP) used in MSX2 machines, including its registers, VRAM, I/O ports, and advanced graphics capabilities. It describes various screen modes (TEXT, GRAPHIC, MULTI-COLOR), their configurations, memory structures, and methods for accessing VRAM and registers. The chapter also covers sprite functionality, including two modes (Mode 1 and Mode 2), sprite attributes, collision detection, and advanced features like interlaced mode, vertical scrolling, and hardware commands for graphics manipulation. This information is essential for programming MSX2 graphics and optimizing VDP usage."
+        },
+        {
+            "title": "Chapter 4: VDP and display screen (section 6)",
+            "uri": "msxdocs://book--msx2-technical-handbook/Chapter4b__VDP_and_Display_Screen",
+            "description": "Details the advanced graphical operations supported by the V9938 video display processor (VDP) in MSX2 machines. The chapter explains 12 VDP commands, including high-speed transfers (HMMC, HMMM, YMMM), logical operations (LMMC, LMCM, LMMM, LMMV), and drawing commands (LINE, PSET, POINT). It covers their coordinate systems, register configurations, logical operations, and execution flow. Examples of usage are provided for each command, along with techniques to optimize execution speed. This section is essential for developers working with MSX2 graphics programming and VDP command integration."
+        },
+        {
+            "title": "Chapter 5: Access to peripherals through BIOS (sections 1 to 6)",
+            "uri": "msxdocs://book--msx2-technical-handbook/Chapter5a__Access_to_Peripherals_through_BIOS",
+            "description": "Explains how MSX2 provides a standardized BIOS interface for accessing peripherals, ensuring compatibility across machines and versions. The chapter covers sound generation using the PSG (Programmable Sound Generator) and 1-bit sound port, cassette interface operations, keyboard input and scanning, printer communication, universal I/O interface for devices like joysticks and paddles, and advanced peripherals such as touch panels, light pens, mice, and trackballs. It also details the CLOCK-IC functions, including timekeeping, alarm settings, and battery-powered memory for storing system configurations. BIOS routines for interacting with these peripherals are described, along with examples of assembly language programs."
+        },
+        {
+            "title": "Chapter 5: Access to peripherals through BIOS (section 7)",
+            "uri": "msxdocs://book--msx2-technical-handbook/Chapter5b__Access_to_Peripherals_through_BIOS",
+            "description": "Titled 'Slots and Cartridges', it explains how MSX computers expand their 64K address space to 1MB using slots, including basic and expansion slots. It covers slot selection, inter-slot calls for accessing BIOS routines across slots, and work areas for managing slot status. The chapter also provides guidelines for developing cartridge software, including header configuration, BASIC program auto-start, and device expansion routines. It includes technical details on slot management, memory allocation, and interrupt handling, essential for integrating hardware and software with MSX systems."
+        },
+        {
+            "title": "Appendix 1: BIOS listing",
+            "uri": "msxdocs://book--msx2-technical-handbook/Appendix1__BIOS_Listing",
+            "description": "Provides a comprehensive list of 126 BIOS routines available in MSX systems, categorized by functionality: RSTs, I/O initialization, VDP access, PSG sound, keyboard/printer/game I/O, cassette operations, and miscellaneous routines. It includes entries specific to MSX2, such as SUB-ROM routines for advanced screen modes, palette management, and mouse/light pen support. Each routine is described with its function, input/output parameters, affected registers, and calling sequence. This appendix is essential for developers working with MSX BIOS to interact with hardware and system-level features programmatically."
+        },
+        {
+            "title": "Appendix 2: MATH-PACK",
+            "uri": "msxdocs://book--msx2-technical-handbook/Appendix2__Math-Pack",
+            "description": "Describes the mathematical routines available in MSX-BASIC, which can also be accessed from assembly language programs. The Math-Pack supports floating-point operations, trigonometric functions, type conversions, integer arithmetic, and power calculations. It uses BCD (Binary Coded Decimal) format for real numbers, with single precision (4 bytes) and double precision (8 bytes). The appendix details the memory structure, DAC (Decimal Accumulator), and ARG areas for calculations, along with entry points for operations like addition, subtraction, multiplication, division, and normalization. It also explains routines for input/output of floating-point numbers, type conversion, and comparison. This resource is essential for developers requiring advanced mathematical functionality in MSX software."
+        },
+        {
+            "title": "Appendix 3: Bit block transfer",
+            "uri": "msxdocs://book--msx2-technical-handbook/Appendix3__Bit_Block_Transfer",
+            "description": "Describes routines for transferring data between VRAM, RAM, and disk using assembly language. These routines, located in the expansion ROM, include operations like BLTVV (VRAM-to-VRAM transfer), BLTVM (RAM-to-VRAM transfer), BLTMV (VRAM-to-RAM transfer), BLTVD (disk-to-VRAM transfer), and BLTDV (VRAM-to-disk transfer). Each routine specifies input parameters, such as coordinates, memory addresses, and logical operations, and outputs flags for error handling. The appendix also explains data formatting, memory allocation for screen modes, and hooks for error handling in BASIC or MSX-DOS. This resource is essential for developers working with MSX graphics and storage operations."
+        },
+        {
+            "title": "Appendix 4: Work area listing",
+            "uri": "msxdocs://book--msx2-technical-handbook/Appendix4__Work_Area_Listing",
+            "description": "Provides a detailed map of the MSX2 system work area, describing memory regions used for various functions, including BASIC interpreter operations, VDP register storage, cassette parameters, key input handling, Math-Pack calculations, and RS-232C communication. It also lists hooks for interrupt handling, device connections, and system expansions. Each entry specifies the address, length, initial values, and purpose of the memory area. This appendix is essential for developers working with MSX2 system-level programming, offering insights into memory management and hardware integration."
+        },
+        {
+            "title": "Appendix 5: VRAM map",
+            "uri": "msxdocs://book--msx2-technical-handbook/Appendix5__VRAM_Map",
+            "description": "Provides detailed memory mappings for various MSX2 screen modes, including TEXT (SCREEN 0), GRAPHIC (SCREEN 1-8), and MULTI-COLOR modes. Each screen mode's VRAM usage is outlined, specifying address ranges for pattern name tables, palette tables, pattern generator tables, sprite attributes, color tables, and sprite generators. The appendix highlights differences in VRAM allocation based on resolution and line modes (e.g., 192 vs. 212 lines). This resource is essential for developers working with MSX2 graphics programming, offering precise VRAM layout information for optimizing screen rendering and memory management."
+        },
+        {
+            "title": "Appendix 6: I/O map",
+            "uri": "msxdocs://book--msx2-technical-handbook/Appendix6__IO_Map",
+            "description": "Provides a detailed mapping of MSX2 input/output ports, specifying address ranges and their associated hardware functions. Key sections include ports for RS-232C communication, VDP (Video Display Processor) access, printer control, sound generation (AY-3-8910), parallel port operations, CLOCK-IC for timekeeping, lightpen control, floppy disk controller (FDC), kanji ROM access, and MSX-Audio. Reserved and user-defined ranges are also noted. This resource is essential for developers working with MSX hardware, offering precise port-level details for programming and device integration."
+        },
+        {
+            "title": "Appendices 8 and 10: Control codes and escape sequences",
+            "uri": "msxdocs://book--msx2-technical-handbook/Appendix8_10__Control_Codes_and_Escape_Sequences",
+            "description": "Provides a comprehensive list of control codes (e.g., cursor movement, text editing, and screen clearing) and their corresponding key combinations (e.g., CTRL + A, CTRL + C). Additionally, it details escape sequences for advanced operations, such as cursor positioning (<ESC> Y), screen editing (<ESC> K), and cursor visibility (<ESC> x5). These codes and sequences are essential for interacting with MSX systems programmatically, enabling precise control over text and screen manipulation."
+        },
+        {
+            "title": "MSX Kun Basic compiler",
+            "uri": "msxdocs://book--msx2-technical-handbook/MSX_Kun_BASIC_compiler.md",
+            "description": "The document describes MSX-BASIC-KUN, a BASIC compiler for MSX computers that significantly accelerates program execution (15 to 100 times faster). It compiles most MSX-BASIC statements, supports strings and floating-point numbers, and introduces turbo blocks (_TURBO ON/OFF) for selective compilation. The compiler has limitations, such as unsupported commands (e.g., BLOAD, PRINT#) and restrictions on variable handling within turbo blocks. It adds new features like inline assembly (#I), clipping control (#C), and overflow checks (#N). The compiler operates within RAM and cannot save compiled programs independently. It is ideal for creating high-performance MSX applications without requiring Z80 assembly language expertise."
+        }
+    ]
+}