# rocm-ernic
[][license]
[][ci-build]
[][ci-build]
[][ci-docs]
[][ci-clang-format]
[][ci-shellcheck]
[][ci-pylint]
[][ci-cmakelint]
[][ci-codeql]
[][ci-system-tests]
[](INSTALL.md)
[][guest-kernel]
[][perf-trends]
[][perf-trends]
[][perf-trends]
[][perf-trends]
[][perf-trends]
> [!CAUTION]
> This release is an *early-access* software technology preview. Running
> production workloads is *not* recommended.
Userspace emulated RDMA NIC for virtual machines, built on
[libvfio-user][libvfio]. Provides full RDMA functionality to guest VMs without
requiring physical RDMA hardware or an in-guest software stack such as
[Soft-RoCE][softroce]. Backends include loopback (for testing and CI), TCP/IP
(multi-node without hardware), nvmeof (an in-process NVMe over Fabrics
target, so a single VM and a single server instance are a complete fabric — see
[`docs/nvmeof.rst`](docs/nvmeof.rst)), and s3 (an in-process S3-over-RDMA
object store with its own in-band HTTP endpoint, so the same single VM is a
complete object fabric — see [`docs/s3.rst`](docs/s3.rst)).
The server emulates an AMD Pensando ionic NIC (`1dd8:1002`, subsystem
`1dd8:5400`), so the guest runs the upstream Linux `ionic` and
`ionic_rdma` drivers with only the small UC address-handle patch in
[`ansible/files/patches/`](ansible/files/patches/) applied, and the upstream
`providers/ionic` in rdma-core. `--tap IFNAME` attaches the emulated Ethernet
interface to a host TAP, giving the guest a real routable segment with working
ARP, ICMP, and TCP/IP. See
[`docs/ionic.rst`](docs/ionic.rst) for details.
## Installing and Using rocm-ernic
See [INSTALL.md](INSTALL.md) for dependencies, supported platforms, and build
instructions.
## Releases
Project releases are published from `vX.Y.Z` tags and attach GitHub release
assets for the `rocm-ernic` server and `ernicctl`; see the
[Releases page](https://github.com/ROCm/rocm-ernic/releases).
The Ansible collection under [`ansible/`](ansible/) is not published to
Galaxy; install it from a pinned commit of this repo (see
[`ansible/README.md`](ansible/README.md)).
## Documentation
Full documentation lives in the [`docs/`](docs/) directory and covers building,
architecture, usage, the kernel driver, the systemd service, testing, and the
API reference.
## License
[MIT](LICENSE.md) for the build system, documentation, and the deployment and automation code;
everything under `src/` and `tests/`, and the fuzz harnesses in
`nix/analysis/fuzz/`, is `GPL-2.0-or-later` unless its per-file SPDX declaration
says otherwise. The patches under `ansible/files/patches/` take the licenses of
the Linux and rdma-core files they modify. The per-file SPDX header is
authoritative; see
[LICENSE.md](LICENSE.md) for details.
<!-- References -->
[license]: https://github.com/ROCm/rocm-ernic/blob/develop/LICENSE.md
[ci-build]: https://github.com/ROCm/rocm-ernic/actions/workflows/build-and-test.yml
[ci-docs]: https://github.com/ROCm/rocm-ernic/actions/workflows/docs-check.yml
[ci-clang-format]: https://github.com/ROCm/rocm-ernic/actions/workflows/clang-format.yml
[ci-shellcheck]: https://github.com/ROCm/rocm-ernic/actions/workflows/shellcheck.yml
[ci-pylint]: https://github.com/ROCm/rocm-ernic/actions/workflows/pylint.yml
[ci-cmakelint]: https://github.com/ROCm/rocm-ernic/actions/workflows/cmakelint.yml
[ci-codeql]: https://github.com/ROCm/rocm-ernic/actions/workflows/codeql.yml
[ci-system-tests]: https://github.com/ROCm/rocm-ernic/actions/workflows/system-tests.yml
[guest-kernel]: https://github.com/ROCm/rocm-ernic/blob/develop/docs/performance.rst
[perf-trends]: https://rocm.github.io/rocm-ernic/perf-trends.html
[libvfio]: https://github.com/nutanix/libvfio-user
[softroce]: https://man7.org/linux/man-pages/man7/rxe.7.html