SDNet - A SANA-II driver for ENC28J60 10BaseT ethernet modules Copyright (C) 2016-2018 Henryk Richter This driver is supposed to support ENC28J60 modules hooked up to the MicroSD slot of Vampire 500/600 cards (sdnet.device) or the expansion port of Vampire 500V2+ cards (v2expeth.device). 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 cabling 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/(2+SPISPEED). FULLDUPLEX - change Ethernet module into full duplex mode, caution: requires MANUAL configuration of duplex mode on the SWITCH, TOO! Otherwise you get a heavy amount of collisions and bad performance! PRIORITY - server task priority (default 1). It depends on the TCP/IP stack whether a priority higher than 1 gives performance benefits. I'd suggest to leave the setting at default, at least for Roadshow. 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 INTERRUPT - (V2EXPETH ONLY!), from Gold 2.10 release and v2expeth.device 1.94 onwards, you can enable the interrupts and avoid polling. It is suggested to disable the timer in that case. See below for an example example1 (useful for DSL via PPPoE on x11 core with AmiTCP): echo "MTU=1492 SPISPEED=1 PRIORITY=6" >ENVARC:sana2/sdnet.config example2 (V500 expansion port, Gold 2.10 or later, interrupt driven): echo "TIMER=0 INTERRUPT SPISPEED=1" >ENVARC:sana2/v2expeth.config Changelog: ---------- 2.00 - parse Vampire 4 UUID for MAC auto-assignment - version bump 1.99 - re-enabled 32 Bit Buffer copies (unless Miami is active) - default server task priority for AmiTCP=6 (otherwise 0) - tuned RX/TX balancing to make RoadShow happy - added Packet Filter hook processing (needs testing) 1.95 - workaround for MiamiDX bugs, 32 Bit Buffer copy routines could not be used safely with it. 1.94 - implemented interrupts for modules connected to V500v2+ expansion port 1.93 - minor restructuring, SAS/C makefile added - smaller binaries (functionally identical) 1.92 - workaround for linker issue, version bump 1.91 - minor cleanups 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 .