developing and tool usage - cayce-msx/msxpp-quick-ref GitHub Wiki
Developing & Tool Usage
The MSX++ provides an I/O device that enables reconfiguring your MSX. This is implemented as a switched I/O device with id $D4. That device can be used from BASIC.
A few examples are provided with OCM-PLD. Their contents are shown here, supplemented with explanations.
Also, a few additional BASIC code examples are added, showing how to interact with the MSX++.
See switched io ports revision ii.pdf (with ii your respective version) for an overview of all the I/O ports and SMART commands.
OCM-PLD examples
The following examples show for a few programs, mostly games, how to start them.
These MSX++-specific tools are used:
SETSMARTCPUSPEEDSLOTMODEGETRESETEXTCLOCKSETAUDIOVDPSPEED
The following more generic tools are used to start the programs:
ROMLOADEPMGLOADMGLOCMSRI
2 Konami carts
SETSMART -0a0f33 # CPU 8.06MHz (fast loading); External Slot-1 + Internal SCC-I Slot-2; Lock Slot-1 & Slot-2 Toggles
ROMLOAD %2>nul # load slot 2 ROM
SETSMART -10 # Internal SCC-I Slot-1 + Internal SCC-I Slot-2
ROMLOAD %1>nul # load slot 1 ROM
SETSMART -03fd # CPU 3.58MHz; warm reset
Ark-a-Noah
setsmart -47 # Vertical Offset 16 "useful for Ark-A-Noah"
ep arkanoah.dsk /r /b>nul # load virtual floppy; set bootable; reset
Knightmare Gold r3
variant 1
Using task-specific tools
cpuspeed -7l # Turbo Pana redirect ON; CPU 8.06MHz; Lock Turbo Toggles
slotmode -1l # Internal SCC-I Slot-1 + External Slot-2; Lock Slot-1 Toggle
mgload kmgr3scc.rom /s1>nul # load slot 1 ROM
getreset -2u # warm reset using 2MiB RAM mapper
variant 2
The same, using SETSMART
setsmart -020a0e292f # Turbo Pana redirect ON; CPU 8.06MHz; Internal SCC-I Slot-1 + External Slot-2; Lock Turbo & Slot-1 Toggle
mgload kmgr3scc.rom /s1>nul # load slot 1 ROM
setsmart -36fc # Unlock Hard Reset Key; warm reset using 2MiB RAM mapper
MKID PROMO
cpuspeed -l # Lock Turbo Toggles
extclock -3 # fixate external bus clock to 3.58MHz
setaudio -s # enable pseudo-stereo
ep mkid.dsk /r /b>nul # load virtual floppy; set bootable; reset
IMAGINE MUSIC DISK
cpuspeed -bu # CPU 3.58MHz; Turbo MegaSD ON; Unlock Turbo Toggles
slotmode -1l # Internal SCC-I Slot-1 + External Slot-2; Lock Slot-1 Toggle
mgload imagine1.rom /s1>nul # load slot 1 ROM
getreset # warm reset
BREAKER
vdpspeed -f # fast VDP mode
ep breaker.dsk /r /b>nul # load virtual floppy; set bootable; reset
TINA'S ADVENTURE ISLAND
slotmode -2 # enable slot 2
mgload tina.rom /s2>nul # load slot 2 (!) ROM
setsmart -3386fd # Lock Slot-1 & Slot-2 Toggles; Internal Slot-2 Linear; warm reset
THE EIDOLON
setsmart -0a112933 # CPU 8.06MHz; External Slot-1 + Internal ASCII-8K Slot-2; Lock Turbo, Slot-1 & Slot-2 Toggles
mgload eidolon.rom /s2>nul # load slot 2 (!) ROM
setsmart -1d2afd # disable MegaSD; Unlock Turbo Toggles; warm reset
SPACE MANBOW
setsmart -4fd7 # Vertical Offset 24 "useful for Space Manbow"; Set Centering YJK Modes/R25 Mask ON
mglocm spmanbow.rom>nul # load slot 1 ROM
POINTLESS FIGHTING!
setsmart -0a132933 # CPU 8.06MHz (fast loading); External Slot-1 + Internal ASCII-16K Slot-2; Lock Turbo, Slot-1 & Slot-2 Toggles
mgload pfightin.rom /s2>nul # load slot 2 (!) ROM
setsmart -152a40 # Japanese Keyboard Layout; Unlock Turbo Toggles; CPU 3.58MHz
reset # warm reset using DOS2 built-in command
F1-SPIRIT: 3D Special
cpuspeed -1 # CPU 4.10MHz; Turbo MegaSD & Turbo Pana redirect ON
sri f13d1.dsk f13d2.dsk # load & run two virtual floppies using SofaRunIt
Using the MSX++ I/O device from BASIC
The switched device has id $D4, or 212 in decimal.
sending a SMART command
10 OUT &H40,212 :' select MSX++ device
20 ID=255-INP(&H40):IF ID<>&HD4THEN END :' verify device is selected
30 OUT &H41,10 :' CPU 8.06MHz (SETSMART command $0A)
40 OUT &H40,0 :' deselect MSX++ device (or rather: all switched devices)
using 16 pages of VRAM
After enabling the I/O device, write the inverse of the wanted video page numbers (0-15) to I/O port $4D. The low 4 bits select page 0, the high 4 bits select page 1.
Code snippets from OCM-extra sample lumshock.asc.
See that file for more information.
10 OUT &H4D,255-A :' A = VRAM PAGE 0-15
20 SETPAGE 0 :OUT &H4D,255-&B00010000 :' show page 0, prepare page 1
30 SETPAGE 1 :OUT &H4D,255-&B00010010 :' show page 1, prepare page 2
40 OUT &H4D,255-16 :' VRAM TO DEFAULT
retrieving details of your device
The following code from firminfo.asc retrieves the I/O device revision number from port $4F (b4-0).
It retrieves the OCM-PLD version from port $4E (b7-0) & $4F (b6-5).
The device type is retrieved from port $49 (b5-2).
See ocmstat.asc for even more details.
10 OUT&H40,&HD4:ID=255-INP(&H40):REV=INP(&H4F)AND31
20 IFID<>&HD4ORREV=0THENPRINT"Generic OCM-PLD or other MSX system":END
30 IFREV<5THENPRINT"OCM-PLD v3.3.3 or earlier";:GOTO80
40 X=INP(&H4E)\10:Y=INP(&H4E)MOD10:PRINT"OCM-PLD version ";
50 IFX\10>0THENPRINTCHR$(48+(X\10));
60 PRINTCHR$(48+(XMOD10));".";CHR$(48+Y);
70 Z=(INP(&H4F)AND96)\32:IFZ>0THENPRINT".";CHR$(48+Z);
80 PRINT" by KdL":PRINT"Switched I/O ports Revision ";
90 IFREV\10>0THENPRINTCHR$(48+(REV\10));
100 PRINTCHR$(48+(REVMOD10)):PRINT
110 TY=ID-((INP(&H49)AND60)\4):PRINT"System type: MSX++ ";
120 IFTY=IDTHENPRINT"computer"ELSEPRINT"compatible"
130 OUT&H40,0:END
toying with the status LEDs
Note that SM-X & SX-2 only have one LED with is controlled by bit 7.
Code snippets from OCM-extra sample lights.asc:
10 OUT &H41,34 :' Lights Mode ON + 'Red Led' OFF
20 OUT &H44,&B01111110 :' Enable LEDs 2-7
30 OUT &H41,35 :' Lights Mode ON + 'Red Led' ON
40 OUT &H44,&B11100111 :' Enable all LEDs except 4&5
41 OUT &H44,&B10000000 :' Enable main LED on SM-X/SX-2
50 OUT &H41,33 :' Lights Mode OFF w/ Auto LEDs - OCM-PLD drives all the LEDs
are we running at 50Hz or 60Hz?
Port $49 bit 7-6 store the MSX++ state; VDP(10) bit 1 the MSX state.
Note that MSX++ can override the VDP state.
From vhzstat.asc:
10 OUT &H40,212: V=INP(&H49)AND64
20 IF V=0 THEN V=INP(&H49)AND128 ELSE V=VDP(10)AND2
30 IF V=0 THEN PRINT"60Hz" ELSE PRINT"50Hz"
retrieve dipswitch status
Note that the physical status is only read at startup.
See dipswitches for how to interpret the 8 bits.
10 OUT&H40,&HD4
20 DIP=INP(&H42)
read values from dynamic port $4B
I/O port $4B is an expansion port that can return 256 different properties. It's there for future additions; currently only one such property is defined. Each property has an index value.
As you'd expect, the current property has index value 00.
See switched io ports revision ii.pdf (with ii your respective version) for precise information.
Property 00 encodes six pieces of information in its bits, two of which are specific to SM-X/SX2.
Port $44 functions as an index that determines the state (i.e., property) of port $4B.
Write the complement of the index (i.e., 255-index) to port $44.
Then read $44 until index is returned.
Finally, read $4B to retrieve the wanted property.
An example in BASIC, reading property 0 - 7:
10 OUT &H40,212
20 FOR ID=0 TO 7
30 OUT &H44,255-ID
40 IF INP(&H44)=ID THEN A=INP(&H4B) ELSE GOTO 40
50 PRINT "PORT $4B:[ ID";ID;"] = &B"+RIGHT$("00000000"+BIN$(A),8)
60 NEXT ID
Note that port $44 is also used for reading/writing LED status. Therefore, sending SMART command $22 or $23 before executing the code above, will count up for 0 to 7 in binary LEDs (on machines having 9 LEDs, like the SX1). If you don't want/need that, ensure SMART command $21 is sent first. That makes sure the LEDs are not changed when reading values from dynamic port $4B.
Detecting OPLx sound chips
OPL3 uses I/O ports C0-C3h & C4-C7h.
An MSX-AUDIO OPL (or compatible) is present & enabled when I/O port C0h returns 00h, 02h, 04h or 06h:
10 IF INP(0C0h) & 11111001b=0 THEN PRINT "OPL detected"
Run this on SX2/SM-X after enabling OPL3, and OPL detected will be printed.
More info: https://www.msx.org/wiki/MSX-Audio_programming
I didn't test this, but OPL3 should be present when I/O port C4h & 06h == 0:
10 IF INP(0C4h) & 00000110b=0 THEN PRINT "OPL3 detected"
MoonSound OPL4 is present when I/O port C4h returns 00h. SX2/SM-X does not support OPL4 and indeed does not return 0 on this port.