| Readme: | 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.
|
Ambient (143)
Roadshow_1.13_demo.lha