RISCOS.com

www.riscos.com Technical Support:
Programmer's Reference Manual

 

AUN


Introduction

The AUN software that this chapter describes forms the core component of Acorn's new networking strategy, called Acorn Universal Networking (AUN). AUN uses an industry standard method of passing data over a network: a family of protocols called TCP/IP.

AUN uses the TCP/IP standard in such a way as to retain Econet's existing program interfaces, so your existing network programs should continue to work. Furthermore, AUN's use of the TCP/IP standard supports the concept of Open Systems. Acorn machines - such as Level 4 FileServers - can now co-exist on the same network as other machines that use TCP/IP - such as UNIX workstations and NFS file servers. You can follow this path by using AUN in conjunction with its sister product, the TCP/IP Protocol Suite; this is described in an application note, available from Acorn Customer Services.

AUN has been designed with an eye to the future, to preserve users' investment as long as possible. In particular, it has been designed so that as new and faster networking technologies become available, developers can easily add support for them by replacing a single hardware-specific module.

For details on using existing Econet networks and AUN networks, refer to the guides supplied with your computer, such as the RISC OS User Guide. For details on installing and managing an AUN network, see the AUN Manager's Guide.

You should note that networking modules are only loaded if the computer has a network interface fitted.

The rest of this chapter will refer to an example network; this is shown below.

Overview

AUN concepts

The basic structure of an AUN site network is one of physically distinct networks, typically associated by location and function with a particular room, department or curriculum area. Adjacent networks are interlinked via gateway stations (described below), which pass messages between the two networks.

Networks

A network is a physical network of a single type (e.g. Ethernet, Econet). A network is delimited by any gateway stations used to connect it to other networks. For more information on gateway stations, see the section below entitled Stations.

Network names

Each network must have a unique name. Network names are not seen or handled by users; they are only used to configure the AUN software for a site.

Nets

A net is a part of a network that appears to the user as a single entity.

In both Econet and Ethernet, individual segments of a physical network can be linked together by a bridge. However, there is a difference between the two:

  • Two bridged Econets remain distinct from each other, and so constitute two distinct nets. Hence in an Econet based network there may be several nets: the initial net, and an extra net for every bridge added.

. The compsciA network is made up from nets 1, 2 and 3, which are three Econet segments connected by a bridge.

  • Two bridged Ethernets appears to users to be a single Ethernet, and so constitute a single net. Hence in an Ethernet based network there will always be one net; in other words, the net and the network are one and the same thing.

Net 131. The science network and net 129 are identical, and consist of the same two bridged Ethernet segments.

It is important that you grasp the distinction between a net and a network; this chapter will rigorously distinguish between the two.

Net numbers

Each net must have a unique number.

For an Econet the net number must be between 1 and 127.

  • If the net is a part of a larger Econet network linked together by bridges, its net number will already be set in the bridge, and the network manager should use the same net number for AUN.
  • If the net is not connected to any other Econets (i.e. there aren't any bridges on the net) it will not have a net number assigned to it; under native Econet it will just use the default net number of 0. However, for AUN the network manager must assign it an otherwise unused AUN net number in the permitted range 1 - 127.

For types of net other than Econet (e.g. Ethernet) the net number must be in the range 128 - 252. If such a net is the only net on the site (i.e. the whole AUN network consists of a single non-Econet net, such as Ethernet), the network administrator need not set up a net number. It will use net number 128 by default, but - since it is the local net for all stations - users can also refer to it as net 0, in line with Econet convention.

Net numbers 0, 253, 254 and 255 are reserved.

Stations

A station is a computer connected to a net. There are two types of AUN stations.

Client stations

A client station has a single AUN-configured network interface with which it is connected to a net.

Client stations will form the vast majority of stations in each net, and are typically used as personal workstations.

Gateway stations

A gateway station has two AUN-configured network interfaces with which it is connected to a net in each adjacent AUN network. It relays messages between these two networks via the interfaces. The networks may be of different physical types (e.g. Ethernet and Econet). There may only be a single gateway between any two networks.

Station numbers

Each station must have a number, which must be between 2 and 254. Station numbers 0, 1 and 255 are reserved.

A station number must be unique on the net(s) to which the station is connected.

A gateway will have the same station number on both connected nets:

A gateway station's number must therefore be unused by any other station on either net.

Technical details

Protocols

AUN uses the UDP, IP, ARP, RevARP and RIP protocols from the TCP/IP family:

  • The transport protocol is User Datagram Protocol (UDP), enhanced by a proprietary handshake mechanism designed to support the semantics of Econet SWI calls. This is not a straightforward port of the four-way handshake mechanism used by native Econet, but is rather a two-way handshake protocol overlaid with a timeout and retransmission mechanism better suited to the characteristics of IP traffic.

TCP itself is not used, as it is a stream oriented protocol unsuited to supporting an Econet-like data delivery service.

  • The network protocol is Internet Protocol (IP).
  • Address Resolution Protocol (ARP) is used to map IP addresses into physical network addresses.
  • Reverse Address Resolution Protocol (RevARP) is used by client stations to request their own IP addresses from gateway stations.
  • Routing Information Protocol (RIP) is used to pass routing table information between stations.

Software

The AUN software consists of several closely related modules:

  • The Net module implements the two-way acknowledgement handshake, and presents an Econet-like service to applications via Econet SWI calls. It also implements the RIP function.
  • The Internet module implements UDP, IP, ARP and RevARP protocols, and exports an industry standard (Berkeley socket) interface to other RISC OS software such as the TCP/IP Protocol Suite.
  • The device driver module provides a Driver Control Interface (or DCI) that enables the AUN software to communicate with a particular network interface. Each type of network interface needs its own device driver. There are no device drivers supplied in RISC OS 3.5; they are instead normally supplied with network interfaces, either in ROM or on disc.
  • The MbufManager module provides memory management facilities for version 4 onwards of the DCI, and is used by protocol stacks and device drivers. (It was previously an internal part of the Internet module, and so was not potentially accessible to other protocol modules.)
The software in detail

The following diagram illustrates the relationship between the modules in AUN:

There is a particularly close connection between the Net module and the Econet module. The Net module learns which nets may be accessed via a directly connected Econet, and which nets need to be accessed via IP (ie nets that do not use Econet, or nets using Econet that can only be reached via a gateway). The Net module intercepts SWI calls to Econet from higher-level applications such as NetFS, NetPrint and Broadcast Loader, and - by examining the destination net number - determines whether to route the calls to the Econet module for traffic over native Econet, or to the Internet module for traffic over IP.

If the AUN station does not have an Econet interface fitted then the Econet software module will not be present, and so all traffic will be via the Internet module and IP protocol.

The Internet socket interface - used by the Net module in AUN - remains exposed for parallel use by other applications. Hence other protocols running over IP, such as NFS, can run at the same time as AUN. For more details of the Internet socket interface, see The Internet module.

Since device drivers are not a part of RISC OS itself, we don't document the DCI in this manual. (This also applies to the MbufManager module, which is anyway a conceptual part of the DCI). Both the DCI and the MbufManager module are subject to change as the range of Acorn networking products is expanded and updated. Should you wish to program using the DCI (say to implement a new network interface), you should contact Acorn Customer Services.

Addresses in Econet and AUN

Under native Econet, users and programs uniquely identify each station with two one-byte numbers, thus:

net.station

Under AUN, users and programs use exactly the same scheme, to preserve compatibility with native Econet. However, the underlying Internet protocols used by AUN use four-byte numbers to identify stations. The AUN software therefore needs to translate each two-byte address passed by a user or program into a four-byte IP address. The AUN interpretation of each of the four bytes is:

site.network.net.station

The bottom two bytes (net.station) are the same two bytes as are seen by users and programs. The network byte is used to provide additional routing information to the underlying IP software only, so that it can route data to the correct destination network. The site byte is currently unused and always has a value of one.

Technically speaking, an AUN IP address is a Class A IP address, with a netmask of &FFFF0000.

For example, the AUN interpretation of a command - in the normal IP emphasis - to:

'send data to host 1.3.129.16'

is actually:

'send data to station 129.16... (which is located in network number 3)'

or, more meaningfully:

'send data to station 129.16... (which is located in the science network)'.

The difference between the addressing used by native Econet and the IP address used by AUN is summarised by the table below:

Network Bytes Form Examples
Native Econet address 2 net.station 3.2
8.103
129.12
AUN IP address 4 1.network.net.station 1.1.3.2
1.4.8.103
1.3.129.12

AUN IP address configuration

How a gateway station finds its full IP address

When a gateway station starts up, it reads its station number from CMOS RAM. (This number is set by the SetStation command supplied with the AUN software.)

To find the site, network and net numbers of both its interfaces, the gateway station looks at its AUN Map file and Configure file.

The Map file

The Map file tells the gateway station the IP address of each net on the site. As an example, let's look at the Map file for the site illustrated on Net 131:

| Example: Large site network containing 5 dept networks linked via backbone
compsciA        1 2 3                   | old compblock econet
compsciB        128                     | compblock Ethernet
science         129                     | science Ethernet
art             4                       | art room econet
business        130                     | business studies ethernet
backbone        131                     | backbone ethernet

The gateway station converts each network name to a network number in the order they're read; the first network has the number 1, the second is number 2, and so on. Adding in the net numbers to the example above, the following full IP addresses apply to the example network. (The site number defaults to 1, and the station field is read by each individual station from its configured value in CMOS RAM):

Network name Network number Net
number

Returned
IP address
compsciA 1 1
2
3
1.1.1.station
1.1.2.station
1.1.3.station
compsciB 2 128 1.2.128.station
science 3 129 1.3.129.station
art 4 4 1.4.4.station
business 5 130 1.5.130.station
backbone 6 131 1.6.131.station
The Configure file

The Configure file tells the gateway station its own position in the site: specifically, which network is connected to which interface. For example:

| Example1:
|       network compsciA is Econet;
|       network backbone is Ethernet.
Econet          is compsciA
Slot 0          is backbone

This tells the gateway that its Econet interface is connected to the compsciA network, and its Ethernet interface (in slot 0) is connected to the backbone network. What it does not tell the gateway is whether the Econet interface is connected to net 1, 2 or 3. The gateway station resolves this by reading the correct net number (in this case 2) from an Econet bridge on its own net. Thus, if the station number were 7, the two interfaces' IP addresses would be:

1.1.2.7 for the Econet interface
1.6.131.7 for the Ethernet interface

Note that an Ethernet network must always consist of a single net, and so the gateway does not have to resolve the same ambiguities as for Econet.

How a client station finds its full IP address

Like a gateway station, an AUN client station reads its station number from CMOS RAM at start-up time.

However, at this stage it does not know its site, network and net numbers; instead, it finds these out from a gateway station connected to its local network.

To do so the client station broadcasts a RevARP message requesting its IP address. The gateway receives this broadcast on the interface that is connected to the client's network, and returns that interface's IP address, first setting the station number to zero:

site.network.net.0

Because the gateway station's interface and the client station are on the same network, the returned site and network numbers are therefore the same as those of the client station. The net numbers will also be the same, unless the client station and the gateway station are on different nets within the same network (which can only be the case if they are separated by Econet bridges).

The client station takes the returned address and substitutes its own station number. It also determines if it is connected to a bridged Econet; if so, it replaces the returned net number - which may be incorrect - with the correct net number, read from an Econet bridge on its own net.

Default addresses

If a client station does not get a response to its request for its full IP address, this means that no gateway computer is present and so the local network is isolated. This being the case, then:

  • If the station is connected to an Econet it will use native Econet rather than the Internet protocols used by AUN.
  • If the station is connected to any other network it adopts a default IP address of 1.0.128.station, giving a user address of 128.station.

When/if a gateway computer subsequently comes 'on-line' it will immediately send a message to the other stations on the previously isolated network, so they may then complete their address and routing configuration, and get access to all other networks in the AUN system.

Consequently while a network is isolated all its stations may communicate between themselves; stations don't 'hang' awaiting a response from a gateway. You may later start up a gateway station to bring the isolated network into your site's AUN network. However, since this is likely to change 'on the fly' all the addresses of that network's stations, you must take care only to do this when there are no users active on the network.

Application program interface

The application program interface, or API, is the same as the RISC OS 3 (version 3.10) Econet SWI interface, with certain usage qualifications described below. For full details, refer to the RISC OS 3 Programmer's Reference Manual.

Existing user applications which access Econet do not require functional modification at the network interface in order to run over an AUN network.

The AUN module intercepts SWI calls to Econet from user software. It treats the calls differently according to how it can access the destination station:

  • If the destination station can be accessed directly via Econet, AUN passes the SWI calls to the resident Econet handler. This avoids unnecessary IP protocol overheads for a localised Econet-only transaction.
  • Otherwise the destination station must be accessed via IP. AUN maps the SWI calls into calls to the Internet module, having first expanded the two-byte net.station destination address into a four-byte site.network.net.station IP address.

The maximum amount of data which can be passed in a single transmission SWI via IP is 8192 bytes.

When transmitting to a station via IP, transmission SWI calls will return only the error values Status_NetError and Status_NotListening in the event of failure. Over raw Econet other Econet-specific error values may be returned.

Constraints on the use of Econet SWI calls over AUN
Immediate operations

In general the Immediate mechanism is considered to be Econet specific. The only Immediate operation supported by AUN over IP is Econet_MachinePeek. All other Immediate SWI calls return Status_NotListening, unless the destination station is accessible via a directly connected Econet.

Transmission strategy

An application's choice of values for the Count and Delay parameters it passes to transmission SWIs may make assumptions about the actual physical characteristics of Econet. For example some Econet utility programs set the Count to 0 in Immediate operations, relying on the fact that the return of a scout acknowledge frame in response to a valid scout frame will always be effectively instantaneous. However, over an AUN IP network this assumption is invalid; the functional equivalent of the scout acknowledge may arrive 'sometime', or even 'never'.

Consequently AUN uses a retransmission strategy more suitable to the nature of IP traffic, whilst retaining the existing retransmission strategy for transmissions to a directly connected Econet. The retransmission strategy for AUN over IP is as follows:

For ordinary data, AUN employs a two-way handshake. A receiving station will return a positive acknowledgement if it has successfully received a data frame into an open receive block, or else a reject message if there is currently no open receive block, or some other detectable reception error has occurred.

If count > 1
The maximum elapsed timeout period in seconds (T) requested by the application is computed as:
T = (Count × Delay) / 100
On receipt of reject messages, the sender will retransmit the data frame 10 times after 1 centisecond timeouts, then:
If T < 5
T × 10 retransmissions will occur, each after 10 centisecond timeouts;
Else
If the destination station is not on the same network as the sender
exactly 50 retransmissions will occur, each after (T × 100) / 50 centisecond timeouts;
Else
If the retry delay < 25 centiseconds
exactly 50 retransmissions will occur;
Else
(T × 4) retransmissions will occur, each after a 25 centisecond timeout.
(This provides some optimisation for simultaneous loading of software from a local file serer, whilst protecting against excessive overload at gateway stations caused by rapid retransmission).
If no response is received at all then:
If T < 5
1 retransmission will occur, after a 5 second timeout;
Else
T / 5 retransmissions will occur, each after 5 second timeouts.
Else
The sender will transmit exactly once. The transmission status will not chance until a positive acknowledgement or a reject message has been received, or a 5 second timeout has elapsed.

For an Immediate operation (i.e. Econet_MachinePeek), a SWI call with Count = 0 or Count = 1 always results in a Status_NotListening return; no actual network transmission is made. In other cases the sender transmits an Immediate message exactly once, changing transmission status only when a response has been received or a 5 second timeout has elapsed.

Bridge protocol

Use of the Econet Bridge protocol by a RISC OS net utility program to identify valid net numbers does not work over non-Econet networks within an AUN system, as no actual Econet bridges are present to respond. However, cycling through the range of net numbers in a sequence of calls to Econet_ReadTransportType can provide this information without involving any network transactions; the call returns R2 = 0 if the given net number is not currently accessible from the local station.

Note that this constraint does not affect use of the Bridge protocol onto a directly connected Econet system.

Meaning of net 0

In AUN, a station may be connected to both an Econet and an Ethernet at the same time. This means that the assumption that Net 0 means the local network is no longer safe, as the AUN software could not, in this case, distinguish the two connected networks with certainty. Hence applications running over AUN should strive to supply an actual net number with every transmission SWI call.

You should note that the actual net number of a connected Econet may in fact be 0, if there are no bridges present; however the net number of an Ethernet in a correctly configured AUN network can never be 0, so no clash will occur. If a net number of 0 is supplied to a transmission SWI, AUN maps it to the net number of a directly connected net, with Econet taking priority over Ethernet if both are connected.

Local broadcasts

If a station is connected to both Econet and Ethernet, transmit SWI requests for a local broadcast - as issued by Broadcast Loader- are directed to the Econet only.

Data delivery

As with Econet, AUN over IP cannot guarantee that a message apparently correctly received and acknowledged by a receiving station will not be retransmitted if the acknowledgement is lost in transit. Applications using AUN should therefore ensure that they can detect whether a transmission has been repeated. This is usually done by adding a sequence number or bit to transmissions.

* Commands


*Configure BootNet

Sets the configured state for whether or not the AUN software is loaded

Syntax

*Configure BootNet On|Off

Use

*Configure BootNet sets the configured state for whether or not the AUN software is to be loaded from RISC OS 3.5. Drivers are always loaded from a network interface, irrespective of this configured setting.

You should configure this value to 'On' if the station is to be a client station using an AUN-configured network, and to 'Off' otherwise (i.e. if the station is to be a gateway station, or to be connected to a TCP/IP-configured network).

The default state is 'Off'.

Example

*Configure BootNet On

Related commands

None


*DeviceInfo

Displays driver module internal statistics

Syntax

*EBInfo

Use

A *DeviceInfo command displays detailed information about driver module activity. Note that this command is supplied by the driver that comes with a network interface, rather than by RISC OS. Each of the standard Acorn drivers provides such a command:

Command driver for:
*EcInfo Acorn Econet
*EbInfo Acorn Ethernet

We expect third party drivers to provide a corresponding command; you should see the documentation supplied for the command name.

It is presented mainly as an aid to trouble-shooting, should you require it.

Example

*EBInfo
EtherB interface statistics
eb0: 80C04 Network slot, enabled, hardware address 00:00:A4:10:17:00
packets received = 27735              packets transmitted = 2391
bytes received = 2040394              bytes transmitted = 392460
receive interrupts = 27279            transmit interrupts = 2390
Standard clients:
Frame = &0800, ErrLvl=00, AddrLvl=01, FrmLvl=00
Frame = &0806, ErrLvl=00, AddrLvl=01, FrmLvl=00
Frame = &0835, ErrLvl=00, AddrLvl=01, FrmLvl=00
Log:EtherB messages can appear here

Related commands

None


*NetMap

Displays the current AUN map table

Syntax

*NetMap [net_number]

Use

*NetMap displays the current AUN map table either for the specified net, or for all nets if no parameter is specified. The map table shows the net number of each net, its name, and its Internet address.

Each station obtains the information held in the map table from a gateway's Map file. Since this file is identical for all gateways on a correctly set up network, the output from this command is the same for all stations, and only varies when the network's layout is altered.

Examples

*NetMap 129
129     science         1.3.129.x

*NetMap
1       compsciA        1.1.1.x
2       compsciA        1.1.2.x
3       compsciA        1.1.3.x
128     compsciB        1.2.128.x
129     science         1.3.129.x
4       art             1.4.4.x
130     business        1.5.130.x
131     backbone        1.6.131.x

Related commands

*Networks


*NetProbe

Reports if a remote station is accessible and active

Syntax

*NetProbe net_number.station_number

Parameters

net_number - remote station's net number

station_number - remote station's station number

Use

*NetProbe reports if a remote station is accessible and active, and hence can be reached from the local station and network. This command does so by sending a control message to the specified station and awaiting a reply.

Examples

*NetProbe 128.135
Station present

*NetProbe 128.201
Station not present

Related commands

None


*NetStat

Displays the current status of any network interface(s) configured for AUN

Syntax

*NetStat [-a]

Parameters

-a - give all information, rather than simplified version

Use

*NetStat displays the current status of any network interface(s) configured for AUN. The optional parameter -a gives extra information, including traffic counters and full IP addresses. Known network numbers which are marked with an asterisk ('*') represent nets in a directly connected Econet network.

Example

*NetStat -a
Native Econet     0.5                                             information for native Econet
Interface         Econet?                                         information for first AUN interface
AUN Station       4.5
Full address      1.4.4.5
Interface         EtherB                                          information for second AUN interface
AUN Station       131.5
Full address      1.6.131.5
Known nets        1     2     3    *4     128   129   130
                  131
                                                                  information below only given if optional parameter a supplied
TX stats          Data=0, Immediate=2, Imm_Reply=0, Retry=0
                  Error=20, Data_Ack=5, Data_Rej=0, Broadcast=10
                  (local=0, global=5)
RX stats          Data=5, Immediate=0, Broadcast=0, Discard=0
                  Retry=0, Error=0, Data_Ack=0, Data_Rej=0
                  Imm_Reply=2, Reply_Rej=0
Module status     0140

Related commands

None


*NetTraceOff

Turns off a gateway's tracing of routing protocol messages

Syntax

*NetTraceOff

Use

*NetTraceOff turns off a gateway's generation of trace information about its transmission and reception of routing protocol messages. For more details, see the description of the *NetTraceOn command.

This command is provided by the gateway variant of the AUN module, and is hence only available on gateway stations. It is anyway irrelevant to client stations.

Example

*NetTraceOff

Related commands

*NetTraceOn


*NetTraceOn

Turns on a gateway's tracing of routing protocol messages

Syntax

*NetTraceOn [filename]

Parameters

filename - name of file to which to direct output

Use

*NetTraceOn turns on a gateway's generation of trace information about its transmission and reception of routing protocol messages. This information is stored in the given file, or - if none is specified - in the file !Gateway.Trace. You can load the trace file into a text editor such as Edit in the usual way.

To view the default file you will need to open the Gateway application directory; hold down the Shift key while you double-click on its icon.

This command is provided by the gateway variant of the AUN module, and is hence only available on gateway stations. It is anyway irrelevant to client stations.

Example

*NetTraceOn

Example output

Fri Mar 27 16:26:06:  ==> 131.123
    compsciB        local
    backbone        local
Fri Mar 27 16:26:17:  ==> 131.5
    compsciB        local
    backbone        local
Fri Mar 27 16:27:31:  ==> 131.150
    compsciB        local
    art             gateway=1
    backbone        local

Related commands

*NetTraceOff


*Networks

Displays the current AUN routing table

Syntax

*Networks

Use

*Networks displays the current AUN routing table. This shows the names of any local networks (i.e. those to which the station is directly connected). It also shows the names of those remote networks that the station knows how to reach, and the gateway that it will use to do so.

The AUN routing table alters as gateways start up and shut down, and so the information returned by this command varies as the state of the network alters.

Examples

*Networks                      a client on the 'backbone' net
art             gateway=131.5  connected to the 'art' net by
backbone        local          gateway 131.5

*Networks                      a gateway between the 'art'
art             local          net and the 'backbone' net
backbone        local          (i.e. station 131.5 above)

Related commands

*NetMap


*SetStation

Sets a station's number

Syntax

*SetStation [station_number]

Parameters

station_number - a station number in the range 2 - 254

Use

*SetStation sets a station's number, storing it in CMOS RAM so it is not lost when the computer is switched off. If no number is specified then one is prompted for. If the new station number given is invalid, then the current station number is preserved.

This command is not a part of the standard AUN software, to prevent users from altering station numbers. It is instead supplied as a separate program on the Support disc of the AUN/Level 4 FileServer distribution, in the ArthurLib directory. You can run this program from the desktop by double-clicking on its icon; a window shows the prompt for the station number.

The number is stored in the same location as is used by Econet to store station numbers. If the station is connected to both an AUN network and a native Econet, it will accordingly use the same station number for both types of network. Altering the station number for one network will alter it for the other.

You can find out a station's current station number by typing at a command line:

*Help Station - if Econet is fitted

or:

*NetStat - if AUN is installed

Examples

*SetStation 20

*SetStation
New station number: 20

Related commands

*Help Station

This edition Copyright © 3QD Developments Ltd 2015
Last Edit: Tue,03 Nov 2015