Internet 4 migration

End of life of COMPAT_INET4 options

Background

When RISC OS 3.7 was released the operating system ROM included an updated version of the Internet module based on 4.4BSD Unix, rather than 4.3BSD Unix as used in the earlier Internet 4 shipped in the RISC OS 3.5 and 3.6 system ROM.

With this came some changes/extensions to the structure layouts used to communicate with functions in the Internet module. These additions aimed to:

• Make the functions extensible for larger (eg. IPv6) addresses in future
• Add fields to allow the expected layout to be deduced for forwards compatibility
• Make the functions safer to call by avoiding copying out results into an undersize buffer

The Internet module provides access to these functions via SoftWare Interrupts (SWIs) which other programs pass parameters to as needed. Even though 4.4BSD dropped support for all the old style calls, to help the transition at the time a parallel set of SWIs retained some compatibility with the older layouts, and a new set of SWIs were added in order to access the new features.

These SWIs are specific to RISC OS, which makes it difficult to build on top of software aimed at other operating systems, so Acorn provided a TCP/IP interface library (“TCPIPLibs”) which used all the familiar names and parameters that other operating systems used and then mapped these to RISC OS SWIs. Exactly which SWI was called (old or new) was based on an opt-in compiler switch COMPAT_INET4.

Why make this change?

Currently underway is an ambitious project to replace the network components with more up to date versions based on a successor version of FreeBSD. This will unlock support for WiFi connectivity and IPv6 addressing too.

In order to reduce complexity, and help any developers porting modern network utilities from other operating systems, the opportunity is being taken to make a course correction and unify the use of structure definitions on the 4.4BSD set. That means the library will no longer allow the COMPAT_INET4 opt-in to be selected.

It is also expected that a similar transition period will be needed in the future to support running RISC OS on AArch64 as that will, in effect, reorganise several of the structures once more to add longer 8 byte pointer addresses.

I’m a user, what do I need to do?

RISC OS 3.7 shipped with Internet 5.02 (24 Jun 1996), so provided you’re running RISC OS 3.7 or later you already have everything ready.

Any users still running RISC OS 3.6 or RISC OS 3.5 are advised to either:

• Make sure they use Acorn’s 1997 release of the universal !Boot application, which automatically loads Internet 5.04 during booting.
• Use any release of the universal !Boot application from RISC OS Open, this also automatically loads a newer set of modules during booting.
• Update the operating system ROM to RISC OS 3.7 or later. Contact your supplier to buy a new ROM and for details of how to fit it.

I’m a developer, what do I need to do?

What you should do depends on which tools your program is compiled with. Here we consider:

• SWIs emulated for backwards compatibility
• GCC SDK
• Desktop Development Environment
• BBC BASIC

SWIs emulated for backwards compatibility

For backwards compatibility the following set of 6 SWIs will be translated to the extent noted:

GCC SDK

Support for Internet 4 was removed in November 2006 for this tool chain, so provided you’ve recompiled your program since then there’s nothing to do.

Binaries built before this date work on Internet 4 in the RISC OS 3.5/3.6 system ROM, and also Internet 5, and also on the new TCP/IP stack provided it only uses the SWIs listed above which are provided for compatibility.

BBC BASIC

If you call the socket SWIs directly from BASIC then those socket SWIs listed above will continue to be available, albeit in their currently limited form. To access any new features you’ll need to change to use the Internet 5 style SWIs introduced with RISC OS 3.7.

In future, manipulating 128 bit quantities in BASIC is expected to be challenging given the constraints of the language, though not impossible!

Desktop Development Environment

The first thing to check is whether you use the opt-in at all? Check your Makefile to see which predefines there are:

If your project didn’t opt-in then there’s nothing to do, you’re already using Internet 5 style calls.

If you do find COMPAT_INET4 present there are a few steps to follow to migrate. They are limited in scope to just 4 header files you might have included and can be searched for with simple search patterns.

1. Delete the highlighted predefine -DCOMPAT_INET4 from the Makefile.
2. Review uses of the following 4 header files:

3. Change the libraries in the link step to link with Socklib5 (applications) Socklib5zm (modules) rather than Socklib/Socklibzm.
4. Update any RMEnsures in your application !Run file to ensure at least Internet 5.02 is found, and raise an error if not present.

From the above list of 4 header files, except for specialist use, by far the most commonly encountered change will relate to socket addresses (sockaddr and sockaddr_in) which adds a length member. Set the length member to sizeof(struct sockaddr) or sizeof(struct sockaddr_in) respectively; they are 16 bytes in size for IPv4 and 28 bytes for IPv6.

See how this example application was updated in practice by following the above steps.

In summary:

• A new TCPIPLibs will be made available. Software linked with this will require Internet 5 or later, and on machines loading the new TCP/IP stack it will in future also be able to talk IPv6
• If you build (or use software which was built) with current TCPIPLibs without defining COMPAT_INET4, this software already requires Internet 5, and will continue to function unchanged on the new TCP/IP stack (although your software wouldn’t be able to take advantage of IPv6 of course)
• If you build or use software which defined COMPAT_INET4 it will work on Internet 4 in the RISC OS 3.5/3.6 system ROM, and also Internet 5 whether in ROM or loaded during booting, and also on the new TCP/IP stack provided it only uses the set of SWIs listed above which are provided for compatibility.

In other words, in order to gain access in future to IPv6 extensions you will need to use the new TCPIPLibs, which won’t support the COMPAT_INET4 compile time switch, and therefore wouldn’t run using the Internet 4 module built into the RISC OS 3.5/3.6 system ROM. Software can support Internet 4 or IPv6, but not both.