Original NASCOM basic start address.
-h | --help This help test.
-v | --verbose Output more messages.
Examples:
nasconv --image 3dnc.cas --output 3dnc.bas --nasaddr 0x10fa --loadaddr 0x4341 Convert the file 3dnc.cas from NASCOM cassette format.
```
--------------------------------------------------------------------------------------------------------
## Design Detail
This section provides internal design information for understanding how the tranZPUter SW-700 functions and its interactions with the Host (the original computer).
### K64F Z80 Host API
The API is based on a common block of RAM within the 64K memory space of the Z80 through which interprocessor communications take place. On the K64F this is declared
in C as a structure and on the Z80 as an assembler reference to memory variables.
```c
// Structure to contain inter CPU communications memory for command service processing and results.
// Typically the z80 places a command into the structure in it's memory space and asserts an I/O request,
// the K64F detects the request and reads the lower portion of the struct from z80 memory space,
// determines the command and then either reads the remainder or writes to the remainder. This struct
// exists in both the z80 and K64F domains and data is sync'd between them as needed.
//
typedef struct __attribute__((__packed__)) {
uint8_t cmd; // Command request.
uint8_t result; // Result code. 0xFE - set by Z80, command available, 0xFE - set by K64F, command ack and processing. 0x00-0xF0 = cmd complete and result of processing.
union {
uint8_t dirSector; // Virtual directory sector number.
uint8_t fileSector; // Sector within open file to read/write.
uint8_t vDriveNo; // Virtual or physical SD card drive number.
};
union {
struct {
uint16_t trackNo; // For virtual drives with track and sector this is the track number
uint16_t sectorNo; // For virtual drives with track and sector this is the sector number. NB For LBA access, this is 32bit and overwrites fileNo/fileType which arent used during raw SD access.
};
uint32_t sectorLBA; // For LBA access, this is 32bit and used during raw SD access.
struct {
uint8_t memTarget; // Target memory for operation, 0 = tranZPUter, 1 = mainboard.
uint8_t spare1; // Unused variable.
uint16_t spare2; // Unused variable.
};
};
uint8_t fileNo; // File number of a file within the last directory listing to open/update.
uint8_t fileType; // Type of file being processed.
union {
uint16_t loadAddr; // Load address for ROM/File images which need to be dynamic.
uint16_t saveAddr; // Save address for ROM/File images which need to be dynamic.
uint16_t cpuFreq; // CPU Frequency in KHz - used for setting of the alternate CPU clock frequency.
};
union {
uint16_t loadSize; // Size for ROM/File to be loaded.
uint16_t saveSize; // Size for ROM/File to be saved.
};
uint8_t directory[TZSVC_DIRNAME_SIZE]; // Directory in which to look for a file. If no directory is given default to MZF.
uint8_t filename[TZSVC_FILENAME_SIZE]; // File to open or create.
uint8_t wildcard[TZSVC_WILDCARD_SIZE]; // A basic wildcard pattern match filter to be applied to a directory search.
uint8_t sector[TZSVC_SECTOR_SIZE]; // Sector buffer generally for disk read/write.
} t_svcControl;
```
Communications are all instigated by the Z80. When it needs a service, it will write a command into the svcControl.cmd field and set the svcControl.result field to
REQUEST. The Z80 then writes to an output port (configurable but generally 0x68) which in turn sends an interrupt to the K64F. The K64F reads the command and sets the
svcControl.result to PROCESSING - the Z80 waits for this handshake, if it doesnt see it after a timeout period it will resend the command. The Z80 then waits for a valid
result, again if it doesnt get a result in a reasonable time period it retries the sequence and after a number of attempts gives up with an error.
Once the K64F has processed the command (ie. read directory) and stored any necessary data into the structure, it sets the svcControl.result to a valid result (success,
fail or error code) to complete the transaction.
**API Command List**
| Command | Cmd# | Description |
| ------------------------- | -------- | ------------------------------------------------------------- |
| TZSVC_CMD_READDIR | 0x01 | Open a directory and return the first block of entries. |
| TZSVC_CMD_NEXTDIR | 0x02 | Return the next block in an open directory. |
| TZSVC_CMD_READFILE | 0x03 | Open a file and return the first block. |
| TZSVC_CMD_NEXTREADFILE | 0x04 | Return the next block in an open file. |
| TZSVC_CMD_WRITEFILE | 0x05 | Create a file and save the first block. |
| TZSVC_CMD_NEXTWRITEFILE | 0x06 | Write the next block to the open file. |
| TZSVC_CMD_CLOSE | 0x07 | Close any open file or directory. |
| TZSVC_CMD_LOADFILE | 0x08 | Load a file directly into tranZPUter memory. |
| TZSVC_CMD_SAVEFILE | 0x09 | Save a file directly from tranZPUter memory. |
| TZSVC_CMD_ERASEFILE | 0x0a | Erase a file on the SD card. |
| TZSVC_CMD_CHANGEDIR | 0x0b | Change active directory on the SD card. |
| TZSVC_CMD_LOAD40ABIOS | 0x20 | Request 40 column version of the SA1510 BIOS to be loaded, change frequency to match the Sharp MZ-80A. |
| TZSVC_CMD_LOAD80ABIOS | 0x21 | Request 80 column version of the SA1510 BIOS to be loaded, change frequency to match the Sharp MZ-80A. |
| TZSVC_CMD_LOAD700BIOS40 | 0x22 | Request 40 column version of the 1Z-013A MZ-700 BIOS to be loaded, change frequency to match the Sharp MZ-700 and action memory page commands. |
| TZSVC_CMD_LOAD700BIOS80 | 0x23 | Request 80 column version of the 1Z-013A MZ-700 BIOS to be loaded, change frequency to match the Sharp MZ-700 and action memory page commands. |
| TZSVC_CMD_LOAD80BIPL | 0x24 | Request the loading of the MZ-80B IPL, switch frequency and enable Sharp MZ-80B compatible mode. |
| TZSVC_CMD_LOAD800BIOS | 0x25 | Service command requesting that the MZ800 9Z-504M BIOS is loaded. |
| TZSVC_CMD_LOAD2000IPL | 0x26 | Service command requesting the MZ-2000 IPL is loaded. |
| TZSVC_CMD_LOADTZFS | 0x2F | Service command requesting the loading of TZFS. This service is for machines which normally dont have a monitor BIOS. ie. MZ-80B/MZ-2000 and manually request TZFS. |
| TZSVC_CMD_LOADBDOS | 0x30 | Reload CPM BDOS+CCP. |
| TZSVC_CMD_ADDSDDRIVE | 0x31 | Attach a CPM disk to a drive number. |
| TZSVC_CMD_READSDDRIVE | 0x32 | Read an attached SD file as a CPM disk drive. |
| TZSVC_CMD_WRITESDDRIVE | 0x33 | Write to a CPM disk drive which is an attached SD file. |
| TZSVC_CMD_CPU_BASEFREQ | 0x40 | Set the tranZPUter to use the mainboard frequency for the Z80. |
| TZSVC_CMD_CPU_ALTFREQ | 0x41 | Switch the Z80 to use the K64F generated clock, ie. alternative frequency. |
| TZSVC_CMD_CPU_CHGFREQ | 0x42 | Change the Z80 frequency generated by the K64F to the Hertz value given in svcControl.cpuFreq, the Z80 will be clocked at the nearest timer resolution of this frequency. |
| TZSVC_CMD_CPU_SETZ80 | 0x50 | Switch to the external Z80 hard cpu. |
| TZSVC_CMD_CPU_SETT80 | 0x51 | Switch to the internal T80 soft cpu. |
| TZSVC_CMD_CPU_SETZPUEVO | 0x52 | Switch to the internal ZPU Evolution cpu. |
| TZSVC_CMD_EMU_SETMZ80K | 0x53 | Service command to switch to the internal Sharp MZ Series Emulation of the MZ80K. |
| TZSVC_CMD_EMU_SETMZ80C | 0x54 | "" "" "" MZ80C. |
| TZSVC_CMD_EMU_SETMZ1200 | 0x55 | "" "" "" MZ1200. |
| TZSVC_CMD_EMU_SETMZ80A | 0x56 | "" "" "" MZ80A. |
| TZSVC_CMD_EMU_SETMZ700 | 0x57 | "" "" "" MZ700. |
| TZSVC_CMD_EMU_SETMZ800 | 0x58 | "" "" "" MZ800. |
| TZSVC_CMD_EMU_SETMZ80B | 0x59 | "" "" "" MZ80B. |
| TZSVC_CMD_EMU_SETMZ2000 | 0x5A | "" "" "" MZ2000. |
| TZSVC_CMD_SD_DISKINIT | 0x60 | Initialise and provide raw access to the underlying SD card. |
| TZSVC_CMD_SD_READSECTOR | 0x61 | Provide raw read access to the underlying SD card. |
| TZSVC_CMD_SD_WRITESECTOR | 0x62 | Provide raw write access to the underlying SD card. |
| TZSVC_CMD_EXIT | 0x7F | Terminate TZFS and restart the machine in original mode. |
**API Result List**
| Command | Result# | Description |
| ------------------------- | -------- | ------------------------------------------------------------- |
| TZSVC_STATUS_OK | 0x00 | The K64F processing completed successfully. |
| TZSVC_STATUS_FILE_ERROR | 0x01 | A file or directory error. |
| TZSVC_STATUS_BAD_CMD | 0x02 | Bad service command was requested. |
| TZSVC_STATUS_BAD_REQ | 0x03 | Bad request was made, the service status request flag was not set. |
| TZSVC_STATUS_REQUEST | 0xFE | Z80 has posted a request. |
| TZSVC_STATUS_PROCESSING | 0xFF | K64F is processing a command. |
--------------------------------------------------------------------------------------------------------
### Z80 Memory Modes
One of the features of the tranZPUter SW-700 hardware design is the ability to create memory maps freely within the 512 macro cell CPLD. Any conceivable memory map within Z80 address space (or any soft-cpu address space upto 18 bits wide)
utilising the 512K Static RAM, 64K mainboard RAM, Video RAM, I/O can be constructed using a boolean equation and then assigned to a Memory Mode, The memory mode is then selected by Z80 software as required, ie. this ability is put to good
use in order to realise TZFS, CP/M and the compatible modes of the Sharp MZ-700 and MZ-80B.
The basis of the memory modes came from version 1 of the tranZPUter SW project where the decoder was based on a Flash RAM. All foreseen memory models required at that time, such as MZ-700, CP/M etc where devised. These modes have been enhanced in later designs
within the CPLD to cater for new features such as the Video Module and no doubt will be further enhanced in the future.
Modes which have been defined are in the table below leaving a few available slots for future expansion.
| Mode | Target | Range | Block | Function | DRAM Refresh | Description |
|------|-------------|---------------|-------|----------------|--------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 0 | Original | 0000:0FFF | Main | MROM | Yes | Default, normal host (ie. Sharp MZ80A/MZ-700) operating mode, all memory and IO (except tranZPUter controlled I/O block) are on the mainboard |
| | | 1000:CFFF | Main | D-RAM | | |
| | | D000:D7FF | Main | VRAM | | |
| | | D800:DFFF | Main | ARAM | | |
| | | E000:E7FF | Main | MM I/O | | |
| | | E800:EFFF | Main | User ROM | | |
| | | F000:FFFF | Main | FDC ROM | | |
| 1 | Orig+ UROM | 0000:0FFF | Main | MROM | Yes | As 0 except User ROM is mapped to tranZPUter RAM and used for loadable BIOS images. |
| | | 1000:CFFF | Main | D-RAM | | |
| | | D000:D7FF | Main | VRAM | | |
| | | D800:DFFF | Main | ARAM | | |
| | | E000:E7FF | Main | MM I/O | | |
| | | E800:EFFF | RAM 0 | User ROM | | |
| | | F000:FFFF | Main | FDC ROM | | |
| 2 | TZFS | 0000:0FFF | RAM 0 | MROM | No | Boot mode for TZFS or any other software requiring use of the tranZPUter RAM. User ROM appears as ROM to the Monitor so it will call the entry point at 0xE800 as part of it's normal startup procedure. The software stored at 0xE800 can switch out the mainboard and run in tranZPUter RAM as required. Two small holes at F3FE and F7FE exist for the Floppy disk controller (which have to be 2 bytes wude), these locations need to be on the mainboard. The floppy disk controller uses them as part of its data read/write as the Z80 isnt fast enough to poll the FDC. |
| | | 1000:CFFF | RAM 0 | Main RAM | | |
| | | D000:D7FF | Main | VRAM | | |
| | | D800:DFFF | Main | ARAM | | |
| | | E000:E7FF | RAM 0 | MM I/O | | |
| | | E800:EFFF | RAM 0 | User ROM | | |
| | | F000:FFFF | RAM 0 | FDC ROM | | |
| 3 | TZFS | 0000:0FFF | RAM 0 | MROM | No | Page mode for TZFS, all RAM in tranZPUter Block 0 except F000:FFFF which is in Block 1, this is page bank2 of TZFS. |
| | | 1000:CFFF | RAM 0 | Main RAM | | |
| | | D000:D7FF | RAM 0 | VRAM | | |
| | | D800:DFFF | RAM 0 | ARAM | | |
| | | E000:E7FF | RAM 0 | MM I/O | | |
| | | E800:EFFF | RAM 0 | User ROM | | |
| | | F000:FFFF | RAM 1 | FDC ROM | | |
| 4 | TZFS | 0000:0FFF | RAM 0 | MROM | No | As mode 3 but F000:FFFF is in Block 2, this is page bank3 of TZFS. |
| | | 1000:CFFF | RAM 0 | Main RAM | | |
| | | D000:D7FF | RAM 0 | VRAM | | |
| | | D800:DFFF | RAM 0 | ARAM | | |
| | | E000:E7FF | RAM 0 | MM I/O | | |
| | | E800:EFFF | RAM 0 | User ROM | | |
| | | F000:FFFF | RAM 2 | FDC ROM | | |
| 5 | TZFS | 0000:0FFF | RAM 0 | MROM | No | As mode 3 but F000:FFFF is in Block 3, this is page bank4 of TZFS. |
| | | 1000:CFFF | RAM 0 | Main RAM | | |
| | | D000:D7FF | RAM 0 | VRAM | | |
| | | D800:DFFF | RAM 0 | ARAM | | |
| | | E000:E7FF | RAM 0 | MM I/O | | |
| | | E800:EFFF | RAM 0 | User ROM | | |
| | | F000:FFFF | RAM 3 | FDC ROM | | |
| 6 | CP/M | 0000:FFFF | RAM 4 | Main RAM | No | CP/M, all memory on the tranZPUter board. Special case for F3C0:F3FF & F7C0:F7FF (floppy disk paging vectors) which resides on the mainboard. |
| 7 | CP/M | 0000:0100 | RAM 4 | CP/M Vectors | No | CP/M main CBIOS area, 48K + 2K available for the CBIOS and direct access to mainboard hardware. F000:FFFF remains in bank 4 and used as the gateway between this memory mode and mode 6. |
| | | 0100:CFFF | RAM 5 | Main RAM | | |
| | | D000:D7FF | Main | VRAM | | |
| | | D800:DFFF | Main | ARAM | | |
| | | E000:E7FF | Main | MM I/O | | |
| | | E800:EFFF | RAM 5 | User ROM | | |
| | | F000:FFFF | RAM 4 | FDC ROM | | |
| 8 | Orig+ Emu | 0000:0FFF | Main | MROM | Yes | Original mode but with the main RAM in the tranZPUter bank 0. This mode is used to bootstrap programs such as MZ-700 programs which bank change on startup and expect the loaded program to be within the main memory which is within a tranZPUter RAM bank. |
| | | 1000:CFFF | RAM 0 | Main RAM | | |
| | | D000:D7FF | Main | VRAM | | |
| | | D800:DFFF | Main | ARAM | | |
| | | E000:E7FF | Main | MM I/O | | |
| | | E800:EFFF | Main | User ROM | | |
| | | F000:FFFF | Main | FDC ROM | | |
| 10 | MZ-700 | 0000:0FFF | RAM 6 | Main RAM | No | MZ-700 mode (OUT $E0) - Monitor RAM replaced with Main RAM |
| | | 1000:CFFF | RAM 0 | Main RAM | | |
| | | D000:D7FF | Main | VRAM | | |
| | | D800:DFFF | Main | ARAM | | |
| | | E000:E7FF | Main | MM I/O | | |
| | | E800:EFFF | Main | User ROM | | |
| | | F000:FFFF | Main | FDC ROM | | |
| 11 | MZ-700 | 0000:0FFF | RAM 0 | MROM | No | MZ-700 mode (OUT $E0 + $E1) - I/O and Video block replaced with Main RAM |
| | | 1000:CFFF | RAM 0 | Main RAM | | |
| | | D000:D7FF | RAM 6 | VRAM | | |
| | | D800:DFFF | RAM 6 | ARAM | | |
| | | E000:E7FF | RAM 6 | MM I/O | | |
| | | E800:EFFF | RAM 6 | User ROM | | |
| | | F000:FFFF | RAM 6 | FDC ROM | | |
| 12 | MZ-700 | 0000:0FFF | RAM 6 | Main RAM | No | MZ-700 mode (OUT $E1 + $E2) - Monitor RAM replaced with RAM and I/O and Video block replaced with Main RAM |
| | | 1000:CFFF | RAM 0 | Main RAM | | |
| | | D000:D7FF | RAM 6 | VRAM | | |
| | | D800:DFFF | RAM 6 | ARAM | | |
| | | E000:E7FF | RAM 6 | MM I/O | | |
| | | E800:EFFF | RAM 6 | User ROM | | |
| | | F000:FFFF | RAM 6 | FDC ROM | | |
| 13 | MZ-700 | 0000:0FFF | RAM 0 | MROM | No | MZ-700 mode (OUT $E5) - Upper memory locked out, Monitor ROM paged in. |
| | | 1000:CFFF | RAM 0 | Main RAM | | |
| | | D000:FFFF | n/a | Undefined | | |
| 14 | MZ-700 | 0000:0FFF | RAM 6 | Main RAM | No | MZ-700 mode (OUT $E6) - Monitor RAM replaced with RAM and Upper memory locked out. |
| | | 1000:CFFF | RAM 0 | Main RAM | | |
| | | D000:FFFF | n/a | Undefined | | |
| 15 | MZ-800/MZ-700 | | | | | See table below. Memory mode is as per the MZ-800. |
| 16 | MZ2000 | 0000:7FFF | RAM 0 | IPL ROM | No | MZ2000 hardware mode, configuration set according to the MZ2000 runtime configuration registers. |
| | | 8000:FFFF | RAM 6 | Lower 32K RAM | | During IPL mode, lower 32K RAM mapped to upper 32K address. |
| | | 0000:FFFF | RAM 6 | Main RAM | | During RUN mode, full 64K RAM mapped into Z80 address space. |
| | | D000:DFFF | Main | VRAM | | Video RAM mapped into Z80 address space when PIO Port A Bit 7 set, Bit 6 clear. |
| | | C000:FFFF | Main | GRAM | | Graphics RAM mapped into Z80 address space when PIO Port A Bit 7 set, Bit 6 set. |
| 21 | K64F Access | 000000:FFFFFF | n/a | FPGA Resources | No | Access the FPGA memory by passing through the full 24bit Z80 address, typically from the K64F. |
| 22 | FPGA Access | 0000:FFFF | n/a | Host Resources | Yes | Access to the host mainboard 64K address space only. |
| 23 | K64F Access | 000000:FFFFFF | RAM | Main RAM | No | Access all memory and IO on the tranZPUter board with the K64F addressing the full 512K RAM. |
| 24 | K64F Access | 0000:FFFF | RAM 0 | Main RAM | Yes/No | All memory and IO are on the tranZPUter board, 64K block 0 selected. Mainboard DRAM is refreshed by the tranZPUter library when using this mode. |
| 25 | K64F Access | 0000:FFFF | RAM 1 | Main RAM | Yes/No | All memory and IO are on the tranZPUter board, 64K block 1 selected. Mainboard DRAM is refreshed by the tranZPUter library when using this mode. |
| 26 | K64F Access | 0000:FFFF | RAM 2 | Main RAM | Yes/No | All memory and IO are on the tranZPUter board, 64K block 2 selected. Mainboard DRAM is refreshed by the tranZPUter library when using this mode. |
| 27 | K64F Access | 0000:FFFF | RAM 3 | Main RAM | Yes/No | All memory and IO are on the tranZPUter board, 64K block 3 selected. Mainboard DRAM is refreshed by the tranZPUter library when using this mode. |
| 28 | K64F Access | 0000:FFFF | RAM 4 | Main RAM | Yes/No | All memory and IO are on the tranZPUter board, 64K block 4 selected. Mainboard DRAM is refreshed by the tranZPUter library when using this mode. |
| 29 | K64F Access | 0000:FFFF | RAM 5 | Main RAM | Yes/No | All memory and IO are on the tranZPUter board, 64K block 5 selected. Mainboard DRAM is refreshed by the tranZPUter library when using this mode. |
| 30 | K64F Access | 0000:FFFF | RAM 6 | Main RAM | Yes/No | All memory and IO are on the tranZPUter board, 64K block 6 selected. Mainboard DRAM is refreshed by the tranZPUter library when using this mode. |
| 31 | K64F Access | 0000:FFFF | RAM 7 | Main RAM | Yes/No | All memory and IO are on the tranZPUter board, 64K block 7 selected. Mainboard DRAM is refreshed by the tranZPUter library when using this mode. |
Key:
MROM = Monitor ROM, the original boot firmware ie. SA-1510
D-RAM = Dynamic RAM on the mainboard.
VRAM = Video RAM on the mainboard.
ARAM = Colour Attribute RAM on the mainboard.
MM I/O = Memory Mapped I/O controllers on the mainboard.
RAM 0 .. 7 = 64K RAM Block number within the 512K Static RAM chip.
Main = Host computer mainboard, ie the Sharp MZ-80A mainboard.
##### MZ700/MZ800 Memory Mode
| MZ-700 ||||| | MZ-800 |
| Register |0000:0FFF|1000:1FFF|1000:CFFF|C000:CFFF|D000:FFFF |0000:7FFF|1000:1FFF|2000:7FFF|8000:BFFF|C000:CFFF|C000:DFFF|E000:FFFF |
| ---------- |---------|---------|---------|---------|--------- |---------|---------|---------|---------|---------|---------|--------- |
| OUT 0xE0 |DRAM | | | | |DRAM | | | | | | |
| OUT 0xE1 | | | | |DRAM | | | | | | |DRAM |
| OUT 0xE2 |MONITOR | | | | |MONITOR | | | | | | |
| OUT 0xE3 | | | | |Memory Mapped I/O | | | | | | |Upper MONITOR ROM |
| OUT 0xE4 |MONITOR | |DRAM | |Memory Mapped I/O |MONITOR |CGROM |DRAM |VRAM | |DRAM |Upper MONITOR ROM |
| OUT 0xE5 | | | | |Inhibit | | | | | | |Inhibit |
| OUT 0xE6 | | | | | | | | | | | | |
| IN 0xE0 | |CGROM* | |VRAM* | | |CGROM | |VRAM | | | |
| IN 0xE1 | |DRAM | |DRAM | | | | |DRAM | | | |
Key:
<return> = Return to the state prior to the complimentary command being invoked.
* = MZ-800 host only.
--------------------------------------------------------------------------------------------------------
### Z80 CPU Frequency Switching
In order to make the tranZPUter SW-700 compatible with other machines it is necessary to clock the CPU at the speed of that machine. It is also desirable to clock the CPU as fast as possible when using software such
as CP/M for maximum performance.
One of the main issues with frequency switching is that the underlying host cannot have its frequency changed, the host is generally generating the clock and it's circuits have been designed to operate within it's clock
tolerances. The tranZPUter SW-700 overcomes this limitation as described below.
To fulfil the requirement to have a switchable Z80 CPU frequency a positive edge triggered frequency switch has been implemented which takes the host frequency as one input and a square wave generator from the K64F as its second input.
The switching mechanism is tied to the bus control logic and so any access to the host will see the frequency of the CPU being changed to that of the host which ensures continued reliable operation. Under startup conditions, the Z80 is
always clocked by the host clock to ensure original specifications of the machine are met.
A second frequency can be selected if the K64F is present as it has the ability using its onboard timers to generate a programmable square wave output. The K64F sets the frequency of this second clock source
and the Z80 can select it via an I/O OUT command. This gives the software running on the Z80 the opportunity to change it's own frequency, albeit to a fixed set one. An extension to the K64F Host API allows the Z80 to make a request
of the K64F to set the Z80 CPU frequency to any possible value, this is useful in TZFS or CP/M so a user can select their own frequency.
Current testing on a CMOS Z84C0020 20MHz CPU has the following observations:
* tranZPUter reliable in the range 1Hz to 24MHz for all functionality.
* When the mainboard is accessed the frequency slows to 3.54MHz (ie. the system clock) and returns to the higher frequency after the mainboard access has completed.
It is also possible to slow down the CPU for training or debugging purposes albeit access to the host circuitry will always run at the host clock frequency,
On an application running under the Z80, the following table outlines the I/O ports to which it must read/write in order to switch frequencies.
##### Z80 CPU Frequency Switching Ports
| Port | Dir | Function |
| ---- | --- | -------- |
| 0x62 | W | Switch Z80 CPU frequency to the second source, ie. the frequency generated by the K64F or external oscillator. |
| 0x64 | W | Switch Z80 CPU frequency to default host source. This is the default on RESET. |
| 0x66 | R | Bit [0] - Clock Selected, 0 = Host Clock, 1 = second clock source (K64F or external oscillator). |
--------------------------------------------------------------------------------------------------------
## Building tranZPUter SW-700 Software
The tranZPUter SW-700 board requires several software components to function:
- zOS embedded - the integral operating system running on the K64F I/O processor
- zOS user - the operating system for a ZPU Evo running as the Sharp MZ-700 main host processor
- TZFS - the Z80 based operating or filing system running on the Sharp MZ-700
- CP/M - A real operating system for Microcomputers which I ported to the Sharp MZ-700 and it benefits from a plethora of applications.
Building the software requires different procedures and these are described in the sections below.
--------------------------------------------------------------------------------------------------------
### Paths
For ease of reading, the following shortnames refer to the corresponding path in this document. The repository can be found at [TZFS](https://github.com/pdsmart/TZFS).
*tranZPUter Repository*
| Short Name | Path | Description |
|------------------|----------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------|
| \ | \[\\]/tranZPUter/cpu | ZPU VHDL definition files. |
| \ | \[\\]/tranZPUter/build | Build files for developing and tesing of the ZPU based tranZPUter board. |
| \ | \[\\]/tranZPUter/devices | RTL definitions of hardware devices used in the ZPU development or tranZPUter development. |
| \ | \[\\]/tranZPUter/docs | Any relevant documentation for the project. |
| \ | \[\\]/tranZPUter/pcb | Gerber files, each tranZPUter version (SW, SW-700 and tranZPUter) within it's own sub-directory. |
| \ | \[\\]/tranZPUter/schematics | Kicad schematics and PCB design files including component library definitions. |
| \ | \[\\]/tranZPUter/software | Root directory for software used in the project. |
| \ | \[\\]/tranZPUter/software/tools | Tools to aid in the compilation and creation of target files. |
| \ | \[\\]/tranZPUter/software/asm | Z80 assembler files for TZFS, CP/M and various original monitor ROMS. |
| \ | \[\\]/tranZPUter/software/roms | ROM files created by assembling the Z80 source. |
| \ | \[\\]/tranZPUter/software/src/tools | tranZPUter v1 Flash RAM memory map decoder file creation tool and NASCOM Basic converter tool. |
| \ | \[\\]/tranZPUter/software/CPM | Original CPM software, grouped according to application including generated Floppy Disk and SD Card images. |
| \ | \[\\]/tranZPUter/software/MZF | Original Sharp MZF format applications which will be added into any generated SD Card image. |
| \ | \[\\]/tranZPUter/software/BAS | A collection of converted NASCOM Basic programs in readable text format. These are added to generated SD Card images. |
| \ | \[\\]/tranZPUter/software/CAS | A collection of NASCOM Basic tokenized tape programs converted from the NASCOM tape images. These are added to generated SD Card images. |
| \ | \[\\]/tranZPUter/software/NASCAS | A collection of original NASCOM cassette images which havent been converted. Use the nasconv tool to convert. |
| \ | \[\\]/tranZPUter/software/config | Configuration files for tools. Currently the disk definition description file for generation of CP/M images. |
--------------------------------------------------------------------------------------------------------
### Tools
All development has been made under Linux, specifically Debian/Ubuntu. I use Windows for the GUI version of CP/M Tools but havent dedicated any time into building TZFS under Windows. I will in due course
create a Docker image with all necessary tools installed, but in the meantime, in order to assemble the Z80 code, the C programs and to work with the CP/M software and CP/M disk images, you will need to obtain and install the following tools.
NB: For the K64F, the ARM compatible toolchain is currently stored in the repo within the build tree.
| | |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
[ZPU GCC ToolChain](https://github.com/zylin/zpugcc) | The GCC toolchain for ZPU development. Install into */opt* or similar common area. |
[Arduino](https://www.arduino.cc/en/main/software) | The Arduino development environment, not really needed unless adding features to the K64F version of zOS from the extensive Arduino library. Not really needed, more for reference. |
[Teensyduino](https://www.pjrc.com/teensy/td_download.html) | The Teensy3 Arduino extensions to work with the Teensy3.5 board at the Arduino level. Not really needed, more for reference. |
[Z80 Glass Assembler](http://www.grauw.nl/blog/entry/740/) | A Z80 Assembler for converting Assembly files into machine code. I have had to fix a bug in the 0.5 release as it wouldnt create a byte at location 0xFFFF, this fixed version is stored in the \ directory in the repository. |
[samdisk](https://simonowen.com/samdisk/) | A multi-os command line based low level disk manipulation tool. |
[cpmtools](https://www.cpm8680.com/cpmtools/) | A multi-os command line CP/M disk manipulation tool. |
[CPMToolsGUI](http://star.gmobb.jp/koji/cgi/wiki.cgi?page=CpmtoolsGUI) | A Windows based GUI CP/M disk manipulation tool. |
[z88dk](https://www.z88dk.org/forum/) | An excellent C development kit for the Z80 CPU. |
[sdcc](http://sdcc.sourceforge.net/) | Another excellent Small Device C compiler, the Z80 being one of its targets. z88dk provides an enhanced (for the Z80) version of this tool within its package. |
--------------------------------------------------------------------------------------------------------
### Build TZFS
Building the software and final load image can be done by cloning the [repository](https://github.com/pdsmart/tranZPUter.git) and running some of the shell scripts and binaries provided.
TZFS is built as follows:
1. Make the TZFS binary using \/assemble_tzfs.sh, this creates a ROM image \/tzfs.rom which contains all the main and banked code.
2. Make the original MZ80A/MZ-700 monitor roms using \/assemble_roms.sh, this creates \/monitor_SA1510.rom, \/monitor_80c_SA1510.rom, \/monitor_1Z-013A.rom and \/monitor_80c_1Z-013A.rom.
3. Copy and/or delete any required Sharp MZF files into/from the MZF directory.
4. Copy files to the SD card.
See [below](/sharpmz-upgrades-tranzputer-sw/#a-typical-build) for the typical build stages.
--------------------------------------------------------------------------------------------------------
### Build CPM
To build CP/M please refer to the [CP/M build section](/sharpmz-upgrades-cpm/#building-cpm) for additional information.
The CP/M version for the tranZPUter is slightly simpler to build as it doesnt involve preparing a special SD card or compacted ROM images.
The CP/M system is built in 4 parts,
1. the cpm22.bin which contains the CCP, BDOS and a CBIOS stub.
2. the banked CBIOS which has its primary source in a 4K page located at 0xF000:FFFF and a
larger, upto 48K page, located in a seperate 64K RAM block.
3. the concatenation of 1 + 2 + MZF Header into an MZF format file which TZFS can load.
4. creation of the CPM disk drives which are stored as 16MB FAT32 files on the K64F SD card.
All of the above are encoded into 2 bash scripts, namely 'assemble_cpm.sh' and 'make_cpmdisks.sh' which can be executed as follows:
```bash
cd
tools/assemble_cpm.sh
tools/make_cpmdisks.sh
```
The CPM disk images can be found in \/1M44/RAW for the raw images or \/1M44/DSK for the CPC Extended format disk images. These images are built from the directories in
\, each directory starting with CPM* is packaged into one 1.44MB drive image. NB. In addition, the directories are also packaged into all the other supported disks as
images in a corresponding directory, ie \/SDC16M for the 16MB SD Card drive image.
The CPM disks which exist as files on the SD Card are stored in \/SDC16M/RAW and have the format CPMDSK\.RAW, where \ is 00, 01 ... n and corresponds to the
disk drive under CP/M to which they are attached (ie. standard boot, 00 = drive A, 01 = drive B etc. If the Floppy Disk Controller has priority then 00 = drive C, 01 = drive D).
Under a typical run of CP/M upto 6 disks will be attached (the attachment is dynamic but limited to available memory).
--------------------------------------------------------------------------------------------------------
### A Typical Build
A quick start to building the software, creating the SD card and installing it has been
summarized below.
````bash
# Obtain an SD Card and partition into 2 DOS FAT32 formatted partitions, mount them as and . The partition size should be at least 512Mb each.
# The first partition will host the software to run on the K64F I/O processor AND all the Sharp MZ software to be accessed by the Sharp MZ-700.
# The second partition will host the software to run on the ZPU Evo processor when it acts as the main Sharp MZ-700 processor.
# Build zOS (embedded)
cd
./build.sh -C K64F -O zos -N 0x10000 -d -T
# Flash /main.hex into the K64F processor via USB or OpenSDA.
cp -r build/SD/* /
# Build zOS (user)
./build.sh -C EVO -O zos -o 0 -M 0x1FD80 -B 0x0000 -S 0x3D80 -N 0x4000 -A 0x100000 -a 0x80000 -n 0x0000 -s 0x0000 -d -Z
cp -r build/SD/* /
# Ensure that the ZPU zOS kernel is copied to the K64F partition as it will be used for loading into the ZPU Evo on reset.
cp -rbuild/SD/ZOS/* /ZOS/
# Build TZFS
cd
tools/assemble_tzfs.sh
# Build the required host (Sharp) ROMS.
tools/assemble_roms.sh
# Build CPM
tools/assemble_cpm.sh
# Build the CPM disks.
tools/make_cpmdisks.sh
# Create the target directories on the SD card 1st partition and copy all the necessary applications and roms.
mkdir -p /TZFS/
mkdir -p /MZF/
mkdir -p /CPM/
mkdir -p /BAS
mkdir -p /CAS
cp /roms/tzfs.rom /TZFS/
cp /roms/monitor_SA1510.rom /TZFS/SA1510.rom
cp /roms/monitor_80c_SA1510.rom /TZFS/SA1510-8.rom
cp /roms/monitor_1Z-013A.rom /TZFS/1Z-013A.rom
cp /roms/monitor_80c_1Z-013A.rom /TZFS/1Z-013A-8.rom
cp /roms/monitor_1Z-013A-KM.rom /TZFS/1Z-013A-KM.rom
cp /roms/monitor_80c_1Z-013A-KM.rom /TZFS/1Z-013A-KM-8.rom
cp /roms/MZ80B_IPL.rom /TZFS/MZ80B_IPL.rom
cp /MZF/CPM223.MZF /MZF/
cp /roms/cpm22.bin /CPM/
cp /CPM/SDC16M/RAW/* /CPM/
cp /MZF/* /MZF/
cp /BAS/* /BAS/
cp /CAS/* /CAS/
# If you want TZFS to autostart, create an empty flag file as follows.
> /TZFSBOOT.FLG
# If you want to run TZFS commands on each boot, create an autoexec.bat file and place required commands into the file.
> /AUTOEXEC.BAT
# Eject the card and insert it into the SD Card reader on the tranZPUter board.
# Remove the Z80 from the Sharp MZ machine and install the tranZPUter board into the Z80 socket.
# Power on. If the autostart flag has been created, you should see the familiar monitor
# signon message followed by +TZFS. If the autostart flag hasnt been created, enter the command
# JE800 into the monitor to initialise TZFS.
````
To aid in building and preparing an SD card, I use a quick and dirty script \/buildall which can be used but you would need to change the ROOT_DIR and disable the RSYNC (I use a remote computer to compile zOS and upload into the K64F).
Any errors and the script will abort with a suitable error message.
--------------------------------------------------------------------------------------------------------
## Credits
Where I have used or based any component on a 3rd parties design I have included the original authors copyright notice. All 3rd party software, to my knowledge and research, is open source and freely useable, if there is found to be any component with licensing restrictions, it will be removed from this repository and a suitable link/config provided.
--------------------------------------------------------------------------------------------------------
## Licenses
This design, hardware and software, is licensed under the GNU Public Licence v3.
### The Gnu Public License v3
The source and binary files in this project marked as GPL v3 are free software: you can redistribute it and-or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
The source files are distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.