GR8NET - GR8BIT

GR8NET - GR8BIT
GR8NET internetworking adapter with multimedia
Technical Data Book
Programmer’s Guide
For firmware version 0.5
Date of 01 June 2017 / Datecode 20170601
AGE Labs / Eugeny Brychkov
© 2015-2017 AGE Labs
Page 1 of 156
© 2015-2017 Eugeny Brychkov
This page is intentionally left blank
© 2015-2017 AGE Labs
Page 2 of 156
© 2015-2017 Eugeny Brychkov
GR8NET adapter facts and features
GR8NET is designed as a standalone cartridge to be used with MSX-compatible
personal computers. It allows PC accessing internet and intranet, provides comprehensive
programming capabilities to programmers. Main features of the adapter are:
RJ-45 UTP Ethernet connection, 10/100 Mbit auto-negotiation / auto MDI, IPv4
TCP, UDP, RAW and HTTP communication protocols
Built-in simple web browser to browse web server directory tree
802.3(u)
10/100
DHCP configuration, DNS auto-resolution
2 user programmable sockets
MSX-BASIC extended command support
Built-in telnet application
Built-in HTTP-based bload application
Operation as 1 Megabyte mapped RAM
ROM mapper emulation (plain, Konami)
Built-in SCC for standalone and Konami implementations
Hardware accelerated functions:
•
Interrupt generator using time period or frequency, with watchdog
•
PCM buffered 8- and 16-bit mono performance
•
Data prefetch from onboard RAM, ROM and W5100
•
Micro-SD card interface
•
Mathpack for FAT16/FAT32 and 32-bit multiplication and division
*
Mixed GR8NET mapper 512K, Mapped RAM 512K mode plus Nextor with SDC support
RAM-disk 2KB to 720KB, user programmable size
Operates at standard 3.58 MHz as well as at overclocked 7.11 MHz bus speeds
Built-in OPLL (YM2413, MSX-Music) with its ROM BIOS (in mapper mode 8)
Built-in OPL-1 with ADPCM (Y8950, MSX-Audio)
MP3 audio streaming from network and SD-card into additional MP3 cartridge
*
* Using additional MP3 cartridge as output device
© 2015-2017 AGE Labs
Page 3 of 156
© 2015-2017 Eugeny Brychkov
Special thanks to the whole MSX community supporting the development of the device and
software, and in particular:
•
Kazuhiko Nishi, Ph.D. for continuous support of the MSX development activities;
•
Wouter Vermaelen for suggestions in functionality of the hardware accelerated functions and
development of the openMSX model of the device, for supervision and guidance of the OPLL/Y8950
hardware development;
•
Albert Beevendorp for providing his knowledge and experience on the Konami SCC chip;
•
Daisuke Shiraishi (白石大介) for advising in FPGA configuration development;
•
Nestor Soriano for allowing and supporting implementation of Nextor for GR8NET;
•
Edo van Zanten and Tristan Zondag for providing measurement and testing for overclocked
MSX machines; Edo for testing of MP3 streaming playback;
•
Moonsoft (Remco Schrijvers) for MoonBlater v1.4 software (Freeware license);
•
Jos van den Biggelaar for providing information on and firmware source code of MP3 cartridge
for implementation of the MP3 cartridge’s firmware fix.
© 2015-2017 AGE Labs
Page 4 of 156
© 2015-2017 Eugeny Brychkov
This page is intentionally left blank
© 2015-2017 AGE Labs
Page 5 of 156
© 2015-2017 Eugeny Brychkov
CONTENTS
DEFINITIONS ..............................................................................................9
0. Introduction ............................................................................................12
1. Quick user guide .....................................................................................13
2. GR8NET adapter design ..........................................................................16
2.1. Physical design ......................................................................................16
2.2. Initialization messages and sequence ......................................................19
3. Using GR8NET in BASIC ..........................................................................22
3.1. Operating in multi-adapter environment ..................................................22
3.2. Built-in helper........................................................................................24
3.3. Diagnostic mode....................................................................................25
3.4. Overall subsystem status........................................................................25
3.5. Memory manager ..................................................................................26
3.6. Setting up the adapter ...........................................................................26
3.6.1. Getting effective configuration information.......................................30
3.6.2. DHCP mode...................................................................................32
3.6.3. Fixed IP address configuration mode ...............................................33
3.6.4. Managing configurations.................................................................36
3.6.5. Managing system time....................................................................37
3.6.6. Updating GR8NET firmware ...........................................................39
3.7. Using built-in HTTP-related commands ....................................................40
3.8. Using NETBLOAD command....................................................................44
3.9. Using built-in TELNET application............................................................46
3.10. Built-in media player ............................................................................47
3.10.1. Playing WAV or MP3 file from network source.................................47
3.10.2. Listening to internet radio .............................................................48
3.10.3. Playing WAV or MP3 files from SD-card ..........................................48
3.10.4. Playing wave from GR8NET RAM ...................................................49
3.10.5. Playing video from SD-card ...........................................................51
3.11. Setting memory mapper .......................................................................54
3.12. Other utilities.......................................................................................55
4. Using GR8NET as BASIC I/O device........................................................66
4.1. BASIC I/O using TCP..............................................................................66
4.2. BASIC I/O using UDP and RAW...............................................................68
4.3. BASIC I/O using HTTP protocol...............................................................69
4.4. The URL parser .....................................................................................70
5. Built-in web browser...............................................................................71
5.1. Opening SD-card located file in the browser.............................................77
© 2015-2017 AGE Labs
Page 6 of 156
© 2015-2017 Eugeny Brychkov
6. Using integrated MSX-DOS .....................................................................78
6.1. GR8NET Disk subsystem (DOS1).............................................................78
6.1.1. Initialization of the DOS1 disk subsystem .........................................79
6.1.2. Using GR8NET DOS1 disk subsystem ...............................................81
6.2. Nextor disk subsystem ...........................................................................85
7. Built-in MSX-Audio and MSX-Music.........................................................87
7.1. Starting with built-in OPLL ......................................................................89
7.2. Playing games with built-in OPLL ............................................................89
7.3. Using built-in MSX-Audio ........................................................................90
7.4. Alternative interface to Y8950 and OPLL registers ....................................90
8. Offline firmware upgrade........................................................................92
8.1. Updating contents of the onboard flash chip ............................................92
8.2. Updating FPGA firmware ........................................................................93
9. GR8NET technical reference....................................................................96
9.1. Identification and detection ....................................................................96
9.2. Setting operating mode and mapper type ................................................98
9.3. Logical page assignment ........................................................................102
9.4. Special control registers .........................................................................104
9.5. Hardware-accelerated functions ..............................................................107
9.5.1. Controlled interrupt generator with watchdog...................................107
9.5.2. PCM function .................................................................................111
9.5.3. Prefetch function ...........................................................................113
9.5.4. Combining functionalities of generator, prefetch and PCM .................117
9.5.5. Sound custom chip (SCC) ...............................................................117
9.5.6. Digital waveform input ...................................................................117
9.5.7. Volume registers............................................................................117
9.5.8. Micro-SD card interface ..................................................................118
9.5.9. Math-Pack .....................................................................................121
9.5.10. Mixer and DAC (digital to analog converter) ...................................126
9.5.11. System registers ..........................................................................126
9.6. Mapper modes ......................................................................................127
9.6.1. Mode 0: GR8NET internetworking adapter .......................................128
9.6.2. Mode 1: plain 32kByte write-protected memory chunk ......................128
9.6.3. Mode 2/3: Konami memory mappers ...............................................129
9.6.4. Mode 4: ASCII-8 memory mapper ...................................................129
9.6.5. Mode 5: ASCII-16 memory mapper .................................................129
9.6.6. Mode 6: Mirrored ROM ...................................................................129
9.6.7. Mode 7: 1 Megabyte mapped memory.............................................129
9.6.8. Modes 8-14: Composite mappers ....................................................130
© 2015-2017 AGE Labs
Page 7 of 156
© 2015-2017 Eugeny Brychkov
10. Programming API..................................................................................132
10.1. Identification of the adapter .................................................................132
10.2. Direct firmware calls ............................................................................133
10.3. URI structure.......................................................................................140
11. Applications ..........................................................................................141
11.1. MSX webserver....................................................................................141
11.2. FTP client ............................................................................................142
11.3. Video player ........................................................................................144
11.3.1. Making videos for MSX .................................................................145
12. Troubleshooting ....................................................................................144
13. Examples of the code ............................................................................150
14. References ............................................................................................153
15. Document revision history ....................................................................154
© 2015-2017 AGE Labs
Page 8 of 156
© 2015-2017 Eugeny Brychkov
DEFINITIONS
Octet
The set of 8 bits – the byte. This term is usually used to denote the part of IP address.
IPv4 address consists of four octets, and thus 32 bits
Variable
The entity in programming language (e.g. MSX-BASIC) which can get various values within
pre-defined range. For example, integer variable may be of any value from -32758 to
32767 if it is considered as signed, and from 0 to 65535 if it is considered unsigned. String
variable if a pointer to the memory location where string’s characters (bytes) are stored.
String variable has size which equals to number of characters in it. Useful characters in the
string can be terminated with special control character (usually 0 or carriage return)
Configured value
Value which is currently in effect for the system or subsystem. In order to configure
specific value, you will have to issue control command putting set of values into effect
Gateway
Device on the subnetwork which provides routing to the wider network (e.g. internet).
Gateway can also serve additional functionality acting as DNS or DHCP server
DNS
Stands for domain name server – the device which translate human-readable conventional
internet names like www.gr8bit.ru into IP address. For successful translation this server
needs access to other name servers, that’s why Gateway is very good place to implement
DNS for subnetwork
DHCP
Stands for dynamic host configuration protocol, which is used to automatically obtain
configuration information without having IP addresses and mask configured manually. For
successful automatic configuration, subnetwork should have DHCP server configured and
running. Usually one physical subnetwork has only one DHCP server
Mask
Bitmap of 4 octets (32 bits) identifying membership of specific host with specific IP address
in the subnet. If wrong mask is set up, you may not get access to subnet resources and
the internet
CRLF
Two characters, CR and LF, with CR having decimal code 13 and LF having decimal code
10. CR stands for “carriage return” which returns cursor to the beginning of current line,
and LF stands for “line feed” which moves one line down. These terms come from dot
matrix printing era, when CR was physical move of the printing head to the position 0, and
LF was move of the shaft, and thus paper, one character position forward
© 2015-2017 AGE Labs
Page 9 of 156
© 2015-2017 Eugeny Brychkov
PCM
Pulse-code modulation, the array of 8-bit or 16-bit samples representing the waveform on
the time dimension
DAC
Digital-to-analog converter, the software, firmware and hardware implementation which
converts digital code which represents specific voltage level to this analog voltage level
Default adapter
The adapter which is used by default to service BASIC CALL statement and device I/O
when user types CALLNET commands without numeric identification of the adapter, or
uses BASIC I/O device name without numeric identification of the adapter
Default URI structure
This structure is used as a template for generating actual URI structures. For example, if
default structure contains www.gr8bit.ru as host name, /software/ as a path, and
myfile.dat as a name, calling URI parser with URI string /software/roms/mg2.rom will
cause output URI structure with same host name, same destination and source ports, but
with path /software/roms/ and file name mg2.rom
Dynamic source port number
Each TCP session is identified by the port number host uses at its end (source port) and
another host’s end (destination port). For example, for HTTP communication usual
destination port number is 80. If same source port number is used for several sessions to
the same remote host’s remote port, it will confuse remote host and whole communication.
Thus GR8NET implements dynamic port numbers in range 0c000h-0ffffh, every connection
request dynamic port number is increased by 1 thus explicitly removing possible issues
related to confusion of the sessions in complex communication. To enable dynamic source
port usage set source port number by CALLNETSETPORT command to 0.
Y8950
It is a chip incorporating OPL version 1 frequency modulation sound generator, and
ADPCM (adaptive differential pulse-code modulation) engine. It can produce FM tones, and
play specially coded and compressed samples giving realistic audio output. This chip, and
circuits built on it, is detected by port I/O commands.
OPLL
This is abbreviation of FM OPerator Type-L Light, a chip, produced by Yamaha under part
number YM2413, represents simplified version of Y8950 without ADPCM. Accessing this
chip is easier, but it also has limitations having only one custom instrument and 18 preset
instruments. This chip does not respond to CPU reads, and to identify its presence
software usually looks for its ROM containing special APRLOPLL signature at its beginning.
© 2015-2017 AGE Labs
Page 10 of 156
© 2015-2017 Eugeny Brychkov
This page is intentionally left blank
© 2015-2017 AGE Labs
Page 11 of 156
© 2015-2017 Eugeny Brychkov
0. Introduction
GR8NET internetworking adapter is designed to provide networking and multimedia
capabilities to the MSX home personal computers.
GR8NET is relatively complex device made of contemporary high-technology
components, and owning it is not only a fun, but also a responsibility. Please familiarize
yourself with DO’s and DON’Ts before you start operating it.
DO:
• Install adapter only into MSX-compatible computers;
• Use adapter only with proven fault-free equipment – including network equipment
and Micro-SD cards;
• Regularly examine edge connector of the cartridge, and slot connector cartridge to
be installed into for dirt, and clear this dirt with spirit or any other solution intended
for connector cleaning;
• Install Micro-SD card with its pins facing front of the cartridge;
• Insert cartridge into the slot by slightly pressing onto its casing, and remove
cartridge from the slot holding cartridge by its casing and gently pulling it out;
• Select different switch combinations for adapters installed in the system;
• In case of questions or problems seek advice from manufacturer/designer and from
community.
DON’T:
• Do not disassemble cartridge and repair it yourself unless you are asked by
authorized person;
• Do not store or operate cartridge in dusty places;
• Do not expose cartridge to the sun rays, excessive heat or excessive cold;
• Do not allow water, moisture or any other solutions getting into the box;
• Do not clean body of cartridge or labels with alcoholic solutions or solvents;
• Do not try disconnecting LAN cable by forcefully pulling it out using cord, press RJ45 connector’s latch first before removing the cable by its head;
• Do not forcefully insert Micro-SD card into its slot; it should be enough to apply
slight vertical pressure to get card in.
There’s a difference how adapter behaves on cold and warm boot. On cold boot
(reset or power cycle) adapter will load its configuration from the flash chip; on warm boot
GR8NET will not load configuration information making configuration set before reboot
effective.
© 2015-2017 AGE Labs
Page 12 of 156
© 2015-2017 Eugeny Brychkov
1. Quick user guide
This chapter covers main functionalities of GR8NET from user experience point of
view; if you need more technical details please refer to the respective section of the
manual. This manual is searchable, just press ^F and put keyword to search for in.
If you have issues please refer to Troubleshooting chapter. Then, if you do not find
answers to your questions please contact info@gr8bit.ru with your questions.
Before installing adapter
If you install more than one GR8NET adapter into your
system, please ensure that adapters are having different
IDs set by their DIP switches at the bottom. ID set up in
binary system, with both off being ID0#, and both on being
ID#3.
Getting help on the commands
Using commands CALLNETHELP and
CALLNETHELP<command>
will
show you basic information on
command availability and usage. If
you find built-in help insufficient,
please refer to the respective
section of this manual.
Getting firmware versions (firmware location)
NETVER command shows you adapter ID (device), version of
the code in flash chip, flash chip firmware build datecode and
FPGA configuration version (engine).
Setting up network
Most convenient mode is DHCP mode (NETDHCP
command). Remote host name should be resolved
(otherwise there’s an issue with DNS being used).
Note that NETSAVE command saves current mode (thus if card did not get
DHCP configuration and booted in Fixed IP mode, after NETSAVE it will
continue booting in Fixed IP mode).
When SD-card can be used
- In mapper mode 8 with Nextor if SD-card’s first partition is formatted with
FAT12/FAT16. SD-card in DOS1 mode is not supported.
- With GR8NET commands like NETBROWSE, NETPLAYWAV, NETPLAYVID, NETBLOAD.
These commands support first partition having FAT16/FAT32 formats and are readonly.
You can develop your own SD-card driver with full read-write functionality, GR8NET hardware allows it. It was deliberately chosen not to
provide write functionality under BASIC without standard BIOS support (e.g. Nextor), thus there’s no driver for DOS1 mode.
© 2015-2017 AGE Labs
Page 13 of 156
© 2015-2017 Eugeny Brychkov
Booting from SD-card with Nextor (system files)
- Only possible in mapper modes 8-14, e.g. to switch to mapper mode 8 use
CALLNETSETMAP(24)
- First partition of SD-card must be formatted as FAT12 or FAT16, it must contain files
NEXTOR.SYS and COMMAND2.COM.
- Card may be formatted using PC, or using Nextor’s CALLFDISK utility (note there’s a bug in
Nextor and you may need to apply this fix to formatted card to have it working with GR8NET SD-card BASIC commands).
Saving data onto SD-card
Booting in mapper mode 8 with Nextor support and using FTP client available here. Usage
guidelines are given in FTP client chapter; otherwise use another device to save data onto
the SD-card (e.g. inserting it into PC).
Using GR8NET RAM-disk
- Press and hold F4 during
adapter initialization to
enable built-in Disk-ROM
- Press and hold F2 until
key release notice to invoke web browser and select target image to load
- Press and hold F1 to force image reload if there’s valid image in RAM already
- Press and hold F3 to disable built-in Disk-ROM
- You can combine keys, e.g. pressing and holding F4 and F2 simultaneously
At any time you can load new image into RAM disk using CALLDSKSETIMG and then
CALLDSKLDIMG commands; previous contents of RAM disk will be invalidated
At any time you can save disk image onto SD-card using CALLDSKSVIMG command
Using built-in browser (ROMs, programs)
- Invoke browser by CALLNETBROWSE in BASIC
- You can browse internet, and first partition of
SD-card formatted with FAT16/FAT32
- Press alphanumeric key to get to next file
starting with the respective character
- Press SELECT key to reload the web page
- Press CLS/HOME key to go to the bottom/top of
the page
- Press TAB key to play WAV or MP3 file
- Use ^V key combination to play video from SDcard
- Press ENTER key to load and execute ROM, BASIC program or binary file
- To have auto-run of the ROM with specific mapper type include target mapper type into
the file name between curly braces, e.g. metalgear2{3}.rom will auto-start in Konami5
mapper mode.
Please refer to Built-in web browser chapter for supported web page formats, and CALLNETBROWSE execution flags
© 2015-2017 AGE Labs
Page 14 of 156
© 2015-2017 Eugeny Brychkov
Target mapper
GR8NET by default boots in mapper mode 0, however if you use GR8NET in mapper mode
8 configuration (512K+512K+Nextor+YM2413) you may override target mapper type by
CALLNETTGTMAP command, and then save setting using CALLNETSAVE. But be aware that
in mapper mode 8 GR8NET RAM buffers are limited to 512K only, and you will have to
boot in mapper mode 0 to perform specific actions (e.g. update flash firmware of the
adapter). To skip adapter re-initialization, press and hold arrow down key after machine
reset and during adapter initialization, and it will forcefully boot in default mapper mode 0.
Playing media files (audio, video)
- You can play WAV files using web browser (TAB key) or CALLNETPLAYWAV command
from network or SD-card. For network play please mind network throughput from the
remote server, for far-away locations playback hiccups may occur. WAV file must be
monophonic.
- You can play MP3 files using web browser (TAB key) or CALLNETPLAYWAV command
from network or SD-card, given you have MP3 cartridge installed in the system and it is
detected on the GR8NET cartridge initialization displaying MP3/ext string.
- You can listen to internet radio CALLNETPLAYWAV(“http://ic3.101.ru:8000/v13_1”)
- You can play MSX video files (SC2, SC8 and SCC for respective screen mode) from SDcard (no network playback) using ^V in web browser or CALLNETPLAYVID command.
How can I play games and save their data onto SD-card?
There are special mapper modes designed for this purpose: mapper 9 to mapper 14 (do
not forget to add 16 when using NETSETMAP command). For example, to play King’s
Valley 2 load game in mapper mode 0 with browser using space key, and then switch to
Konami 5 mapper mode using CALLNETSETMAP(27), where 27 is 16 + 8 + 3. Note that:
- These new mapper modes put game into expanded slot along with main RAM in the
same slot (but another subslot) – some games will not work in this configuration, for
example Metal Gear 2; to have MG2 run with GR8NET Nextor use third argument to
NETSETMAP to disable mapped RAM, e.g. CALLNETSETMAP(27,,1);
- Your SD-card’s first partition must be supported by the game: e.g. be formatted as
720KB diskette, and Nextor must boot into DOS1 mode (press ‘1’ key when GR8NET
initializes).
© 2015-2017 AGE Labs
Page 15 of 156
© 2015-2017 Eugeny Brychkov
2. GR8NET adapter design
It is important that you understand how you can use adapter with your MSX system,
and which configuration options you have – from hardware and from software/firmware
perspectives.
2.1. Physical design
GR8NET internetworking adapter is packaged into standard Konami-size cartridge,
having semi-transparent body. It has several indicating devices which are seen through
this semi-transparent casing.
Figure 1. Adapter set
Product consists of the adapter, Altera Byteblaster-II, ribbon cable and adapter board
to connect Byteblaster to the GR8NET adapter.
Please note that according to user feedback batch #2 (May 2016) and further
Byteblaster-II device is not supplied any more. Ribbon cable and adapter board are being
supplied.
© 2015-2017 AGE Labs
Page 16 of 156
© 2015-2017 Eugeny Brychkov
6
7
1
2
3
4
5
Figure 2. Components of the GR8NET adapter
Adapter consists of the following components (fig. 2):
1. Receive LED, green, seen through the semi-transparent cartridge casing;
2. Micro-SD card slot, card is inserted with its contacts to the front;
3. SD-card indication LED, red, seen through the semi-transparent cartridge casing.
Off means no card or card is idle, regular flash of 3 times per seconds means cart
initialization failure;
4. RJ-45 10/100 Mbit network connector;
5. Transmit LED, yellow, seen through the semi-transparent cartridge casing;
6. Configuration switch;
7. FPGA active serial configuration connector.
© 2015-2017 AGE Labs
Page 17 of 156
© 2015-2017 Eugeny Brychkov
4
9
10
8
Figure 3. GR8NET view from the top
Top view (fig. 3):
8. Network activity LED, green;
9. Connection speed LED, on = 100 Mbit, off = 10 Mbit;
10. Hole in the cartridge to insert Micro-SD card.
11
Figure 4. GR8NET view from the rear
Rear view (fig. 4):
11. Serial number/MAC address. Use light highlighting the text to see through the
semi-transparent casing.
© 2015-2017 AGE Labs
Page 18 of 156
© 2015-2017 Eugeny Brychkov
6
Figure 5. GR8NET view from the bottom
Micro-switches at the bottom of the cartridge (fig. 5) should be dealt with caution –
when changing them please use thin, but not sharp object, and do not press towards the
switch but rather in the direction of the switch thumb movement.
2.2. Initialization messages and sequence
To better understand adapters’ functionality let’s look into how it initializes, and
where you should look at to find vital information about adapter’s configuration and
features.
Slot ID
adapter is
installed in
Adapter #
Adapter memory
allocation
Flash chip
firmware
datecode
Adapter
flags
NTP time
RTC chip
updated
Default
host
GR8NET Disk
ROM messages
GR8NET initialization screen
© 2015-2017 AGE Labs
Page 19 of 156
© 2015-2017 Eugeny Brychkov
The following items are displayed on the GR8NET initialization screen:
• Firmware datecode: the date flash chip firmware was assembled, in the
example above the date is 05th of November 2016. With every release of
firmware this manual is being updated, thus please look for updates regularly
at http://www.gr8bit.ru site;
• Slot ID is the slot where adapter is installed in RDSLT format – with MSB being
set if slot is expanded, bits 1:0 indicating primary slot number and bits 3:2
indicating secondary slot number (e.g. 86 means slot 2.1);
• Adapter # is selection of the micro-switch at the bottom of cartridge, please
refer to Operating in multi-adapter environment;
• Adapter memory allocation shows how 1MB of RAM is allocated: it could be
1024K for mapper 0 (whole adapter RAM is used for GR8NET purposes), or
512K+512K in mapper 8 (512K is used for GR8NET purposes, and 512K is used
as mapped RAM);
• Adapter flags identify status of the adapter, see System registers. Disk ROM
enable bit will be set to the state of disk subsystem status of the previous
adapter initialization, and will be appropriately changed during further Disk
ROM initialization;
• NTP time is the time returned by the NTP server (if request was successful).
RTC updated checkmark symbol means that RTC chip time is updated with NTP
server time. See Managing system time;
• Default host is the one set by NETSETHOST command, and is being resolved
during startup;
• For details on Disk ROM initialization and operation please refer to Using
integrated MSX-DOS.
The following picture shows detailed GR8NET mode initialization sequence. During
cold boot (after power cycle or hard reset) GR8NET firmware is initialized in mapper mode
0, and depending on the setting of target mapper mode (see Setting memory mapper),
adapter will reboot machine in required mapper configuration. Most useful target mapper
configuration is mapper mode 8, when half of GR8NET onboard RAM (512K) are dedicated
for GR8NET, and another half (512K) are configured as mapped RAM for the machine.
Note that to operate in mapper mode 8 GR8NET adapter must be installed in primary
slot, because GR8NET internally performs expansion of the primary slot and presents its
functions in subslot 0 and mapped RAM in subslot 1 of the slot it is installed in.
To cancel re-initialization of the adapter in target mapper configuration
during the cold boot, press arrow down key on the keyboard before adapter
started initialization, and hold the key until adapter displays network
configuration information. This action will force adapter to continue with mapper
mode 0.
Such method was deliberately chosen to allow user cancelling adapter reconfiguration
using MSX keyboard if installation is not supported, or adapter needs reconfiguration which
can be done in mapper mode 0.
Ø
© 2015-2017 AGE Labs
Page 20 of 156
© 2015-2017 Eugeny Brychkov
GR8NET mode initialization sequence
Adapter automatic reconfiguration from
mapper mode 0 to target mode 8 with
special register set in GR8NET bank 0
© 2015-2017 AGE Labs
Messages of adapter in mapper mode 8
(512K+512K), Disk ROM enabled and disk
image present in GR8NET RAM
Page 21 of 156
© 2015-2017 Eugeny Brychkov
3. Using GR8NET in BASIC
Setup and management of the adapter is performed using CALL statements, and
standard BASIC file input/output operators.
Extended BASIC statements are used to configure and manage adapter’s operation.
When using listed CALL statements, you can leave space between keyword CALL and
command name, but the command name should be typed without spaces.
While command names may look long, you will find that their names are convenient
from their functionality point of view. There’s a group of SET commands, and
corresponding GET commands. CALL statements can not return value, and such division
was decided as best fit for programming user interface with the adapter and internet.
Programmer has 2 sockets at disposal for BASIC file I/O operations, each socket can
operate in TCP, UDP or RAW mode, and operate independently.
3.1. Operating in multi-adapter environment
MSX system may have up to 4 GR8NET adapters installed, they are differentiated by
the switch setting of the adapter. Each installed adapter must have unique number set for
it.
There’s a notion of the default adapter – the GR8NET card which responds to the
CALL and device I/O commands if these commands are missing adapter number
identification in their name. For example, CALLNETGETIP0 will explicitly query adapter #0,
while CALLNETGETIP will query default adapter. If system has only one GR8NET adapter,
after reset it will be configured as the default adapter.
Addressing adapters using their numbers may not provide required flexibility, thus
two statements were introduced in order to change default adapter number and operate
target adapter without adapter number following the statement.
NETGETDA
Get default adapter number and list of active adapters
Format
CALL NETGETDA(A,B)
Arguments
Argument A will receive current default adapter number (0-3), argument B will receive
bitmap status of the adapters installed.
Bit Adapter
0
Adapter #0 status
1
Adapter #1 status
2
Adapter #2 status
3
Adapter #3 status
If respective bit is set, adapter is active in the system and you can set it as default adapter
and use its device I/O resources or manage it using CALL statements. If you believe
adapter is physically present in machine, but respective bit in argument B is reset, this may
© 2015-2017 AGE Labs
Page 22 of 156
© 2015-2017 Eugeny Brychkov
mean that adapter under consideration is faulty or was deactivated during initialization
process (after hardware reset) due to conflict with another adapter.
Any of arguments may be omitted. If statement is executed without arguments it displays
information onto the screen.
Example
CALLNETGETDA
Default: 03
Present: 3x1x
NETSETDA
Set default adapter number
Format
CALL NETSETDA(A)
Argument
Argument A is mandatory, it should have value 0-3 and identify active adapter in the
system (see NETGETDA).
Usage
After executing this command for e.g. adapter 2 “CALLNETSETDA(2)” application can use
e.g. “CALLNETGETIP” (without adapter number identification) to manage adapter #2.
Example 1 – code is fixed to adapter numbers 2 and 3
10 CALLNETSETHOST2(“www.google.com”):REM adapter 2
20 CALLNETSETHOST3(“www.gr8bit.ru”):REM adapter 3
Example 2 – code is fixed to adapter numbers 2 and 3
10 CALLNETSETDA(2):CALLNETSETHOST(“www.google.com”):REM adapter 2
20 CALLNETSETDA(3):CALLNETSETHOST(“www.gr8bit.ru”):REM adapter 3
Example 3 – initialization of adapter is not hardwired to its number and defined by the
variable
10 DATA “www.google.com”,”www.gr8bit.ru”
20 RESTORE 10
30 FOR I=2 TO 3:READ A$:CALLNETSETDA(I): CALLNETSETHOST(A$):NEXT I
© 2015-2017 AGE Labs
Page 23 of 156
© 2015-2017 Eugeny Brychkov
3.2. Built-in helper
By typing CALL NET or CALL NETHELP, or CALL DSK or CALL DSKHELP, you will have
access to the helper system of the adapter. NET and DSK are two command branches
implemented in the cartridge, helper works same way for both NET and DSK, thus
everything described for NET below will apply to DSK.
Please note specific rules for invoking helper:
• CALL NET will cause all adapters display their help screen, and there will be Syntax
error after all adapters will respond (fig. 6a);
• CALL NETHELP will cause default adapter to display its help. By looking at the helper
output, you will have an idea which adapter is reporting and thus is set as default
(e.g. #1);
• CALLNETHELP1 will require adapter #1 to respond with its helper. If adapter with
indicated number is not active in the system, Syntax error is given.
By appending the name of the command to the HELP command, you get detailed
description about command in question:
• CALLNETHELPSETHOST will print default adapter’s help for the SETHOST command;
• CALLNETHELP3SETHOST will cause adapter #3 print its helper for SETHOST
command available for it. Note that number of adapter is following HELP keyword
rather than appears at the end of the command.
(a) CALL NET output
© 2015-2017 AGE Labs
(b) CALL NETHELPSETHOST output
Figure 6. Helper screens
Page 24 of 156
© 2015-2017 Eugeny Brychkov
3.3. Diagnostic mode
If something fails during networking operation, you have an option to turn diagnostic
on to see at which step exactly communication fails. In diagnostic mode firmware will print
steps it performs, and you will get an idea the place for troubleshooting.
NETDIAG
Turn built-in diagnostic output on or off
Format
CALL NETDIAG (V)
Arguments
Argument can be numerical variable or constant
Usage
If V is 0, diagnostics are turned off, if non-zero (for example 1), diagnostics are turned on.
3.4. Overall subsystem status
If you need quick overview of the subsystem properties, use CALL NETSTAT
command, which will display all effective IP addresses and status information.
NETSTAT
Display status information about the adapter
Format
CALL NETSTAT
Usage
DHCP host IP address will be displayed only if subsystem was initialized in DHCP mode.
Mode is a bitmap diagnostic byte, bit 0 is set if adapter works in DHCP mode, otherwise in
fixed IP address configuration mode, bit 6 is set if diagnostic mode is turned on, and bit 7
is set if there was error during adapter initialization. Number displayed in the brackets is
adapter number which is reporting the status.
Example
CALL NETSTAT
IP:
192.168.1.44
Mask:
255.255.255.0
GW:
192.168.1.1
DNS:
192.168.1.1
DHCP:
192.168.1.1
MAC:
10:16:00:04:05:06
Mode:
41 (#3)
GR8NET is having 1MB of onboard buffer memory, but not whole memory space may
be available for applications. In case GR8NET Disk subsystem is activated, RAM has space
allocated for RAM disk – 720K in mapper 0 mode and 360K in mapper 8 mode. Variable
identifying free RAM space is called RAM top and can be obtained by NETVARMTOP.
© 2015-2017 AGE Labs
Page 25 of 156
© 2015-2017 Eugeny Brychkov
3.5. Memory manager
GR8NET is having relatively large 1MB onboard RAM, and there’s a simple mechanism
for its management. There’re three variables related to RAM allocation, all three indicate
logical page numbers.
• RAMMAX: maximal number of logical pages available for access using GR8NET
mapper;
• DSKLPG: RAM disk image starting page;
• RAMTOP: number of logical pages available for user data;
• UPRAMS: user protected RAM start logical page.
In any case, the following formula should be true:
UPRAMS ≤ RAMTOP ≤ DSKLPG ≤ RAMMAX.
Logical page #
RAMMAX
…
…
DSKLPG
…
SAMLPG
…
…
RAMTOP
…
…
UPRAMS
…
…
0
Usage
Maximal page # available in current mapper configuration
RAM area reserved for the RAM disk image, maximal size of image for
current mapper can be obtained by DSKCFG statement
Y8950 sample RAM space reserved by GR8NET firmware. If nothing
was reserved, equals to DSKLPG
RAM area reserved by the GR8NET firmware. If nothing was reserved,
RAMTOP equals to SAMLPG
RAM area reserved by user. Manageable by SETMMV statement
RAM available for user operations and NETBLOAD/NETBROWSE
Only UPRAMS variable is user-managed. Please refer to Using GR8NET disk
subsystem chapter for detailed explanation of DSKLPG variable (RAM area allocated for
RAM disk).
© 2015-2017 AGE Labs
Page 26 of 156
© 2015-2017 Eugeny Brychkov
Examples of memory allocations in different mapper modes
GR8NET mapper 0
RAMMAX=80h, DSKLPG=RAMTOP=UPRAMS=26h
Page #
7F
…
With RAM disk
Purpose
Reserved for 720K/360K disk
image
RAMMAX=DSKLPG=RAMTOP=UPRAMS=80h
Page #
7F
Without RAM disk
Purpose
1,048,576 bytes of
available for BLOAD
applications
RAM
and
…
26
25
…
0
311,296
bytes
of
available for BLOAD
applications
RAM
and
0
GR8NET mapper 8
RAMMAX=40, DSKLPG=RAMTOP=UPRAMS=13
Page #
7F
…
40
3F
…
13
12
…
0
RAMMAX=DSKLPG=RAMTOP=UPRAMS=40
With RAM disk
Purpose
N/A (these pages are used as
mapped RAM)
Reserved for 360K disk image
Page #
7F
…
40
3F
…
155,648
bytes
of
available for BLOAD
applications
RAM
and
Without RAM disk
Purpose
N/A (these pages are used as
mapped RAM)
524,288
bytes
of
available for BLOAD
applications
RAM
and
0
User protected RAM start and area are not indicated on the diagrams above. UPRAMS
is a page number, indicating top of the RAM for system utilities like NETBLOAD and
NETBROWSE. For example, in mapper mode 8 with RAM disk if you set UPRAMS variable
to 10h, NETBLOAD and NETBROWSE, if trying to load data more than 131,072 bytes (16
logical pages, 0 to 15) in size, will terminate with error and pages 10h-12h (3 pages of
24,576 bytes, between UPRAMS and RAMTOP) will be unmodified. At the same time,
application may manage this user protected space using memory move statements like
LDBUF and LDRAM.
© 2015-2017 AGE Labs
Page 27 of 156
© 2015-2017 Eugeny Brychkov
NETGETMMV
Get memory manager values
Format
CALL NETGETMMV (U, T, D, M, S)
Argument
All arguments are variables. Any argument may be omitted, but at least one present
Usage
Variable U will receive logical page number of user-protected area start (UPRAMS), T will
get RAM top (RAMTOP), D will get RAM disk image start page (DSKLPG), M will get
maximal number of pages in current mapper configuration (RAMMAX), and S will get
starting page of the Y8950 sample RAM (SAMLPG). Size of current sample RAM can be
calculated as (D-S). See also NETOPL command.
NETSETMMV
Set memory manager value
Format
CALL NETGETMMV (U)
Argument
Argument is variable or constant
Usage
It is possible to set UPRAMS – user-protected RAM start page – with memory management
command. Other variables (RAM top and RAM maximum) are managed by the GR8NET
firmware, and are defined during GR8NET initialization.
© 2015-2017 AGE Labs
Page 28 of 156
© 2015-2017 Eugeny Brychkov
3.6. Setting up the adapter
There’re two modes adapter can operate in: DHCP mode and fixed IP address mode.
DHCP mode is configured by the CALL NETDHCP command, or on PC startup if this mode
was selected as default. If DHCP server is missing or did not reply, adapter configures itself
in fixed IP address mode. It is advised to have single DHCP server on the subnetwork, if
there’re multiple DHCP server, adapter will accept configuration from the first which replied
to the DHCP discovery packet.
Default mode is preserved in adapter’s flash memory, and you can update it using
CALL NETSAVE command.
Figure 7. Configuration logic with MSX-BASIC statements
© 2015-2017 AGE Labs
Page 29 of 156
© 2015-2017 Eugeny Brychkov
3.6.1. Getting effective configuration information
In case of issues with device, the following commands should be used to get effective
configuration of the internetworking system. IP address, mask and gateway information
come directly from the networking chip.
NETIP
Get current configured adapter’s IP address
Format
CALL NETIP (A, B, C, D)
Arguments
Four arguments are variables; any can be omitted, but at least one present
Usage
Variables receive octets of the currently configured IP address, variable A being highest
octet and variable D lowest octet. Variables supplied will keep their original type. If
arguments are omitted, command displays IP address onto the screen in dot-decimal
notation.
Example
CALL NETIP (A, B, C, D)
CALL NETIP (A, , , D)
CALL NETIP
PRINT A;B;C;D
PRINT A;D
192.168.1.44
192 168 1 44
192 44
Ok
Ok
Ok
NETMASK
Get current configured adapter’s subnetwork mask
Format
CALL NETMASK (A, B, C, D)
Arguments
Four arguments are variables; any can be omitted, but at least one present
Usage
Variables receive octets of the currently configured subnet mask, variable A being highest
octet and variable D lowest octet. Variables supplied will keep their original type. If
arguments are omitted, command displays mask onto the screen in dot-decimal notation.
Example
CALL NETMASK (A, B, C, D)
CALL NETMASK (A, , , D)
CALL NETMASK
PRINT A;B;C;D
PRINT A;D
255.255.255.0
255 255 255 0
255 0
Ok
Ok
Ok
© 2015-2017 AGE Labs
Page 30 of 156
© 2015-2017 Eugeny Brychkov
NETGW
Get current configured gateway
Format
CALL NETGW (A, B, C, D)
Arguments
Four arguments are variables; any can be omitted, but at least one present
Usage
Variables receive octets of the currently configured gateway IP address, variable A being
highest octet and variable D lowest octet. Variables supplied will keep their original type. If
arguments are omitted, command displays gateway’s IP address onto the screen in dotdecimal notation.
Example
CALL NETGW (A, B, C, D)
CALL NETGW (A, , , D)
CALL NETGW
PRINT A;B;C;D
PRINT A;D
192.168.1.1
192 168 1 1
192 1
Ok
Ok
Ok
NETDNS
Get current configured domain name server (DNS) IP address
Format
CALL NETDNS (A, B, C, D)
Arguments
Four arguments are variables; any can be omitted, but at least one present
Usage
Variables receive octets of the currently configured DNS IP address, variable A being
highest octet and variable D lowest octet. Variables supplied will keep their original type. If
arguments are omitted, command displays DNS IP address onto the screen in dot-decimal
notation.
Example
CALL NETDNS (A, B, C, D)
CALL NETDNS (A, , , D)
CALL NETDNS
PRINT A;B;C;D
PRINT A;D
192.168.1.1
192 168 1 1
192 1
Ok
Ok
Ok
© 2015-2017 AGE Labs
Page 31 of 156
© 2015-2017 Eugeny Brychkov
3.6.2. DHCP mode
DHCP initialization assumes adapter getting its own IP address, subnet mask,
gateway IP address and DNS server IP address from DHCP server configured and running
on the subnetwork. This mode is the easiest for out-of-the-box running of the
internetworking system.
All SET commands related to the fixed IP address configuration mode do not have
effect unless you reconfigure adapter in fixed IP address mode.
NETDHCP
Perform DHCP discovery and dynamic configuration
Format
CALL NETDHCP
Usage
Adapter invalidates current configuration and tries to find local subnet DHCP server. If
communication with DHCP server is successful, server supplied configuration takes effect,
if communication is unsuccessful, then adapter loads fixed IP address configuration, and
exits with “Device I/O error” error condition. This command resets internetworking system.
Ensure closing all open files before issuing it.
© 2015-2017 AGE Labs
Page 32 of 156
© 2015-2017 Eugeny Brychkov
3.6.3. Fixed IP address configuration mode
In fixed IP address configuration mode you can set up all the IP parameters manually.
If you change any related value, it will take effect only after you reinitialize fixed IP
address mode.
NETFIX
Configure fixed IP address information into network system
Format
CALL NETFIX
Usage
Adapter loads fixed IP configuration variables into its operating subsystem and networking
chip. No checking on the information loaded is performed, if fixed configuration does not
work, please check all the variables present in fixed configuration, and variables which are
in effect (configured values). This command resets internetworking systems. Ensure
closing all open files before issuing it.
NETGETIP
Get fixed IP address value
Format
CALL NETGETIP (A, B, C, D)
Arguments
Four arguments are variables; any can be omitted, but at least one present
Usage
Variables receive octets of the fixed IP address configuration mode IP address, variable A
being highest octet and variable D lowest octet. Variables supplied will keep their original
type. If arguments are omitted, command displays fixed IP address configuration mode IP
address onto the screen in dot-decimal notation.
Example
CALL NETGETIP (A, B, C, D) CALL NETGETIP (A, , , D)
CALL NETGETIP
PRINT A;B;C;D
PRINT A;D
5.20.1.11
5 20 1 11
5 11
Ok
Ok
Ok
NETGETMASK
Get fixed IP address mask
Format
CALL NETGETMASK (A, B, C, D)
Arguments
Four arguments are variables; any can be omitted, but at least one present
Usage
Variables receive octets of the fixed IP address configuration mode subnetwork mask,
variable A being highest octet and variable D lowest octet. Variables supplied will keep
their original type. If arguments are omitted, command displays fixed IP address
configuration mode subnetwork mask onto the screen in dot-decimal notation.
© 2015-2017 AGE Labs
Page 33 of 156
© 2015-2017 Eugeny Brychkov
Example
CALL NETGETMASK (A, B, C, D)
PRINT A;B;C;D
255 255 255 240
Ok
CALL NETGETMASK (A, , , D)
PRINT A;D
255 240
Ok
CALL NETGETMASK
255.255.255.240
Ok
NETGETGW
Get fixed IP address mode gateway IP address
Format
CALL NETGETGW (A, B, C, D)
Arguments
Four arguments are variables; any can be omitted, but at least one present
Usage
Variables receive octets of the fixed IP address configuration mode gateway IP address,
variable A being highest octet and variable D lowest octet. Variables supplied will keep
their original type. If arguments are omitted, command displays fixed IP address
configuration mode gateway’s IP address onto the screen in dot-decimal notation.
Example
CALL NETGETGW (A, B, C, D)
CALL NETGETGW (A, , , D)
CALL NETGETGW
PRINT A;B;C;D
PRINT A;D
5.20.1.1
5 20 1 1
5 1
Ok
Ok
Ok
NETGETDNS
Get fixed IP address mode DNS IP address
Format
CALL NETGETDNS (A, B, C, D)
Arguments
Four arguments are variables; any can be omitted, but at least one present
Usage
Variables receive octets of the fixed IP address configuration mode domain name server IP
address, variable A being highest octet and variable D lowest octet. Variables supplied will
keep their original type. If arguments are omitted, command displays fixed IP address
configuration mode DNS IP address onto the screen in dot-decimal notation.
Example
CALL NETGETDNS (A, B, C, D) CALL NETGETDNS (A, , , D) CALL NETGETDNS
PRINT A;B;C;D
PRINT A;D
5.20.1.2
5 20 1 2
5 2
Ok
Ok
Ok
© 2015-2017 AGE Labs
Page 34 of 156
© 2015-2017 Eugeny Brychkov
NETSETIP
Sets fixed configuration IP address value
Format
CALL NETSETIP (A, B, C, D)
Arguments
Four arguments are numerical variables or constants; any can be omitted, but at least one
present
Usage
Sets card’s IP address within fixed IP address configuration block. To make this IP address
in effect, re-initialize with NETFIX command. If position in argument list is omitted, related
octet of IP address is not changed.
Example
CALL NETSETIP (192, 168, 1, 10)
CALL NETSETIP (, , , 15) CALL NETSETIP
Ok
Ok
Illegal function call
Ok
NETSETMASK
Set fixed configuration IP address mask
Format
CALL NETSETMASK (A, B, C, D)
Arguments
Four arguments are variables; any can be omitted, but at least one present
Usage
Sets card’s mask within fixed IP address configuration block. To make this mask in effect,
re-initialize with NETFIX command. If position in argument list is omitted, related octet of
IP address is not changed.
Example
A=128
CALL NETSETMASK (255, 255, 255, A)
Ok
CALL NETSETMASK (, , , 128)
Ok
CALL NETSETMASK
Illegal function call
Ok
NETSETGW
Set fixed configuration gateway IP address
Format
CALL NETSETGW (A, B, C, D)
Arguments
Four arguments are variables; any can be omitted, but at least one present
Usage
Sets card’s gateway IP address within fixed IP address configuration block. To make this
address in effect, re-initialize with NETFIX command. If position in argument list is omitted,
related octet of gateway IP address is not changed.
Example
CALL NETSETGW (192, 168, 1, 1)
CALL NETGETGW (, , , 1)
CALL NETGETGW
Ok
Ok
Illegal function call
Ok
© 2015-2017 AGE Labs
Page 35 of 156
© 2015-2017 Eugeny Brychkov
NETSETDNS
Set fixed configuration DNS IP address
Format
CALL NETSETDNS (A, B, C, D)
Arguments
Four arguments are variables; any can be omitted, but at least one present
Usage
Sets card’s DNS IP address within fixed IP address configuration block. To make this
address in effect, re-initialize with NETFIX command. If position in argument list is omitted,
related octet of DNS IP address is not changed.
Example
CALL NETSETDNS (5, 20, 1, 2) CALL NETSETDNS (, , , 2)
CALL NETSETDNS
Ok
Ok
Illegal function call
Ok
3.6.4. Managing configurations
When GR8NET adapter initializes, it uses information stored in its ROM configuration
page (logical page BF), mirroring these initial values into the configuration RAM (logical
page FF). In addition to the actions described in 1.4.2 and 1.4.3, you can perform actions
copying DHCP configuration into fixed IP address configuration and updating the
configuration information in ROM so that next time adapter is initialized the new
configuration to take effect.
NETCDTOF
Copy DHCP configuration into fixed IP address configuration
Format
CALL NETCDTOF
Usage
If you adapter configured using DHCP properly and you want to use clone of DHCP
configuration you copy it into fixed IP address configuration variables and tune them.
Variables copied are: IP address, mask, gateway and DNS server IP addresses.
Example
CALL NETCDTOF
CALL NETSETIP(192,168,1,145)
CALL NETFIX
NETSAVE
Save current configuration into ROM configuration page
Format
CALL NETSAVE
Usage
This command updates the following ROM variables: fixed IP address configuration,
adapter operating mode (“Mode”, “netmode”, see NETSTAT) and default URI structure. It
also writes MAC address back, but it is not advised to change it (through debugger or
memory editor) because it may then cause device malfunction or conflict on the network.
© 2015-2017 AGE Labs
Page 36 of 156
© 2015-2017 Eugeny Brychkov
3.6.5. Managing system time
When initializing, GR8NET tries to reach NTP (network time protocol) server to
synchronize system time. If RTC chip is present, firmware updates RTC chip stored time if
specific flag is set in GR8NET configuration. If RTC chip is not present in the system,
firmware just displays current date and time onto the screen.
The following scheme is used to get NTP server’s IP address:
• Fixed IP configuration: if default NTP server IP address set by NETSETNTP is
starting with 0 (0.x.x.x), card tries obtaining IP address of host name set by
NETSETTSHN using DNS address set by NETSETDNS; if default NTP server IP
address starts with non-zero, then this default IP address is used for NTP server
query;
• DHCP mode: if DHCP server responds to DHCP request with NTP server’s IP address
(DHCP option 42), this returned IP address will be used; if DHCP server does not
give option with NTP server’s IP address, then card tries obtaining IP address of
host name set by NETSETTSHN using address of DNS returned by DHCP server.
NETNTP
Get effective configuration of NTP server
Format
CALL NETNTP (A, B, C, D, TZF)
Arguments
A-D are variables receiving effective NTP server IP address octets
TZF is current time zone and update flag
Usage
With this command application gets effective NTP server address, the address used for
time configuration (even if unsuccessful). TZF has the following format:
7
6
5
4
3
2
1
0
TUF
Time zone definition
• TUF is time update flag. If set, forces GR8NET to synchronize system’s RTC (if present)
with NTP server if NTP server query was successful
• Time zone definition is signed 7-bit number, identifying time zone in 15-minute quanta.
o Value of 0 defines UTC time zone, thus zero time shift from time reported by
NTP server;
o Value of -64 (040h) means time shift of -16 hours (15 minutes * 64);
o Value of +63 (03fh) means time shift of +15:45.
NETGETNTP
Get NTP server properties within fixed IP address configuration
Format
CALL NETGETNTP (A, B, C, D)
Arguments
A-D are variables getting NTP server IP address octets of fixed IP address configuration
Usage
This IP address will be used in case DHCP server did not respond with NTP server address.
© 2015-2017 AGE Labs
Page 37 of 156
© 2015-2017 Eugeny Brychkov
NETSETNTP
Set NTP server properties within fixed IP address configuration, and time setting flags
Format
CALL NETSETNTP (A, B, C, D, TZF)
Arguments
A-D are variables or constants defining NTP server IP address within fixed IP address
configuration
TZF is update flag and time zone (refer to NETNTP command)
NETTSYNC
Display and synchronize system time
Format
CALL NETTSYNC
Usage
This command displays and synchronizes current system time (if system has RTC chip
installed) using NTP server. It updates NTP server IP address displayed by NETSTAT
command. Note if GR8NET obtains NTP server IP address using DNS, GR8NET may use
different IP addresses for synchronization because 0.pool.ntp.org uses rotation of IP
addresses.
NETSETTSHN
Set time server host name
Format
CALL NETSETTSHN(A$)
Arguments
A$ is string variable or constant of length of 31 or less characters
Usage
Sets time server host name, which will be used in DHCP mode to resolve to NTP server IP
address, and in fixed mode configuration if IP address set with NETSETNTP starts with 0
(0.x.x.x).
NETGETTSHN
Get time server host name
Format
CALL NETGETTSHN [(A$)]
Arguments
A$ is receives host name; if omitted, host name will be printed onto the screen
Usage
This command is used to get time server host name (see NETSETTSHN).
© 2015-2017 AGE Labs
Page 38 of 156
© 2015-2017 Eugeny Brychkov
3.6.6. Updating GR8NET firmware
You can upgrade/re-flash adapter with the firmware, which was previously loaded
into GR8NET card’s RAM buffer. Command will display information about current firmware,
firmware image loaded into RAM and will check compatibility of new firmware with the
version of hardware.
If you are going to update firmware (contents of the flash chip) and configuration of
the FPGA, you should update firmware first, and then update FPGA configuration.
NETFWUPDATE
Update the firmware – contents of the onboard ROM chip
Format
CALL NETFWUPDATE(A)
Argument
If argument A is omitted or is 0, then command will just display information about current
firmware level located in ROM and in RAM.
If bit 0 of argument A is set, command updates configuration area of the ROM chip.
If bit 1 of argument A is set, command updates main image of the firmware;
Usage
To update both areas – main image and configuration area, type CALL NETUPDATE(3). If
areas loaded into RAM will be found to be valid, update will start, otherwise error message
will be displayed. To load image into RAM, you may use CALL NETBROWSE command
locating
valid
image
on
GR8BIT
website.
Image
is
located
at:
http://www.gr8bit.ru/software/firmware/GR8NET/update.bin.
How exactly do I update firmware image in the flash chip using online update?
• Ensure GR8NET is connected to the internet using either DHCP or fixed IP address
modes;
• Use one of the methods to load firmware image:
o CALLNETBROWSE the GR8BIT server to /software/firmware/GR8NET and press
space key on update.bin file to load it into GR8NET RAM;
o CALLNETBLOAD(“http://www.gr8bit.ru/software/firmware/GR8NET/update.bin”)
o CALLNETSETHOST(“www.gr8bit.ru”):CALLNETSETPATH(“/software/firmware/GR
8NET”):CALLNETSETNAME(“update.bin”):CALLNETBLOAD
• After successful image load run CALLNETFWUPDATE(3). It will validate the image, and
will request your approval to continue.
• After image is loaded into the flash chip, machine will reboot.
• New image is ready for use, and GR8NET will start using it.
This video by Alex Mena https://youtu.be/05iwl8oPKW8 shows online GR8NET firmware
update process.
© 2015-2017 AGE Labs
Page 39 of 156
© 2015-2017 Eugeny Brychkov
3.7. Using built-in HTTP-related commands
There’re several built-in functions, they include accessing remote resources using
HTTP protocol – in other words, downloading information from web servers. One of such
commands is NETBLOAD.
NETSETHOST
Set remote host name, and perform simple DNS query if needed
Format
CALL NETSETHOST (N$ | A, B, C, D)
Arguments
Either string variable or constant; or four numerical variables or constants (any can be
omitted, but at least one present)
Usage
Sets remote host name, or converts network URI structure to SD-card URI structure.
• If string is used as an input and string is not empty, adapter uses DNS server to
perform name resolution into IP address. String should be without protocol definition
(e.g. http://) and without trailing slash. Maximal string length is 31 characters. If
resolution is unsuccessful, “Illegal function call” error is given.
• If string is empty, then when calling NETBLOAD it will access SD-card path rather than
network path. Be sure to set appropriate SD-card path and file name before proceeding
to NETBLOAD.
In case IP address is entered, host name string is emptied, and in some cases web access
may be unsuccessful if remote web server requires valid “host:” HTTP header.
Example
CALL NETSETHOST (“www.gr8bit.ru”)
Ok
CALLNETSETHOST(“”)
Ok
CALL NETSETHOST (195, 208, 1, 126)
Ok
(NETBLOAD will not work, web server
requires header “host: www.gr8bit.ru”)
CALL NETSETHOST
Illegal function call
Ok
NETSETPATH
Set remote resource’s path
Format
CALL NETSETPATH (N$)
Arguments
String variable or constant
Usage
Sets resource’s path. Path is absolute, without trailing slash. Maximal length of the string is
255 characters. The path can address network resource (if URI structure is network one),
or resource on SD-card (if URI structure if SD-card one). Use NETGETHOST to identify
current URI structure type
Example
A$=”/software/roms”
CALL NETSETPATH (A$)
Ok
© 2015-2017 AGE Labs
CALL NETSETPATH (“/software/roms”)
Ok
Page 40 of 156
CALL NETSETPATH
Illegal function call
Ok
© 2015-2017 Eugeny Brychkov
NETSETNAME
Set remote resource’s file name
Format
CALL NETSETNAME (N$)
Arguments
String variable or constant
Usage
Sets remote resource’s file name. Maximal length of the string is 63 characters. The name
can address network resource (if URI structure is network one), or resource on SD-card (if
URI structure if SD-card one). Use NETGETHOST to identify current URI structure type
Example
A$=”vkiller.rom”
CALL NETSETNAME (A$)
Ok
CALL NETSETNAME (“vkiller.rom”)
Ok
CALL NETSETNAME
Illegal function call
Ok
NETSETQSTR
Set query string for remote resource processing
Format
CALL NETSETQSTR (N$)
Arguments
String variable or constant
Usage
Query string must start with question mark. Maximal length of the string is 63 characters.
Query string has effect only for network URI structure type
Example
A$=”?forumtopic=13”
CALL NETSETQSTR (A$)
Ok
CALL NETSETQSTR (“?forumtopic=13”)
Ok
CALL NETSETQSTR
Illegal function call
Ok
During HTTP request construction query string is just added after the file
name, thus in total both strings may make up to 126 characters. If you
have very long file name, you can use query string splitting file name into
two parts which fit into file name and query string limitations.
NETGETHOST
Get remote host name and IP address
Format
CALL NETGETHOST (F, N$ | A, B, C, D)
Arguments
F is numerical variable, N$ is string variable, A, B, C, D are numerical variables. Any
argument can be omitted
Usage
Gets remote host name or IP address. F is the byte flag having the following meaningful
bits:
• bit 0 reset for network URI structure, set for SD-card URI structure;
• bit 1 reset if hostname/file properties are not valid, set if they are valid.
© 2015-2017 AGE Labs
Page 41 of 156
© 2015-2017 Eugeny Brychkov
For network URI structure, N$ will receive host name; for SD-card URI structure N$ will be
empty string.
If numerical variables are supplied, they get octets of the IP address of remote host in
case URI structure is network one, otherwise displays Illegal function call.
If all arguments are omitted, displays information about remote host onto the screen.
Example
CALL NETGETHOST (F,A$)
PRINT F;A$
2 www.gr8bit.ru
Ok
CALL NETGETHOST (, A, B, C, D)
PRINT A;B;C;D
195 208 1 126
Ok
CALL NETGETHOST
www.gr8bit.ru (195. 208.1.126)
Ok
NETGETPATH
Get remote resource’s path
Format
CALL NETGETPATH (N$)
Arguments
String variable
Usage
Gets remote resource’s path. If argument is omitted, prints path onto the screen
Example
CALL NETGETPATH (A$)
PRINT A$
/software/roms
Ok
CALL NETGETPATH
/software/roms
Ok
NETGETNAME
Get remote resource’s file name
Format
CALL NETGETNAME (N$)
Arguments
String variable
Usage
Gets remote resource’s file name. If argument is omitted, prints file name onto the screen
Example
CALL NETGETNAME (A$)
PRINT A$
vkiller.rom
Ok
CALL NETGETNAME
vkiller.rom
Ok
NETGETQSTR
Get query string set up for remote resource
Format
CALL NETGETQSTR (N$)
Arguments
String variable
© 2015-2017 AGE Labs
Page 42 of 156
© 2015-2017 Eugeny Brychkov
Usage
If argument is omitted, prints query string path onto the screen
Example
CALL NETGETQSTR (A$)
PRINT A$
?forumtopic=13
Ok
CALL NETGETNAME
?forumtopic=13
Ok
NETSETPORT
Set communication port numbers in the default URI structure
Format
CALL NETSETPORT (A, B)
Arguments
A and B are variables of constants
If B is 0 (default setting), then dynamic port number is used (recommended)
Usage
A is remote port number for communication (e.g. 80 for web server), B is local source port.
Command does not check validity of the ports. Please ensure that for generic HTTP
communication you use port number above number 49152.
Example
A=80
CALL NETSETPORT (A,50000)
Ok
CALL NETSETPORT (80)
Ok
CALL NETSETPORT
Illegal function call
Ok
NETGETPORT
Get communication port numbers
Format
CALL NETGETPORT (A, B)
Arguments
A and B are variables
Usage
Variable A gets remote port number for communication (e.g. 80 for web server), B gets
local source port number. If arguments are omitted, prints port numbers onto the screen
Example
CALL NETGETPORT (,B)
PRINT B
-15536
Ok
© 2015-2017 AGE Labs
CALL NETGETPORT
Dest: 80
Src: 50000
Ok
Page 43 of 156
CALL NETGETPORT
Dest: 80
Src: 0 (dynamic)
Ok
© 2015-2017 Eugeny Brychkov
3.8. Using NETBLOAD command
NETBLOAD command loads binary data from the remote server using HTTP protocol,
or from installed SD-card. You have to supply the following information for NETBLOAD to
succeed:
• Bloading from network:
o NETSETHOST » valid host name or IP address; if hosting server has multiple
web server names configured for it, you will have to set up host name and
ensure successful IP address resolution;
o NETSETPATH » valid path to the remote resource;
o NETSETNAME » valid remote file name; if name is empty network operation
will try to return folder contents as returned by web server;
o NETSETQSTR » valid query string;
o NETSETPORT » valid port numbers: remote and local;
o Properly configured GR8NET adapter with its IP address, subnet mask,
gateway, DNS server IP address.
• Bloading from SD-card:
o Have SD-card installed with FAT32 or FAT16 file system on it;
o NETSETHOST » to set up SD-card URI structure type;
o NETSETPATH » set path on the SD-card;
o NETSETNAME » set file name; if file name is empty, directory image will be
loaded.
File size to download should not exceed size of the buffer available under user
protected RAM (UPRAMS), otherwise it will be truncated and NETBLOAD will finish with
error. If download fails, use NETDIAG command to turn on diagnostic output and track
NETBLOAD command execution, and NETCODE command to find out error code and HTTP
return code.
For information about URI structure and URI string, refer to URI structure chapter.
NETBLOAD
Load binary file from the remote web server using HTTP
Format
CALL NETBLOAD (P$, A, PG, ADDR)
Arguments
P$ is URI string to the remote resource (use SDC:// device for SD-card)
A is byte variable or constant
PG is starting logical page number
ADDR is starting page address in GR8NET bank 1 area (6000-7FFF)
Usage
By default NETBLOAD takes structure URI managed by the NETSETHOST, NETSETPATH,
NETSETNAME and NETSETQSTR commands, however if P$ is supplied, it overrides specific
parts of the URI, or even changes its type to SD-card structure.
© 2015-2017 AGE Labs
Page 44 of 156
© 2015-2017 Eugeny Brychkov
Value of A makes sense for binary executables only (files which are created by BSAVE
having 7-byte header in them). If A is 2, executable data loaded will be moved to location
indicated by the header and will be executed; if A is 1, then executable data will be loaded
into respective location but will not be executed. If A is 0 then data will not be loaded into
respective location and will not be executed. If A is omitted, value 0 is assumed.
PG:ADDR value set identify offset to start loading data to. PG is logical page number in
range 0…07Fh, and ADDR is CPU RAM space within GR8NET bank 1 (6000h-7FFFh) where
page number PG will be presented during data load start. If file will not fit into the RAM (it
will overflow to logical page 80h, which is first ROM page) then Device I/O error will be
generated.
Examples
CALLNETBLOAD
will load data, and if it will detect that it is binary no
action will be taken
CALLNETBLOAD(,2)
will load data and if it is binary, move it and execute
CALLNETBLOAD
will use host www.gr8bit.ru, and empty path and file
(“http://www.gr8bit.ru”)
name (will read root of the web server)
CALLNETBLOAD
will load indicated file from indicated path from the
web server defined by NETSETHOST command
(“/software/binary/file.bin”)
CALLNETBLOAD(“file.bin”,2,&h7000) will load indicated file from path set by
NETSETPATH command and web server set by
NETSETHOST command, starting logical page 2 and
GR8NET bank 1 address 7000h (thus data will start
at 2*2000h+1000h=9000h in the GR8NET physical
RAM).
NETVARBSIZE
Get size of bloaded data in bytes
Format
CALL NETVARBSIZE (S)
Arguments
Numeric variable
Usage
After bloading data from remote server and checking for successful completion using
NETCODE, application can obtain size of data bloaded.
© 2015-2017 AGE Labs
Page 45 of 156
© 2015-2017 Eugeny Brychkov
3.9. Using built-in TELNET application
GE8NET firmware has simple implementation of the telnet utility, which can be used
to connect to remote hosts and perform manual tasks in real-time.
NETTELNET
Perform telnet session using TCP
Format
CALL NETTELNET (F)
Arguments
F is variable or constant, if omitted input is assumed to be 0
Usage
Before using telnet, ensure subsystem has remote host’s IP address set up properly (see
CALLNETSETHOST command), and local and remote ports are defined as required (see
NETSETPORT command). Command connects to remote resource using TCP. F is bitmap
flag, its bit 0 if set forces output of locally typed characters onto the local screen, bit 1 if
set instructs telnet not to add LF to each locally typed CR character.
© 2015-2017 AGE Labs
Page 46 of 156
© 2015-2017 Eugeny Brychkov
3.10. Built-in media player
Three formats are supported by the card’s software and firmware:
• Wave files (.WAV) with single audio channel; before being played, file should be
converted to mono (e.g. using VLC player converter). As GR8NET’s output is
monophonic, there’s no need to have two channels in audio stream, and it allows
playing mono audio at higher sampling rates;
• MPEG layer 3 files (MP3); to play this format you will need to have additional MP3
cartridge installed in your system as an output device; MP3 file playback from RAM
buffer is not supported;
• MSX video files (SC2, SC8 and SCC for respective video modes) will only play from
the SD-card because network bandwidth is not enough to provide appropriate
streaming speed for smooth video playback.
3.10.1. Playing WAV or MP3 file from network source
You can play WAV file in two ways: from built-in browser by pressing TAB key on the
directory entry, or by calling NETPLAYWAV from BASIC. It will contact remote server,
identify type of the file, and if it will appear to be valid file, will proceed to playback.
To be identified as WAV file it should have valid RIFF header; to be identified as MP3
file the content should start with ‘I’ (ID3 tag) or byte 0ffh (first 8 bits of MP3 frame).
The utility is using hardware acceleration – PCM function and prefetch directly from
W5100 buffers, which allow proper play of the 8-bit WAV samples at 22050 kHz frequency,
or 16-bit samples at 11025 kHz.
It is advised to select 22050 kHz with 8-bit WAV samples because quality of the
output sound is defined by the sampling rate rather than difference between 8 and 16 bits
in the sample.
Important: if network data stream is delayed, playback will hiccup, causing
unpleasant experience. Ensure minimal delays on the network by having server as close to
GR8NET as possible from timing perspective and remove unneeded traffic from the
network during playback.
Warning: player allows user pressing ESC key to terminate playback. While this is
very useful feature in terms of user interface, TCP connection being used for data
exchange does not assume graceful unilateral exit in the middle of the TCP
data exchange process. While GR8NET sends disconnect request to the
server, it then sends rude connection close request to the server. Server’s
web server sending process may still need to send all data through its
socket, thus, while GR8NET will not be accepting data at its side, server will
have port open, and thus GR8NET application will experience problems when reusing same
source port number after such ungraceful termination of the connection. The workaround
to it is to turn dynamic port allocation on by NETSETPORT statement.
© 2015-2017 AGE Labs
Page 47 of 156
© 2015-2017 Eugeny Brychkov
NETPLAYWAV
Play wave file
Format
CALL NETPLAYWAV (A$)
Arguments
A$ is a string variable or constant identifying URI to the remote file. Argument is
mandatory. If URI provided is missing required parts (e.g. host name, remote port #),
then this information will be obtained from values in default URI structure managed by
NETSETHOST, NETSETPATH, NETSETPORT statements.
Example
CALL NETPLAYWAV(“http://www.somehost.com/somepath/somefile.wav”)
CALL NETPLAYWAV(“somefile.wav”)
3.10.2. Listening to internet radio
Internet radio providers do as simple as send stream of MP3 frames to the connected
client, and technically there’s absolutely no difference between playing MP3 file over
network and playing internet radio stream. You just need to point URI to the right host,
destination port and path to start receiving MP3 frames. For example,
CALL NETPLAYWAV(“http://ic3.101.ru:8000/v13_1”)
will play Russian internet radio called “Relax FM”. List of all stations served by this media
server can be found here.
As you see you will not be able to play internet radio through web browser as you,
most probably, will not be able to open it as web page in GR8NET browser supported
format.
You can still click ESC key to interrupt playback. It may continue for some moments
after cancellation, until MP3 cartridge’s frame buffer depletes.
Note about multicast: multicast does not work properly over the internet, at least in
relation to internet radio transmissions.
3.10.3. Playing WAV or MP3 files from SD-card
Playing media files from the SD-card is very similar to playing them from network, the
only difference is that you use local SDC:// device, which has minimal data transmission
delays, for example
CALL NETPLAYWAV(“sdc:///mypath/myfile.mp3”)
thus playing from SD-card can be considered as more reliable from quality predictability
point of view. If you are going to design application which will use wave or MP3 playback,
the best was would be have media file on the SD-card rather than on the network.
© 2015-2017 AGE Labs
Page 48 of 156
© 2015-2017 Eugeny Brychkov
3.10.4. Playing wave from GR8NET RAM
This feature provides flexible way to play WAV samples in GR8NET RAM, which can
be of various size, various sample rate, size, and which can be dynamically synthesized in
the RAM.
Note: MP3 playback from GR8NET RAM is not supported.
The set of commands described below use GR8NET hardware acceleration – prefetch
from RAM, PCM playback function and controlled interrupt generator, thus you should not
make changes to these hardware functions while wave play functionality is in use. In
addition, commands may use Math-Pack’s BDC-to-integer conversion, changing its input
and thus output values.
Important: command name is NETPLAYBUF, and format of the
respective commands described below deviate from standard.
NETPLAYBUF command must be followed by adapter number (0…3), if
not default adapter should be used, and then by modifier letter
which defines functionality.
Thus to address adapter #2 setting addresses application should issue
NETPLAYBUF2A (and not NETPLAYBUFA2). This mechanism of modifier letter, rather than
additional parameter for the command, was chosen in order to improve speed of
processing. [#] in command descriptions below designate possible one digit number of
adapter being addressed. If this number is omitted, current adapter is assumed.
NETPLAYBUF[#]A
Set up starting buffer address and data size and perform initial buffering
Format
CALL NETPLAYBUFA (PG, ADDR, SIZ)
Arguments
All arguments are mandatory
PG is logical page number and ADDR is pointer within this logical page for wave data start;
SIZ is data size (ensure position does not slip outside of GR8NET 1MB buffer RAM)
Usage
Command calculates absolute starting address and ending address of the wave data, and
sets prefetch function up. Then it fills PCM memory with data (performs initial buffering).
PG should be within 0…&h7F range, ADDR within 6000-7FFF (GR8NET bank 1).
Example
CALL NETPLAYBUF3A (2, &h675F, 20000)
NETPLAYBUF[#]P
Initiates playback of pre-buffered data
Format
CALL NETPLAYBUFP (B, FREQ)
Arguments
B is size of the data: 8 or 16 (bits)
FREQ is frequency in Hertz: 1…65535 Hz
Usage
© 2015-2017 AGE Labs
Page 49 of 156
© 2015-2017 Eugeny Brychkov
This command starts controlled interrupt generator and PCM function to play pre-buffered
PCM data. When PCM buffer depletes, playback starts, thus it is vital to execute
CALLNETPLAYBUFC command before it happens.
Example
CALL NETPLAYBUFP (8, 13200)
NETPLAYBUF[#]C
Continues playback, replenishing PCM buffer from prefetch
Format
CALL NETPLAYBUFP
Usage
This command sets replenishes data from prefetch into PCM buffer RAM. If data space has
ended, or PCM buffer is full, command does nothing.
Use this command in interrupt handler to regularly replenish data so that wave playback
continues without interruptions.
Example
10 ON INTERVAL=40 GOSUB 100
20 CALLNETBLOAD(“sdc:///mywavedata.raw”)
30 CALLNETPLAYBUFA(0,&h6000,573168)
40 CALLNETPLAYBUFP(8,13200):INTERVAL ON
50 CALLNETPLAYBUFS(A):IF A=0 THEN 50 ELSE STOP
100 CALLNETPLAYBUFC:RETURN
NETPLAYBUF[#]S
Get status of the playback
Format
CALL NETPLAYBUFS (S)
Arguments
S must be a variable, returning -1 when PCM playback has ended, and 0 when it is still
running. End of playback is the state when prefetch has no more data, and PCM has
finished playing all its buffer data.
NETPLAYBUF[#]R
Reset playback engine
Format
CALL NETPLAYBUFR
Usage
This command resets PCM function and controlled interrupt generator.
The following algorithm shows flexibility and usefulness of the RAM buffer playback:
1. Application loads data into the GR8NET RAM (e.g. using BLOAD command), for
example data is 8-bit, 16 kHz and size is 500,000 bytes;
2. Runs NETPLAYBUFR to ensure that subsystem is reset;
© 2015-2017 AGE Labs
Page 50 of 156
© 2015-2017 Eugeny Brychkov
3. Runs NETPLAYBUFA (2, &h675F, 500000!) command with arguments stating the logical
page 2 and address 675Fh within GR8NET RAM, and setting full size of data to play.
Command buffers about 32 KB of first data, but does not start its playback;
4. At required time application runs NETPLAYBUFP (8, 16000) to start playback of the
wave data. Command exits immediately.
5. Playback of 8-bit data at 16 kHz will take 0.75 seconds, thus sound is expected to stop
within these 0.75 seconds. BASIC program must, within this time, call
CALLNETPLAYBUFC command to replenish data in PCM buffer; the best way to do it is
using ON INTERVAL GOSUB mechanism, ensuring that this command is called some
time before data in PCM buffer is expected to deplete.
6. To find out if wave data finished playing, application uses NETPLAYBUFS(S) command.
7. Finally, program resets hardware acceleration functions use NETPLAYBUFR command.
3.10.5. Playing video file from SD-card
Since end of March 2017 utility GR8VIDEO.COM is replaced with GR8NET firmware
built-in BASIC command NETPLAYVID. This command supports video files created using
method, described in chapter Making videos for MSX for screen modes 2, 8 and 12.
Mode
VDPs
Scan
Video configuration
Audio
configuration
SCREEN 2
SCREEN 8
T, 3, 5
3, 5
SCREEN 12
5
256 x 192 pixels
X*Y to be not greater than 13,872,
60 Hz
but not less than 11,098 (for
example 136*102)
22050 Hz, 8-bit,
mono
T: TMS99xx, 3: V9938, 5: V9958
Screen 2 (256*192)
Screen 8 (136*102)
Screen 12 (136*102)
Sample videos are located at http://www.gr8bit.ru/software/video/. To prepare video
for playback, use your PC to decompress video and copy it to SD-card.
The NETPLAYVID command will run supported videos on any machine, but you
should mind the limitations:
• If machine is having only 16kB of VRAM, command can play only SCREEN 2 videos, and
will use only single VRAM page thus there will be artifacts visible on the screen;
© 2015-2017 AGE Labs
Page 51 of 156
© 2015-2017 Eugeny Brychkov
•
•
•
•
On Turbo and overclocked machines above 5.37 MHz videos in SCREEN 8 and 12
modes may run faster than expected. Application or user should set nominal machine
clock mode before playing the video;
Playback from the network is not supported;
During playback command switches Turbo-R’s R800 CPU into Z80 mode, and restores
original mode after playback is finished;
After playing SCREEN 2 mode video files, default “blue” MSX palette will be reloaded,
but screen’s foreground, background and border color assignments will be preserved.
NETPLAYVID
Play video file from SD-card
Format
CALL NETPLAYVID (SDU [, SI])
CALL NETPLAYVID (SM)
Argument
The command works in two modes, depending on the type of first argument
Mode 1: first argument is string
SDU is a string constant or variable pointing to the video file on the SD-card, for
example “sdc:///video.sc8” or “sdc:///videos/msxvideos/myvideo.sc2”;
SI bit [0] is screen initialization flag, if set to 1 then screen will not be initialized. If
omitted, value of 0 is assumed;
SM bit [6] is set to force black background and border color in modes 8/12 (effective
for background color only if bit 0 is not set);
Mode 2: first argument is integer
SM bits [3:0] is screen mode to initialize screen with, valid values are 2, 8 and 12;
SM bit [7] is disable screen flag, if set to 1 screen will be disabled for display;
SM bit [6] is set to force black background and border color in modes 8/12.
Usage
The command is split into types for specific purpose so that application can have screen
initialized, then put some its own art into the screen around video display area, and then
call actual video playback.
Application can use BASIC’s SCREEN operator to initialize desired screen mode, but
CALLNETPLAYD(SM) is having several important features: (a) it initializes screen mode as
SCREEN does; (b) it clears both video pages to be used by video player, and (c) it can
disable screen (using BL bit of VDP register 1) so that further VRAM/drawing operations
are not visible to the user. Screen is got enables by the following CALL NETPLAYVID (SDU,
1) command which starts actual video playback.
In video modes 8 and 12, CALLNETPLAYD(SM) initializes video pages with the background
color set by COLOR x, y, z, thus to have black background perform e.g. COLOR 15,0,0
before initializing screen mode. In video mode 2 background and border colors are always
forced to be 0 (black).
Video file name does not indicate format, screen mode or geometry; all these properties
are coded into the video file.
© 2015-2017 AGE Labs
Page 52 of 156
© 2015-2017 Eugeny Brychkov
Typical video playback BASIC program
10 gc=peek(&hf3ea):bc=peek(&hf3eb):color 15,0,0
20 callnetplayvid("sdc:///3do.sc2")
30 callnetplayvid(136)
40 callnetbload("sdc:///hmm3-intro-frame.sc8")
50 callnetbtov(0,0):callnetbtov(1,0)
60 vdp(10)=vdp(10) and 127
70 callnetplayvid("sdc:///hmm3-intro-video.sc8",1)
80 color 15,gc,bc
Get current background and border colors,
set current to 0 (black)
Play video (screen 2 mode)
Initialize screen 8, disable screen output
(136=128+8)
Bload image into GR8NET RAM
Move this image to VRAM’s page 0 and
page 1 so that when pages are alternated
this image appears on both even and odd
video frames
Set 192 lines per screen, display is still
disabled
Start playing screen 8 video, do not reinitialize the screen (1) and enable screen
output (automatically)
Revert back to initial background and
border colors
Note the following:
• CALLNETPLAYVID(SM) uses first RAM buffer page, thus image load must be
performed after screen 8 initialization (otherwise image may be corrupt).
Alternatively, image may be loaded into RAM page 1 or further with
CALLNETBLOAD(“sdc:///mygame/image.sc8”,,1);
• Video player alternates two pages when displaying video, thus take care to load
background image into both video pages, as shown in line 50 above. Screen 2
videos are displayed full screen, thus there can be no images around the video
display area;
• When playing SCREEN 2 videos border and background colors will be automatically
set to 0 (not depending on COLOR operator setting) because color 0 may be
reserved for black, while others may change their palette.
Errors
If there’s error, command terminates with Device I/O error for first mode and Illegal
function call for second mode with:
• NETCODE 2B if there was SD-card read;
• NETCODE 2E if screen mode coded into the file is not supported on the machine;
• NETCODE 20 if there’s no enough VRAM to display the image.
It is the task of application to ensure file will play on the target machine (e.g. using
NETSYSINFO).
Playback can be interrupted by pressing ESC key.
© 2015-2017 AGE Labs
Page 53 of 156
© 2015-2017 Eugeny Brychkov
3.11. Setting memory mapper
GR8NET adapter can function in the following memory mapper modes (see Setting
operating mode and mapper type chapter for more information):
Mode Purpose
Mode
Purpose
Modes 0 – 7: cartridge may be in Mode 8 – 14: cartridge must be in primary slot;
primary or expanded slot
GR8NET with 512K is in subslot 0, 512K mapped RAM
is in subslot 1, Nextor is in subslot 2
0
GR8NET
8
FM-Pak is in subslot 3
1
Plain write-protected 32K
9
Plain write-protected 32K in subslot 3
2
Konami without SCC
10
Konami without SCC in subslot 3
3
Konami with SCC
11
Konami with SCC in subslot 3
4
ASCII 8
12
ASCII 8 in subslot 3
5
ASCII 16
13
ASCII 16 in subslot 3
6
Mirrored ROM
14
Mirrored ROM in subslot 3
7
1 Megabyte mapped RAM 15
Not allowed
Mode is switched by the CALL NETSETMAP command, which sets specified memory
mapper type and reboots machine. Important: 1 MB buffer RAM is not used during
GR8NET adapter initialization, and after soft or hard reset it is kept intact if no other
networking operation is explicitly performed (e.g. BLOAD). Thus you still can issue
NETSETMAP command to start the image. Power cycle erases the data in buffer RAM.
NETSETMAP
Set specified memory mapper type and reboot
Format
CALL NETSETMAP (A, M, MRPD)
Arguments
A is variable or constant identifying mapper type and location of special register set
M is variable or constant, identifying if GR8NET will respond to mapped RAM register ports’
read. Read more about setting this argument in Mapper read flag of the chapter System
registers. Valid values are 0 (read disabled), 1 (read enabled), and 2 (auto-detect, default).
MRP is mapped RAM pending disable bit, value must be 0 (enable) or 1 (disable). When
this value is 1, mapped RAM will be disabled after mapper type is changed.
If argument A is omitted, M is set for current mapper mode.
Important note
Properly designed software will never read mapped RAM mapper ports located at 0fch-0ffh, keeping
track of its changes in its memory or through system. However, some applications are designed the way
they identify size of memory mapper by reading these mapper ports, and will misbehave in case
mapper size does not match information read from the port. Example: system is having built-in 128K
mapper, which has 3 significant bits on data bus. If you will run GR8NET with mapper port read
disabled, application, after writing 0 to port 0fch will read 0e0h, thinking there’re only 128K mapper,
and proceed setting 0e0h as first mapped RAM page. However, if GR8NET mapped RAM is chosen as
© 2015-2017 AGE Labs
Page 54 of 156
© 2015-2017 Eugeny Brychkov
main RAM, in mode 8 (5 significant bits) it will have page 20h set instead of 0, and machine will crash.
One of the applications affected is MSX debugger DBG.COM (DBGE.COM), which will not run if mapper
read is disabled.
Example
(netbload knightmare.rom)
CALL NETSETMAP (1)
(reboot)
CALL NETSETMAP
Missing operand
Ok
(netbload metal gear 2)
CALL NETSETMAP (24, 1)
(switch to mapper 8 with special
register set and respond to mapper
regs reads)
CALLNETSETMAP(27,,1)
(will run Metal Gear 2 with mapper 3 in subslot 3 with GR8NET mapped RAM disabled in subslot 1, and
Nextor available in the system in subslot 2)
NETGETMAP
Get current memory mapper type and some other operating flags
Format
CALL NETGETMAP (I)
Arguments
I is 16-bit variable getting mapper type and flags; its bits 7 to 0 are the value of current
mapper register, and bits 8, 13 and 4 are bits from system mode register.
Example
CALLNETGETMAP
411B M3 (512K+none+Nextor+K5)
Ok
The above output means that GR8NET is having slot expansion internally (mapper mode is 1B = 16+8+3),
operating in mapper mode 3 in subslot 3 (Konami 5), has Nextor in subslot 2, has mapped RAM disabled
(“none”, bit 6 is set 411B).
NETTGTMAP
Set target memory mapper configuration to switch to at the startup
Format
CALL NETTGTMAP (A [, M])
Arguments
See NETSETMAP command
Usage
The difference between NETTGTMAP and NETSETMAP is that former will cause adapter to
restart machine in target mapper mode when machine cold-starts. The values set by
TGTMAP is preserved by NETSAVE command to become in effect on next cold boot.
© 2015-2017 AGE Labs
Page 55 of 156
© 2015-2017 Eugeny Brychkov
3.12. Other utilities
GR8NET has some other useful utilities for developer and programmer to run and use
within development and debugging process. They include dumping data from buffer RAM,
calculating checksum and transferring data between conventional RAM and adapter’s
buffer RAM.
NETDUMP
Dump data from adapter’s buffer RAM
Format
CALL NETDUMP (P, A, C)
Arguments
All arguments are variables or constant and are mandatory
Usage
P is the logical page number to switch to in GR8NET bank 1 (6000-7FFF) for dumping, A is
starting address, and C is byte count. You can dump any location of the memory visible to
the CPU (see fig. 8). Dumping output will adjust to the width of the screen. Maximal
dumping bytes per line is 16. Warning: be wary about dumping of special registers’
prefetch data registers as their reading will cause prefetch pointer to change according to
number of reads of the register.
Figure 8. NETDUMP command output
NETLDBUF
Load data from main memory to adapter’s buffer RAM
Format
CALL NETLDBUF (P, BA, C, RA [, M])
Arguments
All arguments are variables or constant, start of chunk (BA) and end of chunk (BA+C)
should reside in the GR8NET bank 1(6000-7FFF)
Usage
Loads data from main RAM pointed by RA into the adapter’s buffer RAM page P starting
address BA. Whole transfer should remain within buffer RAM (BA+C≤7FFF). You can
© 2015-2017 Eugeny Brychkov
© 2015-2017 AGE Labs
Page 56 of 156
transfer only to single buffer RAM page with single LDBUF command. Argument M, if set,
causes change of the mapper type to M and machine reboot (if change is performed to
mappers 7 or 8, mapped RAM register read bit it detected automatically). Value of 255 for
M is reserved.
Example: BASIC program called MAPLOAD.BAS to load 128kBytes ROM image divided into
8*16kBytes chunks into buffer RAM
10
20
30
31
40
definta-z:INPUT"FILE W/O EXTENSION";A$
fori=0to7:f$=a$+".C"+chr$(i+48):print"Loading #";str$(i);": ";:bloadf$
callnetldbuf(i*2,24576,8192,&h9001):callnetrchks(i*2,24576,8192,a):PRINTHEX$(A);" ";
callnetldbuf(i*2+1,24576,8192,&hb001):callnetrchks(i*2+1,24576,8192,a):PRINTHEX$(A)
nexti:print"Load complete"
After this BASIC program completes, issue CALLNETMAP(2) to restart machine and start
execution of the loaded ROM image.
NETLDRAM
Un-load data from adapter’s buffer RAM to main memory
Format
CALL NETLDRAM (P, BA, C, RA)
Arguments
All arguments are variables or constant and are mandatory, BA=6000-7FFF
Usage
Loads data from the adapter’s buffer RAM page P (0-3E) starting address BA into main
RAM pointed by RA. Whole transfer source data should remain within buffer RAM
(BA+C≤7FFF). You can transfer only from single buffer RAM page with single LDBUF
command.
NETRCHKS
Calculate simple 16-bit checksum on the buffer RAM contents
Format
CALL NETRCHKS (P, A, C[, R])
Arguments
P, A and C are variables or constants, R is variable
Usage
Calculates simple 16-bit checksum for the data block setting page P in GR8NET bank 1
beforehand, from address A with byte count C. If variable R is supplied, puts this
checksum into this variable. If R is not supplied, prints checksum onto the screen.
Example: see NETLDBUF’s MAPLOAD.BAS for implementation of this command
© 2015-2017 AGE Labs
Page 57 of 156
© 2015-2017 Eugeny Brychkov
NETGETMEM
Read 4 consecutive bytes (32-bit data) from the memory
Format
CALL NETGETMEM (P, ADDR, [A,][B,][C,][D])
Arguments
P is logical page number to be presented in GR8NET bank 1 (6000-7FFF) for access
ADDR is address of Z80 visible memory to access
A, B, C and D are variables receiving contents of the memory
Usage
This statement loads variables A to D with consecutive memory values: A=(ADDR),
B=(ADDR+1), C=(ADDR+2), D=(ADDR+3). Variables A to D will keep their original type,
having contents in 0-255 range. If variable location is omitted, the memory location is
skipped however is being read. The benefits of using this statement are (1) it replaces up
to 4 PEEKs from general memory location, and (2) it gives access to GR8NET RAM buffer
memory (as you can not access it with PEEK).
NETSETMEM
Write 4 consecutive bytes (32-bit data) into the memory
Format
CALL NETSETMEM (P, ADDR, [A,][B,][C,][D])
Arguments
P is logical page number to be presented in GR8NET bank 1 (6000-7FFF) for access
ADDR is address of Z80 visible memory to access
A, B, C and D are variables or constants to write to the memory
Usage
This statement writes variables A to D with consecutive memory values: (ADDR)=A,
(ADDR+1)=B, (ADDR+2)=C, (ADDR+3)=D. Variables A to D should be in 0-255 range of
any type, otherwise Overflow error occurs. If variable location is omitted, the memory
location is skipped and not written to.
NETGETMD
Get 32-bit double word from memory converted to double-precision and stored in variable
Format
CALL NETGETMD (P, ADDR, A)
Arguments
P is logical page number to be presented in GR8NET bank 1 (6000-7FFF) for access
ADDR is address of Z80 visible memory to access
A is double-precision variable (type 8)
Usage
This statement takes 4 bytes from the location pointed by P/ADDR, converts it to doubleprecision floating point BCD format and stores in variable A. It uses MathPack’s binary/BCD
conversion hardware acceleration function. This command is very useful in couple with
NETSDCRD to get sector of cluster number (which are 32-bit) into double-precision BASIC
variable, which can hold such value.
© 2015-2017 AGE Labs
Page 58 of 156
© 2015-2017 Eugeny Brychkov
Example
` Imagine first FAT sector is loaded into location 1:6000, command takes cluster 2 number from FAT sector and puts it into V
DEFDBL V:CALL NETGETMD (1, &H6004, V)
` and then uses this variable to read first sector of cluster 2 into location 0:6000
CALL NETSDCRD (0, &H6000, V, 1, N)
` if command returns mismatching number of sectors it has read
IF N<>1 THEN PRINT “Read error”
NETSETDM
Convert double-precision value to 32-bit double word and store this dword into memory
Format
CALL NETSETDM (P, ADDR, A)
Arguments
P is logical page number to be presented in GR8NET bank 1 (6000-7FFF) for access
ADDR is address of Z80 visible memory to access
A is double-precision variable (type 8) or double-precision constant (#)
Usage
This statement converts A into 32-bit dword and stores it into location pointed by P/ADDR.
Fractional part is discarded. If overflow condition is detected (A>2^32-1) then Overflow
error is given. Statement uses MathPack’s BCD/binary conversion hardware acceleration
function. This command may be useful when working with SD-card’s FAT file system to
convert double-precision variable into 32-bit value to update FAT entry. See NETGETMD
command.
Examples
CALLNETSETDM (255,&H6800,120*8#)
DEFDBLX:X=2^24-1:CALLNETSETDM (255,&HD000,X)
NETSDCRD
Read sectors from the SD-card
Format
CALL NETSDCRD (P, ADDR, S, N, O)
Arguments
P is target logical page number to be presented in GR8NET bank 1 (6000-7FFF) for access
ADDR is target address of Z80 visible memory to copy read data to
S is double-precision variable (type 8) or double-precision constant (#), absolute sector
number to read
N is number of sectors to read, maximum 8
O is number of sectors actually read. If O Is not equal to N, check SD-card status registers
Usage
This statement reads N number of sectors starting sector number S into SD-card buffers,
and then moves data into the location pointed by ADDR switching page P in GR8NET bank
1 before the move. Important: target address space (pointed by ADDR as start and
ADDR+N*512-1 as an end) can only reside in areas 6000-7FFF and C000-FFFF. All other
addressing space is not available.
© 2015-2017 AGE Labs
Page 59 of 156
© 2015-2017 Eugeny Brychkov
Examples
‘ The following command switches to logical page 0, but copies data into address &hC000 which is main memory
CALLNETSDCRD (0,&HC000,0#,1,O):IF O<>1 THEN PRINT”Error”
‘ The following command switches to logical page 0, and copies data into its beginning (as address points into area of 6000-7FFF)
DEFDBLS:S=10*80:CALLNETSDCRD (0,&H6000,S,8,O):IF O<>8 THEN PRINT”Error”
NETBTOV
Move binary data from the GR8NET buffer to VRAM
Format
CALL NETBTOV (P, ADDR)
Arguments
P is an argument consisting of two fields: bit 0 is part of the VRAM to write to: 0=0000FFFF, 1=10000-1FFFF, bits 8:1 identify GR8NET logical page data starts in
ADDR is VRAM address offset from the position indicated in binary header
Usage
Binary image loaded into the buffer (e.g. by NETBLOAD) should have valid binary header,
otherwise Illegal function call error is generated.
Examples
CALLNETBTOV
‘ image is located in logical page 0, load at VRAM address
indicated in file’s header
CALLNETBTOV(,&h100)
‘ load image with VRAM offset of 0100h
CALLNETBTOV(184*2+1) ‘ VRAM image is located in logical page 0B8h (in GR8NET
ROM), and load this image into VRAM area starting 010000h
NETCODE
Return communication status and HTTP response code
Format
CALL NETCODE (E [,H])
Arguments
E is variable receiving error code of the last communication operation, mandatory
H is variable receiving HTTP code of the last HTTP-related operation (e.g. netbload). The
value is only valid if there was not communication system error (E=0)
Communication system error codes (hexadecimal)
00 No error
10 TCP open timeout
01 UDP open error
11 TCP state timeout
02 String too long
12 TCP communication error
03 Domain name error
13 Connection close error
04 Transmit error
20 Memory overflow
05 Command timeout
21 Size mismatch
28
29
2A
2B
2C
2D
06
2E
UDP packet timeout
22
Invalid HTTP header
SD-card not ready
Invalid SD-card FS
Invalid URI structure
SD-card I/O error
URI resource not found
Invalid
format
(e.g.
WAV file)
Operation not supported
Operations setting the flags (E/H) include: NETBLOAD/E/H, NETDHCP/E, NETSETHOST/E,
NETBROWSE/E/H.
© 2015-2017 AGE Labs
Page 60 of 156
© 2015-2017 Eugeny Brychkov
NETSNDVOL
Set or display GR8NET audio volume levels
Format
CALL NETSNDVOL (M, S, W, P, O)
Arguments
Arguments should be in range 0 (mute) to 128 (full volume).
Any of arguments can be omitted.
Usage
If all the arguments are omitted, command displays values of all five volume levels onto
the screen. If specific argument is omitted, volume of specific channel is not changed. M is
master mixer volume level, S is SCC volume, W is waveform input volume, P is PCM
volume, and O is built-in Y8950/OPLL volume.
Examples
CALLNETSNDVOL(,&h60)
‘ lower SCC’s volume by 25%
CALLNETSNDVOL(0)
‘ mute GR8NET output completely
NETGETCLK
Get clock source of the built-in SCC and MSX bus clock frequency
Format
CALL NETGETCLK (SF, BC)
Arguments
SF is flag identifying current clock source for built-in SCC. If SF is returned zero, then SCC
is being clocked by MSX system bus clock; if non-zero, then by internal 3.571429 MHz
clock source
BC receives clock frequency of the MSX system bus in Hertz
Usage
This command is used in case machine has non-standard configuration and system clock
appearing on the CLOCK pin of the MSX bus connector is non-standard. Basing on the
output of this command software makes a decision to switch SCC to GR8NET internal clock
which is close to standard external system bus frequency.
Examples
CELLNETGETCLK
CELLNETGETCLK(,B) : IF B>3580000 THEN CALLNETSETCLK(1)
Freq: 3579543 Hz
Ok
SCCCLK: MSXBUS
Ok
NETSETCLK
Set clock source of the built-in SCC
Format
CALL NETSETCLK (SF)
Arguments
If SF is zero, built-in SCC will be clocked by system bus clock, is non-zero then will be
clocked by the GR8NET built-in 3.571429 MHz clock source. Argument is mandatory
Usage
© 2015-2017 AGE Labs
Page 61 of 156
© 2015-2017 Eugeny Brychkov
Software can switch GR8NET built-in SCC into its native frequency in case on overclocked
machines so that SCC output sounds properly.
Examples
CALLNETSETCLK(1)
Ok
NETSYSINFO
Get system information and system performance data
Format
CALL NETSYSINFO (MV, CL, TP, VP, VM, MA, MR)
Arguments
If arguments are omitted, system information is printed onto the screen
Any individual argument can be omitted
Usage
This command is used to get system information, informing you about PC you are using,
its performance, video system configuration and RAM configuration.
Here’s the list of information available, with explanation
Arg
Output
Explanation
MV System: MSX2
This is machine version. MV may be 0 (MSX1), 1 (MSX2), 2
(MSX2+) and 3 (MSX Turbo-R). If machine is Turbo-R,
then MV bits 5 and 6 are meaningful: bit 5 set means Z80
mode, reset means R800 mode; bit 6 set means ROM
mode, reset means DRAM mode
CL MSXBUS: 3579544
MSX slot clock signal frequency, the same returned by
NETGETCLK command, in Hertz
TP T-perf: 60670*(51+8) This is T-cycle performance, and TP gets number of loops
machine performed within one second with instructions of
51 cycle total duration (plus 8 for additional M1 wait state
according to MSX specification). Thus for this output
machine performed 1/60670/(51+8) T-cycles, and it is
equivalent to 279,36 ns, exact value for calculated bus
© 2015-2017 AGE Labs
Page 62 of 156
© 2015-2017 Eugeny Brychkov
Arg
Output
VP
VM
Video: V9938
(50 Hz), 128KB
MA
32
MR
32
Explanation
clock speed of 1/3579544 (see argument CL)
Video processor type: 0=TMS, 1=V9930, 2=V9958
Combined 16-bit value: low byte (VM AND 255) is current
vertical refresh rate (0=60Hz, 1=50Hz, 255=error
identifying), high byte (VM\256) is size of VRAM in 4KB
blocks (0=4KB, 1=8KB, 2=16KB, 4=32KB, 8=64KB,
16=128KB, 255=error identifying)
Number of default mapper 16KB pages found by searching
for RAM. Default mapper (slot) is the one which is selected
for system data in bank 3. Note that for Turbo machines
this value can be less than mapper size, and even not
power of 2 (e.g. 12 in DRAM mode because Turbo protects
highest 4 ROM-shadowed RAM pages). Maximal value is
256 (4096KB)
Memory mapper size: number of mapper 16KB pages
system tried identifying by accessing memory mapper
registers. Maximal value is 256 (4096K), -1 if it can not
identify mapper size. May be bigger than actual RAM – e.g.
for Turbo-R A1ST with 256KB RAM installed mapper will
show 32 pages (512KB mapper size), showing only 12 for
argument MA
NETVARRWTH
Set networking RX window threshold
Format
CALL NETVARRWTH (G, N)
Arguments
G is a variable receiving current value of threshold, default is 0
N is variable or constant setting threshold (0 to 2047)
Usage
W5100 chip, unfortunately, is not designed to work in heavy loaded and switched
environment, especially where packets may get massively lost or there’re spurious
retransmissions which hinder normal and sequenced TCP/IP data packet flow. For technical
information about issue please refer to the WIZnet support forum website at
http://wizwiki.net/forum/viewtopic.php?f=4&t=3670.
The issue is that remote hosts/proxies may expect W5100 to behave in specific way, but
W5100 does not satisfy expectations. To mitigate this issue there’s threshold value used
which makes BLOAD and PLAYWAV statements keeping threshold number of bytes in the
W5100’s RX buffer so that remote host/proxy did not have an option sending more than
one data packet a time without W5100’s acknowledgement, and thus performing
retransmissions immediately as requested by W5100 without filling its buffer (which is not
accepted by W5100) prior performing retransmission.
Default value of RX buffer threshold is 0, assuming whole RX window is used and as soon
as at least one byte appears in RX buffer it is withdrawn by the firmware.
© 2015-2017 AGE Labs
Page 63 of 156
© 2015-2017 Eugeny Brychkov
By default W5100 is having 2048 bytes buffer per socket, thus remote host/proxy, seeing
W5100 reporting 2048 bytes window, may divide it to two 1024 byte areas, and send
packets of 1024 data bytes long. This means that 2 packets fill W5100’s RX socket buffer
completely, thus, in such situations, to keep space for only one packet application may set
threshold to 1024.
Please note that limiting receiving buffer using RX buffer threshold may significantly lower
data transfer speed, but it increases reliability of the transfer in highly loaded and
erroneous networking environments.
NETVARUDTO
Set UDP packet timeout for DHCP and DNS operations
Format
CALL NETVARUDTO (G, N)
Arguments
G is a variable receiving current value of timeout, default is 20
N is variable or constant setting threshold (0 to 255)
Usage
The UDP timeout controls the time system waits for incoming UDP packet to arrive for
DHCP and DNS requests. Value indicates number of 100 ms periods, thus value of 20
means 2 seconds timeout; value of 0 means 256 periods (25.6 seconds). This command is
instrumental if network is heavily loaded, DHCP server is relatively away from GR8NET or
is just being slow in responding to the requests. This value is being preserved by
CALLNETSAVE command. If both arguments are present, G gets previous value of the
timeout, before value N is set.
NETFKOPLLR
Fake OPLL ROM into mapped RAM
Format
CALL NETFKOPLLR
Usage
This command is oriented onto the software which runs in GR8NET mapper modes 1-6
(ROM emulation mode), and can not run in mapper mode 8 when MSX-MUSIC ROM is
available in GR8NET subslot.
This ROM, to be exact – specific signature in this ROM, is required for software to detect
presence of MSX-MUSIC chip (YM2413). This command checks if there’s mapped RAM
available and it has at least 48KB, and copies MSX-MUSIC ROM into mapped RAM page 2
(otherwise Out of memory error is given). Then, after machine reboot, MSX BIOS detects
ROM image in RAM; applications will also detect presence of MSX-MUSIC and find required
signature.
However, if RAM mapper page 2 contents will get modified (for example, by loading
application in MSX-DOS mode), machine may malfunction as it will be calling corrupt
location using BASIC CALL command.
In addition, this command overwrites mapped RAM page 2, and its original contents will be
gone.
© 2015-2017 AGE Labs
Page 64 of 156
© 2015-2017 Eugeny Brychkov
The primary purpose of this command is to allow games, running in GR8NET mapper
modes 1-6 (e.g. Aleste) to produce FM-sound using GR8NET built-in YM2413
implementation. All other uses should be thoroughly considered for side-effects.
© 2015-2017 AGE Labs
Page 65 of 156
© 2015-2017 Eugeny Brychkov
4. Using GR8NET as BASIC I/O device
You can use BASIC I/O commands to access remote resources or send datagrams
using GR8NET. Important to know that if your I/O program is stuck in GR8NET waiting for
input from remote host, you can press CTRL-STOP to abort the I/O operation, and BASIC
will return with “Device I/O error”.
There’re two sockets available for user, 0 and 1. Each following device name must be
appended with this number to identify the socket. A socket can not be opened two times
simultaneously. Attempting opening socket second time will give File already open error.
Devices available for use are
Device Purpose
TCP
Open the socket to use TCP (transmission control protocol), in client mode. This
means the socket will attempt actively connecting to remote resource to establish
connection
TCS
Open the socket to use TCP (transmission control protocol), in server mode. This
means the socket will be set in listening mode waiting for incoming connection.
To identify if connection is established use EOF function
UDP
Open the socket to use UDP (user datagram protocol)
RAW
Raw mode is not yet implemented
HTTP Open the socket to use TCP (transmission control protocol), in client mode, and
send GET request to the remote resource. Header is being checked for HTTP
response status code. If code is not 200 (OK) Verify error is generated
HTTR Raw HTTP mode – same as previous but server response header should be read
and processed by the application
4.1. BASIC I/O using TCP
TCP is based on persistent connection, and each byte you put into the output file is
sent immediately, and as soon as there’s free space in adapter’s networking chip buffer,
next character is being received from remote host. But you should be aware that remote
hosts may have timeout settings, thus for reliable TCP communication you should use EOF
function to check if remote host is still on the line.
Let’s look at how communication takes place on the example. This simple program
reads file from the remote server using HTTP protocol and displays it onto the screen:
10
20
30
40
50
60
70
CALLNETSETHOST("www.gr8bit.ru")
OPEN"TCP0A:"AS#1
PRINT#1,"GET /software/roms/@license.txt HTTP/1.0"
PRINT#1,"HOST: www.gr8bit.ru":PRINT#1,””
IF LOC(1)<>0 THEN LINEINPUT#1,A$:PRINTA$
IF EOF(1) THEN PRINT:PRINT"RECEIVED":END
GOTO 50
© 2015-2017 AGE Labs
Page 66 of 156
© 2015-2017 Eugeny Brychkov
Line 10 sets up the remote host, with firmware resolving the host name into its IP
address. Line 20 opens stream in TCP mode, using adapter #0 socket 0, in I/O file mode.
Line 30 and 40 print HTTP headers into the output stream, line 50 checks if there’s
anything in the input buffer, and performs line input from it. Line 60 checks if data
exhausted, and ends if it is. Receive is performed in loop until there’s no received data and
remote host disconnects.
Device file name should have the following format:
Field
Values
Notes
BASIC device name TCP
This identifies the device name and thus protocol which
TCS
will be used. As there could be up to 4 adapters with 2
UDP
user sockets each, just device name is not enough
RAW
HTTP
HTTR
Adapter ID
0
Number of the adapter to be used to open the stream. If
1
adapter with identified number does not exist in the
2
system, Bad file name error will be given. If adapter ID
3
field is omitted, default adapter # is used
Socket ID
A
This identifies socket number of the adapter selected. A
B
means socket 0, B means socket 1. This field can not be
omitted
Thus valid device names could be HTTPA:, UDP0B:, but not HTTP:, UDPB0:.
Now let’s look at the application of each command in turn.
Command
OPEN
PRINT#,
PRINT
#USING
LINEINPUT#
INPUT#
INPUT$
Application
You can use devices TCPA and TCPB for TCP communication. These
devices are client-side, which connect to the remote host. If you need to
use server-side application of the TCP, use devices TCSA and TCSB –
these two devices, instead of performing active connect to the remote
host, listen for incoming connections instead. Note that these TCPA/TCSA
and TCPB/TCSB device pairs use the same hardware socket, thus you can
use only one of them at the time, however can use 0 and 1 devices
simultaneously. Open the network resource in binary mode, if you will try
random access on it, BASIC will return “Sequential I/O only” error
Use these commands like you do on any other file, but be cautious: (a) at
the end of each print without “;” BASIC prints CRLF. If you perform binary
output, CRLF will corrupt your packet; (b) if you print numeric values,
they may print with heading or trailing spaces.
Use this input command with caution: it expects line to terminate with
CRLF, however many internet resources use only LF as next line
character, and LINEINPUT routine malfunctions – returning “String too
long” error, or being stuck at the end of the file waiting for CRLF.
The same use as usual, but before requesting specific number of
characters, ensure this number is present in the RX buffer using LOC
function, otherwise system may get stuck waiting for incoming character
© 2015-2017 AGE Labs
Page 67 of 156
© 2015-2017 Eugeny Brychkov
Command
CLOSE
MAXFILES=
LOC(f)
LOF(f)
EOF(f)
Application
Closes the socket, and removes its assignment with the socket
Important to know that invoking this BASIC feature is not only reallocates
memory for I/O buffers, but it forcefully closes all open files before it.
Thus doing this command may interrupt your communication process.
Please use it before you start communication ensuring you have needed
file handles allocated for your software
Function returns number of bytes waiting in the receive buffer
Function returns number of bytes free in TX buffer
Function returns 0 if there’s still data received to read, and returns -1 if
there’s no data received and remote host has closed the TCP connection
You can load or merge programs from the internet onto your MSX PC:
Command
Application
LOAD
These operators will properly work only with HTTP: device, which parses
MERGE
header and feeds contents of the remote data to the BASIC. Remote
BASIC file should be in ASCII format. Example:
A$=”http://www.gr8bit.ru/software/basic/kove.asc”
LOAD”HTTPA:A$”
After execution of the LOAD (successful or unsuccessful) variable A$ is
cleared.
4.2. BASIC I/O using UDP and RAW
These devices use the same sockets 0 and 1, thus for socket 0 you can have only one
type of device opened – TCP, UDP, RAW or HTTP, the same is for socket 1.
UDP and RAW protocols are transactional type communications, and require proper
packet to be assembled before it is sent to remote host. For this purpose there’s additional
command introduced to send the datagram.
NETSNDDTG
Send datagram to remote host
Format
CALL NETSNDDTG (F)
Arguments
F is BASIC file number, mandatory
Usage
After you load required data into the networking chip TX buffer, you use this command to
send the datagram to the remote host.
Programmer checks output of LOC function to be non-zero to identify if there’s
datagram received. This function returns number of bytes received, but in case of UDP
each datagram is preceded by the 8-byte header, which identifier host datagram is
© 2015-2017 AGE Labs
Page 68 of 156
© 2015-2017 Eugeny Brychkov
received from, remote port and size of the datagram. Thus buffer may contain several
datagrams, with LOC returning size of all received datagrams with headers, and
programmer parsing headers to process UDP packets.
RH0
RH1
RH2
RH3
RP0
RP1
SZ0
SZ1
Where RH is remove host IP address octets, RP is remote port number, and SZ is the size
of datagram received. Note that RP and SZ and stored in big-endian notation, this means
that most significant byte comes first, and least significant last.
4.3. BASIC I/O using HTTP protocol
Communication using HTTP device is almost the same as for TCP/TCS, with two
significant differences:
1. In this mode socket actively attempts connecting to the remote resource and sends
HTTP GET request to remote resource using values set by SETHOST, SETPATH and
SETNAME. SETHOST is used in “Host: “ HTTP header, and SETPATH/SETNAME are
used to make up URI of the GET request.
2. OPEN, LOAD and MERGE statements for HTTP device is expanded. Look at the
example below.
10 A$=”http://www.gr8bit.ru:80/software/roms/@license.txt”
20 OPEN "HTTP3A:a$" AS #1
…
You can set BASIC string variable to specific URL, and pass it into the open or load
statement using variable as a file name. Important: default values explained in item
1 above are being updated by the URL parser, thus if you assign A$=”path/” then
OPEN will be passed host set by SETHOST, file name set by SETNAME, and path set
by SETPATH being appended with path/ subdirectory.
There’re two devices which work using HTTP protocol:
• HTTP: device will load header, parse it for the HTTP response code and open BASIC
device if code returned is 200. Therefore BASIC program will start reading remote
file data immediately;
• HTTR: device is raw HTTP protocol device and it will not parse HTTP header, thus
BASIC program will need to do it by itself.
Both HTTP: and HTTR: devices are ASCII character access devices. While you may
be able to obtain control codes through these channels, character with code 26
(01Ah) serves as an end of file marker, will terminate transmission and will never be
returned, however there’s a cheat available to allow BASIC applications reading
binary files. Please refer to the examples section for implementation.
© 2015-2017 AGE Labs
Page 69 of 156
© 2015-2017 Eugeny Brychkov
4.4. The URL parser
As explained in section 2.3 parser updates fields which as present in provided URL.
The following URL formats are valid and meaningful:
Value
Meaning
file.dat
New file name only
/file.dat
New file name located in the root
/path/
New path from the root
path/
Path to append to current path
http://host
New host name
http://host/
New host with new root path
http://host/file
New host name with file in the root
http://host/path/
New host with new path
http://host:port
New host with new destination port
http://host:port/path/file.dat New host with new port, new path and new file
The list above is not exhaustive, it just shows you some important examples of URLs
you can use, and what they will mean and change for OPEN, LOAD and MERGE statement.
Parser will not update source port number, please use SETPORT command to set it.
© 2015-2017 AGE Labs
Page 70 of 156
© 2015-2017 Eugeny Brychkov
5. Built-in web browser
There’s simple web browser built into the GR8NET firmware, its primary purpose at
the time or initial release is to let user conveniently browsing directory listings provided by
the web servers and SD-card. Browser is capable to displaying relatively small text files. To
invoke browser use CALL NETBROWSE command in BASIC.
(b) 80-character width
(a) 40-character width
Figure 9. Browser screens
Figure 3 shows 40- and 80-character display of the browser. If your machine has
V9938 and above we recommend using 80-character display mode, however if you have
MSX1 machine you will be anyway able using the browser in 40-character screen mode. To
choose the mode, set SCREEN0’s screen width before launching browser using WIDTH
command.
When starting browser, it checks for SD-card being installed, and if SD-card is in the
slot, it prompts for the source to browse (fig. 9c). Please do not make files with names
longer than 28 characters. Supported SD-card file systems are FAT32 and FAT16.
(d) SD-card file listing
(c) Prompt when SD-card is inserted
Figure 9 (continued). Browser screens
© 2015-2017 AGE Labs
Page 71 of 156
© 2015-2017 Eugeny Brychkov
Key
Navigation is performed by the following keyboard keys:
Function
Using these keys you navigate the web page. If next or previous
link is visible, focus will change to that link, if not, page will be
scrolled in required direction – up or down
Arrow up
×
Ø
Arrow down
ENTER key
9
Space key
This key selects the link for activation. If you select text file or
subdirectory their content will be loaded into the browser. If you
select binary file, it will be loaded and executed. If execution will
return back to browser, browser will reload directory listing file
was selected in. If you select ROM image, it will be loaded, and if
ROM image’s file name contains digit in {} braces, then this digit
will serve as mapper type identification, and ROM will be launched
using identified mapper type
Space key acts the same way as Enter key, except images will not
be executed, and after load browser terminates. ROM images are
loaded into GR8NET buffer RAM, binary files are being transferred
into their required location, and message will be given about
binary image start and execution addresses. This behavior can be
modified by special flags within second argument to the command
This key allows going back one web page. If you opened text file
which does not have links at all and you want to return to
directory listing without re-launching the browser, click Backspace
key.
Pressing TAB key on the entry in the list which presents wave file
will cause browser to invoke built-in WAV player and play this file.
After playback completes, or user interrupts the playback, system
will return to the browser
Move to the top or bottom of the page. If top of page is displayed
and first link is on focus, moves view to the bottom of the page. If
bottom or other part of the page is displayed, moves view to the
top of the page.
Refresh the page (reload and display)
←
F4
Backspace
TAB
CLS
HOME
SELECT
!
1
A
)
0
© 2015-2017 AGE Labs
Pressing alphanumeric keys will move focus to the next linked
entry with its description (link text) starting with the respective
character pressed.
Case of alphabetical character does not matter.
Z
Page 72 of 156
© 2015-2017 Eugeny Brychkov
Key
Function
Exit web browser
ESC
CTRL
V
Play video file from the SD-card. After playback is finished,
execution returns to the browser.
As mentioned in Enter key section, browser can run ROM automatically if file name of
the resource is having special section – braces {} with maximum 3 characters in them:
• First character must be present, it selects mapper type from 1 to 6, e.g. {3} to start
ROM in Konami SCC mode;
• Second character may be omitted if third character is not present, and identifies if
GR8NET will restart in composite mode having GR8NET, mapped RAM and Nextor in
expanded slot. Value can be 0 or 1. Example: {31} will cause GR8NET to restart in
mapper mode 1*8+3, thus in mapper mode 11;
• Third character may be omitted, and identifies if composite mode will have mapped
RAM disabled (nothing will be present in subslot 1); values can be only 0 or 1.
Example: {311} will cause restart with mapper mode 11, and no mapped RAM in
subslot 1.
Web browser has several limitations; please keep them in mind when creating web
pages/directory listings to be accessible by GR8NET:
• While file names allow 63 characters, keep file names limited to 23 characters,
otherwise they may be truncated by the display;
• Do not use double quotes " within file names. This character is reserved for
identification of hypertext reference boundaries during HTML document parsing;
• Create descriptions for files and directories – these descriptions will help very much
in 80-character mode view;
• Ensure number of links per page is not more than 250 – including header’s Name,
Last modified, Size, Description and Parent directory means limit number of entries
(files and subdirectories) up to 245 maximum;
• Images are not displayed and discarded;
• Please use HTML checking tool in case you create custom web pages to ensure tag
consistency;
• Some HTML constructions are not supported at all, some characters are considered
as bad characters. In this case browser will display stream error and terminate.
© 2015-2017 AGE Labs
Page 73 of 156
© 2015-2017 Eugeny Brychkov
Browser supports simple directory listing format provided by web servers, and
supports so called fancyindexing view. Below is an example of the .htaccess configuration
file for Apache:
HeaderName header.html
IndexIgnore *.html
IndexOptions FancyIndexing
Options +Indexes
IndexOptions DescriptionWidth=*
Adddescription "@LICENSE STATEMENT" @license.txt
Adddescription "Sample WAV files for GR8NET testing" audio
Adddescription "Sample BASIC programs" basic
Adddescription "Bloadable executables" binaries
Adddescription "Firmware update and troubleshooting tools" firmware
Adddescription "ROM images for GR8NET testing" roms
Adddescription "Diskette images" bootimg
Adddescription "MSX images to load to VRAM" images
Adddescription "MSX videos, software to create MSX videos" video
Do not forget that settings in .htaccess are automatically inherited by the
subdirectories if not overridden in the hierarchy, thus if you add description to specific file
on one level then if there’s file with same name down the subdirectory tree the defined
description will be displayed if not overridden by Adddescription in the directory containing
the file under consideration.
NETBROWSE
Invoke internet and SD-card browser in BASIC
Format
CALL NETBROWSE [(I$, F)]
Arguments
I$ is string variable or constant used as source URI to start browsing with. Command reuses default structure set by SETHOST, SETPATH, SETNAME and SETPORT, thus take
special care to put as much information into I$ as possible: host name, destination port,
path and name (or make sure appropriate values are set by abovementioned commands
before you run browser). Please refer to The URL parser chapter;
If you invoke browser with intent to browse internet, but are brought to
browsing SD-card, ensure that URI structure you use as input is network-type
(contains http:// in its definition).
F is an integer representing a set of bitmap flags. F can be a constant, expression, formula
or variable. In case F is an integer variable, several status bits will be returned in it. If this
argument is omitted, it is assumed of value 0.
•
7
ESCF
6
DIR
(output)
(output)
5
4
3
NOSEL
2
DIRENA
1
NOLOAD
0
SPCMV
(input)
(input)
(input)
(input)
SPCMV: if this bit is set, when user presses SPACE key on the selection, target will be
loaded into the GR8NET RAM, but no action will be taken on it (e.g. binary file with
header will not be moved in its designated location), and browser exits;
© 2015-2017 AGE Labs
Page 74 of 156
© 2015-2017 Eugeny Brychkov
•
•
•
•
•
NOLOAD: if this bit is set, browser will not load selected target into GR8NET RAM. This
bit makes sense only when SPCMV bit is set. Application can use NETVARBRSTR
command to get and process selection and load it afterwards;
DIRENA: if this bit is set, pressing SPACE key on directory will select directory and exit;
if this bit is not set pressing SPACE key on directory will cause content load and
continuation of browsing. This option has effect only when SPCMV is set;
NOSEL: if set, forces no source device selection page (Internet/SD-card), browsing will
proceed directly to device identified by URI structure/URI string (http:// or sdc://);
ESCF: this bit is set when browser exits having user pressed ESC key. In this case
output of NETVARBRSTR will point to last directory user have been viewing;
DIR: on completion of browser process, this bit is set if contents loaded or pointed to is
not a file entry, but directory entry. For network operations, contents should be a web
page with directory list generated by web server, or any other HTML text returned by
web server for the directory; for SD-card operation, loaded content will be operating
system image of the directory.
Examples
CALLNETBROWSE
Start browsing using default URI structure
set by NETSETHOST, NETSETPATH and
NETSETPORT
CALLNETBROWSE (“http://myserver”)
Start browsing server myserver with path
set by NETSETPATH and port set by
NETSETPORT
CALLNETBROWSE
Start browsing server myserver with path
(“http://myserver:80/mypath/”)
/mypath/ (trailing slash is mandatory to
distinguish path and name)
CALLNETBROWSE (“sdc:///roms/konami/”, 8)
Start browsing SD-card in /roms/konami/
subdirectory without having source
selection web page displayed
CALLNETBROWSE (“sdc:///roms/konami/”)
This command will first bring Internet/SDcard selection screen, and whatever
selection you will make, proceed to
browsing SD-card
F=8+4+2+1
Starts browsing location pointed by A$,
CALLNETBROWSE(A$, F)
without source selection screen, with
IF F AND 128=128 THEN PRINT “ESC pressed” SPACE key selecting file or subdirectory
ELSE CALLNETVARBRSTR(O$):PRINT O$
entry and not loading its contents.
© 2015-2017 AGE Labs
Page 75 of 156
© 2015-2017 Eugeny Brychkov
NETVARBRSTR
Get URI string of the location selected by user within the browser
Format
CALL NETVARBRSTR (O$)
Arguments
O$ is string variable receiving URI path corresponding to user selection by Enter or Space
key. If browsing was terminated by ESC key (ESCF flag is set), O$ will identify directory
user has chosen to press ESC key in to terminate browsing.
Important: if resulting full URI string will not fit into string variable allowed by BASIC (due
to its size being loner than 254 characters or string variable area depletes), String too long
error will be generated. To ensure smooth execution of BASIC program, ensure you handle
this possible error through ON ERROR statement.
Usage
Use this command immediately following CALLNETBROWSE command completion. Other
commands may use same memory location for storing URI information thus may modify
content and returned URI may be invalid.
© 2015-2017 AGE Labs
Page 76 of 156
© 2015-2017 Eugeny Brychkov
5.1. Opening SD-card located file in the browser
Browser was designed for the purpose displaying contents provided by the web server
or browsing contents of the SD-card as directory tree. When entering browser, input URI
location is parsed and file name is removed in order for URI to point to directory location.
For loading and executing files from the BASIC programs and BASIC command prompt
NETBLOAD command should be used.
However there’re could be cases when it is required to open file in the browser – as
text or HTML – for example, showing readme file contents or provide custom listing of the
SD-card resources using HTML index files. Using command
CALLNETBROWSE(“sdc:///mypath/myfile.html”,8)
will open contents of the subdirectory mypath (as file name is removed). There’s a hack
available for SD-card browsing presenting file as directory, e.g.
CALLNETBROWSE(“sdc:///mypath/myfile.html/”,8)
when after URI parsing directory path is /mypath/myfile.html/. Adding trailing slash to the
file name will cause parser to treat file name as part of the path, and will seek to the start
of the file (not knowing that it is file and not subdirectory). Then, when opening the
contents of the myfile.html, browser identifies that it is not a subdirectory, but a HTML file,
and displays it appropriately.
The following rules should be followed:
• File must exist of the SD-card;
• HTML file must be properly formatted – it should start with !DOCTYPE or HTML
directive, otherwise it will be displayed as text file. For the example see source of
any directory listing, e.g. http://www.gr8bit.ru/software/firmware/GR8NET/ (right
click into the page display area and select “View page source”);
• All anchors in HTML file should be absolute, and all file URIs to be displayed in the
browser must have trailing slash in their URI;
• Second parameter 8 (NOSEL bit set) is required to suppress display of browsing
source selection and browsing from the SD-card root.
© 2015-2017 AGE Labs
Page 77 of 156
© 2015-2017 Eugeny Brychkov
6. Using integrated MSX-DOS
Disclaimer: you agree that AGE Labs/Eugeny Brychkov (GR8NET device), and Nestor
Soriano (Nextor software) are not liable, and can not be held liable for the adverse effects
of managing data contents using GR8NET Disk subsystem and Nextor built into GR8NET
device, including, but not limited to data loss, data corruption, data unavailability, storage
device format consistency. You should perform regular backups of the storage media
contents, and, in case of proven storage system malfunction, report it, along with the plan
to reproduce malfunction, to abovementioned developers. Abovementioned developers do
not perform restoration of the damaged volumes, and do not guarantee that there will be
updates or fixes available for reported, known or unknown issues with the GR8NET built-in
storage systems.
Disk subsystems described below are independent, can run separately, or, if Nextor is
started, Nextor will take over control of GR8NET disk subsystem (if this subsystem is
activated).
6.1. GR8NET Disk subsystem (DOS1)
Since February 2016 GR8NET is having integrated Disk-BASIC in its ROM logical pages
88h-89h (16 Kbytes). This disk subsystem is available in mapper type 0 (GR8NET) and
mapper type 8 (512K+512K). Use this disk subsystem in mapper modes 9-14 with caution
because GR8NET RAM is being shared between game mappers, and loading disk image
may corrupt ROM image in game mapper.
This implementation of DOS version 1 supports all the disk I/O functionality, but main
disk ROM is located in CPU bank 2 (8000-BFFF), with vital anchors embedded into the
standard GR8NET firmware at logical page 80h.
WARNING! It is not allowed for applications to call Disk-ROM directly.
Applications should use standard interfaces like BDOS or MSX BIOS entries and
hooks related to management and control of the standard storage devices.
Because of control transfer between GR8NET pages and CPU page switching,
integrated Disk-ROM has slightly lower performance than original Disk-ROM found in
storage devices in CPU bank 1 location (4000-7FFF). If original performance is needed,
please do one of the following:
• Install MSX-DOS version 2 cartridge into the system, this cartridge will take control
over integrated MSX-DOS version 1 BIOS and use GR8NET as an end storage
device;
• Install another storage device in slot ID lower than that GR8NET installed into. This
will make this another device as a master, and it will use GR8NET as an end storage
device.
GR8NET disk subsystem initializes after GR8NET networking initialization finishes. Disk
and networking work independently, thus it is possible to have Disk-ROM with GR8NET
RAM as a RAM-disk with no valid networking connection, however in this case there will be
no valid disk image in the RAM, and you will need to format RAM-disk before using it.
© 2015-2017 AGE Labs
Page 78 of 156
© 2015-2017 Eugeny Brychkov
6.1.1. Initialization of the DOS1 disk subsystem
First step of the disk subsystem initialization is checking of the GR8NET RAM for valid
diskette image. This operation is performed even if disk-ROM is disabled through mode
register, and gives you opportunity to enable the disk subsystem using F4 key to use
available diskette image. If valid disk image is detected, Valid disk image in RAM message
is displayed.
If disk subsystem is enabled in the mode register, or you pressed and held F4 key
during GR8NET adapter initialization, then the following workflow applies:
1. Space is allocated for the disk image: 720KB (90 logical pages) in GR8NET mapper
mode 0, and 360K (45 logical paged) in GR8NET mapper mode 8;
2. Firmware displays Disk subsystem message and waits for 3 seconds, displaying
dots on the screen. You have an opportunity to press and hold modifier keys (F3
to disable disk ROM, F1 to refresh image, F2 to invoke browser) during this
period;
3. If Disk-ROM is still enabled, then, depending on the keys being pressed, actiona
are taken according to the image below.
4. If load of remote image was successful or there was valid image identified before,
firmware checks if image fits into the RAM allocated for the image. If it does not,
displays warning message Warn: disk image will not fit, and then Disk image is
mounted message;
5. GR8NET firmware starts initialization of the disk subsystem.
© 2015-2017 AGE Labs
Page 79 of 156
© 2015-2017 Eugeny Brychkov
You have an opportunity to change behavior of the disk subsystem initialization
procedure by pressing and holding the following keys during GR8NET initialization:
Key
Behavior
F3
F4
F1
F2
Disable disk-ROM. By pressing this key you disable disk-ROM and new
image load (thus corruption of the RAM if there was no valid disk image in
RAM). This key has immediate effect – as soon as you press it during dot
display process, further disk-related operations are aborted
Force disk-ROM. In case disk-ROM is disabled in the adapter’s mode
register, by pressing and holding this key when GR8NET finishes
initialization of its networking subsystem will cause override of disable bit,
and forces GR8NET to perform disk-ROM initialization
Force image reload. By pressing this key you instruct to reload default
image even if valid image is present in the RAM. If F2 is pressed at the
same time, you go to browser, and default image is reloaded only if browser
is exited with ESC key
Invoke browser. If you do not want default disk image to be loaded you can
press this key and invoke browser to browse the directory pointed by the
default
image
URI
structure.
Example:
default
URI
is
http://www.gr8bit.ru/software/bootimg/bootimg0.dsk, by pressing F2 you
will be brought to browsing of http://www.gr8bit.ru/software/bootimg/
directory. Please note that to have disk image loaded properly by the
browser you should press Space key, not Enter key.
After initialization is finished, GR8NET in its Disk-ROM part functions as any other
standard storage controller:
• It tries to load MSXDOS.SYS and then COMMAND.COM to boot into the disk
operating system mode;
• If DOS mode is unsuccessful, it tries loading AUTOEXEC.BAS and executing it;
• If both previous steps are unsuccessful, machine goes to MSX BASIC. You can easily
identify if GR8NET is mastering the disk operations by the string it displays when
BASIC is entered.
© 2015-2017 AGE Labs
Page 80 of 156
© 2015-2017 Eugeny Brychkov
6.1.2. Using GR8NET DOS1 disk subsystem
Standard Disk-BASIC commands and standard BDOS function are supported by the
disk subsystem.
By default disk-ROM initializes with single logical drive (e.g. A:) for RAM disk. It is
possible to force two-drive configuration by putting number of drives in brackets into file
name of the image being loaded. For example, mydskimg{2}.dsk.
You have the following commands to manage GR8NET-specific implementation of the
disk subsystem and its driver:
DSKGETIMG
Get current disk image location
Format
CALL DSKGETIMG [(P$)]
Arguments
P$ is a string variable. If P$ is empty, image was not loaded or invalidated
Example
CALL DSKGETIMG
http://www.gr8bit.ru:80/software/bootimg/diskimg0.dsk
Ok
DSKSETIMG
Set disk image location
Format
CALL DSKSETIMG [(P$)]
Arguments
P$ is a string variable or constant
Usage
If argument is supplied, statement sets new image location to be loaded from. Logically,
this command is followed by DSKLDIMG command to load the image from new location.
If argument is omitted, raises disk change flag forcing Disk subsystem re-read RAM disk’s
control structures.
{2} in the file name of the image will force two drive configuration, (e.g. A: and B:), where
drive A: will be a RAM disk, but drive B: will always return Not ready error.
Note: during URI parsing default URI structure is used, thus to avoid dependence of
default URI setting define all fiends in P$: server name, path, file name, and remote port
number.
Note: NETSAVE command preserves current remote disk URI information, and preserved
URI will be used as a boot location on next GR8NET initialization.
Examples
CALL DSKSETIMG(“http://www.gr8bit.ru:80/software/bootimg/diskimg0.dsk”)
CALL DSKSETIMG(“sdc:///disks/laydock.dsk”)
CALL DSKSETIMG(“sdc:///disks/dsbest{2}.dsk”)
© 2015-2017 AGE Labs
Page 81 of 156
© 2015-2017 Eugeny Brychkov
DSKLDIMG
Loads image into the RAM disk area in GR8NET buffer RAM
Format
CALL DSKLDIMG
Important notice
(Re-) loading disk image will overwrite current RAM-disk’s image present in the RAM, and
all current information will be lost. Before loading new image ensure you backed required
data up from current image of RAM disk onto another device (e.g. floppy disk, hard disk,
SD-card).
Usage
Statement uses previously set disk image location loading it into the RAM. Location to load
data into is defined by DSKLPG variable (see memory management chapter). If size of
image being loaded is bigger than space allocated for RAM disk, Device I/O error is given.
If disk configuration (i.e. number of sectors in its maximal size) does not fit into space
allocated for RAM disk, image will be loaded successfully, but for all sectors above space
available for RAM disk subsystem will return Not ready error. If HTTP return code is not
successful (not 200), Verify error is given.
DSKSVIMG
Saves RAM-disk image onto SD-card
Format
CALL DSKSVIMG(P$)
Argument
P$ is string constant or variable, if omitted location set by DSKSETIMG will be used
Usage
This command is not designed to be used programmatically, please use it from command
prompt.
Target file on SD-card must be already present, with matching size of the image in the
GR8NET RAM. For example, if you have 360K disk image loaded into GR8NET RAM, it can
only be saved into already existing 360K file located on SD-card.
In case of errors, command will return Illegal function call error in BASIC, and further
information can be obtained by NETCODE command. Possible causes: SD-card not ready
(install operational SD-card), operation not supported (supplied URI must be SD-card
SDC:// device, target file size should match image size), URI resource not found (point to
existing file), SD-card I/O error (there’s physical read/write card error), Invalid SD-card FS
(in case there’re problems with file system).
© 2015-2017 AGE Labs
Page 82 of 156
© 2015-2017 Eugeny Brychkov
Example to the left shows command execution
flow, please notice that:
- There’s warning displayed, indicating that
there’s some issue with image of RAM-disk;
- Image sectors does not match RAM-disk
space, another indication that there’s
something wrong with image in RAM.
In order to proceed with saving the data, you
must press keys S and Y sequentially, otherwise
command will abort.
Important notice
Regularly back your SD-cards up. This command DSKSVIMG writes to the SD-card, and
AGE Labs/Eugeny Brychkov will not be held responsible for SD-card data integrity, usability
and validity.
Preparing SD-card for disk image saving
This task is as easy as:
- Choose correct size of the target file – 720K or 360K;
- Locate existing, or create new .DSK image using diskette image creator or emulator;
- Copy this file to SD-card using Nextor or another platform (Linux/Windows/Mobile OS).
DSKCFG
Obtain or manage state of disk image
Format
CALL DSKCFG (MS, SETS)
Arguments
MS is a variable receiving maximal number of logical pages RAM disk can be set to;
SETS is variable or constant setting size of RAM disk, should be 0 ≤ SETS ≤ value of MS
Usage
Each GR8NET mapper mode has maximal size of RAM disk preset, you can not create RAM
disk of more than MS pages in size. Thus SETS should be ≤ MS. Please refer to Memory
manager chapter.
When SETS argument is present, disk subsystem re-allocates RAM disk structures so that
there’s required number of pages between RAMMAX and DSKLPG memory manager’s
variables. This action will nullify image location (managed by DSKSETIMG), and sets disk
change flag for RAM disk. If it advised for format RAM disk using DSKFMT command after
resizing it because if disk image start changes RAM disk’s control structures will appear
invalid, and image will not be handled properly. If SETS is 0, then RAM disk’s size is 0, and
for any read or write operation system will respond with Not ready error.
© 2015-2017 AGE Labs
Page 83 of 156
© 2015-2017 Eugeny Brychkov
When re-allocating RAM disk space:
• If RAMTOP value before re-allocation is equal to DSKLPG value, top
of RAM will be aligned to the new start of disk image start page. In
other words, if there’s nothing else being allocated by the GR8NET
system below disk image, RAMTOP frees space according to DSKLPG
change. If RAMTOP value before re-allocation is not equal to
DSKLPG, it remains unchanged and no memory size below this page
changes.
• Same holds true to UPRAMS variable (user protected RAM area start), but, unlike
system-managed RAMTOP, this UPRAMS variable can be changed by NETSETMMV
statement to be equal to RAMTOP, and thus, if RAMTOP is equal to DSKLPG, full space
below new DSKLPG becomes available for user and NETBLOAD/NETBROWSE
operations.
DSKFMT
Initialize RAM-disk image
Format
CALL DSKFMT
Important notice
Formatting RAM-disk will wipe data from it. Before performing format, ensure you backed
required data up from current image of RAM disk onto another device (e.g. floppy disk,
hard disk, SD-card).
Usage
This statement formats RAM disk. There’re two formats available, chosen automatically:
• If RAM disk size is between 46 and 90 logical pages (368K-720K), disk is formatted
as 720K disk, with missing clusters marked as bad (0FF7h) in FATs;
• If RAM disk size is between 1-45 logical pages (8K-360K), disk is formatted as 360K
disk, with missing clusters marked as bad (0FF7h) in FATs;
• If RAM disk size is 0, returns Out of memory error.
FORMAT
Initialize RAM-disk image: not available for RAM disk
Format
CALL FORMAT
Usage
You can not format RAM disk with this standard Disk-BASIC command. Please use
DSKFMT statement. It is designed this way so that you do not mistakenly format real
floppy or hard drive.
DSKSTAT
Get/set state of the disk subsystem
Format
CALL DSKSTATE (T, S)
Arguments
T is variable and if 0, disk system is set as disabled, if T is 1 it is set as enabled;
© 2015-2017 AGE Labs
Page 84 of 156
© 2015-2017 Eugeny Brychkov
S is variable getting bitmap of the disk subsystem status
Usage
Changing T (status of disk system) will take effect on next warm boot. Hard reset or power
cycle will force reloading of the default state of disk subsystem. After changing the status,
you can use CALLNETSAVE command to update configuration page in flash chip and make
setting effective after cold start.
Variable S gets the following bitmap:
Bit Description
7-4 Reserved
3
Set if disk image in its maximal configuration does not fit RAM disk reserved area
2
Set if DSKCHG (disk change flag) is raised
1
Set if image is mounted and is being used by the disk subsystem
0
Set if disk subsystem is enabled
6.2. Nextor disk subsystem
Since December 2016 GR8NET is having Nextor disk subsystem in mapper modes 814 (512+512). The kernel is located in the subslot 2 of the expanded slot. Note that
expansion is performed by GR8NET adapter, and thus adapter has to be installed in
primary slot. To have Nextor operational both FPGA and flash chip firmware must be
updated, please refer to chapters Updating GR8NET firmware and Updating FPGA firmware.
Nextor supports FAT12 and FAT16 file systems, and will properly work with image
loaded by GR8NET DOS1 disk system (see GR8NET Disk subsystem (DOS1)), as well as
with storage located on the SD-card.
SD-card format should be:
• Partition-less, containing volume without MBR (master boot record), starting from
boot sector. Windows OS usually formats SD-cards of size less or equal to 1GB this
way. When formatting you should ensure FAT file system option is selected (FAT32
or ex-FAT options must not be used);
• Partitioned cards, having MBR. Windows OS usually formats cards of more than 1GB
size this way. Nextor will automatically mount only first partition.
If you have SD-card of size of 1GB or less, most probably it gets formatted as single
volume without MBR and FAT16 and you can start using it without any special preparation.
If your SD-card is 1GB or more, it will, most probably, be partitioned by Windows OS
using MBR, and you need to:
• Ensure you format partition with FAT (not FAT32 or ex-FAT) file system;
• Or use CALLFDISK embedded BASIC Nextor command to partition the card for using
with Nextor.
To boot your MSX into MSX-DOS2 you should put files NEXTOR.SYS and
COMMAND2.COM into the root directory of the volume (RAM disk or SD-card).
To dynamically mount additional volumes use MAPDRV.COM utility for DOS or
CALLMAPDRV utility for BASIC.
© 2015-2017 AGE Labs
Page 85 of 156
© 2015-2017 Eugeny Brychkov
For more information on using Nextor disk subsystem please refer to Nextor 2.0 User
Manual.
To disable Nextor initialization, please press and hold the following respective key
until GR8NET initialization finishes completely:
GR8NET
(Nextor) slot
1 (1.2)
Key scancode
(hex)
1A
2 (2.2)
19
International
keyboard
Russian keyboard
E
У
U
D
В
W
1
To forcefully boot Nextor in DOS1 mode press ad hold
© 2015-2017 AGE Labs
Page 86 of 156
key (scan code 01h).
© 2015-2017 Eugeny Brychkov
7. Built-in MSX-Audio and MSX-Music
Starting January 2017 GR8NET hardware and firmware is having built-in MSX-Music
(OPLL) capabilities. Starting mid of February 2017 is it having built-in MSX-Audio (limited
version of Y8950). OPLL Implementation is functionally identical to the YM2413 chip, but
uses 16-bit sound and finer timing than the original. MSX-Audio is based on OPLL
implementation, and has no ADPCM analysis/AD and discrete DA function.
OPLL and MSX-Audio are controlled by the command CALLNETOPL, which should be
used to enable or disable built-in Music and Audio hardware, and provide their
configuration.
When enabled, Audio and Music are present at their respective I/O ports (7C/7D for
OPLL and C0-C1 for Y8950) for writing in all mapper modes, and, when in mapper mode 8,
OPLL ROM BIOS will appear in subslot #3. In all other mapper modes OPLL BIOS is not
available.
NETOPL command settings are preserved by the NETSAVE command.
NETGETOPL
Gets status of built-in OPLL/Y8950, and initial setting of sample RAM size
Format
CALL NETGETOPL (G, GRS)
Arguments
G is variable, a bitmap will be returned with status of the OPL subsystem
GRS is variable getting size of Y8950 sample RAM in 8kByte pages
Usage
Variable G is having the following format:
7
OPLLDIS
OPLVLVL
AUDDIS
6
0
1
0
1
0
1
=
=
=
=
=
=
5
4
Reserved, must be 0
3
2
AUDDIS
1
OPLVLVL
0
OPLLDIS
OPLL output is enabled (default)
OPLL output is disabled
Normal volume (default)
Double volume
MSX-Audio audio and register outputs (Y8950) are enabled (default)
MSX-Audio audio and register outputs are disabled
GRS variable gets size of the Y8950’s sample RAM, indicating initial size of sample RAM
size, which is used to allocate RAM when adapter initializes. To get actual size of sample
RAM, refer to NETGETMMV command.
Any of arguments may be omitted, but at least one must be present.
© 2015-2017 AGE Labs
Page 87 of 156
© 2015-2017 Eugeny Brychkov
NETSETOPL
Enables or disables built-in OPLL/Y8950, controls doubling of output amplitude, and sets
sample RAM size
Format
CALL NETSETOPL (S, SRS)
Arguments
S is variable or constant, a bitmap of OPLL/Y8950 disable and volume settings
SRS is variable or constant setting size of Y8950 sample RAM in 8kByte pages (max 32,
default)
Usage
S follows the same format as G in NETGETOPL:
OPLLDIS 0 = Enable OPLL output (default)
1 = Disable OPLL output
Using this bit the command sets OPLL disable bit in System mode register
accordingly (see System registers chapter). Please note that this bit disables
built-in OPLL output, not OPLL itself. It still performs all required actions
internally, and enabling OPLL output will immediately cause valid FM sound to
appear
OPLLVLVL 0 = Normal volume (default)
1 = Double volume
This bit sets output volume level for the OPLL/Y8950. In double volume mode
audio outputs twice amplitude than in normal mode, however if many channels
are generating the sound, output may occasionally appear overloaded, and
output sound may be slightly distorted. Using this bit command sets OPL
2Xvolume bit in System mode register (see System registers chapter).
AUDDIS
0 = Enable MSX-Audio audio and register outputs (Y8950) (default)
1 = Disable MSX-Audio audio and register outputs
Using this bit the command sets Y8950 disable bit in System mode register
accordingly (see System registers chapter). Please note that this bit disables
built-in Y8950 audio and register output, not Y8950 device itself. It still
performs all required actions internally, and enabling Y8950 output will
immediately cause valid FM sound to appear. However to get valid ADPCM
output application should ensure it prepared ADPCM RAM properly after
enabling MSX-Audio.
SRS sets initial size of sample RAM size, which is used to allocate RAM when adapter
initializes. After changing value using SRS, you have to reboot machine to make setting
effective. If you want change to be permanent, use CALLNETSAVE command.
SRS can not be larger than 32 (256kBytes of sample RAM).
© 2015-2017 AGE Labs
Page 88 of 156
© 2015-2017 Eugeny Brychkov
7.1. Starting with built-in OPLL
OPLL is available in all mapper modes given its disable bit is reset manually or during
its configuration from flash (saved by NETSAVE). OPLL ROM BIOS is only available in
mapper mode 8, in subslot 3, if OPLL is not disabled.
You can start using and testing OPLL capabilities with the following plan:
• Boot GR8NET into BASIC, and use command CALLNETSETMAP(24) to reinitialize it in
mapper 8 mode so that OPLL ROM BIOS is visible to the system;
• During GR8NET initialization, press and hold keys F4 and F2 to get into browsing of
the RAM disk image;
• Select moonblas.dsk image with space key, and wait until machine goes to BASIC
and starts executing the application;
• In the MoonBlaster v1.4 application press F5 key to get to files menu, and using
space key list directory, and then select any sample module available in this RAM
disk image;
• Press F1 key to start song playing.
Boot image selection screen
MoonBlaster utility playing the song
Please note that MoonBlaster utility does not work in mapper mode 0 – it seems it
requires 512kB of RAM, and OPLL ROM BIOS. It also does not work in DOS2/Nextor mode
(that’s why RAM disk image is built under DOS1).
7.2. Playing games with built-in OPLL
When games are loaded with their respective mapper type (for example, Aleste loads
with mapper type 5 – ASCII16), OPLL ROM BIOS is not available any more, and game is
unable to detect OPLL chip (unless it assumes chip should be there).
In these situations you will need two GR8NETs in the system, one configured in
mapper mode 8 (having GR8NET network, 512kB of RAM, Nextor and OPLL ROM BIOS),
and another configured for the game. You can take the following steps to achieve the
result:
• Install GR8NET with ID=0 into slot 1, and GR8NET with ID=1 into slot 2. Connect
network cable to latter GR8NET with ID=2;
• On first boot, in BASIC, perform CALLNETSETMAP(24) and system will reset with
former adapter being configured in mapper mode 8;
© 2015-2017 AGE Labs
Page 89 of 156
© 2015-2017 Eugeny Brychkov
• On second boot, in BASIC, you perform commands CALLNETSETDA(1) to set default
adapter with ID=1 (latter one) and use CALLNETBROWSE browsing for game on the
internet (or installed SD-card) using latter adapter;
• When you choose the game, adapter with ID=1 (in slot 2) will reconfigure to
mapper type required for the game, and system will reboot with first adapter being
configured in mapper mode 8, and second configured with the game.
7.3. Using built-in MSX-Audio
MSX-Audio is detected differently than OPLL (Y2413), and applications supporting this
hardware should find it without MSX-Audio BIOS.
To play PCM samples MSX-Audio needs sample RAM, its space is automatically
allocated from the available GR8NET RAM space. To see effective RAM map please use
NETGETMMV command.
You can disable Y8950 with AUDDIS bit, and sample RAM will not be allocated and
freed space will be available for use, but in this case Y8950’s audio output will also be
disabled. Alternatively you can set sample RAM to lower values than 32, or to 0 to disable
ADPCM function. Value set corresponds to number of 8KB GR8NET RAM logical pages, thus
32 pages is 256KB, and 2 pages is 16KB.
7.4. Alternative interface to Y8950 and OPLL registers
Both audio devices are operating through I/O, but GR8NET provides alternative
read/write access to its built-in audio registers.
© 2015-2017 AGE Labs
Page 90 of 156
© 2015-2017 Eugeny Brychkov
Picture above shows starting locations of the Boot ROM page F0 and highlights
specific regions which are defined for FM generation by OPLL or Y8950.
• Green area shows 64 executable bytes of the boot ROM. This location is protected for
writing by the CPU;
• Red locations are channel register settings for OPLL (YM2413), in total 9 channels, 3
bytes per channel. First byte’s bits [7:4] are instrument number, bits [3:0] are volume
attenuation (OPLL registers 3x), second byte’s bit [5] is sustain key, [4] is key on/off,
[3:1] are octave, and [0] is F-Number MSB (OPLL registers 2x), and third byte’s bits
[7:0] are LSBs of F-Number;
• Fuchsia colored area is OPLL’s custom instrument properties, as defined in the
datasheet’s registers 0-7;
• Yellow locations are channel register settings for Y8950, in total 9 channels, 3 bytes
per channel. First byte’s bits [3:1] are feedback, bit [0] is connection type (Y8950
registers C0-C8), second byte’s bit [5] is key on/off, [4:2] are octave, and [1:0] are
MSBs of F-Number (Y8950 registers B0-B8), third byte’s bits [7:0] are LSBs of FNumber (Y8950 registers A0-A8);
• Light blue locations are definitions of Y8950’s instruments, 9 in total. Even locations
are attributed to even operators (modulators for chained connection), and odd
locations are for odd operators (carriers for chained connection). Instrument format is
the same as for OPLL, except that byte at instrument offset +3 contains KSL/TL for
carrier.
Two FM registers are not accessible this way: OPLL’s rhythm register 0B and Y8950’s
rhythm register BD. They should be accessed via standard I/O.
Y8950’s ADPCM registers are also accessible only through standard I/O, but there’s a
way to access sample RAM. To know starting page and size of the sample RAM use
NETGETMMV command, and then you have direct way to access these RAM pages using
NETSETMEM and NETLDBUF.
© 2015-2017 AGE Labs
Page 91 of 156
© 2015-2017 Eugeny Brychkov
8. Offline firmware upgrade
If you perform major upgrade – both updating flash chip and configuration of the
FPGA, you may start with online upgrade of the flash chip contents and then update FPGA,
or perform both updates offline in any order.
8.1. Updating contents of the onboard flash chip
In contrast with firmware update using NETFWUPDATE command described above,
this method assumes that GR8NET card flash chip’s image is totally damaged and does not
initialize and does not operate. If you use Turbo-R machine please ensure that you
perform update in Z80-compatible mode.
However even if card’s chip is dead you have an option to skip card’s
startup. GR8NET has special logical page 0F0h which is presented by the main
engine (FPGA chip) to the CPU when BIOS initialization starts. Code in this page
checks for arrow up key press, and if key is pressed, skips change of the page
to code image provided by flash, thus not initializing GR8NET adapter.
Thus if you suspect that adapter’s firmware stopped working properly, turn machine
off, remove all the external cartridges and devices except storage device, put adapter
under question into the slot 1, turn machine on holding arrow up key, and wait for BASIC
prompt. Then run fwupdate.bas utility from the attached storage device.
×
Figure 10. FWUPDATE.BAS utility screen output
© 2015-2017 AGE Labs
Page 92 of 156
© 2015-2017 Eugeny Brychkov
Utility will read firmware flash image into GR8NET’s RAM buffer, and request to
confirm MAC address. Option 1 is sourced from configuration logical page FFh, option 2 is
sourced from the current image of the flash chip (logical page BFh), and option 3 allows
you entering manual value if both options 1 and 2 are invalid.
You obtain valid MAC address from the serial number of the GR8NET cartridge as
shown on fig. 4. In the manual prompt you should enter 12 hexadecimal digits without
spaces and without colons, for example
? 101600040506
Then you confirm MAC address choice, and utility flashes the flash chip with the
image in GR8NET buffer RAM.
Firmware update utility FWUPDATE.BAS together with binary image of the flash chip
and accompanying mandatory executable binaries are available for download from GR8BIT
website.
Location of the files:
• http://www.gr8bit.ru/software/firmware/GR8NET/bloadable/
o Executable files FWUPDATE.BAS, FWUPDATE.BIN, SAVEMAC.BIN;
o Firmware image files UPDATExx.BIN (66 files in total);
o Or RAR archive containing all these files above;
• http://www.gr8bit.ru/software/firmware/GR8NET/
o UPDATE.BIN firmware image cumulative file (528KB) to be NETBLOADed in
case GR8NET is functional.
8.2. Updating FPGA firmware
If you are supplied with the update for the GR8NET engine – FPGA chip, you can
apply the update using Byteblaster-II (was being supplied within batch #1) or USB-Blaster
device (should be obtained separately to GR8NET). These devices are further referred as
Blaster device.
Blaster device requires printer parallel port on the computer, with installed
programming software – either standalone Altera Programmer, or a bundle of Altera
Quartus software. This software is available for download from Altera website for free
through online registration.
WARNING! Connecting wires between programming device – Blaster
and GR8NET card should be performed with all the related devices
disconnected from the power mains (not just powered down).
In case of improper grounding – e.g. MSX PC having 2-wire power
cord and thus NOT having protective ground connection, PC/notebook
Blaster is connected to having OR not having connection to protective
ground, monitor connected to the MSX computer having OR not having
connection to protective ground – may cause AC voltage up to 127VAC between signals
and thus damage devices being connected – GR8NET and Blaster.
Please follow the steps to achieve successful update:
© 2015-2017 AGE Labs
Page 93 of 156
© 2015-2017 Eugeny Brychkov
1. Download Altera Programmer from Altera’s download center and install it (fig.
11b). Note that versions above 13.1 do not support Cyclone III chips, thus select
this version for download;
2. Prepare FPGA update image;
3. Unscrew cartridge, remove board from the casing. Be very careful as device is
sensitive to the ESD;
4. Disconnect MSX PC and its connected devices from the power mains. It is allowed
leaving only PC with parallel port powered on;
5. Connect Blaster device to its ribbon cable, and ribbon cable to the connector
adapter, and connector adapter to the GR8NET as shown on the fig. 11a. Ensure
you connected adapter properly and there’re no hanging pins of the adapter;
6. Insert GR8NET into any slot of MSX PC;
7. Carefully connect Blaster device to the parallel port of the PC having Altera
programmer (or full Quartus software package) installed;
8. Connect MSX PC to the power mains, turn it on: programming procedure will
require power from MSX PC to GR8NET. It may appear that GR8NET will not
initialize because Blaster will immediately hijack operation of the FPGA (this is how
Blaster was designed by Altera). Do not worry about this issue and proceed to
next step;
9. Start Altera Programmer application (fig. 11c): (1) set up ByteBlaster-II or USBBlaster device and choose it; (2) select Active Serial mode; (3) select FPGA update
image; (4) select Program/configure mode and (5) optionally Verify mode; and (6)
perform programming;
10. Device will be unavailable while programming is in progress, and if MSX was using
the device, it may crash;
11. After programming is complete, un-tick “program” checkbox and tick “verify” one,
and perform verification of the image (programmer will read image and compare it
– this way you will be 100% sure that image was loaded correctly);
12. Power MSX PC off, disconnect Blaster device from PC’s port, disassemble
connection chain in backward order;
13. Turn MSX PC on and check that GR8NET initializes;
14. Put GR8NET board into the cartridge casing, carefully screw it.
Figure 11 a. Connection of the connector adapter to the GR8NET
© 2015-2017 AGE Labs
Page 94 of 156
© 2015-2017 Eugeny Brychkov
Figure 11 b. Altera’s download website
1
2
6
3
4
5
Figure 11 c. Altera programmer dialog window
© 2015-2017 AGE Labs
Page 95 of 156
© 2015-2017 Eugeny Brychkov
9. GR8NET technical reference
GR8NET employs several modern technologies and relatively complex device in its
programming and management of its resources. If you experience difficulties with it,
please contact developer or community for more information and support.
9.1. Identification and detection
You MSX computer may have up to 4 GR8NET adapters installed. Each adapter is
physically preset with ID number by the switch located in the edge connector’s cartridge
box window (fig. 5 and 12). Adapter ID is set in binary system, with switch being turned
ON designating digit 1, thus both switches turned off identify adapter #0, and both
switches turned on identify adapter #3.
OFF = 0
SW1 = bit 0
SW2 = bit 1
ON = 1
Figure 12. Configuration switches
Configuration, or activation, of all the GR8NET adapters in the system is performed by
firmware using two I/O ports – 5Eh and 5Fh. Only one selected adapter can be chosen to
be accessed through I/O ports at the time however application still can access adapters’
features available in their memory space.
Port 5Eh: adapter and register selection
7
6
5
4
Selected adapter ID
Default adapter ID
SAID1
SAID0
DAID1
DAID0
© 2015-2017 AGE Labs
3
RID3
Page 96 of 156
2
1
Register ID
RID2
RID1
0
RID0
© 2015-2017 Eugeny Brychkov
The following fields are defined in the register 5Eh:
Field Description
SAID Adapter being selected, the one which will be further accessed through I/O port
5Fh
DAID Default adapter (see chapter 3.1). These bits should not be changed by the
application
RID Register index being selected to be accessed through port 5Fh
When adapter is not yet initialized, it accepts writes to the port 5Eh, but will not
respond to port 5Eh or port 5Fh reads and perform no action on port 5Fh writes.
When adapter has successfully initialized, it will respond to port 5Eh and port 5Fh
reads if its switch configuration matches field SAID, and it will write to registers indexed by
RID.
Thus mechanism allows selection of specific adapter for I/O access, and provides
mechanism for deactivation of the adapter in case there’s conflicting configuration between
multiple adapters installed into the system.
When port 5Eh is read, adapter identified by the SAID will return previously written
value. Logically, all installed adapters are expected to keep same copy of the port 5Eh
contents.
Port 5Fh reads from or writes to register pointed by the value in RID field of port 5Eh
register of the adapter identified by SAID field. Register allocation is the following:
Index
Function
Op
(hex)
0
R
1
R/W
2
3
4
R/W
R
R
W
5
R
6-E
F
-
If adapter is present and activated, this register reads as the following
data in loop: ‘G’ (47h), ‘R’ (52h), ‘8’ (38h), ‘N’ (4Eh), following by
GR8NET engine’s (FPGA) build year (word, little-endian), month (byte)
and day (byte). The sequence is reset by writing index 0 to port 5Eh. If
adapter is inactive 0ffh is returned, and all other registers are n/a
This register is initialized by the GR8NET firmware, and should hold
adapter’s slot ID in RDSLT format. Thus application, by setting SAID
bits, can identify the location of the adapter in the CPU memory space.
Application should NOT write to this register
Mapper register, see Setting operating mode and mapper type chapter
Major version of the hardware (e.g. 0)
Minor version of the hardware (e.g. 5)
PCM replenishment data byte, functions the same as PCM data register
Prefetch data register, functions the same as prefetch data register in
special control register set
Reserved
Unavailable
GR8NET adapters should be used in the following way:
1. User orders adapters using their identification switches from #0 to #3. Numbering
order may not be contiguous;
© 2015-2017 AGE Labs
Page 97 of 156
© 2015-2017 Eugeny Brychkov
2. User attaches specific network cables to specific adapters, thus there will be clear
association between adapter # and network it is physically connected to;
3. Application is expected to know adapter # connected to each network, and
performs enumeration of the adapters using port 5Eh bits SAID to see if required
adapter is present (“GR8N” from register 0, or just first ‘G’ for easiness) and
properly initialized (valid slot ID in register 1 – not 00 and not FF);
4. Application, using slot ID got from each adapters’ register index 1, initializes these
adapters to work with predefined subnetwork, and uses memory access to the
adapters’ resources;
5. If application needs to change specific adapter’s mapper type (see Setting
operating mode and mapper type chapter), it selects adapter using SAID bits and
writes to its register 2. Note that mapper type change takes effect immediately.
9.2. Setting operating mode and mapper type
Now we know how to detect and manage multiple GR8NET adapters in the system,
we will consider how to manage adapters individually.
Adapter management starts with its I/O mapper register 2 (see also Identification and
detection chapter).
Mapper register (set to 5Eh after hard reset)
7
6
5
4
Special control register appearance
Bank 3
Bank 2
Bank 1
Bank 0
3
2
1
0
Memory mapper type
GR8NET adapter’s CPU visible memory space is divided into four locations – GR8NET
banks: 4000-5FFF (GR8NET bank 0), 6000-7FFF (GR8NET bank 1), 8000-9FFF (GR8NET
bank 2) and A000-BFFF (GR8NET bank 3). Please do not confuse these with CPU memory
banks, which are 0000-3FFF (CPU bank 0), 4000-7FFF (CPU bank 1), 8000-BFFF (CPU bank
2) and C000-FFFF (CPU bank 3).
Exception to banking system explained above is ASCII16 mapper mode, however
internally to GR8NET this mode is a clone of ASCII8 mode with predefined second logical
page number.
Important: here and further we will be talking about GR8NET banks. If we will need
to refer to CPU banking subsystem, it will be explicitly stated as “CPU bank” or “Z80 bank”.
Special control register appearance: special control registers is the area of the
visible CPU memory which overlays the data currently visible in the specific bank. This
means that having turned these registers on in bank 0 makes currently selected bank 0‘s
page’s data behind these registers inaccessible for reads and for writes.
If bit 7 of mapper register is set, then special control registers appear at the end of
bank 3; if bit 6 is set, then same special control registers appear at the end of bank 2; if
bit 5 is set, then same special control registers appear at the end of bank 1; and if bit 4 is
set, then same special control registers appear at the end of bank 0.
© 2015-2017 AGE Labs
Page 98 of 156
© 2015-2017 Eugeny Brychkov
GR8NET mapper uses control registers in bank 0 only, together with ROM’s physical
page 0 (logical page 80h). This ROM page has no meaningful data or code in the special
control register area.
Important: you can turn special control registers on in any mapper type except
mapper type 7 “Mapped RAM”. Four bank change registers present in the special control
register set will reflect current pages set in banks, and are writable providing additional
method changing the pages in the specific 8 Kilobyte bank.
Memory mapper type: 4 bits representing the mapper currently in effect. Mapper
type change takes immediate effect when written to.
GR8NET may function in several mapper configurations, providing programmer a
couple of standard and custom functionalities. The following mapper modes are available:
#
0
1
2
3
4
5
6
7
MM Type
Description
Simple mappers, can be present in primary or expanded slot
GR8NET mapper Card operates as the GR8NET internetworking adapter
Plain writePresents write-protected logical pages 0, 1, 2 and 3 (first 4 RAM
protected 32K pages) in GR8NET banks.
ROM
Examples of software using this mapper are King’s Valley,
Knightmare and many more
Konami without 256 Kbytes memory mapper. 5 significant page number bits, 32
SCC
pages, bank 0 is fixed at page logical 0 (first RAM page).
(K4 mapper)
Examples of the software using this mapper are Nemesis, Penguin
Adventure, Treasure of Uşas, Metal Gear
Konami with
512 Kbytes memory mapper. 6 significant page number bits, 64
pages, SCC is contained in page 63 overlaying presented logical
SCC
page 63 contents.
(K5 mapper)
Examples of the software using this mapper are Nemesis 2, King’s
Valley 2, Metal Gear 2
ASCII 8
1 Megabyte memory mapper (all presented by onboard RAM). 7
significant page number bits, 128 pages. Examples are Auf
Wiedersehen Monty and Arkanoid II
ASCII 16
1 Megabyte memory mapper (all presented by onboard RAM). 6
significant page number bits, 64 by 16K pages. Switching to page
#x presents logical pages x*2 and x*2+1 in respective 16 Kbyte
bank location
Mirrored ROM
GR8NET RAM buffer pages 0/1 contents are presented in CPU
address space 0000-3FFF, pages 2/3 are presented in CPU address
space 4000-7FFF, and pages 4/5 are presented in CPU address
space 8000-BFFF.
Mapped RAM
Provides 1 MByte standard mapped RAM. Note than GR8NET
responds to reading of memory mapper ports FCh-FFh according to
the second option set by NETSETMAP command.
© 2015-2017 AGE Labs
Page 99 of 156
© 2015-2017 Eugeny Brychkov
Below is the list of the composite mappers; in these modes GR8NET performs slot
expansion, thus GR8NET adapter itself must be installed in the primary slot (no slot
expanders). These modes are specifically designed for gaming and applications which run
as ROMs but require access to network (GR8NET mapper), storage (Nextor) and wants to
have more RAM (512K). In these modes functions are allocated in the following way:
• Subslot 0: GR8NET mapper with 512K RAM. Note that in modes 9-14 GR8NET RAM
mirrors contents of game mapper in subslot 3, thus writing to GR8NET RAM will
modify information visible to CPU in subslot 3 (for example invoking NETBROWSE
will overwrite several pages at the beginning; loading disk image using built-in DiskROM will also corrupt original information in specific designated logical pages);
• Subslot 1: 512KB mapped RAM;
• Subslot 2: Nextor storage subsystem;
• Subslot 3: see table below.
#
8
9
10
11
12
13
14
15
MM Type
Description
Composite mappers, must be present in primary slot only
FM-Pak
Subslot 3 contains FM-Pak ROM
Plain writeProvides GR8NET RAM (seen in read/write mode through
protected 32K 0) the same way as mapper mode 1
ROM
Konami without Provides GR8NET RAM (seen in read/write mode through
SCC
0) the same way as mapper mode 2
(K4 mapper)
Konami with
Provides GR8NET RAM (seen in read/write mode through
SCC
0) the same way as mapper mode 3
(K5 mapper)
ASCII 8
Provides GR8NET RAM (seen in read/write mode through
0) the same way as mapper mode 4
ASCII 16
Provides GR8NET RAM (seen in read/write mode through
0) the same way as mapper mode 5
Mirrored ROM
Provides GR8NET RAM (seen in read/write mode through
0) the same way as mapper mode 6
Illegal
Do not use this mapper type
subslot
subslot
subslot
subslot
subslot
subslot
Changing mapper ID through I/O:
• GR8NET mapper type is automatically initialized with logical page numbers 80h, 81,
82h and 83h;
• ASCII-8/ASCII-16 mapper types are initialized with page numbers 0;
• Other mapper types are initialized with logical page numbers 0, 1, 2 and 3
respectively.
Changing mapper ID through banking special control registers:
• The only automatic change is changing to K4 mapper when bank 0 is automatically
initialized with logical page 0;
• Before changing ensure that you have set correct page numbers in special control
registers to continue proper execution;
© 2015-2017 AGE Labs
Page 100 of 156
© 2015-2017 Eugeny Brychkov
• There’s a cheat in the mappers 2 and 3. While you can change pages through native
mappers’ page change mechanism using mentioned number of significant bits,
when accessing banking registers through special control registers space you have
access to all 8 bits, thus for example in K4 mapper mode writing 05Eh into bank
register application will get access to RAM’s page 05Eh rather than to page 01Eh.
© 2015-2017 AGE Labs
Page 101 of 156
© 2015-2017 Eugeny Brychkov
9.3. Logical page assignment
Every bank can be set to display specific logical page contents. You should distinguish
between physical pages which correspond to memory or register area of specific device
and logical pages which represent one assembly of all available memory spaces of all
GR8NET onboard devices.
Page mapping is performed in the following way:
Logical
page #
(hex)
Number of
pages
(dec)
FF
1
FE
1
FD
F1
13
(Reserved area)
F0
1
GR8NET boot page
EF
CA
38
(Reserved area)
C9
1
C8
1
SD-card status and
MathPack
SD-card data buffers
C4
4
PCM buffers
C0
4
W5100 pages
BF
BE
B8
B7
B6
B5
9B
9A
99
8A
89
88
87
81
1
Configuration data
Adapter configuration stored in flash chip
7
GR8NET logo
See GR8LOGO.ASC in the examples chapter
2
OPLL ROM
OPLL ROM appears in subslot 3 in mapper mode 8
when OPLL is not disabled using NETOPLL
27
(Reserved area)
1
GR8NET code
Routines supporting operation of the GR8NET adapter
16
Nextor
Nextor software is available in mapper mode 8
2
Disk-ROM
MSX-DOS version 1 integrated Disk-ROM
7
GR8NET code
80
1
Adapter ROM BIOS
main page
7F
40
64
Adapter buffer RAM
3F
00
64
Adapter buffer RAM
Function
Description
System configuration
and variable page
SCC (sound custom
chip)
8Kbytes of RAM for GR8NET configuration data
implemented using Altera Cyclone III
Available in bank 2 only within 9800-9FFF address
space. All other space is n/a and read as 0FFh
Empty, returns 0FFh
This page is presented to CPU after hard reset, called
on GR8NET initialization start. See chapter 6
Empty, returns 0FFh
Presents diagnostic information on the SD-card
operation and mathematical functions
4 Kbytes RAM (presented twice in 8K CPU window)
32 Kbytes of RAM implemented within Altera Cyclone
III chip for PCM streaming audio
C0 is W5100 registers space, C2 is TX buffers space,
and C3 is RX buffers space
Routines supporting operation of the GR8NET adapter
Main page of the ROM presented in GR8NET bank 0
during adapter operation in mode 0
User and/or RAM disk area in mapper 0, mapped RAM
in mapper 8-14
User data and/or RAM disk area, available in mappers
0 and 8-14. In mapper modes 9-14 are also present as
respective game mapper in subslot 3
When mapper requiring 16 Kbyte page is used (ASCII-16) GR8NET engine sets two
consecutive 8 Kbyte pages.
© 2015-2017 AGE Labs
Page 102 of 156
© 2015-2017 Eugeny Brychkov
After hard reset ( RESET signal activation due to reset button press and release or
power cycle) bank 0 is set to logical page F0h corresponding to boot page provided by the
GR8NET engine (FPGA chip), which checks for arrow up keypress and skips or proceeds
with further initialization switching to logical page 80 (first physical ROM page).
© 2015-2017 AGE Labs
Page 103 of 156
© 2015-2017 Eugeny Brychkov
9.4. Special control registers
As explained in Setting operating mode and mapper type chapter, special control
registers can reside at the end of in any 8 Kbyte banks, render logical page’s contents
behind these registers in accessible. Application may switch these same registers on in any
one or more banks it needs, or turn them off in all banks (like it is done for e.g. Konami
memory mappers by default).
Register address
B0
B1
B2
B3
SD-card management
Function
5FC0
7FC0
9FC0
BFC0
Status
5FC1
7FC1
9FC1
BFC1
Sector buffer position
5FC2
5FC3
5FC4
5FC5
7FC2
7FC3
7FC4
7FC5
9FC2
9FC3
9FC4
9FC5
BFC2
BFC3
BFC4
BFC5
5FC6
7FC6
9FC6
BFC6
Sector count
5FC7
7FC7
9FC7
BFC7
Command/status
register
5FC8
…
5FCB
5FCC
…
5FCF
5FD0
…
5FD7
5FD8
5FD9
7FC8
…
7FCB
7FCC
…
7FCF
7FD0
…
7FD7
7FD8
7FD9
9FC8
…
9FCB
9FCC
…
9FCF
9FD0
…
9FD7
9FD8
9FD9
BFC8
…
BFCB
BFCC
…
BFCF
BFD0
…
BFD7
BFD8
BFD9
MSX-Audio settings
(ADPCM RAM)
5FDA
7FDA
9FDA
BFDA
OPLL volume
Sector #
(32-bit value)
Description
Shows SD-card access machine
status and allows manual reset of
the card
Defines the place in the buffer
where sector data (will) reside
512-byte Sector number to
perform operation on
Number of sectors to process
(0=no op, max 8)
Starts SD-card R/W process
Reserved
SD-card size
32-bit size of SD-card in 512-byte
sectors
Reserved
Starting RAM logical page number
Current RAM size in 8kB pages
Linear volume from 80h (full
sound) to 0 (mute) (see also
Volume section of this table)
System registers
5FDB
7FDB
9FDB
BFDB
System mode register
5FDC
7FDC
9FDC
BFDC
Error register
© 2015-2017 AGE Labs
Page 104 of 156
Mapper read (bit 0), clock source
(bit 1), OPLL (bits 2), 2xVolume
(bit 3) and Y8950 (bit 4) settings
Register keeping error code for last
network subsystem operation
© 2015-2017 Eugeny Brychkov
Register address
B0
B1
B2
B3
Function
5FDD 7FDD 9FDD
BFDD
P5EDATA
5FDE
9FDE
BFDE
Mapper ID
5FDF 7FDF 9FDF
Bank switching
5FE0 7FE0 9FE0
5FE1 7FE1 9FE1
5FE2 7FE2 9FE2
5FE3 7FE3 9FE3
Configuration
BFDF
Adapter ID
7FDE
BFE0
BFE1
BFE2
BFE3
Switchable
Switchable
Switchable
Switchable
bank
bank
bank
bank
5FE4
7FE4
9FE4
BFE4
My slot ID
5FE5
5FE5
9FE5
BFE5
Bank2 slot ID
0
1
2
3
Description
Contents of the register written to
port 5Eh
Mapper ID register, same as
appears in index register 2 through
I/O
Adapter identification
These four registers identify logical
page numbers presented in
respective banks
Slot ID of the adapter in RDSLT
format. Appears in I/O index
register 1
Storage area to preserve bank 2
slot identifier when switching bank
2 to GR8NET slot
Volumes
5FE6
7FE6
9FE6
BFE6
Master DAC volume
5FE7
7FE7
9FE7
BFE7
SCC volume
5FE8
7FE8
9FE8
BFE8
Digital waveform input volume
5FE9
7FE9
9FE9
BFE9
PCM volume
Controlled interrupt generator with watchdog
5FEA 7FEA 9FEA BFEA
Control register
5FEB 7FEB 9FEB BFEB
24-bit timer counter
5FEC 7FEC 9FEC BFEC
value/Frequency
(Must read LSB first, must write MSB last)
5FED 7FED 9FED BFED
Waveform input
5FEE 7FEE 9FEE BFEE Digital waveform input (16-bit)
5FEF
7FEF
9FEF
© 2015-2017 AGE Labs
BFEF
Signed integer
(Must write LSB first, for 8-bit samples writes
MSB only)
Page 105 of 156
GR8NET DAC linear
volume. All volumes are
in range of 080h
(maximal, unmodified
sample data) and 0h
(mute)
SCC linear volume
Linear volume for the
digital data in the area
5FEF:5FEE
Linear volume for the
PCM playback
Start/stop, run, mode
Controlled interrupt
generator with watchdog
This register is used to
mix within internal
GR8NET DAC
© 2015-2017 Eugeny Brychkov
Register address
B0
B1
B2
B3
PCM function
5FF0 7FF0 9FF0 BFF0
5FF1 7FF1 9FF1 BFF1
5FF2 7FF2 9FF2 BFF2
5FF3 7FF3 9FF3 BFF3
5FF4 7FF4 9FF4 BFF4
5FF5 7FF5 9FF5 BFF5
5FF6 7FF6 9FF6 BFF6
Prefetch function
5FF7 7FF7 9FF7 BFF7
5FF8 7FF8 9FF8 BFF8
5FF9 7FF9 9FF9 BFF9
5FFA 7FFA 9FFA BFFA
5FFB 7FFB 9FFB BFFB
5FFC
7FFC
9FFC
BFFC
5FFD
5FFE
7FFD
7FFE
9FFD
9FFE
BFFD
BFFE
9FFF
BFFF
Function
Control register
PCM buffer bytes free
(Must read LSB first)
PCM buffer write pointer
Description
Start/stop, mode, status
PCM function pointers
(Must write MSB last)
PCM data register
(also available @ port index 5)
Sequential replenishment
of the PCM memory
Control register
Low 16 bytes of the
start/current memory pointer
Low 16 bytes of the end
memory pointer or mask
High nibble: high 4 bytes of end
pointer, low nibble: high 4 bytes
of start/current pointer
Two locations (16-bit word) for
prefetched memory data
Control and status
Prefetch function pointers
Prefetch data word
Adapter mode
5FFF
7FFF
© 2015-2017 AGE Labs
Adapter flags
Page 106 of 156
Used by the firmware to
identify the behavior of
specific functions
© 2015-2017 Eugeny Brychkov
9.5. Hardware-accelerated functions
There’s a set of useful functions programmer can use to accelerate access to the
card’s resources, and implement specific multimedia solutions. These functions, as well as
some card’s configuration parameters, are accessed through special control registers.
9.5.1. Controlled interrupt generator with watchdog
Controlled interrupt generator provides the feature to generate controlled timing to
PCM function, controlled hardware interrupt and timing to the applications using polling of
generator’s status register. Interrupt counter can use 100 nanoseconds clock period (10
MHz frequency) or 279 nanoseconds clock period (3.58 MHz, sourced from MSX bus). The
timing properties of the interrupts are calculated using the following formulas:
• at 10 Mhz period Tint = 10 −7 * n ;
• at 3.58 Mhz period Tint = 279.33 ∗ 10 −9 * n ;
• frequency f int = 1
.
Tint
There’re two modes generator can operate in: countdown timer and frequency
generation.
In countdown timer mode timer counter value is 24-bit and thus can have values
from 0 to 16,777,215. Sample values are listed below.
Countdown timer @10 Mhz (CLS bit=0)
Counter
Tint , sec
0
1.6777216
10
1 µs
f int (Hz)
0.596
1000000
128
227
453
907
1250 10000000 16777215
12.8 µs 22.7 µs 45.3 µs 90.7 µs 125 µs
1
1.67772215
78 125
44 053
22 075
11 025
8 000
162
45,25
µs
22 099
325
90,79
µs
11 015
448
125,14
µs
7 991
1
0.596
Countdown timer @3.58 Mhz (CLS bit=1)
Counter
Tint , sec
f int (Hz)
0
4.6863732
10
2,79 µs
0.2133846 1000000
46
12,85
µs
77 826
81
22,63
µs
44 198
3580000 16777215
1
4.6863729
1
0.2133846
In frequency generation mode value is 16-bit, with most significant byte always being
0.
Frequency generator (always uses 10MHz clock, bit CLS has no effect)
Frequency
Tint , sec
f int (Hz)
0
15.259 µs
10
0.1
50
20 ms
8000
125 µs
11025
90.7 µs
22050
45.4 µs
44100
22.7 µs
65535
15.26 µs
65535
10
50
8 000
11 025
22 026
44 052
65 531
© 2015-2017 AGE Labs
Page 107 of 156
© 2015-2017 Eugeny Brychkov
In order to make new counter/frequency value effective, you have to write 24-bit’s
MSB, even if it is the same as was written before. On this write whole 24-bit value is
latched into the generator.
In case you need longer interrupt period, you can implement interrupt counting in
software. For example, in case you need event to occur each minute, you set interrupt
generator to 1 second, and count 60 interrupts.
Reading 24-bit counter will give application the current countdown value at the time
when LSB was read. Application should read LSB first, and MSB last to get stable correct
value. Programmer should make adjustment for counter value reading and processing
operations to identify more or less definitive countdown stage of the timer/generator.
The GR8NET card as a source of the interrupt is not standard for the MSX PC, and
MSX PC standard interrupt service routine does not clear the interrupt from GR8NET. It
presents specific risk when interrupt generator is started but for some reason is not
serviced, GR8NET will keep interrupt wire active, causing MSX interrupt service routine
performing recursive calling – because MSX PC service routine enables maskable interrupts
before it finishes. Keeping Z80 CPU interrupt line low for long time will cause call stack to
overflow and code execution failure.
Watchdog mechanism is introduced preventing failures arising from recursive
interrupt service routine calling. It will keep hardware interrupt line active for another
countdown period after interrupt line activation. If this period expires and application does
not clear interrupt condition, if hardware interrupts are enabled, watchdog deactivates
hardware interrupt line and suspends generator; however if hardware interrupts are
disabled watchdog does not suspend generator. In both cases watchdog sets generator
error bit in control/status register. Main code of application will need to sense this error
condition and restart generator if it has shut down.
If hardware interrupts are enabled, when counter reaches zero (in frequency mode
countdown number is internally calculated within generator circuit) hardware interrupt is
generated. In IM1 (interrupt mode 1) call to physical address 0038h is performed in case
CPU’s maskable interrupts are enabled.
© 2015-2017 AGE Labs
Page 108 of 156
© 2015-2017 Eugeny Brychkov
Bit
0
1
2
3
4
5
6
7
Interrupt generator control register (5FEA) has the following format:
Name Description
OP
Generation operation control
W: set to 1 resume counting and reset to 0 to suspend counting
R: is set to 1 if interrupt generator counter is counting
RST
Reset control
W: Set to 1 to reset generator internal counter. If you set OP bit
simultaneously with setting RST bit, counter will reset and generator
restart counting using new values. Resetting counter also resets ER
and INT bits
R: n/a
HZP
Period of Hz mode
W: If reset to 0, generator treats 24-bit value in counter register as timer
countdown counter; if set to 1 then counter register’s low 16-bits (first
two bytes) are treated as frequency in Hertz
R: Value written before
WDE Watchdog enable bit.
W: set this bit to 1 to enable watchdog
R: Value written before
IGE
Hardware interrupt enable bit.
W: set this bit to 1 in order to enable hardware interrupt line activation
R: Value written before
CLS
Generator clock source.
W: If reset to 0 generator uses 10 MHz clock (100 ns period) for
countdown, if set to 1 generator uses 3.58 MHz clock (~279 ns period)
R: Value written before
ER
Interrupt generator error.
W: write 1 to clear this error, writing 0 has no effect
R: is set to 1 if counter stopped counting because its interrupt request
was not cleared in time and timing is disabled by watchdog. Condition
is cleared by writing 1 into this bit. Writing to bit 1 (RTS) also clears
this condition
INT
Interrupt occurrence flag.
W: write 1 to clear this bit (mean interrupt was serviced), writing 0 has no
effect
R: Set to 1 if interrupt generator is the source of the hardware interrupt.
The condition is being cleared by writing 1 to this bit
To use controlled interrupt generator:
1. Disable generator by writing RST=1 and OP=0;
2. Choose source and mode you will be using: source can be 10 MHz clock or 3.58
MHz clock, and mode can be countdown count or frequency in Hertz. Calculate 24bit value accordingly, and write 24-bit generator counter register. MSB of this
register should be written last, even if it is 0, because whole 24-bit value if
© 2015-2017 AGE Labs
Page 109 of 156
© 2015-2017 Eugeny Brychkov
3.
4.
5.
6.
7.
8.
internally latched on the write to this MSB byte location. Note that in HZP=1
(Hertz) mode only MSB is not effective, and should always be written 0;
Decide if you will need hardware interrupt. If you do not need it, skip to step 5.
Set up interrupt handling routine. In IM1 mode Z80 jumps to address 0038h. In
DOS mode you can change the jump instruction at location 0038h, but in BASIC
mode the jump is in ROM and you will have to find another way to your interrupt
handling code – use standard hooks (HKEYI or HTIMI), or switch slot in the bank
0 to the RAM and process interrupt code in this RAM. In case you will use
standard hooks ensure timing requirements are met because standard service
routine procedure starts with a number of push instructions, keyboard and other
device handling. In case you will write your own interrupt service routine from the
scratch do not forget to poll for VDP interrupt and clear its condition otherwise
machine will fail due to improper handling of the VDP interrupt;
Decide if you need to disable watchdog (WDE bit). You may need it disabled to
have hardware interrupts line being active until they are served (e.g. if you use
code which massively uses interrupt masking, for example in disk I/O).
Start counter writing RST=1, OP=1, WDE, HZP, IGE and CLS bits simultaneously;
Your interrupt handling routine should write 1 to IG to clear interrupt condition
and reset hardware interrupt line (if IGE is 1) in case it reads 1 in bit INT.
Application code should monitor condition of ER bit, if it is set, then one of more
interrupt periods are missed. In case watchdog is enabled, it is task of main code
to monitor ER bit, because watchdog suspends interrupt and interrupt service
routine will not be called any more. To clear ER flag write 1 to this bit. If
application (or programmer) notices that ER flag is set, they may choose to
decrease frequency of interrupts, or redesign the code;
When generator is not needed any more, perform step 1, restore all hooks and
slot assignments.
Important notes:
• Code should clear interrupt condition before enabling maskable interrupts;
• When application reads interrupt generator control register to obtain status
information, this reading takes time, and further processing of the information read
from this register also takes time, and value you have read may have expired every
nanosecond after you have read it. Thus if ER bit is not set, you are not guaranteed
that it is not got set when you started processing the status. The certain condition is
when you read the status register and it has ER bit set – it 100% means that there
was and is an error condition. Therefore, please design you code in the way that it
services generator’s interrupt request in time, and ensure main application code
regularly monitors status of generator and restarts it if needed.
• Implementation of the interrupt service routine may look the following way:
3A
07
38
EA5F
xx
LD
RLCA
JR
© 2015-2017 AGE Labs
A,05FEAh
C,xx
Page 110 of 156
© 2015-2017 Eugeny Brychkov
This code, instead of masking/testing bit in register A, shifts INT bit in A into the CY
flag and tests this flag.
9.5.2. PCM function
GR8NET provides feature of streaming PCM data into its mixer basing on the contents
of the PCM buffer. This buffer is 32 Kbytes long, and is being written into the mixer using
controlled interrupt generator’s counter. At interrupt counter equal to 99 (44 053 Hz) full
buffer 16-bit contents will be sent to mixer and DAC within 0.3719 seconds, if counter is
1122 (8 kHz) full buffer 8-bit contents flush will take 4.096 seconds. After the hardware
reset PCM function is in reset state.
In contrast with Z80-interrupt-based implementations, when sample output to DAC
may float in time due to Z80 command execution flow and maskable interrupt
management, PCM function does not have any sample output time instability, and always
outputs samples within approximately 10 nanoseconds delay after generator’s countdown
counter reaches zero.
There’re four registers related to the PCM function operation:
• PCM buffer bytes free: the 16-bit value indicates the free space in the PCM buffer
in bytes. Check this value to identify how much data PCM buffer needs to be
buffered with to continue waveform output without delays and interruptions.
Important: the value is dynamically calculated during execution of PCM playback
thus it is constantly being changed; to read correct value you must read least
significant byte first, and then most significant byte. 16-bit load commands like LD
HL,(05FFBh) are suitable for getting correct value;
• PCM buffer write pointer: the 16-bit value identifying the location in the PCM
buffer where application should write PCM data. This pointer is tightly coupled with
bytes free pointer: application should use this pointer to buffer data into PCM buffer
of the PCM buffer bytes free count. After writing data into the PCM buffer, you
should update PCM buffer write pointer.
15 14 13
N/A
PPN
•
12
11
10 9
8
7
6
5
4
3
2
1
Address within respective 8 Kbyte page (0000-1FFF)
0
PCM buffer write pointer points to physical location within the PCM buffer, with PPN
being physical page # of the PCM buffer (00b to 11b) and 13-bit address (00001FFF) being the position within respective physical page. When accessing PCM
pages through Z80 visible banks, programmer should set up respective page in
specific bank (page# is 0C4h+PPN), and then access 13-bit address within this page.
PCM function control register (5FF0) has the following format:
© 2015-2017 AGE Labs
Page 111 of 156
© 2015-2017 Eugeny Brychkov
Bit
0
Name
RP
1
SP
2
DS
3
PE
4
AS
5-6
7
N/A
HSP
•
•
Description
PCM reset control
W: reset to 0 (default) to put PCM function into the reset state
R: reset to 0 if PCM function is in reset state
Start or suspend PCM processing.
W: if set starts or continues PCM processing
R: reset if PCM function was not started, suspended or ended its
operation; set to 1 if PCM is processing
PCM data size. Reset to 0 for 8-bit sample data, set to 1 for 16-bit sample
data.
W: data size
R: data size
Playback ended.
W: n/a
R: if set to 1 means that playback has ended
Auto-stop.
W: If set to 1, when PCM function plays all the data available (write
pointer equals to internal read pointer), it stops, deactivating SP bit,
and application will need to start further playback manually. If reset to
0, PCM function waits for new sample, and as soon as new sample
arrives, it puts it into its DAC.
R: Value written before
Reserved
R: Bit is set to 1 if PCM buffer has at least one space for sample of DS size
W: n/a
PCM function data register is write-only register allowing application to replenish
PCM memory without using pointers. Application reads bit 7 of the control register
to see if there’s at least one space for the sample of the type set in control register’s
DS bit, and if bit is set to 1, writes sample to the PCM data register. Sample is being
written to the position currently pointed by PCM buffer write pointer, and pointer is
increased by number of bytes written. Both byte-load and word load commands are
allowed on the PCM data register, but application should ensure information it writes
remains aligned with sample data size set in DS.
PCM function data register is also available through I/O index port #5 for write only.
This functionality is very useful when performing OUTI or OTIR commands from the
memory to PCM data register with source memory pointer increase but no change
to output location (port number in CPU register C).
To
1.
2.
3.
use PCM function please follow the following steps:
Reset PCM function by writing 0 into PCM control register;
Set RP bit to get PCM function out of reset condition;
Perform data buffering. Ensure you buffer monophonic data of 8- or 16-bit in
sample size. Read PCM buffer bytes free (maximal value is 32766 bytes – even
value to be aligned with 16-bit sample data), read PCM buffer write pointer, then
© 2015-2017 AGE Labs
Page 112 of 156
© 2015-2017 Eugeny Brychkov
4.
5.
6.
7.
8.
set logical page number in required bank to 0C4h+PPN, and sequentially fill buffer
with data performing rotation within same bank page is presented in and within
the PCM logical pages (0C4h-0C7h), for example after page 0C5h address 1FFF
goes page C6h and address 0000, after page 0C7h and address 1FFF goes page
0C4h and address 0000. After you loaded the data to process, increase 16-bit PCM
buffer write pointer by the number of bytes you wrote. Do not write more data
than bytes free register indicates otherwise PCM sound may become corrupt.
Set controlled interrupt generator for required frequency by writing 0 into IG bit
and then setting values in registers 5FEB-5FE9.
Decide if you need generator to generate hardware interrupts, and start the
generator by writing 1 to IG bit (and IGE bit as decided);
Start PCM playback by simultaneously writing 1 to SP bit, and setting DS bit to
respective sample size;
In your application monitor PCM buffer bytes free register, and if it is not zero, go
to the step 3. If you preserved logical page # value and address within page, you
can reuse them to write data, but you have to use new bytes free count;
If you need to stop/suspend PCM data performance, write 0 to SP bit. Reading SP
bit will give you information about if PCM is playing or had finished the playback.
This status will also be available in PE bit – if it is set, playback has ended.
Note: if you decide to disable interrupts from controlled interrupt generator (bit IGE is
set to 0), then watchdog will not function.
9.5.3. Prefetch function
For complex DSP (digital signal processing) implementations, involving big amounts of
memory, MSX system may not be able to keep pace with interrupt servicing. Servicing PCM
content from the GR8NET 1MByte RAM to the digital waveform input involves managing
20-bit address, banking mechanism, 20-bit sample counter. Within 8-bit machine such
tasks present enormous overhead in computing and register load-testing, even if all values
are stored in the primary and alternate register sets.
Consider the following (non-optimized) code which gives understanding in level of
processing complexity:
plyint:
push
ld
rlca
jr
rlca
jr
; PCM playback interrupt service routine
af
a,(05feah)
; read generator status register
c,service
; INT bit set, go to service
c,error
; ER bit is set, go set flag ending DSP
in
ei
reti
a,(099h)
; clear VDP interrupt if it was raised
ld
ld
a,099h
(05feah),a
; clear generator’s interrupt condition
ld
and
sbc
bc,1
a
hl,bc
svcend:
service:
© 2015-2017 AGE Labs
Page 113 of 156
© 2015-2017 Eugeny Brychkov
ex
ld
sbc
ex
jr
de,hl
c,b
hl,bc
de,hl
c,plyend
exx
ld
ld
ld
ld
inc
ld
ld
inc
ld
a,e
(05fe1h),a
a,(hl)
c,a
hl
a,(hl)
b,a
hl
(05feeh),bc
; get 16-bit sample into BC from (HL) which is within
; 6000-7FFF window, and increase HL
; place sample into digital waveform input
bit
jr
inc
ld
7,h
z,nonb
e
h,060h
; test if HL, pointer to data to read, went over 8000h
; if yes, increase page # and reset pointer to start
; of the bank 1
exx
jr
svcend
; decrease sample counter - pair DE:HL
; counter is 0, go end playback
; switch to alternate register set
; E is RAM page in bank 1
nonb:
This code is even unable to perform PCM output from the GR8NET RAM at 11025 kHz.
Needless to say, machine is busy with stupid unneeded tasks it is not designed to perform.
In order to unload such tasks off the Z80 CPU and increase the speed, prefetch
function was designed. It has two 20-bit pointers, which designate start of the contiguous
RAM addressing area, and end of the area (thus each pointer is within 00000-FFFFFh). No
memory banking is involved; address is plain address within onboard physical device (RAM,
ROM chips or W5100).
Let’s consider the design of the prefetch control register.
Bit
0
Name
PE
1
2
PSRC
3
CYC
4-6
7
N/A
HHE
Description
Prefetch ended
W: n/a
R: is set to 1 if start and end pointers are equal
W: Source for the prefetch.
00 onboard 1 MByte RAM (00000-FFFFF)
01 onboard 512 Kbyte ROM (00000-7FFFF)
10 onboard W5100 chip (00000-07FFF)
11 n/a
R: Previously written value
W: set to 1 is cyclical prefetch mode. End counter acts as mask, not as
physical end address
R: Previously written value
Reserved
HTTP header end.
W: n/a
R: bit is set to 1 if 4 previous bytes read from prefetch data register equal
to 0D, 0A, 0D and 0A designating end of HTTP header and start of
data
© 2015-2017 AGE Labs
Page 114 of 156
© 2015-2017 Eugeny Brychkov
Prefetch function may work in two different modes:
• CYC = 0: in this mode prefetch function presents one-shot pass within address
space. Application writes start and end absolute memory device pointers, and
reads prefetched data from prefetch data register until bit 0, PE, becomes 1.
• CYC = 1: in this mode prefetch cycles through the specific address space.
Application writes start absolute address, and writes address mask into end
register. When reading prefetched data, next address following maximal masked
address will be reset to 0. Let’s illustrate it on the example: addressing W5100
chip’s socket 2 RX space through prefetch. Application writes 0707A into the start
register (assuming data to be read starts at address 07A within 2K memory space
of socket 2); then writes 07FFh into end register (2K memory space mask).
Application gets information from W5100 chip how many data bytes are available
at the socket 2’s buffer, and starts reading this count of bytes from prefetch data
register. If data being read is received using HTTP protocol, application checks
HHE bit, and finalizes HTTP header when this bit it set, and then continues with
HTTP data. When start pointer (current pointer) reaches 077FF (077FF & 07FF
equals to 07FF), next pointer is calculated using 077FF & not(07FF), and equals
to 07000. In cyclical mode PE flag has no valuable meaning.
Application can read either 8-bit or 16-bit value from the prefetch data register area.
Each time value is read from this register, next value from onboard device is fetched to be
returned next time CPU reads the register. Important: if application uses 16-bit word
reads, it must ensure that both start and end counter are odd or even, otherwise end of
prefetch will be missed because end-of-prefetch event will happen between reads of 16-bit
word and will be reset on 16-bit load command completion, resulting with start pointer
being 1 byte ahead of end pointer.
When using prefetch, interrupt service routine may look the following way:
contply:
…
ld
ld
de,05ffah
bc,05feah
ld
or
jr
…
a,(plyend)
a
z,contply
ex
ld
rlca
jr
rlca
jr
ex
ei
reti
af,af'
a,(bc)
plyint:
intstop:
; pointer to prefetch status register
; pointer to the generator status register
ld
ld
jr
; prefetch interrupt service routine
; preserve A which is being used in main code
; load generator’s status register, BC is preset to 05FEAh
c,service
; service the interrupt
c,intstop
af,af'
; end playback with error: generator error occurs
; restore A
a,1
(endflag),a
intexit
; generator error occurs: end playback
; set some flag to signal parent code that playback ended
© 2015-2017 AGE Labs
Page 115 of 156
© 2015-2017 Eugeny Brychkov
service:
ld
ld
ld
rrca
jr
ld
ld
hl,(05ffbh)
(05feeh),hl
a,(de)
; read prefetched 16-bit sample, a byte into L and next byte into H
; write it to digital waveform input
; read prefetch status register, DE is preset to 05FFAh
c,intstop
a,99h
(bc),a
; if end bit it set, go set the flag
; WDE=1, IGE=1, clear INT bit, continue interrupt generation
; clear interrupt condition
a,(099h)
af,af'
; clear VDP interrupt if it's raised
intexit:
in
ex
ei
reti
It is clear that this (slightly optimized) interrupt handler is much faster and uses less
CPU time.
To use prefetch function please follow the following steps:
1. Decide if you need one-shot or cyclical prefetch operation, and choose source
device.
2. Write start absolute address and either end absolute address (CYC=0) or mask
(CYC=1) into pointer registers;
3. Write prefetch control register;
4. Read 8-bit byte or 16-bit word from the prefetch data register. If you read a byte,
start pointer will be increased by 1, if word – it will be increased by 2;
5. You can know current prefetch pointer by reading start pointer’s locations;
6. In one-shot mode, to know if start (current) and end pointers match, read
prefetch flags register. Bit 1 is set if pointers match. Be careful with 16-bit word
prefetch access: pointer matching may happen during execution of the 16-bit data
load instruction;
7. You can continuously read through whole onboard device (one-shot operation) or
through specific memory window (cyclical operation).
Important note: prefetch performs data read from location, pointed by start absolute
address each time CPU accesses GR8BIT adapter, before serving CPU access request. It is
designed deliberately this way for the following reasons:
• As soon as you manually modify start address, prefetch data register will
immediately have new value from new location available for CPU read;
• If after you set up start address data at the start address location changes, reading
prefetch register you will have up-to-date data at the time of CPU access. Consider
the scenario: application wants to read W5100 RX buffer using prefetch. It sets up
start address, and polls for incoming data. While data did not come, start address
contains garbage. When data comes, start address byte changes its value, which is
prefetched just before prefetch register is being read.
© 2015-2017 AGE Labs
Page 116 of 156
© 2015-2017 Eugeny Brychkov
9.5.4. Combining functionalities of generator, prefetch and PCM
All three functions can be combined in order to unload useless pointer calculations off
the CPU. Example could be playback of the PCM data located in the GR8NET card’s RAM.
After loading audio file into the RAM, application knows its start address and end address.
Before anything else, application resets generator. Application sets these addresses up in
the prefetch function. Then application resets PCM function, and while bit 7 of PCM control
register is set to 1, reads sample (8-bit or 16-bit) from prefetch data register, and writes
this sample to PCM data register, thus buffering samples into PCM memory. After PCM
control register’s bit 7 becomes 0 (PCM buffer is full), or source data exhausted (bit 0 of
prefetch flags register is set), application starts PCM playback function, but it does not play
yet. To start operation, application sets up controlled interrupt generator (without
hardware interrupt generation), and launches it. Then application regularly checks bit 7 of
PCM control register, and quickly replenishes samples from prefetch register, until PCM
control register bit 7 becomes 0 or prefetch data ends.
Employing such technique allows programmer to know beforehand the frequency of
PCM buffer’s need for sample replenishment, and thus is able to schedule other useful
tasks between replenishments. At the same time replenishment task becomes most easy –
checking two status bits and moving 8-bit or 16-bit data from one fixed memory location to
another, without any pointer operations and bank switching.
9.5.5. Sound custom chip (SCC)
If application will set logical page 0FEh in any GR8NET mapper bank, it will be able to
use features of the SCC sound like it would switch to page 03Fh within Konami-with-SCC
cartridge space.
9.5.6. Digital waveform input
GR8NET provides functionality to mix custom waveforms into its output signal by
setting digital sample values into digital waveform input (16-bit, 5FEF:5FEF). Modification
may be timed by the GR8NET controlled interrupt generator’s interrupt service routine.
Important: for proper update of the 16-bit sample write low byte first, and then write high
byte. Actual update of the sample for mixing takes place when high byte is written. 16-bit
load commands like LD (05FFEh),HL are suitable for storing correct value within single CPU
instruction.
9.5.7. Volume registers
GR8NET has four volume registers, allowing application modifying digital volumes of
the internal GR8NET devices. Decreasing the volume of available channels may be useful
© 2015-2017 AGE Labs
Page 117 of 156
© 2015-2017 Eugeny Brychkov
because mixture of the input digital signals may overflow 16-bit physical DAC, presenting
sound overload effect and corruption of the output analog waveform.
Each volume register may have values from 80h (128 decimal) marking maximal
volume (unmodified digital sample), and 0 marking muting the digital sample. Sample
volume scaling down is performed in linear way.
• SCC volume register (5FE6): performs scaling of the digital sample going from SCC
module;
• Master DAC volume (5FE7): performs scaling of the digital sample after final digital
mixing;
• Digital waveform input volume (5FED): performs scaling of the digital sample
written to the digital waveform input register;
• PCM volume (5FF5): performs scaling of the digital sample going from the PCM
playback.
After hardware reset all volume registers are initialized to the maximum (080h).
9.5.8. Micro-SD card interface
GR8NET is having micro-SD-card slot and supports SC/HC cards. Independently of the
card architecture, application will access card data on 512-byte sector level. GR8NET is
having one RAM buffer page dedicated for the storage of the data read from or to be
written to the card, thus may hold maximum 8 sector contents at a time.
Let’s consider registers related to the SD-card operation:
SD-card status register
Bit Name Description
7
INSLT Set if SD-card is physically present in the slot
(R)
6
INIP
(R/W)
5-4
CTP
(R)
3-2
SDE1
SDE0
1
SDE
(R)
(R)
0
SDRDY
(R)
Initialization is in progress.
W: Write 1 to restart SD-card initialization process. The bit will become 0
when initialization complete (see status in bits 3:0)
R: Is set if SD-card is initializing
SD-card type. Valid only after successful initialization of the card. 00 = SC
V1 card, 01 = SC V2 card, 10 = HC card, 11 = MMC
Contains error code if SDE bit is set. 00=no error, 01=SD-card is busy,
10=R1 response timeout, 11=data token timeout
This bit is set if SD-card finished initialization with error, and SD-card
interface can not be used to access the SD-card. Application may try reinitialization of the card using INIP bit of this register
Is set if SD-card interface is ready to accept requests
Sector buffer position: identifies the position in the SD-card buffer memory which
will be used to read data from (write operation) or write data to (read operation). Sector
buffer position may have values ranging from 0 to 7, register is organized in the way
application can read it and calculate absolute CPU address for access:
© 2015-2017 Eugeny Brychkov
© 2015-2017 AGE Labs
Page 118 of 156
ld
ld
ld
add
7
0
de,(05fc0h)
e,0
hl,06000h
hl,de
6
0
;
;
;
;
5
0
sector buffer position goes to D
align to 512 byte boundary
base address for GR8NET bank 1 (example)
now HL contains physical CPU address to access data
4
0
3
2
SBP
1
0
0
After successful read or write command completion buffer position is increased by the
number of sectors successfully processed. When writing this register, ensure you write
position into bits 3:1, and not to 2:0.
Sector #: represents 32-bit value, little-endian, which is used to identify the sector
(block) number to be accessed. Application can not access SD-card in byte mode, even if
card supports it.
After successful completion sector # is increase by the number of sectors successful
processed.
Sector count: this register has the following format:
7
6
5
4
3
NOSP (R)
CHKPT1 (W)
2
1
NOSR (R/W)
0
NOSR is Number Of Sectors Requested to be accessed. Value of 0 means no
operation and 8 means 8 sectors to process. After read/write operation completion NOSR
contains number of sectors remaining to process;
NOSP is Number Of Sectors Processed, and after the operation is set to the number
of sector successfully read or written during last SD-card interface access. This is read-only
property.
CHKPT1 is Check Pattern value which is written together with NOSR. CHKPT1 is
equal to 9, thus to instruct SD-card interface to read or write 7 sectors application should
write 097h into the sector count register. Such check pattern write should be performed
each time read or write operation is requested, because check pattern is reset after
completion of the request. If check pattern written is not equal to 9, operation returns
error and SDCMD (command) register has BADCP bit set.
Command register:
7
6
5
DSKCHG
0
0
CHKPT2
4
R2VAL
3
R/W
2
CAINV
1
CERR
0
COPST
(W)
Setting COPST starts the SD-card access operation; the access will be read if R/W is
reset to 0 or write if R/W is set to 1. When access is complete, COPST bit is reset to 0. If
CERR bit is set then request processing completed with error, and application should
check SD-card status register’s bits 3:2 to know the cause of the error. Application also has
access to the advanced troubleshooting information, available in the logical page C9h.
© 2015-2017 AGE Labs
Page 119 of 156
© 2015-2017 Eugeny Brychkov
If after execution of the command CAINV bit is set then command was not
processed because if was passed with invalid argument (e.g. card is in byte-addressing
mode and block requested is outside of 32-bit range or check patterns are invalid).
When writing command register bits, application should ensure writing check pattern
2 CHKPT2 being 06h, thus to start card write operation application should write 069h into
the CTRIG.
Bits CAINV and CERR are reset by writing 0 into them, or by issuing new read or write
command.
R2VAL is set when R2 response following write command is valid (see C9h page
contents).
Bit DSKCHG indicates if SD-card was removed since last time this bit was cleared.
When GR8NET initializes, it sets this bit into 1 to signal to driver performing full
initialization of the structures. To reset the flag, driver writes 1 to this bit when accessing
SD-card for read or write operations. It is possible to write 080h into the command
register; this will not trigger any operation, but it will clear all error bits. If card is not
present in the slot this bit DSKCHG will be steady 1 and will not be changeable. Please
sense card insertion status by using INSLT bit of status register.
Logical page C9h contents (see SD-card “physical layer” specification for more detail)
Offset
Size Description
Dec
Hex
0
1
2
6
10
11
27
128
0
1
2
6
0A
0B
1B
80
1
1
4
4
1
16
5
16
R1 response from the card given for the last request
R2 response if bit R2VAL is set
R3 response given during initialization for CMD58 command
R7 response given during initialization for CMD8 command
Data token value detected during last read or write command
Card identification register (CID) given during its initialization
Last command given to the SD-card
128-bit CSD register reported by the SD-card
To use SD-card interface please follow the following steps:
1. (optional) Reset the SD-card subsystem by writing 1 into INIP bit of SD-card
command register. Wait until bits SDRDY or SDE become set. If SDRDY is set
proceed to next step, or if SDE is set investigate the reason by looking into bit
SDE1/SDE0, R1/R3/R7 responses in the logical page 0C9h;
2. Read command register and check for its bit 7 being 1. If it is set, check INSLT bit
of status register. If INSLT is reset, card is not in the slot. Halt operations until
user inserts card into the slot. Note that reseating of the SD-card in the slot resets
sector buffer position register to 0;
3. Set up RAM buffer position (note to use bits 3:1), and sector #;
4. Write 090h+number of sectors to process, not more than 8 sectors. If you set up
more than 8 sectors, or write something else than 9 into high nibble, command
will immediately return with CAINV bit set in status register;
5. Write 0E0h+flags into the command register, having but 7 set to reset DSKCHG
state bit. Meaningful flags to start the processing are bit 0 COPST (should be set
to 1) and bit 3 R/W (0=read, 1=write). If you write something else than 6 into
© 2015-2017 AGE Labs
Page 120 of 156
© 2015-2017 Eugeny Brychkov
high nibble, command will immediately return with CAINV bit set in status register.
If you write 0 into COPST bit no operation will be performed;
6. Wait for COPST bit to become 0, then examine bits CERR and CAINV. If CAINV is
set, then you made a mistake in the arguments to the command (also you have
set sector # out of the SD-card memory space), if bit CERR is set then there was
problem with SD-card operation – you will need to look into bit 4 R2VAL and if set
analyze R2 response available in logical page 0C9h, and look into SDE1/SDE0 bits
of status register to see at which stage error have happened (card did not become
ready, command was not accepted by card or proper data token was not
received);
7. Note that after successful operation buffer position (SBP) and sector #
automatically increase by the number of sectors processed, if you need to retry
operation you will have to reload both fields.
9.5.9. Math-Pack
Working with modern storage and data processing devices is not an easy task using
8-bit CPU, and GR8NET provides support for Z80 to complete relatively complex tasks.
While addition and subtraction of 32-bit values does not take much CPU power if it is not
main task of the application, multiplication and division is almost a killer for any optimized
code.
Functionalities described below are originally designed to be complementary for the
SD-card support however application is free to use them for any other purpose. All values
are little endian.
Logical page C9h, explained in previous section, has additional fields:
Offset
Size Op
Description
Dec
Hex
File-system specific math
32
20
1
R/W Sectors per cluster [boot sector: +0Dh]
33
21
2
R/W Reserved sectors [boot sector: +0Eh]
35
23
1
R/W Number of FAT copies [boot sector: +10h]
36
24
4
R/W Volume starting LBA [MBR: +1C6h+10h*MBR_entry#, or 0 if there’s no MBR]
40
28
4
R/W Sectors per FAT *
44
2C
4
R
LBA of the start of the first FAT copy
48
30
4
R
LBA of the start of the second FAT copy (valid if available)
52
34
4
R
LBA of the starting cluster / root directory **
User-defined cluster number calculations
56
38
4
R/W Cluster # ***
60
3C
4
R
LBA for the first sector of cluster
64
40
4
R
LBA of the FAT sector to get next cluster # in the chain
68
44
2
R
Offset in the FAT sector (see previous item) to get next
cluster#
70
46
1
R/W File system type and cluster number flags
© 2015-2017 AGE Labs
Page 121 of 156
© 2015-2017 Eugeny Brychkov
Notes for the table above:
* This field has different layout for FAT32 and FAT16 file systems:
• FAT32: it is 32-bit value of the sectors per FAT from EBPB [boot sector: +24 (dword)];
• FAT16: it is divided into two logical registers – bits [15:0] designate 16 bits of
sectors per FAT [boot sector: +16 (word)], bits [31:16] designate number of root directory
entries [boot sector: +11 (word)].
** For FAT32 it has LBA number for first data cluster #2, for FAT16 it has LBA number of
root directory start.
*** For FAT16 only lower 16 bits of the cluster number are used for calculations.
Application copies volume data into the fields (sources of data are indicated in the
square brackets), and obtains sector address for FAT and first data cluster. Calculation is
performed within tenths of nanoseconds, thus from Z80 point of view – immediate.
Following formulas are used:
• First FAT = (reserved sectors) + (volume starting LBA)
• Second FAT = (first FAT) + (sectors per FAT)
• Starting cluster (root dir) = (first FAT) + (number of FATs) * (sectors per FAT)
In order to simplify file operations, application may use calculations for specific cluster
number (they are based on the values stored into and calculated by the formulas above):
LBA (absolute sector number) of the beginning of the cluster, FAT sector LBA and offset
within this FAT sector to get next cluster number in the file chain.
• Cluster LBA = (LBA of cluster #2) + (cluster # – 2) * (sectors per cluster) + (root
directory size if FAT16)
• LBA of FAT sector to get cluster chain = (first FAT) + (cluster #) * (2 – FSTYP) * 2 /
512
• Offset in FAT sector to get next cluster = ((cluster #) * (2 – FSTYP) * 2) AND 01FFh
File system type and cluster number flags location (+70) has the following format:
7
0
6
0
5
0
4
3
2
1
CLNFLG
0
FSTYP
(R)
(R/W)
If FSTYP is 0, FAT32 file system is assumed (FAT chain offset*4), if FSTYP is 1, FAT16
file system is assumed (FAT chain offset*2). This flag also affects internal calculations
using sectors per FAT (+28) and cluster # (+38) fields. If FSTYP is 1 (FAT16), sectors per
FAT register has different purpose, and cluster # higher 16-bits, while writable and
readable by CPU, are discarded in calculations.
© 2015-2017 AGE Labs
Page 122 of 156
© 2015-2017 Eugeny Brychkov
Cluster number flags CLNFLG may have the following values:
#
0
1
2
3
4
5
FAT32 (FSTYP=0)
*000_0002…*FFF_FFEF
*FFF_FFF8…*FFF_FFFF
*000_0000
*FFF_FFF7
*000_0001
*FFF_FFF0…*FFF_FFF6
FAT16 (FSTYP=1)
0002…FFEF
FFF8…FFFF
0000
FFF7
0001
FFF0…FFF6
Description
Normal data cluster
End of chain
Zero cluster
Bad cluster
Special reserved
Other reserved
The following code may be used to identify type of the cluster:
ld
rrca
and
jr
dec
jr
dec
jr
jr
a,(MTHBASE+FSTYP)
;
;
;
;
;
;
;
;
;
0fh
z,datacl
a
z,endchn
a
z,empfil
fserr
get FS flags, MTHBASE points to BASE address of MathPack, FSTYP is 046h
flags now are in bits 3:0
not only flags bits are in A, ZF is set if flags are 0 (normal data cluster)
go there if we have data cluster # in CLUNUM (CLUNUM is +38h in MathPack}
is flags nibble equal to 1? (end of cluster chain)
go there for end of chain
is flags nibble equal to 2? (empty file, no cluster was allocated in directory entry)
go there for processing empty file contents
otherwise bad or reserved cluster = file system error
Logical page C9h has the following type conversion extensions:
Offset
Dec
Size
Op
Description
Hex
Binary/BCD type conversions
Integer to BCD
71
75
47
4B
4
8
R/W Unsigned integer 32-bit source value
R
Double precision result (BASIC Type-8, DEFDBL)
8
4
R/W Double precision source value (BASIC Type-8, DEFDBL)*
R
Unsigned integer 32-bit result, modulus if BCD is negative
BCD to integer
83
91
53
5B
Double precision format is compliant with the MSX BASIC representation of the
double floating point variables. Two operations are available:
• Unsigned 32-bit integer → Double precision representation;
• Double precision representation → Unsigned 32-bit integer. Note that location
marked by * has special format:
+0
EX10
Byte offset
+1
+2
+3
+4
Significand (mantissa), 10 BCD digits
+5
(R/W)
+6
0 (R)
+7
0 (R)
And EX10 byte has special format:
7
IOVFL
(R)
Bits
6
5
4
3
2
1
0
Exponent of 10, compliant with MSX-BASIC type-8 format (40h=power 0) (R/W)
While conversion from unsigned integer to double precision will not cause any
problems, revers operation – conversion from double to 32-bit integer may. Double value
© 2015-2017 AGE Labs
Page 123 of 156
© 2015-2017 Eugeny Brychkov
may represent numbers bigger than 232-1, or have fractional part. In scope of the
conversion, fractional part will be removed; if double has only fractional part binary equal
to 0 will be returned. If double represents number bigger than 232-1, output integer is set
to maximal value of 232-1, and bit IOVFL will be set.
Location of IOVFL bit is not writable, application can write anything there without any
action from GR8NET engine. In any case exponential part and mantissa will be treated as
modulus of the input value.
Bytes at location +6 and +7 are also not writable always returning 0. They have to be
0 if integer BCD is composed properly according to the specifications.
Conversion calculations are expected to complete in maximum 500 nanoseconds –
from Z80 CPU standpoint – immediately.
Logical page C9h has the following 32-bit math extensions:
Offset
Size Op
Description
Dec
Hex
Generic 32-bit math operations
95
5F
1
R/W Division operation control bits and flags
Multiplication
96
100
104
60
64
68
4
4
8
R/W Operand A for multiplication, 32-bit, Signed
R/W Operand B for multiplication, 32-bit, Signed
R
Product of above A*B, 64-bit, Signed
70
74
78
7C
4
4
4
4
R/W
R/W
R
R
Division
112
116
120
124
Numerator
Denominator
Quotient (numerator \ denominator)
Remainder (numerator MOD denominator)
Multiplication operation is expected to be executed within 200 nanoseconds; Division
operation is expected to be executed within 320 nanoseconds – both from Z80 standpoint
– immediately.
Location +95 (+5Fh) has special format to control division operation:
7
6
5
4
3
2
1
0
SIGD
SIGN
0
0
0
0
DIV0
DLOCK
(R)
(R/W)
(R/W)
(R/W)
SIGN and SIGD are bits which define state of the numerator and denominator
respectively. Bit is set to 1 if value in respective field is signed, and reset to 0 if unsigned.
Special care was taken to handle most negative value, designing actual computing space
as 33 bits instead of 32 bits.
DIV0 is a flag being set if denominator is equal to 0 meaning that calculated values of
quotient and remainder are not correct.
DLOCK, if set, suspends division calculation, and quotient and remainder remain the
same even if application changes numerator and denominator. This feature is very useful if
application performs wave division – e.g. when quotient is going to be used as numerator
for next wave of division. Application sets DLOCK flag, performs LDIR or
NETGETMEM/NETSETMEM from quotient to numerator, and then resets DLOCK flag to
obtain new division result.
© 2015-2017 AGE Labs
Page 124 of 156
© 2015-2017 Eugeny Brychkov
Quotient is returned with the sign according to the setting of bit 31 of numerator and
denominator and SIGN/SIGD flags. Remainder is always returned positive.
GR8NET performs identification of the clock speed of the slot it is installed in,
presenting the frequency in Hertz in the page C9:
Offset
Dec
Size
Op
Description
Hex
Clock speed
144
90
4
R
Double word (32-bit) representation of the slot connector’s
clock speed
Application may examine this value and switch to GR8NET internal source of the clock
for built-in SCC by setting respective bit in System mode register.
© 2015-2017 AGE Labs
Page 125 of 156
© 2015-2017 Eugeny Brychkov
9.5.10. Mixer and DAC (digital to analog converter)
GR8NET features 16-bit physical DAC circuit. Before final 16-bit sample is formed, all
three channels (SCC, digital waveform input, and PCM) scaled using respective volume
registers, and then master DAC volume is applied. Mixer has 21-bit adder, and in case
value overflows – sample value < -215 or > 215-1 – sample is truncated to the minimum or
maximum respectively.
Then 16-bit sample is shifted into the digital DAC chip, which produces monophonic
output to the machine’s analog mixer. To protect DAC from the problems with MSX
machine’s mixer, operational amplifier is added using voltage follower circuit.
9.5.11. System registers
There’re two registers to consider:
•
System mode register
7
6
5
4
3
2
1
0
N/A
MMDR
MMDPR
Y8950
disable
OPL
2Xvolume
OPLL
disable
SCC clock
source
Mapper
read flag
(must be preserved)
Mapper read flag: if this flag (bit 0 of register) is set, then, when CPU reads mapped
RAM ports 0fch-0ffh, GR8NET mapped memory mapper will respond with respective values
appropriate for mapper in effect: in mapper mode 7, 6 bits will identify one of 64 RAM
pages, in mapper mode 8, 5 bits will identify one of 32 RAM pages.
Warning! GR8NET is able to output whole byte to the data bus, it can
not output only significant bits (6 or 5 bits) leaving remaining bits in
high-impedance state. By enabling mapped RAM mapper read flag, you
may cause electrical conflict on the data bus in case there’re other
mapped memory mappers putting their whole byte output onto the bus,
or MSX machine is designed in the way (using internal data bus
buffers) it may have signal conflicts internally to it. This issue should
not cause damage to the system, but please use this feature prudently.
Check Multiple memory mappers in MSX system discussion for more information.
SCC clock source: if this flag (bit 1 of register) is set, then internal SCC and OPLL get
clock frequency of 3.571429 MHz, if this flag is reset, slot connector’s CLOCK pin is used as
SCC clock. This flag may be required to set if application is going to use GR8NET built-in
SCC in overclocked machine having slot connector being clocked with frequency other than
standard 3.579545 MHz.
OPLL disable: if this flag (bit 2 of register) is set, then internal OPLL analog output is
disabled, and OPLL ROM BIOS will not appear in subslot 3 in mapper mode 8.
OPL 2Xvolume: if this flag (bit 3 of register) is set, then internal OPLL/Y8950 output
twice amplitude of the waveform, increasing volume of the device approximately 1.5 times.
However setting this bit has a downside: if many channels are producing the sound, output
may become overloaded and output sound may occasionally appear distorted.
© 2015-2017 AGE Labs
Page 126 of 156
© 2015-2017 Eugeny Brychkov
Y8950 disable: if this flag (bit 4 of register) is set, then internal Y8950 output (analog
and digital) is disabled.
MMDR (mapped memory disable register) and MMDPR (mapped memory disable pending
register) are two related registers. When MMDR is set to 1, mapped RAM is disabled – not visible in
its slot/subslot and does not respond for I/O port mapper register reads even if Mapper read flag is
set; thus MMDR disables mapped RAM immediately. MMDPR, if set, will be assigned to MMDR
when GR8NET mapper type I/O register write is performed; thus it is a kind of pending change so
that mapped RAM disable happens only when mapper type is changed, and not before it (because
immediate mapped RAM disable may cause machine to lose its RAM if GR8NET mapped RAM was
set as primary RAM).
Error register: this register is having special behavior, If ERRST bit is set, Error code in
the register is reset to 0. If ERRST bit is not set, then, if current Error code is 0, new code
being written will be stored in it; however, if Error code is not 0, it will not be modified.
7
ERRST
•
6
5
4
3
Error code
2
1
0
Adapter flags: this is status register, identifying operation mode as shown below.
7
Interface
1: Error
0: OK
6
5
4
3
2
Diag mode
1: On
0: Off
Reserved
Reserved
Reserved
Disk ROM
1: Enabled
0: Disabled
© 2015-2017 AGE Labs
Page 127 of 156
1
Network
1: DHCP
0: Fixed
0
Boot state
0: Cold
1: Warm
© 2015-2017 Eugeny Brychkov
9.6. Mapper modes
When system is powered on, GR8NET starts in mapper 0 mode. Then you can change
mapper type in BASIC using CALL NETSETMAP command. After the change, system will
reboot to make new mapper type effective.
9.6.1. Mode 0: GR8NET internetworking adapter
In this mode application may enjoy whole range of functionalities described in this
document. The important requirement for proper software operation is having logical page
80h (first ROM page) in the bank 0.
In mode #0 memory mapped in the following way:
Address
Function
range
4000
Bank 0
(default is beginning of the ROM chip space)
…
5FFF
Regs
6000
Switchable bank 1
…
7FFF
Regs
8000
Switchable bank 2
…
9FFF
Regs
A000
Switchable bank 3
…
BFFF
Regs
Special control registers are available in bank 0 only. If application will switch
registers on in another bank(s), it should switch them off before calling any API of the card
as card does not expect these registers to be in banks 1, 2 and 3.
9.6.2. Mode 1: plain 32kByte write-protected memory chunk
In this adapter represents its first 32kBytes of onboard RAM as plain contiguous space
starting 4000 and ending BFFF. After machine reboot, MSX BIOS only turns bank 1 (40007FFF) to the cartridge’s slot location, if you will need to use bank 2 (8000-BFFF) you
should turn this bank to cartridge slot manually.
Write protection is necessary for some software to run properly, thus please load final
image before you change mapper into this mode.
If you need same plain 32kByte memory mapper, but having writable RAM, please
use GR8NET memory mapper loading code and data into logical pages 0, 1, 2 and 3,
setting these pages in bank registers in special configurations registers respectively and
turning special registers in all the banks off.
© 2015-2017 AGE Labs
Page 128 of 156
© 2015-2017 Eugeny Brychkov
9.6.3. Mode 2/3: Konami memory mappers
These memory mappers feature in the games of size more than 32kBytes like
Vampire Killer or King’s Valley 2. The difference between them is that in mode 2 mapper
has fixed mapper page 0 in its 4000-5FFF location, and does not have SCC in its page 63 in
location 9800-9FFF. For more information refer to the Albert Beevendorp’s tech pages.
In this mode you can use special control registers and all logical pages, with one
exception. In Konami with SCC mapper mode, logical RAM page 3fh will be overlaid by SCC
in case this page is turned on in bank 2. In banks 0, 1 and 3 application will be able to
access whole contents of logical page 3fh.
9.6.4. Mode 4: ASCII-8 memory mapper
This mode is very similar to the Konami mode 2 mapper with slightly different bank
switching addresses, and availability of the six address bits which allow 512 Kbytes of total
addressed RAM. When switching to this memory mapper through port I/O or NETSETMAP
command, all 4 page numbers presented in mapper banks are initialized to 0.
9.6.5. Mode 5: ASCII-16 memory mapper
This mapper assumes changing contents of only two CPU 16KB banks, 4000-7FFF and
8000-BFFF. GR8NET adapter emulates this behavior using its 8K banking system: for
example if application switches 16KB CPU bank 1 to page number 5, GR8NET engine will
switch two its banks – bank 0 and bank 1 – to pages 10 and 11. Thus each 16KB page X is
represented by the two logical GR8NET pages equal to X*2 and X*2+1. When switching to
this memory mapper through port I/O or NETSETMAP command, all 2 page numbers
presented in mapper banks are initialized to 0.
9.6.6. Mode 6: Mirrored ROM
This mode is similar to mode 1, but first 64 Kbytes of GR8NET RAM are presented
from the CPU address 0.
9.6.7. Mode 7: 1 Megabyte mapped memory
In this mode card represents its available RAM to the MSX machine as normal
mapped RAM, available in all banks. Mapper is having its internal memory mapping
registers at ports 0FCh-0FFh, its readability will be controlled by second argument of
NETSETMAP command.
Cartridge is fully dedicated for mapped RAM operation, there’s no GR8NET ROM
initialization, and no CALLNET or CALLDSK commands present, and BASIC will return
Syntax error if you try using them.
If card will be the one with largest memory installed into the non-Turbo machine, its
space will become main memory for MSX. This may affect behavior of some applications
and games which by default expect RAM to be in slot 3.2.
© 2015-2017 AGE Labs
Page 129 of 156
© 2015-2017 Eugeny Brychkov
9.6.8. Modes 8-14: Composite mappers
To work in these mapper modes GR8NET adapter must be in primary slot.
These modes represent mixture of the mapper modes 0 to 6, they are very useful in
case your MSX machine is having small amount of RAM. When booting, GR8NET will be
chosen as main RAM with 512K in size (if there’re no other larger memory mappers). In
addition, game mappers present in subslot 3, will have access to GR8NET’s Nextor system
with SD-card.
The following diagrams show memory mapping assuming GR8NET is installed in
primary slot X.
Slot X.0
Contains GR8NET
ROM with full
functionality, except
available RAM is
halved to 512K.
Running NET
commands (browser
and other accessing
GR8NET RAM buffer)
will alter this Ram
contents.
Slot X.1
Contains 512K
mapped RAM, the
second half of the
available GR8NET
onboard RAM space.
This mapped RAM
can be disabled by
setting 3rd argument
of NETSETMAP to 1,
or setting third
argument in brackets
of file name to 1,
e.g. {311} when
using browser.
Slot X.2
Contains Nextor
ROM. Note that if
application being run
is game, or any
other not supporting
FAT16 volumes, you
must insert SD-card
with first partition
formatted standard
diskette image
(720K/FAT12), and
boot GR8NET’s
Nextor in DOS1
mode holding ‘1’ key
during its
initialization.
Slot X.3
Contains game
mapper or FM-Pak
ROM depending on
mapper type
selected:
8: FM-Pak ROM
9: Plain 32K
10: Konami 4
11: Konami 5 / SCC
12: ASCII-8
13: ASCII-16
14: Mirrored
See details below.
Subslot 3 will have respective game mapper type identified by mapper number minus
8, thus mapper mode 11 will have Konami 5 (8+3) mapper in place. If you select mapper
type 8, then FM-Pak ROM will appear in subslot 3.
Important note: game mappers share their space with GR8NET buffer RAM located
in subslot 3. As soon as RAM in the location is writable, you can alter (or corrupt) ROM
image in game mapper in subslot 3 through subslot 0. While you can load ROM images on
the fly using GR8NET browser, and they will appear in subslot 3 immediately, using specific
GR8NET commands (e.g. starting browser or using LDBUF) may corrupt current data in
subslot 3.
© 2015-2017 AGE Labs
Page 130 of 156
© 2015-2017 Eugeny Brychkov
When changing to modes 8-14, do not forget that configurations having GR8NET
functionality in them require special registers to be set in GR8NET bank 0, and take special
care about mapper read flag, thus to perform change you may do the following:
CALL NETSETMAP(16+8, 2)
CALLNETSETMAP(16+8+3,,1)
to switch to mapper mode 8 with “auto” mapped RAM
mapper read flag
to switch to mapper mode 11 with Konami SCC mapper in
subslot 3, also with “auto” mapped RAM mapper read
flag, and have mapped RAM disabled in subslot 1 (e.g.
special case for Metal Gear 2 because it can not run in the
same slot with main RAM).
Another tradeoff of having mapped RAM together with GR8NET mapper is that RAM
disk can only be of 360K in size (see Memory manager chapter), and, together with RAM
disk enabled, will have only 152K memory available for system and user. In case 720Ksized disk is loaded into the RAM disk space, GR8NET firmware will throw warning, and all
reading or writing sectors exceeding 360K limit will return Not ready error.
© 2015-2017 AGE Labs
Page 131 of 156
© 2015-2017 Eugeny Brychkov
10. Programming API
GR8NET in its mapper mode 0 has predefined page allocation: bank 0 is always
logical page 80h (ROM start with calling points), bank 1 is always RAM (by default config
page 0FFh), bank 2 is always switchable ROM page, and bank 3 is always W5100. When
application starts, it should expect such bank allocations; when exiting, application should
revert back to the original bank allocations.
Some calls will modify pages visible in banks, for example TCPEST will switch to
W5100 registers in bank 3, and thus programmer should pay attention to the changing
pages in the banks after calling GR8NET API.
If you are going to use BDOS (0005h) call in MSX-DOS environment you should know
that if you have GR8NET slot switched on in CPU banks 1 or 2 BDOS call may change them
back to RAM slot.
Your application will interface with GR8NET directly – identifying card using ports 5Eh
and 5Fh, and accessing GR8NET adapter’s RAM, ROM and W5100.
10.1. Identification of the adapter
It is user’s task to properly enumerate adapters within the system by their
configuration switches, and connect respective network cables to each adapter.
Applications may provide choice of the adapters and their functionalities. Applications may
perform specific auto-detection actions to find out network adapters are connected to – e.g.
using DHCP requests to see which IP address adapter is given, or performing ping to the
predefined remote host.
To identify if adapter #2 is installed, application can use the following execution flow:
...
ld
out
in
cp
jr
a,080h
(05eh),a
a,(05fh)
'G'
nz,noadap
; adapter #2, register 0
; select adapter and register
; get register 0 value from adapter #2
ld
out
in
cp
jr
a,081h
(05eh),a
a,(05fh)
0ffh
nz,inierr
; adapter #2, register 1
; get adapter #2's register 1 (slot ID)
ld
(slotid),a
; otherwise preserve adapter #2 slot ID
ld
out
in
...
a,082h
(05eh),a
a,(05fh)
; adapter #2 register 2
; no adapter #2
; adapter did not initialize properly
; get adapter #2's register 2 (mapper type reg)
After identifying slot ID adapter #2 is located in, application will switch to this slot
and operate the adapter.
If application will want to detect GR8NET device using slot and subslot scan, it will be
able to find GR8NET adapter by the string “GR8NET” at the address 5FB8h followed by 2
bytes identifying major and minor version of the adapter’s software.
© 2015-2017 AGE Labs
Page 132 of 156
© 2015-2017 Eugeny Brychkov
10.2. Direct firmware calls
When you have GR8NET adapter slot switched on in CPU bank 1 and GR8NET mapper
bank 0 is having page 80h visible, you have access to the direct call API, which provides
specific very useful functionalities to your application.
Some firmware calls require turning GR8NET in CPU bank 2 on, use B2ON and B2OFF
routines to turn it on and off respectively.
You should keep in mind that during execution of these calls executing code should
still have access to the supplied data, do not place strings to print to the screen into main
PC RAM in CPU bank 1, because executing code is located in this bank. If you need temp
storage, you can use GR8NET’s RAM in GR8NET bank 1 (6000-7FFF) configuration page
0FFh from addresses 7800h to 7FFFh (do not use 6000-77FF as this space contains
GR8NET firmware control data and can be used for temporary data storage).
Example of network operation workflow using GR8NET direct firmware calls
DATCOD
Address
Input
Output
Registers
Notes
Get year, month and day of flash chip firmware build
5F70h
DE=year (e.g. 2016), B is month (1-12), C is day (0-31)
You can use this call to identify firmware build date and thus if capabilities
application requires are available or not. To find out if this call is available or
© 2015-2017 AGE Labs
Page 133 of 156
© 2015-2017 Eugeny Brychkov
not check address of (05F70h) to contain JP instruction (0C3h).
UDPOP
Address
Input
Output
Registers
Notes
Open socket for UDP communication
5F73h
A = socket number (0 or 1)
DE = UDP port number
CY is set if error
AF, BC, HL, IX, IY
Before calling this routine, GR8NET should be turned on in CPU bank 2 with
B2ON
GCURSL
Address
Input
Output
Registers
Notes
Get current slot ID information
5F76h
D = CPU bank number (0, 1, 2, 3)
A = slot ID in RDSLT format
AF, BC, DE, HL
For bank 1 A will return own GR8NET slot information, or subslot 0 of own slot
if adapter is mapper mode 8.
B2OFF
Address
Input
Output
Registers
Notes
Turn GR8NET adapter off in CPU bank 2 (8000-BFFF)
5F79h
Nothing
Nothing
Restores visibility of slot (subslot) before B2ON is called
B2ON
Address
Input
Output
Registers
Notes
Turn GR8NET adapter on in CPU bank 2 (8000-BFFF)
5F7Ch
Nothing
Nothing
Turning GR8NET on in CPU bank 2 is required to call several firmware calls
(TX, RX, TCPEST, UDPOP) allowing access to GR8NET banks 2 (expansion ROM
pages) and 3 (LAN chip). This routine should NOT be called recursively, as it
stores previous slot ID information in the single memory cell, and if called
second time, information in this cell will be rewritten by the GR8NET slot ID
GWREGS
Address
Input
Output
Get W5100 socket status registers
5F7Fh
A = socket number (0 or 1)
D = socket status register
E = socket interrupt register
IX, IY
For the information about meaning of the information returned in DE please
refer to the W5100 datasheet. In most cases application will need socket
Registers
Notes
© 2015-2017 AGE Labs
Page 134 of 156
© 2015-2017 Eugeny Brychkov
status register to identify the state socket is in (open, established, closing,
closed) to perform appropriate operation in it and its data exchange.
NETCMD Instruct W5100 to perform send of receive command
Address
5F82h
Input
A = socket number (0 or 1)
CY is set to instruct socket to send
CY is reset to instruct socket to receive
Output
CY is set if socket error occurs
Registers IX, IY, HL, BC
Notes
This routine should be executed after calling TX or RX: after TX in order to
instruct W5100 to send data transferred to its buffer, after RX for
acknowledging previously received data and get ready receiving new data
(TCP) or free space to receive UDP packet(s). This routine need not be
executed in the loop, once it is executed, W5100 is performing requested task.
In case of receive command subsequent call to this routine in TCP mode will
cause W5100 to re-acknowledge previously received data to the remote host (a
kind of network retry)
RX
Address
Input
Output
Registers
Notes
MMVAR
Address
Input
Output
Registers
Get received data from the socket
5F85h
A = socket number (0 or 1)
HL = pointer to RAM buffer (must be outside of CPU bank 1)
DE = maximum buffer size (data will be ≤ 2KB)
ZF is NZ if there's more data waiting to be received
BC = size of data copied into the buffer (if ZF is NZ)
HL = at the end of data in the RAM buffer (if ZF is NZ)
All registers in alternate register set, IX, IY
GR8NET should be switched on in CPU bank 2 with B2ON. This routine does
not issue RECV command to the W5100 chip’s socket, use NETCMD call with
CY reset for this purpose
Get / set memory manager variables
5F88h
CY is set to set user protected area starting page
A=user protected area starting page (UPRAMS)
CY is reset to read memory manager variables
CY is set if UPRAMS can not be set (in case of input CY being set)
H = RAMMAX (total number of RAM pages available)
L = DSKLPG (RAM disk image starting page)
D = RAMTOP (maximal page number available for user
E = UPRAMS (first page number of user-protected RAM area)
B = number of RAM pages available within user protected area
For more information please refer to Memory manager chapter.
AF, C
© 2015-2017 AGE Labs
Page 135 of 156
© 2015-2017 Eugeny Brychkov
Notes
Gives information about availability of the GR8NET buffer RAM, and reservation
of the user space which will not be used by system tools like NETBLOAD.
DEV8RW DEV_IO routine for built-in Nextor
Address
5F8Bh
Input
CY=0 to read, 1 to write
A = Device number, should be 1
C = Logical unit number, should be 1
B = Number of sectors to read or write
HL = Source or destination memory address for the transfer
DE = Address where the 4 byte sector number is stored
Output
A = Error code
Registers All
Notes
Reads specified number of sectors from SD-card into memory location.
IMPORTANT: routine does not implement XFER method, thus space pointed by
HL must be located in RAM. Size of SD-card in sectors can be obtained from
SD-card size register from special register set.
PARURI
Address
Input
Output
Registers
Notes
TCPEST
Address
Input
Output
Registers
Notes
PUTSTR
Address
Input
Output
Registers
Parse URI string into the URI structure
5F8Eh
HL points to the URI string
BC points to the URI structure
All
Function populates fields which are present in the URI string. For example, if
destination port is not listed in URI string, this field will not be updated. Thus
before calling network access routines ensure that all fields in URI structure are
correctly populated
Establish TCP/IP connection
5F91h
A socket number (0, 1)
BC points to the URI structure
CY is set if error occurs
All
Do not use sockets 2 or 3 as they may be used by system routines like BLOAD
and DHCP/DNS requests. This routine performs DNS query on the host name in
the URI structure if its flag is set to 0. Before calling this function, GR8NET
bank 2 should be turned on with B2ON
Print inline string
5F94h
Null-terminated string follows CALL instruction
AF
© 2015-2017 AGE Labs
Page 136 of 156
© 2015-2017 Eugeny Brychkov
Notes
This routine uses CHPUT function of the MSX BIOS
PRSTR
Address
Input
Print formatted string pointed by HL
5F97h
HL points to the null terminated text
BC for %c
All
Uses MSX BIOS CHPUT routine. String should not be located in CPU bank 1.
Format:
• “%%” prints % sign
• “%c” prints contents of BC register in hexadecimal representation
• “%H” followed by byte count [1 byte] and address [2 bytes] prints bytes in
hexadecimal format of byte count from location pointed by address (i.e.
performs memory dump)
• “%A” is similar to “%H”, however %A is followed by termination character
[1 byte] then maximal number of characters to dump [1 byte] and then
address [2 bytes].
In %A and %H options 0 byte count dumps 256 bytes.
Output
Registers
Notes
GHCODE
Address
Input
Output
Registers
Notes
Get HTTP response code from the HTTP header
5F9Ah
HL = pointer to HTTP header
CY reset then HL = HTTP response code
CY set if error
All, except BC is preserved
The header string should be null-terminated
MGETRQ Construct GET HTTP request
Address
5F9Dh
Input
HL points to the User Agent string
BC points to the URI structure with all fields filled in
DE points to the destination memory area
Output
CY set if error
CY reset then HL = pointer to created request string, BC = byte count
Registers All
Notes
This function provides HTTP request text to be sent using TX call
TX
Address
Input
Output
Put packet into TX buffer of W5100
5FA0h
A = socket # (0 or 1)
HL = pointer to data to send within CPU banks 0, 2 and 3
DE = number of bytes to send (≤ 2KB)
If CY is set there’s no space in socket’s buffer, and
• HL is unchanged
© 2015-2017 AGE Labs
Page 137 of 156
© 2015-2017 Eugeny Brychkov
Registers
Notes
GETDEC
Address
Input
Output
Registers
• BC = free space available within socket’s TX buffer
If CY is reset then
• HL points to the end of data transferred to TX buffer
• BC equals to DE
IX, IY, F, BC
Application should successfully establish connection with remote host before
calling this function. Before calling this function, GR8NET bank 2 should be
turned on with B2ON. Data and its parts should not be located within CPU bank
1 (4000-7FFF). Minimal number of bytes to send is required for UDP
communication so that routine would not send partial UDP packet.
Get decimal representation of the number from the text
5FA3h
DE = text in memory, can be preceded with leading spaces
CY set if error, DE is not changed
CY reset then BC:HL = 32-bit number, DE points to byte after recognized
number
All
CHKHIP
Address
Input
Output
Registers
Notes
Check host name to be an IP address
5FA6h
BC = URI structure
All
This routine should be called before TCPEST; it checks host name to be an IP
address, and if it is, moves this IP address into resolved IP address field and
sets flag that IP address is valid
CHRPUT
Address
Input
Output
Registers
Notes
Put character onto the screen
5FA9h
A = character to print
None
This routine uses MSX BIOS CHPUT routine
PRDE16
Address
Input
Output
Registers
Notes
PRIPA
Address
Input
Output
Print 16-bit number in decimal representation
5FACh
HL = value to print
AF
This routine uses MSX BIOS CHPUT routine
Print IP address in decimal notation onto the screen
5FAFh
HL = pointer to 4 octets of IP address
-
© 2015-2017 AGE Labs
Page 138 of 156
© 2015-2017 Eugeny Brychkov
Registers
Notes
All
This routine uses MSX BIOS CHPUT routine
SCLOSE
Address
Input
Output
Registers
PRHEX
Address
Input
Output
Registers
Closes socket
5FB2h
A = socket #
IX, IY, AF
Print hexadecimal representation of A (2 characters)
5FB5h
A = byte
AF
GR8RSG GR8NET adapter ROM signature
Address
5FB8h
This address contains characters “GR8NET” followed by major (byte) and minor (byte)
versions of the flash chip firmware.
© 2015-2017 AGE Labs
Page 139 of 156
© 2015-2017 Eugeny Brychkov
10.3. URI structure
You will use URI structure to provide input for several firmware calls like TCPEST,
PARURI, MGETRQ or CHKHIP. Before performing any of these calls, however, you should
ensure that URI structure is set up with information required for successful execution of
the call. For example, TCPEST requires source and destination ports, as well as proper
setting of the flag.
+#
+0
+1
Len
1
32
Network URI structure
Bit 0 reset (0) identifies
network URI structure. Bit 1
reset (0) means that host
name was not resolved yet
Host name
SD-card URI structure
Bit 0 set (1) identifies SD-card URI
structure. Bit 1 reset (0) means that
starting cluster and file size are not
valid
32-byte directory entry (see below)
(31+’\0’)
+33
4
+37
2
+39
2
+41
+281
240
(239+’\0’)
64
(63+’\0’)
+345
64
(63+’\0’)
+409
EOS
IP address. If it corresponds to
host name (or host name is
empty and IP address should
be effective) if bit 1 of byte in
offset +0 is set
Remote (destination) port (e.g.
80 for HTTP)
Local (source) port. Do not use
port numbers below 49153
Path on the server
File name of the resource on
the server
Query string for the server’s
resource
End of structure
Starting cluster of the file (32 bits),
valid if bit 1 of byte in offset +0 is
set
File size in bytes (32 bits), valid if bit
1 of byte in offset +0 is set
Path for the file
File name
N/A, is not used
End of structure
URI type is identified by the parsing code (PARURI call) by the prefix. If URI string
start with HTTP:// then structure type is (changed to) network structure, if with SDC://
then to SD-card structure type. Type is indicated by the bit 0 of byte in offset +0 of the
structure. Please note that for SD-card type of structure host name is skipped, thus to
identify path from the root you should use SDC:///path/filename.
Host name field of 32 bytes in size, when URI structure identifies SD-card resource,
will contain directory entry corresponding to path + file name if bit 1 of byte in offset +0 is
set. Exception is root directory – this field will contain all nulls except one field of byte
offset +0bh will contain 010h (“subdirectory”).
© 2015-2017 AGE Labs
Page 140 of 156
© 2015-2017 Eugeny Brychkov
11. Applications
This chapter lists several applications you can use with GR8NET, and describes how
you should use them, and their limitations. In case you are willing to write application for
GR8NET, please contact us at info@gr8bit.ru.
11.1. MSX webserver
Type: MSX-DOS executable
Location: http://www.gr8bit.ru/software/binaries/ws.rar, password “webserver”
Related video: https://youtu.be/0tQw_Xuq900
Root of the web server should be located on the SD-card, in any subdirectory. To
start web server, you type
ws [GR8NET adapter number] /[web server root]
for example
ws 0 /www
In case resource you identify as webserver root is not a
valid subdirectory, or it does not exist, application will exit with
the error. At any moment you can terminate execution of the
web server application by CTRL-STOP key combination.
CTRL +
STOP
2
1
3
4
8
7
5
9
6
10
Webserver application displays the following information when operates:
1. Webserver IP address;
2. Webserver network mask;
3. Socket number, in total 4 sockets per GR8NET adapter;
© 2015-2017 AGE Labs
Page 141 of 156
© 2015-2017 Eugeny Brychkov
4. State of the socket: L (listening), R (receiving request), C (closing), S (sending
response header) and D (sending data);
5. Requestor IP address and port;
6. File name in 8:3 format;
7. HTTP response code;
8. Size of the file;
9. Total data bytes sent through the socket;
10. Visualization mode: 0 or blank (display everything), 1 (do not display total data
bytes), 2 (do not display total data bytes and file sizes).
When creating web server
pages for GR8NET, please ensure
files are named in standard 8:3 DOS
format otherwise web server will not
find files and return 500 Bad request
error.
It is advisable to use user agent
which allows customization of the
number of concurrent connections to
the web server. Mozilla Firefox is a
good choice; as GR8NET adapter has
only 4 sockets, you need to ensure
that there will be no more than 4 concurrent requests made to the adapter otherwise
Connection refused error will be returned to the requestor.
In Firefox, open new tab and go to about:config address. Accept warning about
modification of the default configuration, find option network.http.max-persistentconnections-per-server and decrease it to 4 or even to 2, this will minimize issues with
refusal of the GR8NET to serve HTTP requests.
Changing visualization level from 0 (default) to 1 or 2 will speed up
communication because webserver will not spend time displaying numbers
F5
onto the screen. With visualization level 0 local download speed is about 25
Kb/s, with level 1 is about 100 Kb/s. To change visualization level press and
release F5 key, change takes effect on release of the key.
11.2. FTP client
Type: BASIC program
Location: http://www.gr8bit.ru/software/basic/ftp.asc
Load application from the local storage device, or use HTTP: network device to get it
from the abovementioned URI location.
© 2015-2017 AGE Labs
Page 142 of 156
© 2015-2017 Eugeny Brychkov
FTP server name
USER:
User name
PASS: password for user
CWD: target directory
Sample download dialog
FTP client is able to download to and upload files from the local storage device.
Please examine sample download dialog above carefully and note that you should use raw
FTP commands, you can find full list here.
FTP client works with server putting it into passive mode by PASV command. In
passive mode FTP server waits for active connection by the client to exchange requested
information through the data connection.
For uploading files onto the FTP server, use STOR (store) command instead of RETR
(retrieve); for listing directory contents onto the screen use LIST command (also preceded
by PASV command).
© 2015-2017 AGE Labs
Page 143 of 156
© 2015-2017 Eugeny Brychkov
11.3. Video player
Status: discontinued, please use NETPLAYVID built-in command
Type: MSX-DOS executable program
Location: http://www.gr8bit.ru/software/video/
Video player application consists of the several parts: video maker and video player.
Video player is GR8VIDEO.COM application which should be executed under MSX-DOS.
It requires several input parameters, and command line should be as follows:
GR8VIDEO X[!] /absolute_path
where
X is adapter number (0-3) to be used for video playback;
! is an optional character which causes player not to perform waiting input when
error condition is detected;
/absolute_path is an absolute path to the video file on the SD-card, starting from
the root. Note that leading slash character is mandatory.
The following modes are supported:
Mode
VDPs Scan Video configuration
SCREEN 2
SCREEN 8
T, 3, 5
3, 5
SCREEN 12
5
Audio
configuration
256 x 192 pixels
X*Y to be not greater than 13,872,
60 Hz
but not less than 11,098 (for
example 136*102)
22050 Hz, 8-bit,
mono
T: TMS99xx, 3: V9938, 5: V9958
If there’s a condition, which may cause player to display video improperly, application
will display warning message and wait for key press in case ! character is not specified in
the command line. The following issues may occur:
• No enough video RAM: modes 8/12 will refuse to be played on 16K VRAM, and
mode 2 will play using single video page with 16K VRAM, causing visible artifacts on
the screen;
• Unsupported mode: videos created for specific video mode will not play on VDPs
which do not support this mode.
© 2015-2017 AGE Labs
Page 144 of 156
© 2015-2017 Eugeny Brychkov
11.3.1. Making videos for MSX
In general making video is relatively simple, but you should strictly follow the process
and fulfill very specific conditions.
Creation is performed by using Excel 97/2003 macro-enabled spreadsheet. The
following steps are required:
• Obtain video file, the best it should be the MP4 format;
• Use VirtualDub tool to slice video file onto the frames of required size: 256*192 for
SCREEN2 mode, or number of pixels (X*Y) between 13872 and 11098 for SCREEN 8
and 12 modes.
• Use VirtualDub to convert video’s audio into 22050 Hz, 8- or 16-bit mono;
• Use BMP2MSX to convert bitmap frames created by VirtualDub into MSX screen
representation files;
• Run script in Excel spreadsheet to complete video creation.
You will see detailed explanation on video creation when you open the spreadsheet.
All required resources – VirtualDub, BMP2MSX, GR8VIDEO player and MSX video creation
spreadsheet are located at http://www.gr8bit.ru/software/video/.
© 2015-2017 AGE Labs
Page 145 of 156
© 2015-2017 Eugeny Brychkov
12. Troubleshooting
There could be several sources of the problems, internal and external to the adapter,
and before performing major modifications like reflashing the flash chip you have to work
out all possible obvious issues – for simple reason – if there’s some failure, reflashing may
make situation worse.
When GR8NET is inserted, MSX machine does not start, or behaves weirdly
• Ensure adapter is not damaged and does not have symptoms of being poured in with
any solutions, and does not have any foreign objects inside it;
• Check edge connector of the GR8NET and clean it with spirit, not applying spirit onto
the casing. Check slot connector of the machine for bent pins, foreign objects or dirt.
Remove objects and clean connector with spirit. Wait until spirit and its water
component evaporates before inserting GR8NET and trying it again.
GR8NET is installed, but there is no its initialization screen
• Check connectors and clean them;
• Ensure Byteblaster-II/USB-Blaster programming adapter is not connected to the
GR8NET;
• Ensure that arrow up key is not pressed during GR8NET initialization;
• Use Leonid Baraz’s debugger to switch to slot where GR8NET is installed and
investigate (a) if special control registers are present in location 5FC0-5FFF, and (b) if
boot logical page F0h is not corrupt and/or starting page of ROM image (logical page
80h) is not corrupt.
Every networking command (NETBLOAD, NETBROWSE) returns Device I/O error
There’re several things to check:
• CALLNETSTAT to ensure IP addresses are correct;
• CALLNETGETHOST/GETPATH to ensure URI points to existent and accessible remote
resource, and CALLNETGETNAME for NETBLOAD command;
• CALLNETGETPORT to ensure that remote port address is properly set (e.g. 80 for HTTP
server communication);
• Perform re-initialization of network configuration, typing CALLNETDHCP.
Networking operations work unreliably or adapter does not connect at all
• Check RX LED of the adapter: if it lit or very frequently flashes without TX LED flashing,
then subnetwork is most probably having broadcast storm or DoS attack, and you will
need to investigate your subnetwork for computers infected with malware or viruses.
See “how to get network traffic log” section;
• Use PC on the same subnetwork to access remote resources – like web pages on the
remote host or issuing nslookup request. If PC also fails such requests (e.g. web
browser not loading the page, displaying messages like “internet unavailable” or “DNS
bad config”, or nslookup displaying that there’s no DNS server available on the
subnetwork or it is unreachable) – investigate problems with the network. The first
© 2015-2017 AGE Labs
Page 146 of 156
© 2015-2017 Eugeny Brychkov
•
action, if it is possible, may be to reboot router/restart network services like
DHCP/DNS;
Use Wireshark to investigate what is going on with the network. Please refer to the
“how to get network traffic log” section.
Adapter is unable to initialize in DHCP mode
• Check if there’s DHCP server on the network;
• Check if you have two adapters with the same MAC addresses on the network;
• Try placing network hub between GR8NET and your router. Some too clever routing
devices (e.g. Cisco) may need, or be configured, to wait some time after connected
peer to its port goes up (e.g. you turn MSX on or perform its reboot); placing device in
between will keep router’s port always up and configured. The dumber intermediate
hub device is, the better (added 01-Jun-2017);
• Use Wireshark to capture UDP packets.
Adapter is unable to perform DNS queries
• Check if there’s DNS server on the network;
• Use PC on the same network to query DNS using web browser or nslookup. If they fail,
you may need to restart DNS service on the server and will need to investigate
networking problems.
How to get network traffic log?
In order to get network traffic log you will need to install Wireshark application (available
for free from www.wareshark.org). Note that in standard configuration it will be able to
capture only the following packets: packets from the workstation application is installed
on; packets to the workstation application is installed on; UDP broadcast packets.
Wireshark is very useful in troubleshooting issues with DHCP because this protocol uses
UDP broadcast packets. Start Wireshark before GR8NET initializes its network subsystem,
and stop capture after GR8NET finishes, and you will be able to see full log of packet
exchange between GR8NET adapter and DHCP server under “DHCP” protocol type.
To troubleshoot issues with TCP you will need to install Wireshark on the machine running
web server GR8NET is trying to connect to (or install test web server on the machine with
Wireshark installed).
How can I test mappers in GR8NET?
• If card displays its firmware initialization screes and initializes as expected (in DHCP or
fixed IP address mode) you may count then mapper type 0 is functioning properly;
• Use CALL NETBROWSE statement to connect to remote server (by default it is
http://www.gr8bit.ru) and browse directory /software/roms. If this statement will
display contents of remote web page, you can be 100% sure that mapper type 0 is
functioning properly;
• To test mapper #1 (plain write-protected 32K) click Enter on Knightmare;
• To test mapper #2 (Konami without SCC) run The treasure of Uşas or Metal Gear;
• To test mapper #3 (Konami with SCC) run Metal Gear 2 or King’s Valley 2;
• To test mapper #4 (ASCII-8) run Auf Wiedersehen Monty.
© 2015-2017 AGE Labs
Page 147 of 156
© 2015-2017 Eugeny Brychkov
•
To test mapper #7 (Mapped RAM) use CALL NETSETMAP(7) and after reboot examine
bytes at addresses F341-F344 by PRINT HEX$(PEEK(&HF341)). It is very probable that
GR8NET will appear having biggest RAM space in your machine, thus the BIOS will set
it up as main RAM and abovementioned memory cells with contain slot number
associated with the GR8NET adapter (e.g. 01h – slot #1 adapter may be installed in, or
89h if you installed GR8NET into the slot expander’s slot #1.2). Please note that
TESTRAM.COM does not identify non-native mapped RAM properly.
Audio output of the adapter is too loud or too quiet
By default adapter is having all its audio channel volumes set to maximum – 80h (see
NETSND command). Application can change volume level of each device separately.
• Sound is too loud: decrease volume level for the involved device or master volume in
range of 80h (&H80, full sound) and 0 (mute);
• Sound is too quiet: increase volume level for the involved device or master volume in
range of 80h (&H80, full sound) and 0 (mute). However, if volume is still low, it is
possible to increase master volume to 0ffh (&HFF, 255 decimal), causing GR8NET 2x
digital amplification of the total audio signal level. Further volume increase is not
possible without hardware changes to the adapter.
To set maximal possible volume of all the audio in GR8NET, you can use
CALLNETSNDVOL(255,128,128,128). Remember that these values are preserved by
CALLNETSAVE command.
Getting “Wrong version of MSX-DOS” with SD-card
This error appears when you try to run .COM program, and current media (SD-card) does
not have VOL_ID (volume ID) signature in it (e.g. SD-card was formatted on Windows OS).
To confirm to COMMAND2.COM continue using the volume, type the following command:
SET EXPERT=ON
SD-card works with Nextor, but gives Device I/O error with NETBROWSE
There’s something wrong with file system on your SD-card. It must have valid boot sector
and/or master boot record (MBR) with valid volume record.
Most probably, if you formatted SD-card with Nextor’s CALL FDISK, card is missing special
compatible “55 AA” signature in the boot sector. To fix it run the following file from the
web browser http://www.gr8bit.ru/software/basic/nxtbootf.asc.
Machine hangs / reboots when loading software from RAM disk
If software is operational in general, this situation may happen when you enable GR8NET’s
disk subsystem, but your machine is having internal disk-ROM. In this case there will be
extra high memory space allocated for extra drives, and some software (e.g. Psycho
World) will not work because it is coded to load its code, data and stack into area being
reserved by the system.
There’s no software way to resolve the issue; you either load software from internal
storage with GR8NET’s disk subsystem disabled, or remove internal machine’s disk-BIOS
chip from the system, and then software will run properly from the GR8NET RAM-disk.
© 2015-2017 AGE Labs
Page 148 of 156
© 2015-2017 Eugeny Brychkov
Further technical information about GR8NET
• Release notes of the last version:
http://www.gr8bit.ru/software/firmware/GR8NET/gr8net-rom.txt;
• Pending change requests: http://www.gr8bit.ru/software/firmware/GR8NET/gr8netchreq.txt;
• Bug reports: http://www.gr8bit.ru/software/firmware/GR8NET/gr8net-bugs.txt.
© 2015-2017 AGE Labs
Page 149 of 156
© 2015-2017 Eugeny Brychkov
13. Examples of the code
Samples of the following code can be downloaded from http://www.gr8bit.ru/software/basic.
• Reading remote text file with HTTP header
TCP.BAS – program to display contents of
http://www.gr8bit.ru/software/basic.
10
20
30
40
50
60
70
the
@licence.txt
file
located
at
CALLNETSETHOST("www.gr8bit.ru")
OPEN"TCPA:"AS#1
PRINT#1,"GET /software/basic/@license.txt HTTP/1.0"
PRINT#1,"HOST: www.gr8bit.ru":PRINT#1,""
IF EOF(1) THEN PRINT:PRINT"RECEIVED":CLOSE#1:END
LINEINPUT#1,A$:PRINTLOC(1);" ";A$
GOTO 50
• Reading remote text file – contents only, no headers
HTTP.BAS – program to display contents of the @licence.txt file located at
http://www.gr8bit.ru/software/basic.
10
40
50
60
70
CALLNETSETHOST("www.gr8bit.ru"):A$="/software/basic/@license.txt"
OPEN"HTTPA:A$"AS#1
IF EOF(1) THEN PRINT:PRINT"RECEIVED":CLOSE#1:END
LINEINPUT#1,A$:PRINTLOC(1);" ";A$
GOTO 50
• GR8NET disco
PLAYLIST.ASC – program sequentially playing wave files
10 'Sample playlist file for GR8NET
20 CALLNETSETHOST("www.gr8bit.ru"):CALLNETSETPATH("/software/audio/")
30 RESTORE 70
40 CLS:READ A$:IF A$="" THEN PRINT"Finished":END
50 READ B$,C$:PRINT A$:PRINT B$:PRINT:CALLNETPLAYWAV(C$+".wav")
60 GOTO 40
70 DATA "Bad Boys Blue","Queen of Hearts","qoh-22-8"
80 DATA "Genesis","Home by the Sea","hbts-22-8"
90 DATA "Billy Idol","Eyes without a face","ewoaf-22-8"
100 DATA ""
• Displaying BSAVEd pictures
SCR.ASC – program displaying image previously saved with BSAVE in SCREEN8 mode
10
20
30
40
50
60
70
80
'Displaying photo of Nishi-san
callnetsethost("www.gr8bit.ru")
callnetsetpath("/software/images/")
callnetsetname("nishisan.sc8")
callnetbload
screen 8
callnetbtov
a$=input$(1)
• Get file from internet and save it to local storage device
SAVE.ASC – prompts for remote file URI, local file name, and copies the file. File size
should be ≤1MByte.
10 'File copy from internet to local storage device using GR8NET adapter
20 'Developed 02 Jan 2016 by Eugeny Brychkov
30 DEFINTA-P:DEFDBLS-U:S=0#:T=0#:U=0#
40 PRINT"Default server: ";:CALLNETGETHOST:PRINT:PRINT"Default path: ";:CALLNETGETPATH
50 PRINT:PRINT"Default file: ";:CALLNETGETNAME:PRINT"asd":INPUT"Enter URI to the remote file";F$
60 CALLNETBLOAD(F$):CALLNETCODE(A,B):IFA<>0THENPRINT"Bload error: ";A:END
70 CALLNETGETMEM(255,&H6054,A,B,C,D):S=A+B*256+C*65536#+D*16777216#:PRINT"Size: ";S:P=0
80 INPUT"Output file";O$:OPENO$AS#1LEN=128:FIELD#1,128ASS$:LSETS$=STRING$(128,"!")
90 U=&H6000:L=64:IFS<128THEN130ELSEIFS<4096THENL=FIX(S/128)
100 FORM=1TOL:IFS<128THEN130
110 A=VARPTR(S$):CALLNETGETMEM(0,A+1,B,C):T=B+C*256:CALLNETLDRAM(P,U,128,T)
© 2015-2017 AGE Labs
Page 150 of 156
© 2015-2017 Eugeny Brychkov
120
130
140
150
160
PUT#1:U=U+128:S=S-128:NEXT:P=P+1:GOTO90
CLOSE:IFS=0THEN160
OPENO$AS#1LEN=1:FIELD#1,1ASS$:LSETS$=STRING$(1,"!"):T=LOF(1)+1
FORC=1TOS:CALLNETGETMEM(P,U,A):LSETS$=CHR$(A):PUT#1,T:T=T+1:U=U+1:S=S-1:NEXT:CLOSE
PRINT"Finished":END
• Read binary file using BASIC I/O
READBIN.ASC – reads binary file cheating EOF (1Ah) character (please refer to section 4.3).
10 'Read binary file by masking error generated from reading EOF character (error 55 in line 70)
20 'Developed 08 Jan 2016 by Eugeny Brychkov
30 ON ERROR GOTO 100
40 A$="http://www.gr8bit.ru/software/basic/bintest.dat"
50 OPEN "HTTPA:A$" AS #1
60 IF EOF(1) THEN CLOSE#1:END
70 A$=INPUT$(1,1)
80 PRINT HEX$(ASC(A$));" ";
90 GOTO 60
100 IF ERL=70 AND ERR=55 THEN A$=CHR$(&H1A):RESUME NEXT ELSE PRINT "Error";ERR;"in";ERL:END
• Display GR8NET logo
GR8LOGO.ASC – displays GR8NET logo onto the screen (MSX2 and above)
10
20
30
40
'Display GR8NET logo, requires MSX2 machine which supports SCREEN 8
'Developed 13 Apr 2016 by Eugeny Brychkov
SCREEN 8:COLOR ,,0
CALLNETBTOV(369):SET PAGE(1):A$=INPUT$(1):'Image is located in the GR8NET ROM
• Simple FTP client
FTP.ASC – allows downloading and uploading files using FTP. To authenticate use USER
and PASS commands; to list remote directory use PASV and LIST commands; to download
use PASV and RETR commands; to upload use PASV and STOR commands.
10 'Simple FTP client
20 'Developed 08 Jan 2016 by Eugeny Brychkov
30 CLEAR2048:MAXFILES=3
40 INPUT"FTP server";S$:IFS$<>""THENCALLNETSETHOST(S$)
50 CALLNETSETPORT(21):PRINT"Connecting to FTP server...";
60 OPEN"TCPA:"AS#1:PRINT"success":'open control connection
70 LINEINPUT#1,M$:PRINTM$:'Initial FTP server message
80 LINEINPUT Q$:PRINT#1,Q$:'command for FTP server
90 LINEINPUT#1,R$:'response from FTP server
100 PRINTR$
110 I=1:GOSUB440:'get FTP code at the beginning of response string
120 IFN<>227THEN180:'not a response for PASV command
130 PRINT"* Streaming from ";:L=LEN(R$):FORI=1TOL:IFMID$(R$,I,1)<>"("THENNEXTI:PRINT"Parse error":STOP
140 I=I+1:GOSUB440:A=N:GOSUB440:B=N:GOSUB440:C=N:GOSUB440:D=N:GOSUB440:P1=N:GOSUB440:P0=N
150 CALLNETSETHOST(A,B,C,D):PO=P1*256+P0:CALLNETSETPORT(PO)
160 PRINTHEX$(A);".";HEX$(B);".";HEX$(C);".";HEX$(D);"/";HEX$(PO);" *"
170 OPEN"TCPB:"AS#2:GOTO 380
180 IFN<>150THEN380:'not a data exchange response
190 CO$="":FORI=1TO4:A$=MID$(Q$,I,1):A=ASC(A$):IFA=32THEN210ELSEIFA>96ANDA<123THENA=(A AND &HDF)
200 CO$=CO$+CHR$(A):NEXTI
210 PRINT"* Command: [";CO$;"] *":IFCO$="LIST"THEN350ELSEIFCO$<>"RETR"ANDCO$<>"STOR"THENPRINT"* Illegal command
*":STOP
220 FM$="":L=LEN(Q$):FORI=LTO1STEP-1:A$=MID$(Q$,I,1):IFA$<>" "ANDA$<>"\"ANDA$<>"/"THENFM$=A$+FM$:NEXTI
230 IFCO$="STOR"THEN400;'otherwise it is RETR
240 'RETR command: get file from remote server
250 PRINT"* Performing data download [";FM$;"] *"
260 L=LEN(FM$):FK$="":FORI=1TO9:C$=MID$(FM$,I,1):FK$=FK$+C$:IFC$<>"."THENNEXTI
270 EX$="":FORJ=LTO1STEP-1:C$=MID$(FM$,J,1):IFC$="."THENEX$=MID$(FM$,J,4)ELSENEXTJ
280 FM$=LEFT$(FK$,LEN(FK$)-1)+EX$
290 PRINT"* Target is [";FM$;"] *":OPENFM$AS#3LEN=1:FIELD#3,1ASFO$
300 ON ERROR GOTO 470
310 IF EOF(2) THEN CLOSE#3:CLOSE#2:ON ERROR GOTO 0:PRINT"* Download finished *":LINEINPUT#1,M$:PRINTM$:GOTO80
320 A$=INPUT$(1,2)
330 LSETFO$=A$:PUT#3:GOTO 310
340 'LIST command: file listing to the screen
© 2015-2017 AGE Labs
Page 151 of 156
© 2015-2017 Eugeny Brychkov
350
360
370
380
390
400
410
420
430
440
450
460
470
480
490
500
PRINT"* File list *"
IF EOF(2) THEN CLOSE#2:LINEINPUT#1,M$:PRINTM$:GOTO 80
LINEINPUT#2,A$:PRINTA$:GOTO360
IFN<>221 THENGOTO 80 ELSE PRINT"* FTP session finished *":CLOSE#1:END
'STOR command
PRINT"* Performing data upload [";FM$;"] *":OPENFM$AS#3LEN=1:FIELD#3,1ASFO$
FS=LOF(3):FORI=1TOFS:IF EOF(2) THEN CLOSE#3:CLOSE#2:PRINT"Communication error":GOTO80
GET#3:PRINT#2,FO$;:NEXTI:CLOSE#3:CLOSE#2:PRINT"* Completed *":LINEINPUT#1,M$:PRINTM$:GOTO80
'get number from the list; I=position in string; R$ as string
N$="":FORJ=0TO2:C$=MID$(R$,I,1):R=ASC(C$):IFR>&H2F AND R<&H3A THEN N$=N$+C$:I=I+1:NEXTJ
N=VAL(N$):I=I+1:RETURN
'EOF char error handling
IF ERL=320 AND ERR=55 THEN A$=CHR$(&H1A):RESUME NEXT ELSE PRINT"Error";ERR;"in";ERL:END
'find substring TS$ in T$, return TO non-zero if found
TO=0:TR=LEN(TS$):TL=LEN(T$)-TR+1:IFTL<=0THENRETURN
FORTC=1TOTL:IFMID$(T$,TC,TR)=TS$THENTO=1:RETURNELSENEXTTC:RETURN
© 2015-2017 AGE Labs
Page 152 of 156
© 2015-2017 Eugeny Brychkov
14. References
•
•
•
Albert
Beevendorp,
Megabit
ROM
Cartridges,
available
online
at
http://bifi.msxnet.org/msxnet/tech/megaroms (accessed on 10-Jun-2015)
WIZnet, W5100, available online at http://www.wiznet.co.kr/product-item/w5100/,
(accessed on 10-Jun-2015)
SD
Association
(2015),
Simplified
specifications,
available
online
at
https://www.sdcard.org/downloads/pls/ (accessed on 30-Oct-2015)
© 2015-2017 AGE Labs
Page 153 of 156
© 2015-2017 Eugeny Brychkov
15. Document revision history
02
•
•
•
Feb 2016
MSX-DOS integration chapter is added;
Firmware call addresses have changed;
Added cold/warm boot notice into introduction.
10 Mar 2016
• Added output port for PCM function: index register #5 for OUTI/OTIR implementation.
15
•
•
•
Apr 2016
NETBTOV now supports logical page number within its first argument;
NETBLOAD now supports two more arguments PG:ADDR identifying start of data load;
Added NETPLAYBUF family of commands.
11 May 2016
• Inserted Applications chapter; described MSX webserver and FTP BASIC program operation.
09
•
•
•
•
•
Jun 2016
Added SELECT, CLS/HOME and alphanumeric key functionality to browser;
Added mappers 6 and 8, and memory manager chapter;
Added statements: GETMMV, SETMMV, VARRWTH statements;
Added ERRREG into special control registers list;
Completely rebuilt DSK interface;
23 Jun 2016
• Added NTP section and commands;
• Enhanced URI structure to 63 characters for file names, and added query string of max 63 characters.
Added GETQSTR and SETQSTR statements.
04 Jul 2016
• Enhanced URI structure to support SD-card URI;
• Changed NETSETHOST, NETGETHOST including SD-card access;
17 Aug 2016
• Index register #5 can now be input for prefetch function for INI/INIR operation.
09 Oct 2016
• Added more information about mappers, mapper type 8, mapped RAM read flag;
• Expanded browser with input URI argument, input/output flags, added NETVARBRSTR.
05 Nov 2016
• Added TGTMAP command to set target mapper;
• Added value 2 for mapped RAM register read flag for SETMAP and TGTMAP commands to be default
value and causing GR8NET to auto-detect if, within current configuration, it should set up mapper
registers to be readable;
• Split part 2 onto two parts explaining physical design and initialization.
20
•
•
•
Dec 2016
Corrected PARURI firmware call’s address (correct is 5F8E)
Added Nextor as a chapter and into the description of mapper mode 8
Added direct firmware calls DEV8RW, MMVAR, RX, NETCMD, GWREGS, B2ON, B2OFF, GCURSL, UDPOP,
added network operation workflow chart in firmware calls chapter
© 2015-2017 AGE Labs
Page 154 of 156
© 2015-2017 Eugeny Brychkov
29
•
•
•
•
•
Dec 2016
Added support for 7 Mhz overclocked MSX machines;
Moved SD-card CSD information from special register set to the logical page C9;
Added bit 1 in system mode register as source of the SCC clock;
Added MSX slot clock speed identification in logical page C9;
Added two commands NETGETCLK and NETSETCLK.
22
•
•
•
Jan 2017
Added F1 and F2 keys for browser, Disk-ROM initialization diagram;
Inserted chapter 7 Built-In OPLL;
Added NETOPLL command, added 5th parameter into NETSNDVOL command.
13
•
•
•
Feb 2017
Added Y8950 (MSX-Audio) support;
Replaced NETOPLL command with two – NETGETOPL and NETSETOPL;
Added MSX-Audio settings in the special register set (5FD8/5FD9), added Y8950 disable bit in system
mode register;
• Updated memory manager chapter to reflect MSX-Audio sample RAM allocation;
28 Feb 2017
• Added section 5.1 on opening files in the browser
16/21 Mar 2017
• Added NETSYSINFO command to get system information and system performance data for
troubleshooting
• Added NETVARUDTO command to control DHCP and DNS timeouts.
30 Mar 2017
• Added command NETPLAYVID and error code 2E into NETCODE, discontinued GR8VIDEO.COM
application (however it will still run);
• Added CTRL-V key combination into browser to play video files from SD-card using it.
26 Apr 2017
• Added Quick user guide chapter;
• Redesigned WAV player chapter to be media player, and added MP3 streaming support subchapters;
03
•
•
•
May 2017
Added DSKSVIMG command;
Totally reworked built-in Disk-ROM to work from CPU bank 1;
Flash chip firmware version is changed from 0.4 to 0.5.
09
•
•
•
May 2017
Added mapper modes 9-14;
Added NETGETMAP command, added third argument to NETSETMAP command;
Added mapped RAM disable functionality (to disable GR8NET mapped RAM in mapper modes 9-14
because some games can not run if main RAM is in the same slot as game);
• Changed adapter identification through index I/O port 0 from ‘G’ to “GR8N” + GR8NET engine date code.
15 May 2017
• Expanded NETPLAYDVID command to initialize screen without running video;
• Added {} modifier to disk image naming to force 2 logical drive configurations when {2} is in place.
© 2015-2017 AGE Labs
Page 155 of 156
© 2015-2017 Eugeny Brychkov
21 May 2017
• Added NETPLAYVID(SM) flag bits 7 and 6 in addition to screen mode in bits [3:0];
• Redesigned NETPLAYBUF family of the commands.
© 2015-2017 AGE Labs
Page 156 of 156
© 2015-2017 Eugeny Brychkov
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertising