Trinity Ethernet

After a break of a few of months, I’m almost back on the development wagon. I did the odd project tweak during that time but haven’t spent any quality time working on new features.

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 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?