So far I’ve modified the source so it assembles with pyz80. A global search and replace made quick work of changing the label format from “.label” to “label:”, but I had to change many data statements manually. Strings were often combined with other single bytes in defb statements, but the Comet format used by pyz80 doesn’t allow that, requiring defm be used instead.

The existing code is nice and modular, but there are CPC-specific ROM calls sprinkled throughout them. All those need to be changed before a test run on SAM, to avoid us unexpectedly jumping into the middle of nowhere! I changed the stdio.z module to use SAM’s ROM calls for character output, leaving the cursor control and keyboard input doing nothing for now. I also replaced the serial module with a dummy ethernet module, with no-op versions of the required interface functions. They will be fleshed out with calls to the Trinity driver when the rest of the code is ready.

Those changes are enough for a basic run on SAM, without being connected to a real network. Here’s what you see when it’s launched:

The program continues polling for serial and keyboard input in a main loop. The CPC version uses a 300Hz timer to poll for new data from the serial link, which is buffered for later reading from the main loop. Each received byte is passed into either the SLIP or PPP module (whichever was configured during the build), which builds up complete datagrams. These are then passed into the ‘ip_handle’ function inside ip.z for the processing.

The SAM implementation will read complete datagrams from the Trinity driver, so they can be passed straight into ‘ip_handle’. This vastly simplifies the setup above, but introduces a new requirement: ARP. SLIP and PPP push datagrams back into the link and let the remote end deal with routing. With ethernet we need to determine the hardware addresses for delivery, for both local and routed traffic.

I’ll need to write a new arp.z module to sit between the Trinity driver and the IP module. Outgoing traffic for hosts already in the ARP cache can be sent immediately. Anything for as-yet-unknown targets must be buffered, and a who-has ARP request made for the address owner to reply. Once a reply is received, an entry for it is added to the local ARP cache and data buffered for that host is sent. If no reply is received (ideally after multiple attempts), data for the target will be discarded. We must also reply to incoming ARP requests for our own address so other hosts can to talk to us.

I’m still torn between using the SAM ROM routines for I/O and something based on the terminal code I wrote for the Apple 1 emulator. The ROM code would give the same output flexibility as in BASIC, but the general ROM code is a bit on the slow side. My own code could be tailored for a specific mode, either mode 2 for speed or mode 3 for hi-res. It might be easier to stick with the ROM code for now, and change it if it’s too slow.

Last month I picked up one of the first Quazar Trinty boards. Since then I’ve been working on the ethernet side, which is based around a MicroChip ENC28J60 chip. The Trinity board also includes EEPROM and MMC/SD board features, but I’m leaving those for another time. My first task was to write a simple network driver, to allow sending and receiving raw packets from BASIC.

Trinity uses the SAM port range &DC to &DF. The first of these is the microcontroller, which acts as a central hub for all the board’s features. The other ports are used for the EEPROM, Ethernet and MMC/SD card, and each needs to be enabled through the microcontroller before it can be used. Port &DE is used for ENC ethernet chip, and once enabled we can read and write to the chip directly. Well, almost directly as the link uses the SPI bus.

If you’re as clueless about electronics as I am you probably won’t have come across the SPI (Serial Peripheral Interface) bus. It’s a full duplex link where each byte written is paired with a read back from the device. Since reads can’t be performed without a write, Trinity stores the value read for later. Reading from SAM reads only the stored value, without accessing the ENC.

SPI introduces a lag between writing a value and reading any result generated by the write, since the stored value is what was read before the write completed. An additional dummy (zero) write is needed for the actual result to be available for reading. The lag also means block reads require a dummy write before reading each byte. Fortunately, the latest Trinity firmware provides an auto-null-writing feature to simplify and optimise this.

The ENC itself has a banked register setup, arranged as 4 banks of 32 registers. The final 5 registers in each bank are common across all banks, and are used for status registers and bank selection. All ENC features are accessed through these registers, including reading and writing from the internal 8K data buffer. The buffer is used for both transmitting and receiving, with a user-defined portion of it configured as a circular receive buffer. The remaining space is unmanaged and available for transmission storage.

In its power-on state the ENC will see but not receive anything. It has no hardware address set, no space allocated for the receive buffer, and the packet filter is set to ignore everything. The driver initialisation is responsible for setting up all of those, and any other register where the defaults are not suitable. Before we do that it’s wise to ask the Trinity microcontroller to reset the ENC chip back to a known state.

I started my experimentation from BASIC as it was quicker to tweak the ENC registers and see results than launching the assembler for each change. Colin supplied a sample disk with macros to access the board, with most containing a couple of OUTs and maybe an IN. I added to them for higher level functions, such as setting the MAC address and writing blocks of data to the ENC buffer. Once I was happy this was working I was ready to port it to Z80.

I chose to use 6.5K of the 8K buffer for receiving, with 1.5K left for sending. That’s just enough space to send a single full-size ethernet frame. The packet filter was set to receive packets addressed to our MAC address, as well as anything broadcast to the whole subnet. Writing a zero to the packet filter register disables it, so all local network traffic is seen. Couple that with packet decoding and you have an easy network sniffer.

My driver development wasn’t all smooth sailing, with a few bumps along the way. The first was my early attempts to write and read the MAC address values, to ensure my new Z80 code was working. It turns out the subset of ENC registers starting with ‘M’ (which includes the MAC registers) have an extra lag on top of SPI, and require double-reading before they return the correct result. I was also stung by a documented ENC issue with the transmit logic getting stuck under certain conditions. A bug in my work-around meant I would still occasionally hang during transmits.

Even with the driver initialised and reception enabled, we’re still not quite ready to handle a test ping from another machine on the network. Responding to requests requires CRC calculations in the return packets, which involved more work than I wanted to do for a test setup. That will be the job of of a full IP stack. It’s marginally easier to send a ping request from SAM, since the request can be pre-calculated and it’s only the remote host that needs to worry about dynamic responses.

Even pinging an IP address from SAM is surprisingly involved:

1. Use local IP and netmask to determine whether target IP is on our subnet (if not, send to gateway machine for further routing)
2. Check local ARP cache for the target IP (if found, goto 5)
3. Broadcast who-has ARP request to find the MAC of the IP
4. Wait for ARP reply, then add MAC to local ARP cache
5. Construct ECHO REQUEST ICMP packet
6. Send unicast packet to target MAC

Fortunately, we can strip this down for the sake of a simple test. We’re using a local target so step 1 is unnecessary. We can also hard-code the MAC of the target machine, to also skip steps 2 to 4. An ICMP ECHO request packet can then be constructed with fixed details and pre-calculated CRCs. I used Ethereal on my PC to sniff a request sent with a zero CRC, which was expected to fail, then completed the correct CRC with what it reported.

To send a reply, the target machine will perform the same steps as above, with an ICMP ECHO REPLY packet. As SAM is currently unable to reply to ARP requests we must use the “arp” command on the target machine to add a static entry linking SAM’s IP with its MAC address. In my case that meant running the following command in Windows XP:

arp -s 10.0.0.88 02:A4:92:E4:D3:20

The test MAC address I used was formed from bits of the string “TRINITY”, with a few unused zero bits at the end. Bits 0 and 1 of the first byte are flags, but the rest can be pretty much anything. I’ve set flag bit 1 to mark the address as “locally administered”, to avoid the (rather unlikely!) clash with existing network devices. To avoid clashes with other Trinity boards, Colin will be assigning unique addresses to each one sold. For convenience, the MAC and other network settings will ultimately stored on the EEPROM.

The rigid setup above was enough to show that I could ping my PC from SAM, and have the echo reply read from the receive buffer. What we needed now was a proper IP stack to plug my driver into…

While I was working on the driver, Adrian Brown was busy porting Adam Dunkels’ uIP stack from C to Z80. He’s made quick work of it too, with ARP and ICMP already working well enough to ping from PC to SAM without the need for any of my cheating (ping times are typically 7-8ms). Once TCP is ready we’ll have enough for some real applications! Web server anyone?