Henryk Richter
b13808f240
- changed directory layout - Multicast support (automatic RX filter adjustment) - MC68000 target in Makefile - clarified licensing (GPLv3) - README files
283 lines
11 KiB
Plaintext
283 lines
11 KiB
Plaintext
SDNet - A SANA-II driver for ENC28J60 10BaseT ethernet modules
|
||
|
||
Copyright (C) 2016-2018 Henryk Richter <henryk.richter@gmx.net>
|
||
|
||
This driver is supposed to support ENC28J60 modules hooked up to the MicroSD
|
||
slot of Vampire 500/600 cards or the expansion port of Vampire 500V2+ cards.
|
||
|
||
|
||
Installation:
|
||
-------------
|
||
|
||
Installation of the driver is straightforward.
|
||
Just copy the sdnet.device and v2expeth.device to devs:networks and enable
|
||
the interface in your favorite TCP/IP stack as usual. So far, successful
|
||
tests have been done with the free AmiTCP/IP 3.0b2, AmiTCP4.0-4.2, Genesis,
|
||
MiamiDX and RoadShow.
|
||
|
||
devs:networks/sdnet.device - SD card slot of V600/V500
|
||
devs:networks/v2expeth.device - expansion port of V500V2+
|
||
|
||
From version 0.8, the driver will require vampire.resource which is included
|
||
in the ROM of Vampire Cards since the Gold2.5 release.
|
||
|
||
Also, make sure that the Vampire SD Card driver (sagasd.device) is not present
|
||
in the system or at least inactive when using sdnet.device. Both pieces of
|
||
software bang the same hardware registers. v2expeth.device may be used safely
|
||
in conjunction with the SD card driver.
|
||
|
||
|
||
Vampire500 Expansion port Hardware
|
||
-----------------------------------
|
||
|
||
Please see http://wiki.apollo-accelerators.com/doku.php/expansionport for
|
||
guidance.
|
||
|
||
|
||
MicroSD Slot Hardware:
|
||
----------------------
|
||
|
||
In terms of required hardware, you need the following:
|
||
- ready-to-use ENC28J60 module (a 3.3V part, DON'T USE an _unmodified_ 5V
|
||
module!)
|
||
- MicroSD breakout, e.g.
|
||
- a TF to SD extension cable where you rip off the full size SD slot and
|
||
solder on short extension cables towards the ENC28J60 module
|
||
- MicroSD breakout board (that comes directly with pin headers)
|
||
|
||
!!ATTENTION!!
|
||
Be extremely careful with your SD breakout board. Many conveniently looking
|
||
breakouts are made of thick and/or sharp edged PCB material that will likely
|
||
damage your Vampire SD slot. Such breakouts could be made working - but only
|
||
after patient sanding. Some people in the beta test team have destroyed
|
||
their SD slot already. If you don't have the required mechanical skills and
|
||
patience, I'd advise against DIY building.
|
||
!!ATTENTION!!
|
||
|
||
You need to connect the SD breakout pins as follows (microSD card sketch
|
||
looking at the connectors) to the ENC28J60 module:
|
||
|
||
----------------------- ENC28J60
|
||
| 8 ----
|
||
| 7 ---- SO -------------------- SO
|
||
| 6 ----- GND -------------------- GND
|
||
| 5 ---- SCK -------------------- SCK
|
||
| 4 ----- +3.3V ------ +3.3V ----- VCC (see below)
|
||
| 3 ---- SI -------------------- SI
|
||
| 2 ---- /CS -------------------- /CS
|
||
| 1 ---- /INT -- __________ -- /INT
|
||
------ ------------- \_| 3.3 kOhm |_/
|
||
\___| `----------´
|
||
|
||
As there is a myriad of ENC28J60 modules available, the naming scheme on
|
||
a particular board might differ. Please be aware the some of the boards
|
||
have a "CLK" pin as well as an "SCK" pin. Use the latter.
|
||
|
||
My test setup uses a separate 5V to 3.3V DC-DC converter. I got confirmation
|
||
from Igor Majstorovic (majsta) that the 3.3V line on his V500 Vampire designs
|
||
should be able to handle the max. 200 mA required by the module. To be on the
|
||
safe side, I recommend to use a conveniently placed 5V to 3.3V converter
|
||
(hint: the Floppy power connector is easily accessible).
|
||
|
||
Speaking of power: the reason why I didn't recommend 5V ENC28J60 boards
|
||
is that at least some of them have pullups from /CS and /RST to +5V. Your 3.3V
|
||
Vampire SD slot will quite likely not be happy with that.
|
||
|
||
Please put a 3.3 kOhm resistor into the connection from /INT of the ENC28J60 to
|
||
pin 1 of the MicroSD breakout.
|
||
|
||
|
||
Testing a new module:
|
||
---------------------
|
||
|
||
I've included two small test programs: sdnettest and v2expethtest. Both will
|
||
require the TCP/IP stack to be off(!) The program will perform a series of tests
|
||
to check for module presence and communication results at various clock rates. Don't
|
||
be alarmed when the slowest (biggest clock divider) mode is commented with a "fail".
|
||
This is intentional. What matters is that SPI clock dividers 1, 2 and 3 are working
|
||
properly. In case that sdnettest shows a failure for divider 1, see below how
|
||
to set a higher clock divider.
|
||
|
||
Use sdnettest for the SD slot and v2expethtest for the V500 expansion connector.
|
||
|
||
|
||
Software notes:
|
||
---------------
|
||
|
||
|
||
- The SD slot doesn't feature an interrupt. I had to implement polling
|
||
for incoming data. The current default interval is 10ms. (configurable via
|
||
echo "TIMER=20000" >ENVARC:sana2/sdnet.config, value in microseconds,
|
||
don't forget Makedir ENVARC:Sana2 if it didn't exist yet, you may also
|
||
consider "setenv")
|
||
|
||
- SPI speed is set to a safe level supporting higher core speeds than
|
||
x11 (see released x12 cores). Therefore this default of "SPISPEED=2"
|
||
is not providing maximum performance on x10 or x11 cores. For max
|
||
speed you may set echo "SPISPEED=1" >ENVARC:sana2/sdnet.config or
|
||
echo "SPISPEED=1" >ENVARC:sana2/v2expeth.config, respectively. I'd
|
||
suggest to run the test tool to determine the maximum reliable
|
||
speed setting.
|
||
|
||
- The required vampire.resource is unavailable with older versions of the
|
||
Vampire Kick Rom (anything before Gold2.5).
|
||
To load vampire.resource manually, copy the file to SYS:devs/ and
|
||
add the following near the top of your startup-sequence
|
||
C:VERSION >nil: vampire.resource 42
|
||
IF WARN
|
||
LoadModule >nil: DEVS:vampire.resource
|
||
ENDIF
|
||
In case of OS3.9, you can add the "noreboot" keyword to the loadmodule
|
||
line if you call the sniplet above before setpatch.
|
||
|
||
- If you want to use multiple options in the SANA-II config, concatenate them
|
||
in the "echo" command (alternatively "setenv") or use a text editor.
|
||
|
||
|
||
Options
|
||
-------
|
||
|
||
Below you find the options accepted by the drivers. Please note that no special
|
||
configuration is necessary for normal operation. What you find documented below
|
||
is available for tuning purposes.
|
||
|
||
The options template for the config files
|
||
ENVARC:sana2/sdnet.config
|
||
ENVARC:sana2/v2expeth.config
|
||
|
||
is as follows:
|
||
|
||
NOSPECIALSTATS/S,PRIORITY=PRI/K/N,BPS/K/N,MTU/K/N,FULLDUPLEX/S,SPISPEED/K/N,
|
||
TIMER/K/N,MULTICAST/S
|
||
|
||
SPISPEED - SPI clock divider (1-10, default 2), controls maximum
|
||
clock of SPI bus. Actual I/O clock is Core_Clock/(3+SPISPEED).
|
||
|
||
FULLDUPLEX - change Ethernet module into full duplex mode,
|
||
caution: requires manual configuration of duplex mode
|
||
on the switch, too.
|
||
|
||
PRIORITY - server task priority (default 1)
|
||
|
||
BPS - bit per seconds for statistics purposes
|
||
|
||
MTU - maximum transmission unit (default 1500)
|
||
|
||
NOSPECIALSTATS - obsolete, kept for config file backwards compatibility with
|
||
old driver
|
||
|
||
MULTICAST - obsolete, kept for config file backwards compatibility with
|
||
old driver
|
||
|
||
example (useful for DSL via PPPoE on x11 core with AmiTCP):
|
||
echo "MTU=1492 SPISPEED=1 PRIORITY=6" >ENVARC:sana2/sdnet.config
|
||
|
||
|
||
Changelog:
|
||
----------
|
||
|
||
1.90 - first Beta of completely rewritten driver
|
||
- support for concurrent IP stacks
|
||
- faster handling of statistics
|
||
- multiple board support where applicable (not for sdnet)
|
||
- workaround for Shapeshifter network plugin bug
|
||
- GCC or VBCC as compiler
|
||
- faster lowlevel read/write
|
||
|
||
1.03 - small fixes in sdnettest/v2expethtest, graceful exit when not run
|
||
on Vampire Gold 2.5 or later core
|
||
- fixed a minor bug in signal handling
|
||
|
||
1.02 - added build variant for V500V2+ expansion port, same config options
|
||
but distinct config file (ENV:SANA2/v2expeth.config), see
|
||
http://wiki.apollo-accelerators.com/doku.php/expansionport for pinout
|
||
- some more work on robustness (TX robustness and more error handling
|
||
this time)
|
||
- reworked test utilities to send valid BOOTP/DHCP requests while
|
||
doing TX/RX testing, increases chance of received frames within
|
||
testing interval
|
||
|
||
1.01 - some more fine tuning
|
||
- adjustments for Gold 2.7 x12, i.e. SPISPEED=2 by default
|
||
(see above for reverting to clock divider 1)
|
||
|
||
1.0 - some modest performance improvements
|
||
- reworked lowlevel code for higher robustness
|
||
- LED blinking modified: green LED will blink on RX,
|
||
orange LED blinks on TX
|
||
|
||
0.81 - sdnettest added
|
||
|
||
0.8 - proper hardware allocation by means of vampire.resource
|
||
- check for ENC28J60 hardware presence
|
||
|
||
0.7 - cleanups
|
||
|
||
0.6 - SPI speed setting support
|
||
- removal of spi.c,spi.h
|
||
|
||
0.5 - auto-generated MAC address, based on the Vampire FPGA serial
|
||
- busy waiting moved entirely to lowlevel asm source
|
||
- optimized compilation now produces working binaries
|
||
- more cleanups
|
||
|
||
0.4 - cleanups, config variables added
|
||
|
||
0.3 - first version shared with the Apollo team
|
||
|
||
|
||
Compilation / Development Notes
|
||
-------------------------------
|
||
|
||
Either VBCC or GCC (tested with version 2.95 only) can be used. General
|
||
options for compiler usage can be found in Common.mk. Also, you might want
|
||
to adapt the paths to your setup (PREFX,SYSINC). In addition to the regular
|
||
NDK, the sana2.h is expected in the devices/ subdir of the includes. sana2.h
|
||
may be found in the AmiTCP or Roadshow SDK, respectively.
|
||
|
||
Call
|
||
|
||
make -f Makefile.sdnet
|
||
|
||
for building the device.
|
||
|
||
VBCC note: When calling the GNU Make port supplied with ADE/GG natively on AmigaOS3,
|
||
please make sure that "vc" is within the search path of "/bin/sh".
|
||
|
||
Conceptually, the driver was meant to support multiple hardware targets. Therefore,
|
||
it features a SANA-II frontend (device.c,deviceheader.c,deviceinit.c), a main
|
||
server running in a task (server.c) and several hardware backends. A new hardware
|
||
backend requires customized implementation of hw.c and hwprivate.h, along with
|
||
additional hardware-specfic code, if needed. The device unit structure reserves
|
||
three LONGS and three pointers for exclusive use by the hardware instance. Additional
|
||
data for the hardware can be auto-allocated at device initialization time, if necessary.
|
||
See "struct HWData" in hwprivate.h of existing backends.
|
||
|
||
|
||
Copyrights / License:
|
||
---------------------
|
||
|
||
Up to version 1.03, the driver was heavily based on PlipBox, which is in turn based
|
||
on the magPLIP driver found on aminet.net.
|
||
|
||
Versions 1.90Beta and beyond are the result of a complete rewrite. I felt that I couldn't
|
||
incorporate desired features and changes with a reasonable amount of work into the old
|
||
codebase. This resulting package is made available as free software and contributions are
|
||
welcome.
|
||
|
||
|
||
This program is free software: you can redistribute it and/or modify
|
||
it under the terms of the GNU General Public License as published by
|
||
the Free Software Foundation, either version 3 of the License, or
|
||
(at your option) any later version.
|
||
|
||
This program is distributed in the hope that it will be useful,
|
||
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||
GNU General Public License for more details.
|
||
|
||
You should have received a copy of the GNU General Public License
|
||
along with this program. If not, see <https://www.gnu.org/licenses/>.
|
||
|
||
|