Permalink
Switch branches/tags
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
266 lines (201 sloc) 10.2 KB

plipbox: Amiga Driver Documentation

  1. Changes

  • 2011-08-05 38.1a plip2slip support
  • 2012-06-03 38.1b plipbox support
  • 2013-04-06 0.3 introduced own plipbox.device ethernet device
  • 2013-05-19 0.3 converted to markdown. added more stacks
  • 2015-01-11 0.6 adapted to new file names
  1. Supported Network Stacks

The following network stacks have been successfully tested with plipbox:

  1. Setup Hints

2.1 Common Setup

  • All network stacks expect the plipbox device driver in devs:networks on your system volume. So copy this file first before proceeding.

  • Copy plipbox.device from this release in the amiga/bin directory to your Amiga installation. Select the suitable m680x0 version for your hardware platform and copy the plipbox.device file without the RELEASE_000 or RELEASE_020 extension:

     copy plipbox.device_RELEASE_000 devs:networks/plipbox.device
    

2.2 AmiTCP with Network Boot Disk

  • For a very simple setup you can use the Network Boot Disk for Amiga and start with this one. You have to modify the vanilla disk as it does not contain the plipdox drivers, yet.

Initial Setup

  • Insert this disk into your favorite Amiga emulator and perform the following steps to prepare the disk:
  • Initial boot enters setup of the disk. Follow steps to install but cancel the selection of a network driver as we will add the plipbox driver later.
  • Use the setup to configure your IP, netmask, gateway, and DNS server.
  • Finally reboot to finish setup.

Add plipbox Driver

  • Copy plipbox.device on the disk to devs:networks (see section 2.1). I recommend to mount a host directory as a virtual harddisk and take the driver from there (my disk is called shared)

     copy shared:plipbox.device devs:networks/
    
  • Edit the file AmiTCP/db/interfaces and add a line for the plipbox:

     echo "plipbox dev=devs:networks/plipbox.device" >> df0:AmiTCP/db/interfaces
    
  • Edit df0:Prefs/Env-Archive/nbddriver (aka EnvARC:nbddriver) and set plipbox0 as the network device:

     echo plipbox0 > df0:Prefs/Env-Archive/nbddriver
    
  • In EnvARC:sana2/ directory you can place an optional configuration file called plipbox.config. For options see the plipbox documentation. A sample file is available in directory amiga/src of this release. Example:

     echo "NOBURST" > df0:Prefs/Env-Archive/sana2/plipbox.config
    
  • Now reboot to activate changes

  • Use ifconfig plipbox0 to check the status of your network interface. It should be UP and RUNNING.

2.3 Genesis

  • Genesis is very similar to the AmiTCP setup (its more or less a UI for AmiTCP and uses its core for the network stuff)
  • Copy the plibpox.device to your system (see section 2.1)
  • Open the GenesisPrefs
  • In Interfaces select New
    • In Interface Tab enter:
      • Enter the interface Name: plipbox0
      • Enter IP Address, Gateway, Netmask to match your local network
    • In SANA II Tab enter:
      • Specify SANA II device: devs:networks/plipbox.device
    • Confirm interface creation with Okay
    • In Resolve Tab do not forget to name your DNS servers and set your domain name(s)
  • Note: dynamic setup does not work with plipbox. You must either use static or an external DHCP client suitable for AmiTCP/Genesis.
  • Now you can start Genesis and enable your new plipbox0 interface

2.4 MiamiDX

  • Launch MiamiDX
  • Select Hardware Tab and click New:
    • In Select Hardware Type pick Ethernet
    • Enter a name for the hardware, e.g. Name: plipbox
    • Keep Type: SANA II
    • Pick plipbox.device: Driver: devs:networks/plipbox.device
    • Confirm with Ok
  • Select Interfaces Tab and click New:
    • Pick Interface Type: Ethernet
    • Pick Interface connection: LAN
    • Select your hardware: plipbox
    • You can either configure your Amiga statically or with DHCP: Select static or dynamic in IP Type, Netmask Type, Gateway Type. Enter your network parameters in static mode.
    • Note: multicast is not supported in plipbox. Therefore, keep Multicast: disabled.
    • Note: Configure DHCP in TCP/IP Settings... to fetch DNS servers, too.
  • In Databases Tab select Table DNS servers and add your static DNS server IPs (if you don't use dynamic DNS via DHCP)
  • Do not forget to save your settings with Amiga+S or Menu: Settings -> Save
  • Now you can go online with your new interface plipbox
  • If you use multiple plipbox devices in a single network then you have to set a unique MAC address for each one. Select Hardware Tab and double click your plipbox entry. Now select SANA-II Parameters and enter a new MAC address in the Hardware address field.

2.5 Roadshow

  • Begin with copying the plipbox device driver (see section 2.1)

  • Then you need an interface configuration file for the plipbox device. Simply copy a template from Storage/NetInterface and modify this one:

    copy sys:Storage/NetInterfaces/cnet devs:NetInterfaces/plipbox
    
  • Now adjust the following values in the file (use either static or DHCP section!):

    device=plipbox.device
    # -- DHCP --
    configure=dhcp
    # -- static --
    address=<your ip>
    netmask=<your mask>
    
  • Have a look in devs:internet/name_resolution to set your DNS servers and your domain name.

  • After a reboot the interface will be brought up automatically in the User-Startup section of Roadshow

  • For testing you can activate/de-activate the interface with:

    > addnetinterface devs:netinterfaces/plipbox
    > ... use network ...
    > netshutdown
    
  • To make sure that the plipbox device goes offline if you shut down the net you have to add the following options to your interface configuration file:

    downgoesoffline=yes
    
  • If you use multiple plipbox devices in a single network then you have to assign them unique MAC addresses. You can set the MAC address of your plipbox with the following option in your Roadshow device configuration file:

    hardwareaddress=1a:11:a1:a0:00:01
    
  • A complete device config looks like:

    device=plipbox.device
    configure=dhcp
    downgoesoffline=yes
    hardwareaddress=1a:11:a1:a0:00:01
    
  1. plipbox.device Configuration

While the plipbox.device is in general zero-config and needs no adjustement, you can control some options via a configuration file.

The text file needs to be called:

    ENV:SANA2/plipbox.config

Store your file in the environment archive to have it available after the next reboot, too:

    ENVARC:SANA2/plipbox.config

The following options are supported:

  • NOBURST (switch /S) (default: burst on)

    • Starting with version 0.6 a fast burst mode is used for parallel port data transfer. It is always recommended to use this mode. However, if you experience problems with fast transfers then you can use this option to fall back to the old transfer protocol. Its slower but more reliable.
  • TIMEOUT (numerical key /K/N) (default: 500 * 1000) (unit: microseconds)

    • The parallel transfer uses time outs to detect error conditions.
    • Use this value to adjust timing.
  • NOSPECIALSTATS (switch /S) (default: special stats on)

    • The SANA-II device tracks statistics information.
    • Use this switch to disable the extra statistics information that is recorded during normal operation of the device.
  • PRIORITY (numerical key /K/N) (default: 0) (unit: AmigaOS task prio)

    • A server task is used in the plipbox.device to handle the parallel port transfers.
    • Use this value to alter the scheduling priority of the send/receive task.
  • BPS (numerical key /K/N) (default: 60 * 1024 * 8) (unit: bits/second)

    • A SANA-II device reports a bitrate per second value as an indication for the achievable transfer speed of the network device.
    • Use this parameter to adjust the speed that is reported to the TCP/IP stack from the device.
  • MTU (numerical key /K/N) (default: 1500) (unit: bytes)

    • The maximum transfer unit is the maximum number of bytes a device can transfer in a single packet. By default its 1500 and exactly matches the MTU that Ethernet uses.
    • For the plipbox the MTU size is also the size of the parallel transfers.
    • Use this parameter to set a smaller MTU and tune the transfer rates.
    • Note that a non 1500 MTU will cause fragmentation on upper levels.
  1. Build plipbox.device from Source

  • Only for advanced users! All others can use the supplied binaries! You really need to recompile the binaries only if you want to modify or enhance them.

  • I cross-compile the binaries here with vamos running the SAS C V6.58 compiler

  • Install vamos on your Mac or PC

  • Copy the following Amiga Directories either from a real machine or an emulator to a directory on your Mac. The directory is named $HOME/amiga/shared here but you can use another directory as well but need to adjust AMIGA_DIR in amiga/src/makefile!

     ~/amiga/shared:
       wb310             system root of a Workbench 3.1 HD Installation
       sc                complete installation directory of SAS C 6.58
       AmiTCP-SDK-4.3    AmiTCP SDK
    

    The AmiTCP-SDK-4.3 is available on Aminet

  • Enter directory amiga/src of this release

  • Build on your Mac or PC shell with:

     > make dist       build release files
     > make all        build without optimization
     > make opt        build with optimization
     > make clean      remove files of current build
     > make clean_dist remove all build files
    
  • The resulting files can then be found in amiga/bin

EOF