{"id":13540262,"url":"https://github.com/emmericp/ixy","last_synced_at":"2026-01-20T08:04:57.353Z","repository":{"id":25993627,"uuid":"107034926","full_name":"emmericp/ixy","owner":"emmericp","description":"A simple yet fast user space network driver for Intel 10 Gbit/s NICs written from scratch","archived":false,"fork":false,"pushed_at":"2022-02-19T19:32:45.000Z","size":193,"stargazers_count":1241,"open_issues_count":14,"forks_count":129,"subscribers_count":44,"default_branch":"master","last_synced_at":"2025-03-29T12:09:58.838Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/emmericp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-10-15T17:48:06.000Z","updated_at":"2025-03-19T05:51:03.000Z","dependencies_parsed_at":"2022-07-27T05:46:35.056Z","dependency_job_id":null,"html_url":"https://github.com/emmericp/ixy","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emmericp%2Fixy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emmericp%2Fixy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emmericp%2Fixy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emmericp%2Fixy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/emmericp","download_url":"https://codeload.github.com/emmericp/ixy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246774218,"owners_count":20831495,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T09:01:43.991Z","updated_at":"2026-01-20T08:04:57.307Z","avatar_url":"https://github.com/emmericp.png","language":"C","funding_links":[],"categories":["\u003ca id=\"79499aeece9a2a9f64af6f61ee18cbea\"\u003e\u003c/a\u003e浏览嗅探\u0026\u0026流量拦截\u0026\u0026流量分析\u0026\u0026中间人","\u003ca id=\"eec238a1a2657b70f7bbbe68a4421249\"\u003e\u003c/a\u003e其他"],"sub_categories":["\u003ca id=\"99398a5a8aaf99228829dadff48fb6a7\"\u003e\u003c/a\u003e未分类-Network","\u003ca id=\"b239f12aca7aa942b45836032cbef99a\"\u003e\u003c/a\u003e转换"],"readme":"# ixy - a userspace network driver in 1000 lines of code\n\nixy is a simple userspace packet processing framework.\nIt takes exclusive control of a network adapter and implements the *whole driver* in userspace.\nIts architecture is similar to [DPDK](http://dpdk.org/) and [Snabb](http://snabb.co) and completely different from (seemingly similar) frameworks such as netmap, pfq, pf_ring, or XDP (all of which rely on kernel components).\nIn fact, reading both DPDK and Snabb drivers was crucial to understand some parts of the [Intel 82599 datasheet](https://www.intel.com/content/dam/www/public/us/en/documents/datasheets/82599-10-gbe-controller-datasheet.pdf) better.\n\nCheck out our research paper [\"User Space Network Drivers\"](https://www.net.in.tum.de/fileadmin/bibtex/publications/papers/ixy-writing-user-space-network-drivers.pdf) [[BibTeX](https://www.net.in.tum.de/publications/bibtex/ixy-user-space-drivers.bib)] or [watch the recording of our talk at 34C3](https://media.ccc.de/v/34c3-9159-demystifying_network_cards) to learn more.\n\nixy is designed for educational purposes to learn how a network card works at the driver level.\nLack of kernel code and external libraries allows you to look through the whole code from startup to the lowest level of the driver.\nLow-level functions like handling DMA descriptors are rarely more than a single function call away from your application logic.\n\nA whole ixy app, including the whole driver, is only ~1000 lines of C code.\nCheck out the `ixy-fwd` and `ixy-pktgen` example apps and look through the code.\nThe code often references sections in the [Intel 82599 datasheet](https://www.intel.com/content/dam/www/public/us/en/documents/datasheets/82599-10-gbe-controller-datasheet.pdf) or the [VirtIO specification](http://docs.oasis-open.org/virtio/virtio/v1.0/virtio-v1.0.pdf), so keep them open while reading the code.\nYou will be surprised how simple a full driver for a network card can be.\n\nDon't like C? We also have [implementations in other languages](https://github.com/ixy-languages/ixy-languages) (Rust, Go, C#, Java, OCaml, Haskell, Swift, JavaScript, and Python).\n\n\n# Features\n* Driver for Intel NICs in the `ixgbe` family, i.e., the 82599ES family (aka Intel X520)\n* Driver for paravirtualized virtio NICs\n* Less than 1000 lines of C code for a packet forwarder including the whole driver (w/o virtio and VFIO support, see [minimal branch](https://github.com/emmericp/ixy/tree/minimal-ixgbe-fwd))\n* No kernel modules needed (except `vfio-pci` when using the IOMMU / VFIO)\n* Can run without root privileges (when using the IOMMU / VFIO)\n* IOMMU support (see Using the IOMMU / VFIO)\n* Interrupt support (when using VFIO)\n* Simple API with memory management, similar to DPDK, easier to use than APIs based on a ring interface (e.g., netmap)\n* Support for multiple device queues and multiple threads\n* Super fast, can forward \u003e 25 million packets per second on a single 3.0 GHz CPU core\n* Super simple to use (when not using VFIO): no dependencies, no annoying drivers to load, bind, or manage - see step-by-step tutorial below\n* BSD license\n\n# Supported hardware\nTested on an Intel 82599ES (aka Intel X520), X540, and X550. Might not work on all variants of these NICs because our link setup code is a little bit dodgy.\n\n# How does it work?\nCheck out our research paper [\"User Space Network Drivers\"](https://www.net.in.tum.de/fileadmin/bibtex/publications/papers/ixy-writing-user-space-network-drivers.pdf) [[BibTeX](https://www.net.in.tum.de/publications/bibtex/ixy-user-space-drivers.bib)] for a detailed evaluation.\n\nIf you prefer to dive into the code: Start by reading the apps in [src/app](https://github.com/emmericp/ixy/tree/master/src/app) then follow the function calls into the driver. The comments in the code refer to the [Intel 82599 datasheet](https://www.intel.com/content/dam/www/public/us/en/documents/datasheets/82599-10-gbe-controller-datasheet.pdf) (Revision 3.3, March 2016).\n\n\n\n# Compiling ixy and running the examples\n\n### Caution\n**Your NIC has full DMA access to your memory. A misconfigured NIC will cause memory corruptions that might crash your server or even destroy your filesystem**. Do not run this on any systems that have anything remotely important on them if you want to modify the driver. Our version is also not necessarily safe and might be buggy. You have been warned.\n\n**Running ixy will unbind the driver of the given PCIe device without checking if it is in use.** This means the NIC will disappear from the system. Do not run this on NICs that you need.\nWe currently have a simple check if the device is actually a NIC, but trying to use another device could crash your system.\n\n1. Install the following dependencies\n\t* gcc \u003e= 4.8\n\t* make\n\t* cmake\n\t\n\tRun this on Debian/Ubuntu to install them:\n\t\n\t```\n\tsudo apt-get install -y build-essential cmake\n\t```\n2. Configure 2MB hugepages in /mnt/huge using our script:\n\n\t```\n\tcd ixy\n\tsudo ./setup-hugetlbfs.sh\n\t```\n\t\n3. Run cmake and make\n\n\t```\n\tcmake .\n\tmake\n\t```\n4. That's it! You can now run the included examples, e.g.:\n\n\t```\n\tsudo ./ixy-pktgen 0000:XX:YY.Z\n\t```\n\t\n\tReplace the PCI address as needed. All examples expect fully qualified PCIe bus addresses, i.e., typically prefixed with `0000:`, as arguments.\n\tYou can use `lspci` from the `pciutils` (Debian/Ubuntu) package to find the bus address.\n\tFor example, `lspci` shows my 82599ES NIC as\n\t\n\t`03:00.0 Ethernet controller: Intel Corporation 82599ES 10-Gigabit SFI/SFP+ Network Connection (rev 01)`\n\t\n\twhich means that I have to pass `0000:03:00.0` as parameter to use it.\n\n## Using the IOMMU / VFIO\nThe usage of the IOMMU via the `vfio-pci` driver is implemented for ixgbe devices (Intel X520, X540, and X550).\nUsing VFIO will also enable interrupt support.\nTo use it, you have to:\n\n0. Enable the IOMMU in the BIOS.\n\tOn most Intel machines, the BIOS entry is called `VT-d` and has to be enabled in addition to any other virtualization technique.\n\n1. Enable the IOMMU in the linux kernel.\n\tAdd `intel_iommu=on` to your cmdline (if you are running a grub, the file `/etc/default/grub.cfg` contains a `GRUB_CMDLINE_LINUX` where you can add it).\n\n2. Get the PCI address, vendor and device ID:\n\t`lspci -nn | grep Ether` returns something like `05:00.0 Ethernet controller [0200]: Intel Corporation Ethernet Controller 10-Gigabit X540-AT2 [8086:1528] (rev 01)`.\n\tIn this case, `0000:05:00.0` is our PCI Address, and `8086` and `1528` are the vendor and device id, respectively.\n\n3. Unbind the device from the `ixgbe` driver.\n\t`echo $PCI_ADDRESS \u003e /sys/bus/pci/devices/$PCI_ADDRESS/driver/unbind`\n\n4. Enable the `vfio-pci` driver.\n\t`modprobe vfio-pci`\n\n5. Bind the device to the `vfio-pci` driver.\n\t`echo $VENDOR_ID $DEVICE_ID \u003e /sys/bus/pci/drivers/vfio-pci/new_id`\n\n6. Chown the device to the user.\n\t`chown $USER:$GROUP /dev/vfio/*`\n\n6. That's it!\n\tNow you can compile and run ixy as stated above!\n\n# Wish list\nIt's not the plan to implement every single feature, but a few more things would be nice to have.\nThe list is in no particular order.\n\n### Implement at least one other driver beside ixgbe and VirtIO\n\nNICs that rely too much on firmware (e.g., Intel XL710) are not fun, because you end up only talking to a firmware that does everything.\nThe same is true for NICs like the ones by Mellanox that keep a lot of magic in kernel modules, even when being used by frameworks like DPDK.\n\nInteresting candidates would be NICs from the Intel igb and e1000e families as they quite common and reasonably cheap.\n\n### Better NUMA support\nPCIe devices are attached to a specific CPU in NUMA systems.\nDMA memory should be pinned to the correct NUMA node.\nThreads handling packet reception should also be pinned to the same NUMA node.\n\nNUMA handling must currently be done via `numactl` outside of ixy. \nImplementing it within ixy is annoying without depending on `libnuma`, so it's not implemented here.\n\n### RSS support\nWhat's the point of having multiple rx queues if there is no good way to distribute the traffic to them?\nShouldn't be too hard. See Section 7.1.2.8 in the datasheet.\n\n### `tcpdump`-like example\nA simple rx-only app that writes packets to a `.pcap` file based on `mmap` and `fallocate`.\nMost of the code can be re-used from [libmoon's pcap.lua](https://github.com/libmoon/libmoon/blob/master/lua/pcap.lua).\n\n### Multi-threaded mempools\nA mempool can currently only be accessed by a single thread, i.e., a packet must be allocated and free'd by the same thread.\nThis prevents apps that implement different processing steps on different cores, a common multi-threading model for complex chains.\n\nThe current limitation is the list of free buffers in the mempool, it's a simple stack at the moment.\nReplacing this with a lock-free stack or queue makes it safe for use with multiple threads.\n\nThe good news is that multi-threaded mempools are essentially the same problem as passing packets between threads: both can be implemented with the same queue/ring buffer data structure.\n\n\n# FAQ\n\n## Why C and not a more reasonable language?\nIt's the lowest common denominator that everyone should be able to understand -- this is for educational purposes only.\nI've taken care to keep the code simple and understandable.\n\nCheck out our [implementations in other languages](https://github.com/ixy-languages/ixy-languages) (Rust, Go, C#, Java, OCaml, Haskell, Swift, JavaScript, and Python).\n\n\n## I can't get line rate :(\nThere's a weird problem on some systems that causes it to slow down if the CPU is too fast. DPDK had the same problem in the past. Try applying bidirectional traffic to the forwarder and/or *underclock* your CPU to speed up ixy.\n\n## It's more than ~1000 lines! There is a huge `ixgbe_type.h` file.\n`ixgbe_type.h` is copied from the Intel driver, it's only used as a machine-readable version of the datasheet.\nixy only uses `#define` definitions for registers and the two relatively simple structs for the DMA descriptors.\nOverall, ixy uses less than 100 lines of the file and we could remove the remainder.\n\nBut it's nice to have all the struct definitions right there when implementing a new driver feature. Copy \u0026 pasting magic values from the datasheet is significantly less fun.\nAnother interesting approach to making these values available is writing a parser for the tables in the datasheet.\n[Snabb does this.](https://github.com/snabbco/snabb/blob/master/src/lib/hardware/register.lua)\n\n## Should I use this for my production app?\nNo.\n\n## When should I use this?\nTo understand how a NIC works and to understand how a framework like [DPDK](http://dpdk.org/) or [Snabb](http://snabb.co) works.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femmericp%2Fixy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Femmericp%2Fixy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femmericp%2Fixy/lists"}