uio 0.6.0

Helper library for writing linux user-space drivers with UIO.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64

# Linux UIO library for Rust

A thin abstraction library for writing user-space drivers in Linux by using the UIO facility (<https://www.kernel.org/doc/html/latest/driver-api/uio-howto.html>).

In order to use this library, you'll need to make sure your device uses the Linux UIO driver module. For example, the following
sample commands unload the ahci driver in Linux and use the `uio_pci_generic` module for the SSD disk for the PCI
device with vendor `0x8086` and device id `0x1d02`. (Note: Dangerous, don't do this if you don't know what you're doing).

```sh
$ modprobe -r ahci
$ sudo modprobe uio
$ sudo modprobe uio_pci_generic
$ echo "0x8086 0x1d02" > /sys/bus/pci/drivers/uio_pci_generic/new_id
$ lspci -v -d :0x1d02 | grep "Kernel driver in use"
```

Afterwards you should have one or more uio devices available in `/dev/uio*` which you can use to instantiate the
`UioDevice` struct:

```rust
use uio::UioDevice;

fn main() {
    let uio_num = 1; // /dev/uio1
    let dev = UioDevice::try_new(uio_num).unwrap();
    let mmap = dev.map_resource(5).unwrap();
}
```

For async projects, the `async-tokio` feature can be enabled, which allows async waiting for an IRQ:

```rust
async fn main() {
    let uio_num = 1; // /dev/uio1
    let dev = UioDevice::try_new(uio_num).unwrap();
    let mut async_uio: AsyncFd<UioDevice> = dev.try_into().unwrap();
    async_uio.get_mut().irq_enable().unwrap();
    async_uio.irq_wait().await.unwrap(); // Call irq_wait() directly on AsyncFd<UioDevice>
}
```

## Development

This repository contains a [Nix flake](/flake.nix) with a default development shell that can be used for Rust development.
Some information to [setup Nix](https://nixos.org/download/) can be found [here](https://gitlab.com/lriesebos/nix-sandbox).

To build this project:

```sh
nix develop
cargo build
```

## Resources

For more information about UIO check the following links:

- <https://lwn.net/Articles/232575/>
- <http://alvarom.com/2014/12/17/linux-user-space-drivers-with-interrupts/>
- <http://lxr.free-electrons.com/source/drivers/uio/uio_cif.c>
- <https://www.kernel.org/doc/html/latest/driver-api/uio-howto.html>
- <http://lxr.free-electrons.com/source/drivers/uio/uio_dmem_genirq.c>
- <http://www.osadl.org/projects/downloads/UIO/user/>
- <http://dpdk.org/browse/dpdk/tree/tools/dpdk_nic_bind.py>