README.Raspbian

Note: This document describes the installation of DECnet support on Raspbian
Buster for the Raspberry Pi. This is mostly a manual build and install from
sources.

The kit may be obtained by:

    git clone https://github.com/JohnForecast/RaspbianDECnet

Minimum kernel supported:   4.19.93
Minimum Raspbian release:   2020-02-05

Note: For kernels earlier than 5.8

    The help syntax in the Kconfig file has been changed in 5.8 and beyond. If you try to
    build on an earlier kernel version you will get a syntax error during make config or
    make menuconfig. You will need to edit RaspbianDECnet/kernel/net/decnet/Kconfig and
    change "help" to "---help---" for the help headers (There are 2 instances which must
    be changed).
    
In order to bring up DECnet on Raspbian you will need to compile and install
a new kernel along with its associated modules and dtb files.

1. Clone the RaspbianDECnet repository described above. For the rest of this
   document we'll assume that it is cloned into your home directory so it will
   be located in a ~/RaspbianDECnet directory.

2. Installing a new kernel

   Follow the instructions available at:

          <https://www.raspberrypi.org/documentation/linux/kernel/building.md>

   with the following modifications:

   2.1 After cloning the Linux sources

       We will assume that the Linux sources are cloned into a ~/linux
       directory. Copy the DECnet sources into the linux source directory:

          cp ~/RaspbianDECnet/kernel/include/net/*.h ~/linux/include/net
          rm -rf ~/linux/net/decnet
          cp -r ~/RaspbianDECnet/kernel/net/decnet ~/linux/net

   2.2 After creating the default build configuration

       You will need to enable DECnet in the kernel build. I have only tested
       DECnet as a loadable module. Use one of the Linux configuration
       option (e.g. make config or make menuconfig) to change the kernel
       configuration.

          Networking support --->
             Networking options --->
                DECnet support

       note: DECnet: router support has not been tested.

   2.3 Building a 64-bit kernel
   
       The easiest way to build a new kernel is to install the 64-bit version of piOS and build there.
       Add ARCH=arm64 to all the "make" commands. The kernel will be left in arch/arm64/boot/Image and
       needs to be copied to /boot/kernel8.img. The build and copy command will be slightly different
       for the 64-bit kernel than what is documented in the instructions above:
       
            make -j4 Image modules dtbs
            sudo make modules_install
            sudo cp arch/arm64/boot/dts/broadcom/*.dtb /boot/
            sudo cp arch/arm64/boot/dts/overlays/*.dtb* /boot/overlays/
            sudo cp arch/arm64/boot/dts/overlays/README /boot/overlays/
            sudo cp arch/arm64/boot/Image /boot/kernel8.img
            
   
   Follow the remainder of the kernel build and installation guide. After a
   reboot the system will include DECnet support but it will not be active yet.

3. Change the MAC address of the ethernet device

   The easiest way to do this is to change it before IPV4 or IPV6 is loaded.
   Create a file called /etc/systemd/network/00-mac.link with:

          [Match]
          OriginalName=eth0

          [Link]
          MACAddress=aa:00:04:00:xx:yy
          NamePolicy=kernel database onboard slot path

   This assumes that you want to change the MAC address of eth0 - change as
   needed for your system. Note: you can use the address converter at

      <http://www.powerdog.com/addrconv.cgi>

   to convert a DECnet address to its associated MAC address.

   This procedure has been tested to work on the Raspberry Pi Zero W wireless
   adapter.

4. Build and install the userland code

         cd ~/RaspbianDECnet/dnprogs
         make all
         sudo make install

   This will result in user applications and manpages being installed in the
   /usr/local tree, libraries in /usr/lib and C header files in
   /usr/include/netdnet.

5. Build the DECnet configuration database (/etc/decnet.conf)

         sudo /usr/local/sbin/decnetconf

   This will ask for the name and address of the node you are configuring and
   will allow you to specify the name and address of other nodes in your
   network. After setting up the configuration you will need to change the
   protection on the configuration database:

         sudo chmod 644 /etc/decnet.conf

6. Startup DECnet

   See the notes section below to decide if you need to change the sysctl parameters.
   
    6A. Startup DECnet at system boot time

        If you wish to start DECnet every time the system boots, add the following
        to /etc/rc.local before the "exit 0" line:

            modprobe decnet addr=area,node
            #sysctl -w net.decnet.no_fc_max_cwnd=n
            dnetd

        Where area,node is your node address (note the comma separator) and will have been
        used above to set the MAC address of the ethernet adapter.

    6B. Startup DECnet on request

        Create a shell script with the following:

            #!/bin/bash

            sudo modprobe decnet addr=area,node
            #sudo sysctl -w net.decnet.no_fc_max_cwnd=n
            sudo dnetd

        Where area,node is your node address (note the comma separator) and will have been
        used above to set the MAC address of the ethernet adapter.

7. Most of the above (sections 1 - 5) may be automated by downloading the BuildAndInstall.sh shell script,
   making it executable and running it inside a newly created work directory. You will still need to decide
   how to start up DECnet (section 6 above).
   
   7A. Build and install on current system
   
       By default, BuildAndInstall.sh will download, build and install a new Linux kernel and DECnet utilities
       tailored for the system it is running on. If you try to run BuildAndInstall.sh a second time, it will
       notice that an existing build is already present and offer to re-install the existing binaries.
       
   7B. Build a master directory tree for installing on multiple Raspberry Pi's
   
       Note that 32-bit kernels can only be built while running a 32-bit system and 64-bit kernels can only be
       built while running a 64-bit system.
       
       This description assumes that the master tree will be built either on a removable USB drive or NAS storage.
       For a completely universal tree you will need to build the kernel 4 times; 3 on 32-bit systems and 1 on a
       64-bit system. The following sequence will build a completely universal treee:
       
                mkdir -p Master/64-bit Master/32-bit/pi1 Master/32-bit/pi2_3 Master/32-bit/pi4
                
          The directories will hold:
          
            64-bit          - arm64 kernel/executables for all Raspberry Pi's capable of running 64-bit
            32-bit/pi1      - arm32 kernel/executables for Model A, A+, B, B+, all Zeroes and Compute Module
            32-bit/pi2_3    - arm32 kernel/executables for all Pi 2, 3 and Compute Module 3
            32-bit/pi4      - arm32 kernel/executables for all Pi 4 and Compute Module 4
            
          Copy BuildAndInstall.sh to each of the above directories
          
          Boot into a 64-bit system
          
                cd Master/64-bit
                ./BuildAndInstall.sh
          
          At this point, answer the question about what to do when the build completes with "3 - Terminate the script".
          
          Boot into a 32-bit system
          
                cd Master/32-bit/pi1
                forcekernel=kernel ./BuildAndInstall.sh
                cd ../pi2_3
                forcekernel=kernel7 ./BuildAndInstall.sh
                cd ../pi4
                forcekernel=kernel7l ./BuildAndInstall.sh
          
          If the "forcekernel=" option is used, the script will automatically terminate when the build completes.
          
          To install from this master tree, mount the USB drive or NAS storage volume on the target Raspberry Pi,
          cd to the appropriate directory depending on the hardware/software environment and execute BuildAndInstall.sh
          again. The script will recognize that there is a build tree present and offer to install using the available
          binaries.
          
                
Changes from previous DECnet for Linux releases:

    11/18/2021
    
   1. Change Kconfig to use the new syntax. This change occurred in the 5.8 kernel.
   
   
    11/21/2020
    
   1. Fix reference count bug in regard to network devices. This only happened in 5.5 and later and would cause a system shutdown
      to hang. The code now runs correctly in the experimental 5.9 and 5.10 kernels for Raspberry Pi.
      
   2. Fixed a number of bugs found by Paul Koning.
   
   
    10/24/2020
    
   1. Conditional code changes to allow the use of kernel 5.8 and 5.9.
   
   
    10/09/2020
    
   1. Add support in fal2 to know when it is talking to a Linux system pretending to be VAX/VMS.
   
   
    10/06/2020
    
   1. Added a new File Access Listener (FAL) in dnprog/fal2. This version provides simple sequential file access (read/write)
      and directory listing without file name case conversion (as performed by the current version). Tested against VAX/VMS, RSX-11M+,
      RSTS/E, TOPS-10/20 and the Linux dnxxx utilities. To install this version after installing everything else:
      
            cd dnprogs/fal2
            make
            sudo make install
            
            
    09/01/2020
    
   1. Fix computing the actual remote segment size from the SEGMENT BUFFER SIZE parameter to comply with Appendix G of
      the routing spec so that we can interoperate with other systems.
      
      
    08/31/2020
    
   1. Add SEGMENT BUFFER SIZE to override the negotiated segment size when a connection goes outside the local LAN.
      Erik Olofsen reported this problem on HECnet where connections would be correctly established but data would
      fail to flow. The parameter is available via /proc/sys/net/decnet/segbufsize and through sysctl at
      net.decnet.segbufsize and has a default value of 576.
      
   2. Modified nml2 to report SEGMENT BUFFER SIZE in the response for "SHOW EXEC CHAR"
   
   
    08/27/2020
    
   1. Fix NML2 response for "SHOW EXEC CHAR" as reported by Erik Olofsen
   
   
    07/08/2020
    
   1. Document BuildAndInstall.sh
   
   
   06/30/2020
    
   1. Backed out commit 8926684 and made the code contionally compiled based of the Linux kernel version
      being built. This will allow older version of the Linux kernel to run the latest code.
   
   
    06/24/2020
    
   1. Discard routing multicast packets (hellos and L1, L2 routing packets) which were not expected to be
      received due to multicast filtering. This can occur if promiscuous mode is enabled on the ethernet
      NIC by programs like tcpdump or when using libpcap.
      
      
    06/23/2020
    
   1. The existing code would send outbound NSP-level packets directly to remote nodes if there was a valid
      neighbour entry. It would ignore the Intra-Ethernet bit in the routing flags which is used to indicate
      that the nodes are on the same ethernet and may communicate. The inbound logic built a new neighbour
      entry which took the intra-ethernet bit into consideration but then discarded it. We now use this new
      neighbour entry for subsequent transmissions once the socket has transitioned into the RUN state.
      
      
    06/19/2020
    
   1. Fix Connect Initate transmit format if the socket has no name binding (VMS cannot handle a NULL name).
   
   2. Fix optional data on received connect confirm. Was taking the data from the wrong location in  the
      message.
      
   3. Fix destination cache destruction. Was causing extra entries to be created in the neighbour cache.
      Sometimes caused designated router to move to the loopback device so the node would become
      inaccessible on the network.
      
   4. Initial checkin for dts.
   
   
    06/10/2020
    
   1. Fixed bugs related to flow control of interrupt messages - both inbound and outbound.
   
   2. Added initial implementation of dtr - DECnet test receiver. Tested against RSX, VMS and Ultrix
      implementations.
      
      
    05/28/2020
    
   1. Merged changes which were already in the 5.4 kernel tree. This included changed kernel APIs and
      updated comments.
      
    05/27/2020

   1. Fixed system panic when using the loopback device.


    05/22/2020
    
   1. Implemented the missing LISTEN TIMER so that we can detect failed routers and added additional
      code to allow changing the designated router. Note that in order to make the LISTEN TIMER
      available to network management I had to change the format of /proc/net/decnet_dev so, if you
      want network management support via nml or nml2 you must rebuild and install nml or nml2
      after installing these kernel changes.
      
      
    05/19/2020:
    
   1. Added HELLO TIMER to CIRCUITS CHARACTERISTICS. Unable to add LISTEN TIMER until we can pull
      the timer value from the router hello message and implement the T4 timer.
      
      
    05/17/2020:
    
   1. Added a new Network Management Listener (NML) in dnprog/nml2. This version supports
      SUMMARY, STATUS and CHARACTERISTICS for NODES, CIRCUITS and AREAS. I have not made this
      version the default yet. To install it after installing everything else:
      
            cd dnprogs/nml2
            make
            sudo make install
            
            
    05/08/2020:
    
   1. Network Management Listener (NML) now supports 2 additional NICE requests:
   
        - SHOW ACTIVE CIRCUITS
        - SHOW ACTIVE NODES
        
   2. If an earlier version of decnet.ko was loaded via modprobe and supplied with an invalid
      area or address, it would skip loading /proc/net/decnet_dev which would result in certain
      network management requests failing. We now create the file and generate an error message
      when dnetd is started.
      
      
    02/10/2020:
    
   1. Previous versions incorrectly accepted zero value for area and/or node
      via the kernel /proc interface although the decnetconf script
      mentioned above disallowed it.

   2. Special handling has been added for connections to area 0:

              0.0      - Means connect to the local node
              0.n      - Means connect to node n in the local node's area

   3. Automatically determine whether to use DECnet-VMS syntax for specifying
      access control information (node"username password account"::filespec)
      or DECnet-Ultrix and DECnet-RSX syntax
      (node/username/password/account::filespec) based of the first character
      following the nodename.

      This support is available in the file access utilities (dndir, dntype,
      etc) and dntask.
      
   4. This version now handles delayed ack requests for both inbound and outbound
      data messages.


Notes:

   1. If a remote system does not use message or segment flow control the congestion window size will be clamped to 1 which
      means that data will be transmitted synchronously to the remote system one packet at a time; send packet, wait for ack,
      send packet ... You can change this behaviour by uncommenting the sysctl command in each of the startup descriptions
      above and selecting a suitable value.
      
      The flow control mechanism used may be different in each direction and is typically constant for a specific
      system implementation. The following table is not exhaustive:
      
            Linux (this implementation)             No flow control
            VAX/VMS 7.3 - Phase IV                  No flow control
            RSX-11M+ 4.6                            Session control message flow control
            Ultrix 2.2                              No flow control
            Ultrix 4.0                              No flow control
      
   2. Delayed acks are an optional DECnet component to reduce the amount of traffic flowing over the network. There is a
      sysctl parameter, "net.decnet.dlyack_seq" which is set to a default value of 3. This means that when sending large
      blocks of data, every third packet will request an explicit ack. In order to make use of delayed acks when the remote
      system supports "no flow control", "net.decnet.no_fc_max_cwnd" should be increased and, ideally, should be at least
      2 * net.decnet.dlyack_seq.
      
   3. As of 5/5/2020 I changed the startup sequence as described in section 6 above. The old version failed to create
      /proc/net/decnet_dev which describes the devices being used.
      
Systems Tested:

Raspberry Pi Zero W (2019-7-10 version of Raspbian Buster)

Raspberry Pi 2B V1.1 (2019-7-10 version of Raspbian Buster)

Raspberry Pi 4B (2 GB)(2019-7-10 and 2019-9-26 versions of Raspbian Buster)

Raspberry Pi 4B (2 GB) "testing" 64-bit Raspbian kernel (still uses 32-bit userland).

In addition this code has been tested on:

    Debian 9.0 (Stretch) on x86 64-bit systems up to kernel 4.19.269
    Debian 10.0 (Buster) on x86 systems (both 32 and 64-bit systems).


Raspberry Pi 4B (2 GB) 2020-02-05 version of Raspbian Buster

Raspberry Pi 4B (2 GB) 2020-02-13 version of Raspbian Buster

Raspberry Pi 4B (2 GB) 2020-02-13 version of Raspbian Buster running kernel 5.4.42 (32-bit)

With the name change to Raspberry Pi OS:

    32-bit:
    
    Raspberry Pi Zero W 2020-05-27 version of Pi OS with kernel 4.19.126 and 5.4.44
    
    Raspberry Pi 4B (2 GB) 2020-05-27 version of Pi OS with kernel 4.19.126 and 5.4.44
    
    Raspberry Pi Zero W 2020-08-20 version of Pi OS with kernel 5.4.70
    
    64-bit:
    
    Raspberry Pi 4B (8 GB) 2020-05-27 version (fully updated on 6/26/2020) with kernel 5.4.50
    
    Raspberry Pi 4B (8 GB) 2020-08-20 version with kernel 5.4.70
    
    Tested experimental version of kernel 5.9.1 on Raspberry Pi 4B (8 GB)
    
    Raspberry Pi 3B+ 2022-09-22 version with kernel 5.15.79