Software

There are three main categories of software for the Spectranet; library code (i.e. the socket library and peripheral functions), utility code - things like a configuration user interface, and application code - some of which will be burned into ROM. Current plans call for the following:

Net code tutorial

A set of tutorials on writing networked programs for the Spectrum, using the Spectranet and its ROM-based socket library. The tutorials include code fragments, demonstrating how the socket library functions are used, as well as a piece of example code that goes along with each tutorial. Open the example code in another browser tab or window so you can see the socket library calls in context while reading the tutorial.

• Spectranet: Tutorial 1 - A look at network coding on the Spectrum.
• Spectranet: Tutorial 2 - Writing a simple TCP server program.
• Spectranet: Tutorial 3 - Writing a simple TCP client program.
• Spectranet: Tutorial 4 - Using UDP.
• Spectranet: Tutorial 5 - Avoiding blocking and handling multiple sockets at once.
• Spectranet: Tutorial 6 - Extending ZX BASIC.
• Spectranet: Tutorial 7 - Writing ROM modules.
• Spectranet: Tutorial 8 - Other useful network functions.

Programmer's Guide

The following topics cover subjects not directly related to the socket library. The Spectranet contains some useful hardware features, primarily intended to be used for network programs, but which are also useful for general use.

• Guidance to programmers - General advice on the best way to access the hardware.
• Using paged RAM - How to use the Spectranet's paged RAM
• Using flash memory - How to use the Spectranet's flash memory
• Trapping execution - How to use the programmable execution trapper

Library Reference

Assembly language programmers can use the file spectranet.inc in their projects to get a list of symbolic names for the addresses listed below. For the functions that are made available to the C library, headers are provided (sys/socket.h and netdb.h) containing the function prototypes.

The socket library

The most important part is probably the socket library. This will provide a subset of the BSD socket library. The plans are for three equivalent libraries: an assembler library, a C library based around the Z88DK, and a BASIC library. The C library will essentially be a wrapper around the assembler library (with a few extra pieces of error checking, which for asm users will be left up to the programmer).

The rationale for using the BSD socket interface (rather than just a simple wrapper around the W5100's TCP offload engine) is to provide an interface that's familiar to any programmer who has written net code, and also (importantly) to provide hardware independence. The BSD library has worked well for pretty much every network device that speaks TCP/IP, so I know if for some reason, a chip other than the W5100 needs to be used, or a different TCP/IP stack needs to be used, the software interface does not need to be changed - and therefore, code that people have slaved over to make the Spectranet useful won't need to be changed either.

The main functions that will be implemented for all languages are:

• socket (HLCALL 0x3E00) Creates a new socket.
• bind (HLCALL 0x3E0C) Binds a name to a socket (i.e. sets the port).
• listen (HLCALL 0x3E06) Tells an open socket that it should listen for incoming connections.
• accept (HLCALL 0x3E09) Accepts a connection that has arrived on a listening socket.
• connect (HLCALL 0x3E0F) Connects to a remote host.
• recv (HLCALL 0x3E15) Receives data from a socket (SOCK_STREAM)
• send (HLCALL 0x3E12) Sends data to a socket (SOCK_STREAM)
• recvfrom (IXCALL 0x3E1B) Receives a message from a socket.
• sendto (IXCALL 0x3E18) Sends a message to a socket.
• poll (HLCALL 0x3E1E) Checks for new data or a status change on an array of sockets.
• pollfd (HLCALL 0x3E24) Checks for new data or status change on a single socket.
• pollall (HLCALL 0x3E21) Checks for new data or status change on all open sockets.
• close (HLCALL 0x3E03) Closes a socket.
• gethostbyname (HLCALL 0x3E27) Looks up a host by DNS name.

Interface configuration

A number of functions are provided for configuring the interface. These are used by the after reset/power up routines, and the DHCP client. There are matching routines to get information on how the interface is configured (for example, to allow a program to find the IP address that the interface is set to use).

• sethwaddr, gethwaddr (IXCALL 0x3E51, HLCALL 0x3E54) Sets and reads the MAC address.
• ifconfig_inet, get_ifconfig_inet (IXCALL 0x3E48, HLCALL 0x3E6F) Configures the IP address.
• ifconfig_netmask, get_ifconfig_netmask (IXCALL 0x3E4B, HLCALL 0x3E72) Configures the netmask.
• ifconfig_gw, get_ifconfig_gw (IXCALL 0x3E43, HLCALL 0x3E75) Configures the default gateway.
• deconfig (HLCALL 0x3E57) Deconfigures all IP settings.

Filesystem programming

The following system calls provide access to filesystems and files via Spectranet filesystem modules. By default, at least the TNFS (Tiny Network Filesystem) is available. What's below details the "user mode" part of using filesystems (i.e. how to open, close, read, write files etc), if you are looking for information on how to make a new filesystem module (effectively "kernel mode"), then see Creating a filesystem

See the Filesystem tutorial for a couple of examples of filesystem use.

Gaining access to a filesystem

• mount - Mounts a filesystem for use
• umount - Releases a filesystem

Opening, reading and writing files

• open - Opens a file
• read - Reads from an open file
• write - Writes to an open file
• lseek - Seeks to a new position in a file
• vpoll - Polls a file for updates
• vclose - Closes an open file

Operations on directories and directory contents

• opendir - Opens a directory for reading
• readdir - Reads a directory entry
• closedir - Closes a directory
• unlink - Deletes a file from a directory
• mkdir - Creates a new directory
• rmdir - Removes an existing directory
• stat - Gets information on a file or directory
• chmod - Changes permissions on a file or directory
• chdir - Changes the current working directory
• getcwd - Gets the current working directory
• rename - Renames a file or directory

Note that not all filesystems support all operations; a filesystem written for +3DOS discs, for example, would not support chdir, mkdir, rmdir etc.

Memory management

There are two paging areas, area A at 0x1000-0x1FFF, and area B at 0x2000-0x2FFF. Any page from any part of Spectranet memory can be mapped into these areas.

• setpagea (IXCALL 0x3E33) Sets the 4k page in 0x1000-0x1FFF
• setpageb (IXCALL 0x3E36) Sets the 4k page in 0x2000-0x2FFF
• pagein Causes the Spectranet's memory to be mapped into the lower 16K
• pageout Causes the Spectranet's memory to be unmapped
• ixcall Causes a page in and jump to the address in IX, and automatic page out on return.
• hlcall Causes a page in and jump to the address in HL, and automatic page out on return.

Utility functions

A number of utility functions are provided that are useful for networked programs or for Spectranet ROM code.

• clear42 (HLCALL 0x3E30) Clears the screen and sets the print42 routine print position to the top left corner (0,0)
• putchar42 (HLCALL 0x3E2A) Prints a 42 column screen width character.
• print42 (IXCALL 0x3E2D) Prints a null terminated string using the 42 column print routine.
• inputstring (IXCALL 0x3E6C) Reads a string from the keyboard, echoing characters with the 42 character print routine.
• long2ipstring (IXCALL 0x3E39) Converts a 4 byte big endian number into a dotted decimal string.
• ipstring2long (IXCALL 0x3E3C) Converts a dotted decimal string into a 4 byte big endian number.
• mac2string (IXCALL 0x3E5A) Converts a 6 byte MAC address to a hex string.
• string2mac (IXCALL 0x3E3D) Converts a hex string to a 6 byte MAC address.
• rand16 (HLCALL 0x3E42) Generates a 16 bit pseudo random number.

Utility code

Certain utilities will be provided in the ROM. The most important one will be the one that allows the user to configure the device. This will provide a simple user interface for setting the IP address, netmask and gateway, and hardware address (if it needs changing from the one put in ROM on initial programming; unfortunately, joining the IEEE to get Ethernet addresses assigned to the project is prohibitively expensive).