trashernet/README.MD

# Trashernet

![Trashernet Logo](doc/trashernet_logo.svg)

Trashernet is a very trashy Ethernet stack for FPGAs written in VHDL aiming to cover all OSI layers:

* Layer 1, Physical: `trashernet_phy`
* Layer 2, Data link: `trashernet_mac`, `trashernet_eth`, `trashernet_arp`
* Layer 3, Network: `trashernet_ipv4`, `trashernet_ipv4prot`, `trashernet_icmp`

When writing it, the following were the main design philosophies:

1. Standards are nice and all, but this, it just needs to work.
2. Hardware is expensive, LOC are not. So let's do everything we can inside the FPGA.
3. If there's a feature that feels optional even though it isn't, it is. See 1. if in doubt.

**IMPORTANT:** This code (and HW suggestions) violate the Ethernet standard in many ways. Do not use in proper (especially commercial) products.

## Hardware

![Circuit Diagram](doc/circuit.svg)

* RX: Use resistors behind Ethernet magnetics to reduce Ethernet RX voltage levels (0 +-2.5V) to LVPECL voltage levels (1.65V +-400mV). Or LVDS if your FPGA can't handle LVPECL. Also, pull up/down resistors help to avoid glitchy behavior with no cable connected or little data activity.
* TX: Meh, a series current limiting resistor is good enough. Drive two outputs differentially to increase the voltage swing. (Technically not true antivalent signals as there's also the "off" state with both disabled.)

Notes:

* The RX pull up/downs are probably not the best idea, and fixable in a better way. But for now, this shall work -- and suffice!
* On the TX side, I'm grossly overloading the drivers. A line driver would probably be a good idea. Or you can just parallel multiple outputs ;D

## License

This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.

The Trashernet logo uses graphics from [svgrepo.com](https://svgrepo.com), which are released under the Creative Commons CC0 license, granting the right to freely adapt and use them in any context. Thank you for making these available:

* Trash can: https://www.svgrepo.com/svg/66604/trash
* Ethernet jack: https://www.svgrepo.com/svg/292518/ethernet

The font used in the logo, "White Rabbit" by Matthew Welch, is also released on a free-to-use basis. Thank you!

* White Rabbit: https://www.fontsquirrel.com/fonts/white-rabbit
Initial commit 2021-08-27 20:10:47 +02:00			`# Trashernet`

doc: Add Trashernet logo 2021-09-25 20:28:43 +02:00			`![Trashernet Logo](doc/trashernet_logo.svg)`

Initial commit 2021-08-27 20:10:47 +02:00			`Trashernet is a very trashy Ethernet stack for FPGAs written in VHDL aiming to cover all OSI layers:`

			* Layer 1, Physical: `trashernet_phy`
doc: Add ARP layer to README 2022-10-30 17:38:29 +01:00			* Layer 2, Data link: `trashernet_mac`, `trashernet_eth`, `trashernet_arp`
doc: Add IPv4 modules to doc 2022-11-01 17:41:39 +01:00			* Layer 3, Network: `trashernet_ipv4`, `trashernet_ipv4prot`, `trashernet_icmp`
Initial commit 2021-08-27 20:10:47 +02:00
			`When writing it, the following were the main design philosophies:`

			`1. Standards are nice and all, but this, it just needs to work.`
			`2. Hardware is expensive, LOC are not. So let's do everything we can inside the FPGA.`
			`3. If there's a feature that feels optional even though it isn't, it is. See 1. if in doubt.`

			`IMPORTANT: This code (and HW suggestions) violate the Ethernet standard in many ways. Do not use in proper (especially commercial) products.`

			`## Hardware`

doc: Add circuit diagram 2022-01-30 19:27:14 +01:00			`![Circuit Diagram](doc/circuit.svg)`
Initial commit 2021-08-27 20:10:47 +02:00
doc: Add circuit diagram 2022-01-30 19:27:14 +01:00			`* RX: Use resistors behind Ethernet magnetics to reduce Ethernet RX voltage levels (0 +-2.5V) to LVPECL voltage levels (1.65V +-400mV). Or LVDS if your FPGA can't handle LVPECL. Also, pull up/down resistors help to avoid glitchy behavior with no cable connected or little data activity.`
			`* TX: Meh, a series current limiting resistor is good enough. Drive two outputs differentially to increase the voltage swing. (Technically not true antivalent signals as there's also the "off" state with both disabled.)`

			`Notes:`

			`* The RX pull up/downs are probably not the best idea, and fixable in a better way. But for now, this shall work -- and suffice!`
			`* On the TX side, I'm grossly overloading the drivers. A line driver would probably be a good idea. Or you can just parallel multiple outputs ;D`
Initial commit 2021-08-27 20:10:47 +02:00
			`## License`

			`This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.`
doc: Add licensing info about the components of the logo 2022-04-24 12:12:31 +02:00
			`The Trashernet logo uses graphics from [svgrepo.com](https://svgrepo.com), which are released under the Creative Commons CC0 license, granting the right to freely adapt and use them in any context. Thank you for making these available:`

			`* Trash can: https://www.svgrepo.com/svg/66604/trash`
			`* Ethernet jack: https://www.svgrepo.com/svg/292518/ethernet`

			`The font used in the logo, "White Rabbit" by Matthew Welch, is also released on a free-to-use basis. Thank you!`

			`* White Rabbit: https://www.fontsquirrel.com/fonts/white-rabbit`