The MSX Red Book (revised version 1997/08/06) Notes from the editor: - The book was scanned and converted (via O.C.R.) by one person and edited by another (using an IBM PC compatible), independently. - All pages have a fix size of 64 lines. The width was not justified to make future modifications easier, though no line is longer than 80 columns. - This book only covers standard MSX. The BIOS entry points from 0000H to 01B5H should be used instead of the called entries described in the book, because other machines (MSX2, MSX2+, MSX turbo R and customized ones) have different positions for the routines. The use of internal BIOS routine addresses are responsible for many programs only running in MSX. - Some errors present in the original book were fixed, though it was tried to keep it as unaltered as possible. All page numbers match the originals, except undetected errors already present in the original. - Most figures were modificated due to the text-only nature of this file. The character set used during edition was the International IBM PC's one. The following special characters were used and should be changed to the corresponding ones of other character sets: Frame ÚÄÂÄ¿ Pound: œ characters: ³ ³ ³ Micro: æ ÃÄÅÄ´ ³ ³ ³ ÀÄÁÄÙ ------------------------------------------------------------------------------- CONTENTS Introduction .............................. 1 1. Programmable Peripheral Interface ...... 3 2. Video Display Processor ................ 8 3. Programmable Sound Generator ........... 21 4. ROM BIOS ............................... 26 5. ROM BASIC Interpreter .................. 89 6. Memory Map ............................. 208 7. Machine Code Programs .................. 240 Contents Copyright 1985 Avalon Software Iver Lane, Cowley, Middx, UB8 2JD MSX is a trademark of Microsoft Corp. Z80 is a trademark of Zilog Corp. ACADEMY is trademark of Alfred . INTRODUCTION 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. 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, 2 and 3 describe the operation of the Programmable Peripheral Interface, Video Display Processor and Programmable Sound Generator respectively. These three devices ÄÄ 1 ÄÄ INTRODUCTION 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 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 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 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 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. ÄÄ 2 ÄÄ 1. PROGRAMMABLE PERIPHERAL INTERFACE The 8255 PPI is a general purpose parallel interface device configured as three eight bit data ports, called A, B and C, and a mode port. It appears to the Z80 as four I/O ports through which the keyboard, the memory switching hardware, the cassette motor, the cassette output, the Caps Lock LED and the Key Click audio output can be controlled. Once the PPI has been initialized access to a particular piece of hardware just involves writing to or reading the relevant I/O port. PPI Port A (I/O Port A8H) 7 6 5 4 3 2 1 0 ÚÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄ¿ ³ Page 3 ³ Page 2 ³ Page 1 ³ Page 0 ³ ³ PSLOT# ³ PSLOT# ³ PSLOT# ³ PSLOT# ³ ³ C000-FFFF ³ 8000-BFFF ³ 4000-7FFF ³ 0000-3FFF ³ ÀÄÄÄÄÄÄÄÄÄÄÄÁÄÄÄÄÄÄÄÄÄÄÄÁÄÄÄÄÄÄÄÄÄÄÄÁÄÄÄÄÄÄÄÄÄÄÄÙ Figure 1: Primary Slot Register This output port, known as the Primary Slot Register in MSX terminology, is used to control the memory switching hardware. The Z80 Microprocessor can only access 64 KB of memory directly. This limitation is currently regarded as too restrictive and several of the newer personal computers employ methods to overcome it. MSX machines can have multiple memory devices at the same address and the Z80 may switch in any one of them as required. The processor address space is regarded as being duplicated "sideways" into four separate 64 KB areas, called Primary Slots 0 to 3, each of which receives its own slot select signal alongside the normal Z80 bus signals. The contents of the Primary Slot Register determine which slot select signal is active and therefore which Primary Slot is selected. To increase flexibility each 16 KB "page" of the Z80 address space may be selected from a different Primary Slot. As shown in Figure 1 two bits of the Primary Slot Register are required to define the Primary Slot number for each page. The first operation performed by the MSX ROM at power-up is to search through each slot for RAM in pages 2 and 3 (8000H to FFFFH). The Primary Slot Register is then set so that the relevant slots are selected thus making the RAM permanently available. The memory configuration of any MSX machine can be ÄÄ 3 ÄÄ 1. PROGRAMMABLE PERIPHERAL INTERFACE determined by displaying the Primary Slot Register setting with the BASIC statement: PRINT RIGHT$("0000000"+BIN$(INP(&HA8)),8) As an example "10100000" would be produced on a Toshiba HX10 where pages 3 and 2 (the RAM) both come from Primary Slot 2 and pages 1 and 0 (the MSX ROM) from Primary Slot 0. The MSX ROM must always be placed in Primary Slot 0 by a manufacturer as this is the slot selected by the hardware at power-up. Other memory devices, RAM and any additional ROM, may be placed in any slot by a manufacturer. A typical UK machine will have one Primary Slot containing the MSX ROM, one containing 64 KB of RAM and two slots brought out to external connectors. Most Japanese machines have a cartridge type connector on each of these external slots but UK machines usually have one cartridge connector and one IDC connector. Expanders System memory can be increased to a theoretical maximum of sixteen 64 KB areas by using expander interfaces. An expander plugs into any Primary Slot to provide four 64 KB Secondary Slots, numbered 0 to 3, instead of one primary one. Each expander has its own local hardware, called a Secondary Slot Register, to select which of the Secondary Slots should appear in the Primary Slot. As before pages can be selected from different Secondary Slots. 7 6 5 4 3 2 1 0 ÚÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄ¿ ³ Page 3 ³ Page 2 ³ Page 1 ³ Page 0 ³ ³ SSLOT# ³ SSLOT# ³ SSLOT# ³ SSLOT# ³ ÀÄÄÄÄÄÄÄÄÁÄÄÄÄÄÄÄÄÁÄÄÄÄÄÄÄÄÁÄÄÄÄÄÄÄÄÙ Figure 2: Secondary Slot Register Each Secondary Slot Register, while actually being an eight bit read/write latch, is made to appear as memory location FFFFH of its Primary Slot by the expander hardware. In order to gain access to this location on a particular expander it will usually be necessary to first switch page 3 (C000H to FFFFH) of that Primary Slot into the processor address space. The Secondary Slot Register can then be modified and, if necessary, page 3 restored to its original Primary Slot setting. Accessing memory in expanders can become rather a convoluted process. It is apparent that there must be some way of determining whether a Primary Slot contains ordinary RAM or an expander in ÄÄ 4 ÄÄ 1. PROGRAMMABLE PERIPHERAL INTERFACE order to access it properly. To achieve this the Secondary Slot Registers are designed to invert their contents when read back.