Internet module

The Internet module has been updated in line with the previous extensions to the module. Whilst the changes have not been as wide ranging as in earlier versions of the operating system they extend the functionality to support certain specialist tools.

System recovery

The Internet module and the other networking components within the Operating System are able to recover in the face of the Internet module being restarted. Network components within the operating system have been updated to shut down gracefully when the Internet module dies and to attempt to reestablish themselves if it is restarted. This behaviour should be expected of all network components, but there is a long history of components which do not cope well with the stack being restarted. In particular, there is no mechanism for applications to be made aware of this.

Clients should pay attention to the Service_DCIProtocolStatus and Service_DCIDriverStatus service calls in order to cope with such situations.

Address collision

When an address collision is detected by the Internet module (two hosts using the same IP address within the same network) a new service, Service_InternetStatus 8 will be issued. This allows clients to recover by configuring an alternative address. If no measures are taken the Internet module will 'panic' and must be restarted to recover.

Socket pollwords

A new ioctl operation on sockets, FIOPOLLWORD, has been added to provide applications with the ability to set a pollword within shared workspace (for example the module area). This operation allows multitasking clients such as those using the Wimp to be polled when events occur on such sockets.

FIOPOLLWORD is defined as _IOW('f', 120, int[2]) which has a value of &80086678.

The data passed to FIOPOLLWORD consists of two 32bit values. The first of these is the pointer to the word aligned pollword to enable pollword usage, or 0 to disable pollword usage. The pollword should be in shared workspace such as the module area. The second value is a bit number to set within the word pointed to and should be a value between 0 and 31 inclusive.

Usually this would be used in the form :

     struct {long *pollword;
       int bit_number;
     } pwstruct;
     pwstruct.pollword = pollword_in_rma;
     pwstruct.bit_number = 0;
  if (ioctl(socket, FIOPOLLWORD, &pwstruct))
     {fault pollword operation, or fallback to simpler methods */

Aliased interfaces

From Internet 5.37, support for interface aliasing has been enhanced to allow for named aliased interfaces. The new interface naming scheme is compatible with that of earlier versions of the Internet module and it is unlikely that applications will fail to function with aliased names. Interface names are now given in the form :


Where <interface> is given by the device driver (such as 'ea'), <unit> is numbered from 0, describing the units provided by the device driver (most devices only supply a single unit). <alias> is a number from 0, describing the alias for an interface.

The primary address of an interface is described without an alias identifier. Reading non-Internet based information (such as hardware addresses) will ignore the alias number.

Internet module versions 5.37 to 5.43 allocate alias numbers dynamically, resulting in non-deterministic behaviour for clients wishing to create aliases for interfaces. That is, deleting the address associated with 'eh0:0' would cause 'eh0:1' to be renumbered to 'eh0:0'. From Internet 5.44 onward alias numbers are fixed at their creation and can be referred to directly - 'eh0:1' would remain as 'eh0:1' in the above example.

Aliased interfaces cannot be used for DHCP or BootP (only the primary address may be obtained through DHCP or BootP). The ioctl call to obtain interface details, SIOCGIFCONF, will return aliased interfaces as named above.

Aliased interfaces will not be matched within firewalling rules. Only the primary interface ('<interface><unit>') will be matched for these rules.

Clients should treat aliased interfaces as separated interfaces where this is appropriate. For example, where clients wish to broadcast to all connected networks, all interfaces including those which are aliased should be considered.

Datagram control information

Control information may be returned on packets using the 'IP_RECV' prefixed socket options with the recvmsg() system call. In versions of the Internet module prior to 5.54, the control information was not returned for broadcast or multicast datagrams. This information is now correctly returned for broadcast, multicast or unicast use.

Reception interface

In order to support certain multi-homed clients, it is now possible to read the interface on which a datagram was received. This option is known as 'IP_RECVIF' and takes the socket option 20 (see TCPIPLibs:sys.h.netinet). This is similar to the other 'IP_RECV' prefixed options in that it provides an additional field in the options for the packet based on the packet's reception.

Typical usage to enable the use of the data with a socket is :

paramint = 1;
   err = setsockopt(sock, IPPROTO_IP, IP_RECVIF, &paramint, sizeof(paramint));

The details of the packet can be received through the message control data received with readmsg. Typically this might be read thus :

    struct msghdr   msg;
       struct iovec    iov[1];
       int readlen;
       struct cmsghdr  *cmptr;
       static union {cmsghdr cm;
         char              control[1024];
       } control_un;
    msg.msg_control = control_un.control;
       msg.msg_controllen = sizeof(control_un.control);
       msg.msg_flags = 0;
    msg.msg_name = (caddr_t)&saddr;
       msg.msg_namelen = sizeof(saddr);
       iov[0].iov_base = packetdata;
       iov[0].iov_len = sizeof(packetdata);
       msg.msg_iov = iov;
       msg.msg_iovlen = 1;
    readlen = recvmsg(sock, &msg, 0);
       if (readlen < 0)
         return FAILURE;
    if (msg.msg_controllen > 0 &&
           (msg.msg_controllen < sizeof(struct cmsghdr) ||
            (msg.msg_flags & MSG_CTRUNC)))
       {the control data was corrupted so ignore */
       {(msg.msg_controllen > 0)
         {(cmptr = CMSG_FIRSTHDR(&msg);
                cmptr != NULL;
                cmptr = CMSG_NXTHDR(&msg, cmptr))
           {(cmptr->cmsg_level == IPPROTO_IP)
             {(cmptr->cmsg_type) {
                 case IP_RECVIF:
                   {sockaddr_dl *sdl = (struct sockaddr_dl *) CMSG_DATA(cmptr);
                     ifindex = sdl->sdl_index;
                     /* Deal with interface appropriately */
Multicast filtering

Network drivers supporting the multicast filtering specified in DCI 4.04 are now supported by the Internet module. This should ensure that, where hardware filtering is supported, the system load is reduced by ignoring packets which are destined for groups which we are not members of. As with all multicast filtering implementations the system is based on a hash of the destination address and thus cannot filter all traffic. Consult the DCI functional specification for more details (restricted availability).

Multicast use

Under versions of the Internet module prior to 5.55 it was necessary to configure a default route in order to use multicast, either for reception or transmission. Where an interface is specified, the packets will now be sent directly regardless of the configuration of routing.

Improved standard compliance

Various improvements have been made to the Internet module to better comply to the standards for internet hosts. In particular the following changes have been made

  • Addresses within 127/8 will no longer be sent on external interfaces, and will be ignored on reception.
  • ICMP 'unreachable port' and ICMP 'unreachable protocol' are now reported as hard errors which will abort TCP connections, rather than soft errors which would merely cause a retry.
  • ICMP 'time exceeded' is now reported as a soft error, similar to the 'unreachable host', rather than being ignored.
  • Configuration of interfaces with addresses 0.0.0.x or 255.255.255.x is no longer accepted.
Internet module packet filtering

The Internet module provides an interface for packet filtering, allowing clients to capture packets on entry and before output. This can be used for a number of purposes, ranging from auditing through diagnostic logging, to address translation. See the InternetFiltering document for more details.

UpCall behaviour (FIOSLEEPTW)

Under versions of the Internet module prior to 5.63 the ioclt control FIOSLEEPTW would only be effective within a TaskWindow environment. This placed an undue reliance on the TaskWindow module. The restriction has been removed from the module. Where FIOSLEEPTW is enabled, OS_UpCall 6 will be issued whether the component is running under a TaskWindow or not. This should allow alternate implementations and similar sleep operations to be performed.

MBuf Scavenging

In order to cope more gracefully with MBuf exhaustion the Internet module now responds appropriately to a 'scavenge' request from the MBufManager. When MBufManager discovers that not enough space remains to perform an allocation it will request that clients obtain more space through the Service_MBufManagerStatus 'scavenge' (reason code 2). The Internet module responds to this by freeing buffered MBufs from the protocol-specific buffers. This means that IP fragment reconstruction buffers will be released back to the MBufManager such that it may continue its allocation.

Single chains of IP fragments will be released for each scavenge request, starting from the oldest. This should ensure that during large network activity and prolonged periods with interrupts disabled it should be possible to receive packets and continue reconstruction of the most recent data. Scavenge requests should only be common when the network speed exceeds the system's ability to process data, or where packets are generated more rapidly than the network can transmit them.

This documentation is copyright 3QD Developments Ltd 2013 and may not be reproduced or published in any form without the copyright holders permission. RISC OS is subject to continuous development and improvement as such all information is reproduced by 3QD Developments Ltd in good faith and is believed to be correct at the time of publication E&OE. 3QD Developments Ltd cannot accept any liability for any loss or damage arising from the use of any information provided as part of the RISC OS Documentation.

HTML document version 1.03 3rd November 2015