LANceGS Ethernet Card

The LANceGS Ethernet Card is the first released general-purpose Ethernet card for the Apple II series of computers. It was introduced in the year 2000 and developed by ///SHH Systeme in Germany. This is an 8-bit card to maintain compatibility with the Apple II data bus. The single Ethernet port is limited to 10 Meg connectivity. It is 100% compatible with all Marinetti TCP/IP software for the Apple IIgs and Contiki on 8-bit Apple II computers.

As of May 2008, new boards are still available for sale from the developer. It does cost more than other competing products, but is a superior hardware design and has a potential to run more optimally on an Apple II computer if software is developed to take advantage of its full capabilities.

Driver Support

* Marinetti Link Layer - available on disk when the hardware is purchased (requires Marinetti to be acquired and installed separately). GS/OS on the IIgs doesn't have an Ethernet device driver model so every network stack would need to use its own link layer.
* Contiki - the Apple II port includes the driver.

Major Hardware Components

* Ethernet controller: [http://www.smsc.com/main/datasheets/91c96.pdf SMSC 91c96]
* I²C EEPROM: [http://www.atmel.com/dyn/resources/prod_documents/doc0180.pdf 24c04]
This is a 2kb flash memory. The LANceGS stores the MAC Address and a handful of other parameters solely used by software that comes with the card. Developers are strongly encouraged to not store variable data in the EEPROM (use preference files stored on the system disk). The default MAC address for the ethernet port is the only parameter that should be retrieved from the EEPROM.

Programmer's Documentation

It is assumed that there is a familiarity with Apple II software developmentand an understanding of Apple II hardware/firmware. This was written withthe Apple IIgs in mind, but it is relevant for 8-bit Apple computers as well(for example, references to bank $E0 are not relevant). There are 16 I/O registersavailable. They will be referred in hexadecimal: 0 through F.

EEPROM
Even though the Ethernet controller has EEPROM access functionality,Apple IIgs hardware limitations prevent it from working at all. The 16thregister ($E0/C0nF) uses its Bit 0 as write-only to bankswitch betweenEthernet and EEPROM modes. Writing a 0 to Bit 0 in the 16th register willset the Apple II I/O registers to Ethernet mode. Writing a 1 will set the Apple II I/Oregisters to EEPROM mode.

The EEPROM is a 4k-bit serial based on the 2-wire I²C interface. Itsdatasheet describes its operation. In EEPROM mode, the significant registers are $E0/C0n4 through $E0/C0n8 and $E0/C0nF. Again, $E0/C0nF is to bank switch between the EEPROM and Ethernet registers. $E0/C0n4through $E0/C0n7 toggles to set the state of the clock or data. Bit 0 on $E0/C0n8 provides the current state of the data signal. The following chart shows the use of the toggle registers:

Register Toggle State -------- ----------------- C0n4 Set Clock to Low C0n5 Set Clock to High C0n6 Set Data to Low C0n7 Set Data to High

The 24c04 documentation should be reviewed to understand the timing of the I²C EEPROM.

"Notes for emulated environments: The write/erase cycle in the emulated environment is instantaneous. On real hardware, one should expect that extra time is needed to complete the write/erase operation. Accelerators for users may be clocked faster than what developers--developers should use the system clock for timing."

Be careful if you write to the EEPROM. The LANceGS link layer for Marinetti from ///SHH Systeme is hard coded to look for a copyright string in the EEPROM.

"Notes for emulated environments: The copyright string may not be present in the virtual EEPROM. This means the Marinetti Link Layer will need to be patched before it can be used (or the EEPROM needs to be manually updated to include this string). Contiki will continue to work since it does not check for this string. Emulators are recommended to provide a default MAC address when the virtual EEPROM memory is first generated. Ethernet emulators often have the MAC address get generated as an offset of the host's machine MAC address. If there is a way to generate a default IP address and netmask (such as dynamically setting up a host-based NAT) the user's experience can be simplified (for software that uses the EEPROM for such information).

Ethernet Controller
This section assumes there is a general familiarity with the information from the SMSC 91c96 datasheet.

The SMSC has 5 banks of usable I/O registers. Banks 0-3 use I/Oregisters 0-D and Bank 4 uses registers 0-1. Writing to register E isfor bank switching among the SMSC register banks (only bits 0-2 can be set;bits 3-7 are always 0). As you can see, there are more potentially validregisters than what is used by the SMSC.

"Notes for emulated environments: Memory is allocated for all 8 banks (total 128 bytes) so they could be read (initialized with a $00), but they can't be changed with a write.

Some of the SMSC registers are read-only. Some are write-only. Some areread/write. The SMSC datasheet specifies what the read value should be for thewrite-only registers.

When the SMSC registers bankswitch to the EEPROM registers, the the SMSC register bank is not forgotten when the EEPROM registers are bankswitched back to the SMSC registers. For example, if SMSC register bank 2 was active before bankswitching to EEPROM, then SMSC register bank 2 will be active when bankswitched back to the SMSC registers.

When the LANceGS first powers up, the following is expected to happen:
* EEPROM Apple II I/O registers reset to their default values.
* I²C EEPROM is at its initial state (data is 0, clock is 0, and address is 0).
* LANceGS bank 0 registers are active in the Apple II slot's I/O space.
* LANceGS bank 1 register 0 - 3 are: $31, $31, $20, $67, and $18, respectively.
* LANceGS bank 1 register 4 - 9 are all $00.
* LANceGS bank 4 register 0 - 1 are: $40 and $00, respectively.
* LANceGS performs a reset.

The LANceGS reset does the following:
* Set these registers to their default values (as per the datasheet): all bank 0 registers except for 9, bank 1 registers A through F, and all bank 3 registers.
* Disable listening to packets on the wire if it was enabled.
* Reset LANceGS MMU.

The LANceGS MMU reset does the following:
* Set all bank 2 registers to their default values (as per the datasheet).
* The transmit and receive FIFOs are empty.

This is not a replacement for the datasheet, but is considered a supplement for what to expect when writing values to the Ethernet I/O registers
* Bank 0
** Register 0 - store value.
** Register 1 - store value.
** Register 4 - store value. "Emulated systems restart the Ethernet receiver if it was enabled".
** Register 5 – store value.
*** Bit 7 = 1 - LANceGS performs a reset.
*** Bit 0 = 1 - Enable the Ethernet packet receiver. "Emulated systems restart the Ethernet receiver if it was enabled".
*** Bit 0 = 0 - Disable Ethernet packet receiver.
** Register A - store value.
* Bank 1
** Register 0 - store value.
** Register 1 - store value.
** Register 2 - store value.
** Register 3 - store value.
** Register 4 - store value, "Emulated systems restart the Ethernet receiver if it was enabled".
** Register 5 - store value, "Emulated systems restart the Ethernet receiver if it was enabled".
** Register 6 - store value, "Emulated systems restart the Ethernet receiver if it was enabled".
** Register 7 - store value, "Emulated systems restart the Ethernet receiver if it was enabled".
** Register 8 - store value, "Emulated systems restart the Ethernet receiver if it was enabled".
** Register 9 - store value, "Emulated systems restart the Ethernet receiver if it was enabled".
** Register A - store value.
** Register B - store value.
** Register C - store value.
** Register D - store value.
* Bank 2
** Register 0 – store value bits 1 through 7. "Emulated systems may complete these MMU operations immediately so the busy flag never gets set".
** Register 1 - store value.
** Register 2 - store value.
** Register 6 - store value. If bank 2, register 7 has bit 5 = 1, then set bank 2, register 8 with the byte of the Ethernet controller's RAM address and bank 2, register 9 with the next byte of the Ethernet controller's RAM address. Bank 2, register A contains the same value as bank 2, register 8. Bank 2, register B contains the same value as bank 2,register 9.
** Register 7 - store value. If bank 2, register 7 has bit 5 = 1, then set bank 2, register 8 with the byte of the Ethernet controller's RAM address and bank 2, register 9 with the next byte of the Ethernet controller's RAM address. Bank 2, register A contains the same value as bank 2, register 8. Bank 2, register B contains the same value as bank 2, register 9.
** Register 8 - If bank 2, register 7 has bit 5 = 0, then store the value in the Ethernet controller's RAM address based on the pointer register. Increment the pointer register by 1.
** Register 9 - If bank 2, register 7 has bit 5 = 0, then store the value in the Ethernet controller's RAM address based on the pointer register. Increment the pointer register by 1.
** Register A - If bank 2, register 7 has bit 5 = 0, then store the value in the Ethernet controller's RAM address based on the pointer register. Increment the pointer register by 1.
** Register B - If bank 2, register 7 has bit 5 = 0, then store the value in the Ethernet controller's RAM address based on the pointer register. Increment the pointer register by 1.
** Register C – set only the appropriate bits.
** Register D - store value.
* Bank 3
** Register 0 - store value.
** Register 1 - store value.
** Register 2 - store value.
** Register 3 - store value.
** Register 4 - store value.
** Register 5 - store value.
** Register 6 - store value.
** Register 7 - store value.
** Register 8 - store bits 0 – 3 of the value.
** Register C - store value.
** Register D - store value.
* Bank 4
** Register 0 - store value.
** Register 1 - store value.

The only registers which are not trivial to understand when read are Bank 2, registers 8 – B. If any of these registers are read, the current byte in the Ethernet controller's RAM address is returned to which ever register is being read and the Ethernet controller's memory pointer is incremented by 1. The Apple IIgs can read these registers in 16-bit mode and the byte ordering is little-endian.

If the receive FIFO is fully allocated with unread data, then incoming packets are dropped.