Roadshow TCP/IP stack notes (2017-04-28) ======================================== 1. The demonstration version and the commercial release ------------------------------------------------------- Roadshow is a commercial product which can be bought online or on CD-R from "http://www.apc-tcp.de". Support is available at "http://roadshow.apc-tcp.de". A free demonstration version as well as the free software development kit (SDK) are available on the same web site. The demonstration version is almost identical to the commercial version, but there is one important difference: the demonstration version will run only for a short period of time after which it stops. Once stopped, it will remain in memory, which means that you may have to restart your Amiga in order to give Roadshow another try. Because it remains in memory, it also means that you cannot easily shut it down and start a different TCP/IP stack. Sorry! This is not how it should work, but a different way to make the demonstration version work has not yet made itself obvious :-( For information on how to make the TCP/IP stack work again which you used before, after you have given Roadshow a try, please see section 7 of these notes (at the end of this document). 2. Preparations for installing Roadshow --------------------------------------- Before you begin you might want to dip into the documentation provided in the "Documents" drawer. Specifically, the file "Documents/Installation.guide" should be useful when you are setting up your network for the first time. Printable versions of the documentation are available in the "Documents/Printable" drawer. The files in this drawer are in PDF format, suitable for printing through tools such as APDF or any other program which can process and output this document format. Note that the big Roadshow documentation is more than 100 pages in size and may be best used for reference. 3. The installation script -------------------------- Note that if you want to try Roadshow on MorphOS, then the installation script may not work for you. Sorry, this is how it is at the moment, and I do not have any good idea on how to fix this. You can, however, install the single components of Roadshow manually by copying the contents of the "Workbench" drawer to your system partition. Careful: do not copy the "Workbench/S/User-Startup" file! You might want to add the contents of the "Workbench/S/User-Startup" to your "S:User-Startup" file. To begin the installation, double-click on the "Install_Roadshow" icon. The installation script gives you a choice to run in "advanced" or "expert" mode. Picking "expert" allows for a few more choices to be made than the "advanced" mode. For example, in "expert" mode you will always be asked if you want to install a special version of the software, optimized for Amigas with MC68020 CPUs (or better), regardless of whether your current Amiga computer supports this (note: only the commercial version includes these specially optimized versions of the software). Note that if the installation script detects that Roadshow may be already installed, it will ask you if you want to uninstall Roadshow first. The installation script can run in "pretend mode", meaning that if you choose not install for real, then a log of all installation operations will be generated instead, for you to review. Lastly, the installation script can be rerun after you have installed the software and will give you two new choices: 1) you can choose to uninstall the Roadshow software previously installed, and 2) you can have it make backup copies of your current Roadshow configuration files. 4. Installing Roadshow under Amiga operating system version 2 ------------------------------------------------------------- The minimum installation requirements for Roadshow are an Amiga with operating system version 2.04 and 2 MBytes of main memory. But the tools provided for reading the documentation may actually require operating system version 3.0 to work out properly. This means that you may have to use your preferred document reader or text editor to open and review the documentation before you can install Roadshow on your system. The installation procedure for Amiga operating system version 2 should be identical to the procedure used for Amiga operating system version 3 and beyond, though. If need be, you can also install Roadshow manually by copying the necessary files to your system partition. 5. The software development kit ------------------------------- The software development kit (not included with the demonstration version: visit the web site to download it) is provided in the "SDK" drawer, which does not have an icon to double-click on. This drawer contains documentation, source code, examples and other files helpful and/or required if you want to create new software for Roadshow. 6. Creating a stripped-down installation floppy disk ---------------------------------------------------- You might want to create a stripped-down version of the installation disk, for use with installing the TCP/IP stack from a single floppy disk. Here is what you can do: - You need to retain the contents of the "Workbench" drawer, the "Installer" program and the "Install_Roadshow" installation script. - From the "Workbench" drawer, you will need to remove a few files which are not strictly essential to the operation of the TCP/IP stack and the installation script. - The following shell commands can be removed to save space: Workbench/C/ftp Workbench/C/tcpdump Workbench/C/wget - If you do not need the PPP/PPPoE drivers to be installed, the following drawers can be removed: Workbench/Devs/Networks Workbench/S/PPP-Configurations And you can also remove the following shell commands: Workbench/C/ppp_dialer Workbench/C/ppp_connector Workbench/C/ppp_sample - If you know that you are not going to need the special MC68020-optimized version of bsdsocket.library, then you can remove the following drawer and its content: Workbench/Libs/020 Alternatively, if you know that the special MC68020-optimized version is what you need, you can replace the plain MC68000/MC68010 version with the MC68020-optimized version and then delete the plain version: Copy Workbench/Libs/020/bsdsocket.library Workbench/Libs Delete Workbench/Libs/020 ALL QUIET Note that you can, of course, always copy the relevant files manually back to your system partition later. It's just that the installation script will adapt to the missing data and proceed safely if you take care in removing the files and drawers described above. Removing all of the files and drawers described above should make enough room for the remaining installation files to fit onto a single 880K floppy disk. 7. Going back to Miami/AmiTCP/etc. after you have tried Roadshow ---------------------------------------------------------------- Should you find that Roadshow does not compare well to the TCP/IP stack you were using before, and you need to return it, please note that you must uninstall Roadshow first. Otherwise, the TCP/IP stack you were using before will probably not run correctly any more. This is because the Roadshow installation script places the file "bsdsocket.library" in your LIBS: folder, and this prevents other TCP/IP stacks such as "Miami" or "AmiTCP" from working correctly. So, in order to make "Miami" or "AmiTCP" work again, you should either rerun the Roadshow installation script (which includes an option to remove the files it installed before), or delete the file "LIBS:bsdsocket.library" manually instead. 8. Changes ---------- Roadshow 1.13 (24.4.2017) - Tomasz Potrykus provided Polish localization files for Roadshow, "bsdsocket.library", "usergroup.library", "ppp-ethernet.device" and "ppp-serial.device". Thank you very much! - The "ping" command sports a new switch which controls how many packets should be sent ("-c"). This parameter now also implies a test to see for how many packets sent there were matching responses. If fewer responses were received than there were packet sent, "ping" will now exit with return code 5, which can be tested for in shell scripts with "if warn .. endif". Further switches have been added which control how long packets should be sent before the program exits ("-t" and "-o"). - Fixed several bugs in "bsdsocket.library", the "SampleNetSpeed" and "ppp_sample" programs all related to the same problem: combining GetMsg() and WaitIO() is unsound and may lead to memory corruption and seemingly random crashes. You either should use GetMsg() or WaitIO(), but not both in the same context. Thanks go to Sebastian Bauer for finding the problem and convincing my stubborn self to take this issue more seriously! - The "ConfigureNetInterface" command tested the wrong parameter when checking the DHCPUNICAST/K parameter. Fixed. - The 68020+ builds of "bsdsocket.library", "ppp-ethernet.device" and "ppp-serial.device" no longer crash when opened on plain 68000 or 68010 systems. They now just fail to open at all. I added these tests because of problems with the Roadshow installation script which were caused by the CPU type test to mistakenly offer the option to install the 68020+ builds on plain 68000 or 68010 systems. - Updated the Roadshow installation script in order to make the test for the CPU type more robust. It turned out that the "(patmatch ..)" function in versions of the "Installer" tool prior to V43 does not work as documented. In fact, that function barely works at all. This problem broke the old installation script. The new installation script now tests if the CPU type is "68000" or "68010" in a simpler fashion. - The "bsdsocket.h" and "usergroup.h" inline header files for use with GCC 68k have been rebuilt using fd2pragma 1.264 because the versions built with fd2pragma 1.171 were reported not to work correctly. These rebuilt versions are now part of the SDK. Thanks go to Anders Ali Lindgren for reporting the issue! - The "TCP:" handler leaked memory whenever it was opened, 144 bytes to be precise. Thanks go to Patrik Axelsson who detected the problem and provided a test case! - Data received by an open connection and which is never read can accumulate a lot of memory over time. While the TCP/IP stack will eventually signal to the remote that the data has not been read by the client yet, so much memory may have been allocated to hold it that your system runs out of free memory first. Due to performance considerations, and also because it made the data reception from the network interface simpler, Roadshow always allocates a "cluster" of 2048 bytes for each inbound packet, and the received data remains in that "cluster" until it has been processed, even if only 40 bytes of memory would have been sufficient to keep it, for example. This can be problematic in the long run when 20 Megabytes of memory have piled up which contain only some 32 Kilobytes of unread data. To address this quirk, new options have been added to the "RoadshowControl" command. "RoadshowControl set if.receive.useclusters = 0" will make Roadshow store incoming data using as little free memory as possible, at the expense of slightly higher processing effort. In this mode the TCP/IP stack should run much more stable in the long term. Again, Patrik Axelsson found the problem, provided a test case and tested the updated bsdsocket.library version. Thank you very much! - Both the "ping" and "traceroute" commands show greater accuracy when measuring the lengths of time intervals. As Patrik Axelsson demonstrated, the measurements taken could be very coarse on the Amiga 2000, using timer.device version 39. The new measurement method is the most accurate which the Amiga operating system permits. Again, thanks go to Patrik for finding the problem and for providing a test case! - The wget command no longer gets itself into trouble when too little shell stack space is available. Also, the transmission rate calculation finally works as intended. The problem was with how the length of time intervals was calculated, which assumed that the number of microseconds in each time stamp was stored as a signed number. The processing of the short form command options (e.g. "-q" for "--quiet") never worked correctly either, with a bug in clib2 causing the problem. Both the stack space and the short form command option problems were reported by Patrik Axelsson. Thank you very much! Roadshow 1.12 (5.10.2016) - Added new API functions for use with name resolution in order to make it easier to port application software. The new functions include the BSD style gethostbyname_r() and gethostbyaddr_r(), as well as versions of getaddrinfo(), gai_strerror(), freeaddrinfo() and getnameinfo() which are currently restricted to IPv4 addresses. - Processes which share the same library base can now safely perform overlapping name resolution operations, without danger of corrupting each other's query results. Please note that the gethostbyname_r() and gethostbyaddr_r() functions need to be used to be completely safe from accidental corruption. If your code still uses gethostbyname() or gethostbyaddr() then the recent changes will make the name resolution much more robust, but because the functions share state information which is available only once (as part of the library base) conflicts are still possible. - Reworked the ftp client command, improving robustness. This means that buffer overrun issues have been corrected which had remained unfixed since 1994. - The AddNetInterface and ConfigureNetInterface commands, as well as bsdsocket.library itself, have been enhanced to allow for the DHCP server to send address offers using unicast datagrams. Previously, only broadcast datagrams were supported. The unicast support brought a small bug to the surface to the effect that bsdsocket.library never asked the DHCP server to respond with a broadcast datagram. This bug has been fixed. - The bsdsocket.library API function QueryInterfaceTags() tag 'IFQ_HardwareAddressSize' would copy more than 16 bytes for the hardware address. In fact, it would copy as many bytes as there were bits in the address (usually, that would be 48 bytes). This bug could cause the ShowNetStatus command to crash and has been fixed in bsdsocket.library itself. - By request a new ready-made network interface configuration file has been added, for use with the "cnet16.device" driver. This file is found in the "Storage/NetInterfaces" drawer and is called "CNet16". - The TCP/IP stack's internal timekeeping relies upon the system time (as counted in microseconds) to increase "monotonously". This means that as time passes, the system microsecond counter only ever increases and never decreases, and (hopefully) never stays the same. However, this was never guaranteed because you could manually change the clock time, or a tool could automatically switch between daylight saving time and back. These clock changes could cause Roadshow to drop name resolution and routing entries prematurely, and it could also trip up the TCP protocol's time measurements. bsdsocket.library has been updated so that it is no longer sensitive to system clock time changes. Changing the system clock time can no longer result in cache entries getting dropped, or the TCP protocol's time measurements to slip. Ingo Schmitz and Harald Meinzer kindly tested the 68000 version of the updated bsdsocket.library (version 4.321). Thank you very much! Roadshow 1.11 (9.11.2013) - Improved the robustness of the ppp-serial.device and ppp-ethernet.device drivers on Amiga computers with 68000 and 68010 CPUs. Thanks go to Christian Vogelgsang for raising the issue and testing the changes. - The version of ppp-serial.device intended for all Amigas no longer allows Van-Jacobson header compression when running on an Amiga with a 68000 or 68010 CPU. This restriction may be lifted in a future version of the driver. - The ppp-ethernet.device no longer supports Van-Jacobson header compression, because that feature is not supported by the PPPoE protocol anyway. - Replaced the copying routines in the bsdsocket.library version intended for all Amigas, specifically those with 68000 and 68010 CPUs. This change was prompted by the investigation which led to the robustness improvements for the ppp-serial.device and ppp-ethernet.device drivers. The version of bsdsocket.library for Amigas with 68020 CPUs (or better) is essentially the same as before, with its version number bumped to match the library version for all Amigas. - The documentation no longer recommends tweaking the tcp.do_timestamps and tcp.do_win_scale settings. Roadshow 1.10 (19.10.2013) - Added a ready-made, new network interface configuration file for the "X-Surf 100" Ethernet card. - The "ftp" command did not process the "host" parameter correctly, and the optional "port" parameter was ignored. Thanks go to Alexandre Balaban for finding the issue. - The "ppp_connector", "ppp_dialer" and "ppp_sample" commands have been replaced with the correct versions, suitable for "classic" 68000-based Amigas. Previously, these commands were built to run only on AmigaOS 4; I had accidentally copied them from the wrong distribution drawer :-( - The optimized IP/TCP/UDP checksum calculation and verification code in the bsdsocket.library version intended for all Amigas (with 68000 and 68010 CPUs, too, such as the A500, A2000 and A600) was not stable and had to be replaced by the portable version. This change fixes crashes on these Amiga types. Amigas with 68020/030/040/060 were unaffected by these problems. Thanks go to Thorham for verifying the fixes. Roadshow 1.9 (24.2.2013): - Network interface names cannot be longer than 15 characters. Shame on me, I did not remember this when I added the new MorphOS interface files. Network interface file names have been changed as follows: Freescale-MPC52xx -> MPC52xx Marvell-Discovery-II -> Discovery-II Poseidon-Asix -> Asix Poseidon-Davicom -> Davicom Poseidon-MosChip -> MosChip Poseidon-Pegasus -> Pegasus Realtek-RTL8139 -> RTL8139 - USB device driver names have been corrected for the Asix, Davicom and MosChip network interface configuration files. - The documentation has been updated to explain in greater detail how the "DEVS:Internet/servers" configuration file looks like, and how one may convert "inetd.conf" configuration data so that it matches the format of "DEVS:Internet/servers". - Added ready-made configuration lines to the "DEVS:Internet/servers" files for use with the Samba server suite. These lines have been commented out and can be easily reactivated after you have installed Samba on your Amiga (take care, installing Samba is a challenging undertaking!). Roadshow 1.8 (19.1.2013): - Added more example network interface files for use with MorphOS: "Freescale-MPC52xx", "Marvell-Discovery-II" and "Realtek-RTL8139". Roadshow 1.7 (19.1.2013): - Updated the example network interface files "SunGEM" and "VIA-Rhine" to include the line 'state=online', which switches the respective network device drivers online even if DHCP configuration is not used. Roadshow 1.6 (10.1.2013): - Modified AddNetInterface (4.52) to switch an interface online prior to starting DHCP negotiation. This improves compatibility with the MorphOS "sungem_eth.device" and "via_rhine_pci.device" drivers. - AddNetInterface now supports "up", "down", "online" and "offline" as parameters for the "state" configuration file option. - Updated AddNetInterface source code is now part of the SDK. - Added example network interface files "SunGEM" and "VIA-Rhine" for MorphOS.