# HomaModule: a Linux kernel implementation of the Homa transport protocol > HomaModule implements the Homa transport protocol as a loadable Linux kernel module, replacing TCP congestion control with a message-oriented design aimed at tail latency rather than throughput. It ships a syscall API that differs from TCP sockets, benchmarks, a Wireshark dissector and support for a set of specific NICs. **PlatformLab/HomaModule** — A Linux kernel module that implements the Homa transport protocol. - Repository: https://github.com/PlatformLab/HomaModule - Stars: 539 · Forks: 77 - Language: C - License: not declared - Published: 2026-10-22 · Updated: 2026-10-22 · Language: en - Canonical page: https://hysenlabs.com/projects/platformlab-homamodule ## A different transport, not a different TCP HomaModule contains an implementation of the Homa transport protocol as a Linux kernel module. The general protocol is documented in the Homa Wiki, and the implementation and its performance are described in the paper A Linux Kernel Implementation of the Homa Transport Protocol, which appeared at the USENIX Annual Technical Conference in July 2021. A synopsis of the protocol is in protocol.md in the repository. The distinction to hold onto is that Homa is not a variant of TCP. It is a different transport, and the API reflects that. The README says plainly that the API for Homa is different from TCP sockets, and a collection of man pages in the man subdirectory documents it. The design goal is tail latency. The README states that as of August 2020 Homa has complete functionality for running real applications, and that its tail latency is more than 10x better than TCP for all workloads the author has measured, with the observation that Homa's 99th percentile latency is usually better than TCP's mean latency. That is a striking claim and it is a personal measurement by the author, in a first-person voice that this README keeps throughout, so it is best read as a research result rather than a vendor benchmark. The one acknowledged functional gap is the incast optimisation from Section 3.6 of the SIGCOMM paper, which has not been implemented. Incast is the pattern where many senders target one receiver simultaneously, which is exactly what a distributed RPC system does at scale, so this is a real limitation rather than a footnote. The README invites contact if you want to test Homa under large incasts, offering to implement the feature. ## Kernel versions and branches The README is unusually precise about which kernel versions work, and this is the first thing to check before anything else. The head is known to work under Linux 6.17.8, and that is where current development occurs. The head has also recently been updated to compile under Linux 7.0.14, but the README is explicit that these changes are not actively supported and may bit-rot over time, with an invitation to submit fixes if that happens. The branches rhel8 and rhel9.5 are known to run on the corresponding versions of Red Hat Enterprise Linux and are relatively up to date. The README describes them as officially supported in the sense that the author plans to backport changes from the main branch to them. Other versions of Linux have not been tested and may require code changes, typically described as easy to do. The README asks for a pull request in that case, offering to include the changes if they can be done cleanly, the same way the 7.0.14 changes were handled. There is also a long tail of historical branches, one per older kernel version, with names such as linux_4.15.18. The README warns that these older branches are generally out of date feature-wise, since recent commits have not been backported to them. So the support matrix is: a moving head for current development, two maintained distribution branches, and a set of frozen historical ones. For production use the Red Hat branches are the sensible target, and for research the head is where the work happens. ## Building the module Build and install instructions are in INSTALL.md, and the top-level Makefile shows the shape of the build. The kernel build directory is derived from the running kernel by default: ```makefile LINUX_VERSION ?= $(shell uname -r) KDIR ?= /lib/modules/$(LINUX_VERSION)/build ``` The Makefile also accepts KERNEL_SRC as an alternative, which the comment explains is the variable used by PetaLinux and Yocto. If KERNEL_SRC is set, KDIR is set from it, so a cross-compiled or embedded build can point at the right tree without patching anything. The module itself is built with the standard out-of-tree kernel build. The all target runs make in the kernel directory with M pointing at the source, and install does the same with modules_install: ```makefile all: $(MAKE) -C $(KDIR) M=$(shell pwd) modules install: $(MAKE) -C $(KDIR) M=$(shell pwd) modules_install ``` Two other targets are worth knowing about. The kdoc target runs the kernel's own scripts/kernel-doc over the source, which produces the API documentation. The checkpatch target runs scripts/checkpatch.pl with the --file, --strict and --codespell flags over the same source set, which is the kernel's own style checker. That Homa passes the kernel's own checkpatch is a meaningful signal about how the code is written, since checkpatch is unforgiving about kernel coding style. There is also a path for contributing upstream. The Makefile has targets for copying the stripped source files into a Linux source tree under net/homa, and the checkpatch-net-next variant that runs against that copied tree, which is the workflow for getting Homa considered for inclusion in the mainline kernel. ## The module's internals, as the file names reveal them The repository is a set of C files with descriptive names, and reading them tells you how the protocol is structured. The socket layer is homa_sock.c with homa_sock.h. The grant mechanism, which is the part of Homa that replaces congestion control, lives in homa_grant.c. Message routing is homa_outgoing.c and homa_incoming.c. Peer state and memory accounting are in homa_peer.c, with the memory pool in homa_pool.c. The RPC layer is homa_rpc.c. There is homa_interest.c for what a process is waiting for, homa_hijack.c for the mechanism that lets a process take over a flow, homa_offload.c for NIC offload, homa_tx_pool.c for transmit buffers, homa_timer.c for the timers, and homa_plumbing.c for the internal plumbing between the layers. Two of those files are unusual enough to call out. homa_receiver.cc is a C++ file in an otherwise C module, which usually means a component written in a different language for convenience and compiled in. homa_metrics.c is the metrics exporter, and homa_qdisc.c is the queueing discipline. The queuing discipline is one of the more interesting recent additions, and it exists for a specific reason. The January 2026 entry says the new homa_qdisc was introduced to improve performance when TCP and Homa run simultaneously, with results on a c6620 CloudLab cluster with a 100 Gbps network. Without it, running Homa and TCP together degrades Homa badly, with a 4x increase in P99 for short messages, while TCP actually improves. With it, both improve, and Homa's performance when running alongside TCP approaches what it achieves alone. That is the key practical detail about Homa: it does not simply replace TCP, it coexists with it, and the interaction between the two is a design problem the module has to solve. ## Benchmarks, metrics and the tools for working with it The util subdirectory holds utility programs for exercising and benchmarking Homa, compiled by typing make in that directory. The cp_node program can be run standalone on clients and servers for simple benchmarks. For a latency test you run cp_node server on one node of the cluster and cp_node client on another, where the client sends continuous back-to-back short requests and outputs timing information. For a throughput test, running cp_node client --workload 500000 on the client sends continuous 500 KB messages. cp_node --help lists the other options. The cp_bench script uses cp_node to run a variety of benchmarks and was used to generate the data for Figures 3 and 4 in the Homa ATC paper. The example given is: ```bash cp_bench -n 10 -w w4 -b 20 -B homa_vs_tcp ``` The -B option selects one of several benchmarks, and homa_vs_tcp runs both Homa and TCP on the same workload and generates graphs comparing them. Invoked on node0 it runs the W4 workload from the ATC paper, on 10 nodes, generating 20 Gbps of offered load, which the README notes is 80% network load on a 25 Gbps network. For observability there are two mechanisms. Homa collects metrics about its own behaviour, such as the size distribution of incoming messages, accessible through the file /proc/net/homa_metrics, and the script util/metrics.py collects those metrics and prints out all the numbers that have changed since its last run, which is a small but useful design for spotting change. And Homa exports a collection of configuration parameters through the sysctl mechanism, with details in the man page homa.7. There is also a dissector/ directory for Wireshark, and the test/ subdirectory contains unit tests you run by typing make in that directory. ## Where HomaModule is the wrong choice Three limits are structural and they are the reason Homa has not displaced TCP. The first is that the API is not sockets. Every application that wants to use Homa has to be written against a different interface, with its own man pages and its own semantics. There is no transparent mode where the same TCP application runs faster, because the whole point of Homa is that it is message-oriented and makes different scheduling decisions, and that requires the application to express things in those terms. The README links related work in this direction, a preliminary gRPC integration and a Go client, which tells you the ecosystem is thin and experimental. The second is the target hardware. The README states Homa is known to work with Mellanox ConnectX-4, ConnectX-5 and ConnectX-6 and the Intel E810 series using the ice driver, and asks for reports on other NICs. Homa's design leans on offload and on tight control over when packets go out, so it depends on driver support, and the list is short. A cluster on a different NIC family is a porting project. The third is the state of the tree. The 7.0.14 compile is explicitly unsupported and may bit-rot. The incast optimisation from the SIGCOMM paper is still missing, which is the pattern that matters most for the RPC workloads Homa is aimed at. The May 2025 removal of homa_api.c took away homa_abort, homa_reply, homa_replyv, homa_send and homa_sendv, and the April 2025 major refactoring of grant management is described as removing complexity that was causing an unending stream of bugs. That history reads like a system still finding its design. The alternative is TCP with a modern congestion control algorithm such as BBR, which keeps the socket API, keeps the hardware requirements to any decent NIC, and is deployed everywhere. The difference in approach is that BBR tries to reduce tail latency within the TCP framework, while Homa changes the transport's semantics to get there directly, and the price of that change is the API break and the driver dependency. The licence is listed as unknown, with no LICENSE file at the repository root, so anyone planning to use this beyond evaluation needs to establish the terms with the authors first, and for a kernel module that is a sharper constraint than for an ordinary library. ## Conclusion HomaModule suits a systems researcher or a cluster operator who has measured TCP tail latency to be the bottleneck and wants to try a protocol that optimises for it, since the module, the benchmarks and the dissection tooling are all here and the paper documents the design. It is the wrong tool if you need a drop-in replacement, because the API is not TCP sockets and every application has to be rewritten, and it is the wrong tool if you need multi-gigabit TCP throughput, which is the case Homa does not target. Verify first which kernel version you are on, since the head is known to work under Linux 6.17.8 with an unsupported 7.0.14 compile, and note that the incast optimisation from the SIGCOMM paper is still missing, with the last push on 2026-10-15. ## FAQ ### What is HomaModule? It is a Linux kernel module implementing the Homa transport protocol, described in the USENIX ATC 2021 paper A Linux Kernel Implementation of the Homa Transport Protocol. The protocol synopsis is in protocol.md and the general documentation is in the Homa Wiki. ### Which Linux versions does HomaModule support? The head is known to work under Linux 6.17.8 and is where development occurs, and it has recently been updated to compile under Linux 7.0.14, though those changes are not actively supported and may bit-rot. The rhel8 and rhel9.5 branches are maintained for Red Hat Enterprise Linux, and older kernels have separate branches named after the version. ### How do I build and install HomaModule? The README points to INSTALL.md for the full instructions, and the top-level Makefile builds the module out of tree against /lib/modules/$(uname -r)/build by default, with KERNEL_SRC accepted as an alternative for PetaLinux and Yocto builds. The all target builds the module and the install target runs modules_install. ### Does Homa work alongside TCP on the same machine? Yes, and there is a specific mechanism for it. The homa_qdisc queueing discipline was introduced in January 2026 to improve performance when TCP and Homa run simultaneously, since without it Homa's P99 for short messages suffers a 4x increase while TCP improves. With homa_qdisc both improve. ### What tools are available for benchmarking Homa? The util subdirectory holds cp_node for simple standalone latency and throughput benchmarks and the cp_bench script for the larger suites, with the -B option selecting a benchmark and homa_vs_tcp comparing Homa and TCP on the same workload. Metrics are exposed through /proc/net/homa_metrics and collected by util/metrics.py, and configuration parameters are set through sysctl. ### What is still missing from the Homa implementation? The incast optimisation from Section 3.6 of the SIGCOMM paper has not been implemented, which the README flags as the most significant missing functionality and which matters for the large-incast workloads RPC systems produce. The README invites contact if you want to test Homa under large incasts, offering to implement the feature. ## Sources - [Issues](https://github.com/PlatformLab/HomaModule/issues) - [PlatformLab/HomaModule on GitHub](https://github.com/PlatformLab/HomaModule) - [README](https://github.com/PlatformLab/HomaModule/blob/main/README.md) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/platformlab-homamodule