NE2000 Emulation For Bhyve

This is an old revision of the document!

Student: Alex Teaca (iateaca@freebsd.org)
Mentor: Gavin Atkinson (gavin@freebsd.org)

Project description

The bhyve hypervisor uses a virtio net PCI device emulation. However, a number of guest operating systems do not have virtio device drivers and are not able to use this emulation. One of the best supported devices, especially in older operating systems, is the NE2000 device. An implementation of a device model for this NIC would allow a larger number of unmodified guest operating systems to run under bhyve. The proposal aims to emulate the National Semiconductor DS8390/WD83C690 Ethernet adapter which is going to be used for the NE1000, NE2000 and a variety of similar clones.

The emulation is going to work tightly for the /sys/dev/ed/if_ed.c device driver in FreeBSD operating system and will be seen as a PCI device being attached under /sys/dev/if_ed_pci.c driver.

There is a datasheet for the 8390 NIC [0] which will be used for a proper understanding of the chip registers and transmit, receive, and control operations. Also, the ED device drivers mentioned above represent a good source of documentation.

I have found an implementation that emulates the NE2000 NIC in the qemu emulator [1]. Obviously, this code can not be ported in the bhyve tree sources, but certainly will be a good source of inspiration regarding the register emulation and transmit, receive protocols. So, an analysis should be done before starting to design and develop the implementation in bhyve. Actually, the qemu implementation uses the RTL8029AS controller which is an NE2000 compatible Ethernet Controller for PCI interface [2]. This controller I intend to use for the PCI configuration.

The implementation contains three logical phases. The first one is the module initialization where the PCI configuration space is configured and the data structures are initialized. The second one consists in register interpretation by handling the read and write BAR callbacks and eventually the third phase where transmit and receive protocols are emulated using read / write calls on the TAP interface. It should be mentioned that for the data transmission the packet is transferred from the memory to the device FIFO respectively for the data reception from the FIFO to the received buffer using the DMA protocol. Both packet reception and packet transmission are well explained in the 8390 NIC specification [0].

the PCI NE2000 module
the automated tester which is going to validate the NE2000 module

Implement the module initialization so the ED driver in the guest operating system recognizes the NE2000 module as a PCI device.

Design the bridge between the guest and the host operating systems through the TAP interface and find how to get notifications in order to read from the TAP file descriptor. For example, in the “virtio_net” module a callback is registered for the EVF_READ event on the TAP file descriptor.

Analyze of the structure of the registers from the datasheet [0]; design and implement the read and write register operations according to the specification.

Deliver the module initialization and read and write register operations implemented in 25 May - 26 Jun period.

Analyze and understand the transmit and receive protocols through DMA looking on both datasheet specification and qemu implementation [1]; design and implement the packet transmission protocol through DMA according to the specification.

Design and implement the packet reception protocol through DMA according to the specification.

Code and design review with the mentor and fix possible issues; thinking for a testing schema and implement an automatic tester which will be used firstly on the “virtio_net” module; after the implementation is functional it will be used for NE2000 module testing.

Test the NE2000 module implementation, fix some possible bugs and prepare the deliverables and the final evaluation.

(List of steps you plan to use to test your work, as discussed with your mentor)