libgpiod: Add Rust bindings

This adds libgpiod-sys rust crate, which provides FFI (foreign function interface) bindings for libgpiod APIs.

Signed-off-by Viresh Kumar <[email protected]>

---
 .gitignore                            |  5 ++++
 bindings/rust/Cargo.toml              |  5 ++++
 bindings/rust/libgpiod-sys/Cargo.toml | 15 ++++++++++
 bindings/rust/libgpiod-sys/build.rs   | 41 +++++++++++++++++++++++++++
 bindings/rust/libgpiod-sys/src/lib.rs | 13 +++++++++
 5 files changed, 79 insertions(+)
 create mode 100644 bindings/rust/Cargo.toml
 create mode 100644 bindings/rust/libgpiod-sys/Cargo.toml
 create mode 100644 bindings/rust/libgpiod-sys/build.rs
 create mode 100644 bindings/rust/libgpiod-sys/src/lib.rs

.gitignore +5 -0

index 6c08415b390d..9f2fcf440c5d 100644
@@ -35,3 +35,8 @@ stamp-h1
 # profiling
 *.gcda
 *.gcno
+
+# Added by cargo
+
+target
+Cargo.lock

bindings/rust/Cargo.toml new file +5 -0

new file mode 100644
index 000000000000..d0b3a3c88ff1
@@ -0,0 +1,5 @@
+[workspace]
+
+members = [
+    "libgpiod-sys",
+]

bindings/rust/libgpiod-sys/Cargo.toml new file +0 -0

new file mode 100644
index 000000000000..77f82719d269

bindings/rust/libgpiod-sys/Cargo.toml new file +10 -0

+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+
+[features]
+generate = [ "bindgen" ]
+
+[build-dependencies]
+bindgen = { version = "0.59.1", optional = true }
+cc = "1.0.46"

bindings/rust/libgpiod-sys/build.rs new file +41 -0

new file mode 100644
index 000000000000..98863686c7af
@@ -0,0 +1,41 @@
+#[cfg(feature = "generate")]
+extern crate bindgen;
+#[cfg(feature = "generate")]
+use std::env;
+#[cfg(feature = "generate")]
+use std::path::PathBuf;
+
+#[cfg(feature = "generate")]
+fn generate_bindings() {
+    // Tell cargo to invalidate the built crate whenever following files change
+    println!("cargo:rerun-if-changed=../../../include/gpiod.h");
+
+    // The bindgen::Builder is the main entry point
+    // to bindgen, and lets you build up options for
+    // the resulting bindings.
+    let bindings = bindgen::Builder::default()
+        // The input header we would like to generate
+        // bindings for.
+        .header("../../../include/gpiod.h")
+        // Tell cargo to invalidate the built crate whenever any of the
+        // included header files changed.
+        .parse_callbacks(Box::new(bindgen::CargoCallbacks))
+        // Finish the builder and generate the bindings.
+        .generate()
+        // Unwrap the Result and panic on failure.
+        .expect("Unable to generate bindings");
+
+    // Write the bindings to the $OUT_DIR/bindings.rs file.
+    let out_path = PathBuf::from(env::var("OUT_DIR").unwrap());
+    bindings
+        .write_to_file(out_path.join("bindings.rs"))
+        .expect("Couldn't write bindings!");
+}
+
+fn main() {
+    #[cfg(feature = "generate")]
+    generate_bindings();
+
+    println!("cargo:rustc-link-search=./../../lib/.libs/");
+    println!("cargo:rustc-link-lib=static=gpiod");
+}

bindings/rust/libgpiod-sys/src/lib.rs new file +0 -0

new file mode 100644
index 000000000000..1ca355b5f5ac

bindings/rust/libgpiod-sys/src/lib.rs new file +11 -0

+#[allow(non_camel_case_types, non_upper_case_globals)]
+#[cfg_attr(test, allow(deref_nullptr, non_snake_case))]
+
+mod bindings_raw {
+    #[cfg(feature = "generate")]
+    include!(concat!(env!("OUT_DIR"), "/bindings.rs"));
+
+    #[cfg(not(feature = "generate"))]
+    include!("bindings.rs");
+}
+pub use bindings_raw::*;

Signature · 1 line

2.31.1.272.g89b43f80a514

Quoted 5 lines

bindings/rust/libgpiod-sys/Cargo.toml new file +0 -0

new file mode 100644
index 000000000000..77f82719d269

bindings/rust/libgpiod-sys/Cargo.toml line 5

Quoted 6 lines

bindings/rust/libgpiod-sys/Cargo.toml new file +5 -0

@@ -0,0 +1,15 @@
+[package]
+name = "libgpiod-sys"
+version = "0.1.0"
+edition = "2018"
+

Add license and other relevant keys as per the link you helpfully include...

bindings/rust/libgpiod-sys/src/lib.rs line 2

Quoted 8 lines

bindings/rust/libgpiod-sys/src/lib.rs new file +2 -0

new file mode 100644
index 000000000000..1ca355b5f5ac
@@ -0,0 +1,13 @@
+// SPDX-License-Identifier: GPL-2.0
+

GPL-2.0?

Elsewhere you use Apache 2.0 AND BSD-3-Clause for rust code.

+description = "A rust library for libgpiod public header bindings"

+repository = "https://git.kernel.org/pub/scm/libs/libgpiod/libgpiod.git/"

Quoted 5 lines · Kent Gibson

Quoted 5 lines

bindings/rust/libgpiod-sys/Cargo.toml new file +0 -0

new file mode 100644
index 000000000000..77f82719d269

Quoted 8 lines

bindings/rust/libgpiod-sys/Cargo.toml line 5

Quoted 6 lines

bindings/rust/libgpiod-sys/Cargo.toml new file +5 -0

@@ -0,0 +1,15 @@
+[package]
+name = "libgpiod-sys"
+version = "0.1.0"
+edition = "2018"
+

Add license and other relevant keys as per the link you helpfully include...

Is this enough ?

bindings/rust/libgpiod-sys/Cargo.toml +0 -0

index 77f82719d269..af4098cb137d 100644

I picked license details from C code, is that what we should be using here too ?

You should add "categories" and "documentation" if you intend to publish to crates.io.

LGPL is probably not appropriate here, as the binding code ends up being part of the binary - unless you plan to package it as a dynamic library?

The licenses of your dependencies are:

$ cargo license
(MIT OR Apache-2.0) AND Unicode-DFS-2016 (1): unicode-ident
Apache-2.0 AND BSD-3-Clause (1): vmm-sys-util

Apache-2.0 OR MIT (8): bitflags, cc, libc, proc-macro2, quote, syn, thiserror, thiserror-impl MIT (1): intmap
N/A (3): gpiosim, libgpiod, libgpiod-sys

IANAL, but one or more of those would be more appropriate than either GPL or LGPL.
You, Bart and linaro(?) will have to come to some agreement on which license or combination to go with - it depends.

Quoted 2 lines · Kent Gibson

You should add "categories" and "documentation" if you intend to publish to crates.io.

In order to add documentations, should I commit documentation (created with cargo) as well in libgpiod, so I get a link to it ?

Quoted 4 lines

LGPL is probably not appropriate here, as the binding code ends up being part of the binary - unless you plan to package it as a dynamic library?

Quoted 4 lines

The licenses of your dependencies are:

$ cargo license
(MIT OR Apache-2.0) AND Unicode-DFS-2016 (1): unicode-ident
Apache-2.0 AND BSD-3-Clause (1): vmm-sys-util

This is the license used by the user crate for libgpiod, vhost-device, I am inclined to use this then, unless someone has an objection to it.

Quoted 8 lines

Apache-2.0 OR MIT (8): bitflags, cc, libc, proc-macro2, quote, syn, thiserror, thiserror-impl MIT (1): intmap
N/A (3): gpiosim, libgpiod, libgpiod-sys

IANAL, but one or more of those would be more appropriate than either GPL or LGPL.
You, Bart and linaro(?) will have to come to some agreement on which license or combination to go with - it depends.

Signature · 1 line

viresh

That doesn't really work - you get a link to the files in github, not as a web site. You need somewhere that will host those generated files as a web site. You could do that with github-pages if you don't have other options.

When I've done that I would commit the docs to a separate branch, just for the docs, and have github-pages host that branch.

If you eventually publish your crate to crates.io you get documentation on docs.rs for free - and you can skip the documentation key in that case too
- it defaults to the appropriate page on docs.rs.

I assume that would be the case long term - you just need to find someway to host them in the meantime.

Quoted 4 lines · Kent Gibson

That doesn't really work - you get a link to the files in github, not as a web site. You need somewhere that will host those generated files as a web site. You could do that with github-pages if you don't have other options.

I don't have other options for now, so it is github.

Quoted 2 lines

When I've done that I would commit the docs to a separate branch, just for the docs, and have github-pages host that branch.

Okay.

Quoted 3 lines

If you eventually publish your crate to crates.io you get documentation on docs.rs for free - and you can skip the documentation key in that case too
- it defaults to the appropriate page on docs.rs.

Right, that I knew.

Quoted 2 lines

I assume that would be the case long term - you just need to find someway to host them in the meantime.

I wonder if we should be doing this at all right now, or if required only Bartosz should do it instead of me, once this is merged ?

Maybe we need a libgpiod username for that on github ? To make it independent of personal usernames ? From what I saw, the website name will be username.github.io eventually.

I was assuming it was an interim solution, so it doesn't matter so much.

I'd be happy with docs.rs once libgpiod v2 is released and the bindings published to crates.io, and I'm personally good with looking at the generated docs locally in the meantime.

It would be easier for others to take a look if the docs were hosted, but I don't have any feel as to whether that is worth the effort or not.

Quoted 17 lines · Viresh Kumar

Quoted 4 lines · Kent Gibson

That doesn't really work - you get a link to the files in github, not as a web site. You need somewhere that will host those generated files as a web site. You could do that with github-pages if you don't have other options.

I don't have other options for now, so it is github.

Quoted 2 lines

When I've done that I would commit the docs to a separate branch, just for the docs, and have github-pages host that branch.

Okay.

Quoted 3 lines

If you eventually publish your crate to crates.io you get documentation on docs.rs for free - and you can skip the documentation key in that case too
- it defaults to the appropriate page on docs.rs.

Quoted 8 lines

Right, that I knew.

Quoted 2 lines

I assume that would be the case long term - you just need to find someway to host them in the meantime.

I wonder if we should be doing this at all right now, or if required only Bartosz should do it instead of me, once this is merged ?

I was assuming it was an interim solution, so it doesn't matter so much.

I'd be happy with docs.rs once libgpiod v2 is released and the bindings published to crates.io, and I'm personally good with looking at the generated docs locally in the meantime.

It would be easier for others to take a look if the docs were hosted, but I don't have any feel as to whether that is worth the effort or not.

Quoted 4 lines

Maybe we need a libgpiod username for that on github ? To make it independent of personal usernames ? From what I saw, the website name will be username.github.io eventually.

A libgpiod group account might be useful.

And it would be nice to have a libgpiod space somewhere, not just piggybacking on the gpio mailing list. Not sure if github is the best place - but I haven't given it much thought.

Bart, do you have any opinions?

Add rust wrapper crate, around the libpiod-sys crate added earlier, to provide a convenient interface for the users.

Signed-off-by Viresh Kumar <[email protected]>

---
 bindings/rust/Cargo.toml                     |   1 +
 bindings/rust/libgpiod/Cargo.toml            |  13 +
 bindings/rust/libgpiod/src/chip.rs           | 253 ++++++++++
 bindings/rust/libgpiod/src/edge_event.rs     | 101 ++++
 bindings/rust/libgpiod/src/event_buffer.rs   |  66 +++
 bindings/rust/libgpiod/src/info_event.rs     |  68 +++
 bindings/rust/libgpiod/src/lib.rs            | 471 +++++++++++++++++++
 bindings/rust/libgpiod/src/line_config.rs    | 118 +++++
 bindings/rust/libgpiod/src/line_info.rs      | 180 +++++++
 bindings/rust/libgpiod/src/line_request.rs   | 246 ++++++++++
 bindings/rust/libgpiod/src/line_settings.rs  | 277 +++++++++++
 bindings/rust/libgpiod/src/request_config.rs |  96 ++++
 12 files changed, 1890 insertions(+)
 create mode 100644 bindings/rust/libgpiod/Cargo.toml
 create mode 100644 bindings/rust/libgpiod/src/chip.rs
 create mode 100644 bindings/rust/libgpiod/src/edge_event.rs
 create mode 100644 bindings/rust/libgpiod/src/event_buffer.rs
 create mode 100644 bindings/rust/libgpiod/src/info_event.rs
 create mode 100644 bindings/rust/libgpiod/src/lib.rs
 create mode 100644 bindings/rust/libgpiod/src/line_config.rs
 create mode 100644 bindings/rust/libgpiod/src/line_info.rs
 create mode 100644 bindings/rust/libgpiod/src/line_request.rs
 create mode 100644 bindings/rust/libgpiod/src/line_settings.rs
 create mode 100644 bindings/rust/libgpiod/src/request_config.rs

bindings/rust/Cargo.toml +1 -0

index d0b3a3c88ff1..1e57ef2c0002 100644
@@ -2,4 +2,5 @@
 
 members = [
     "libgpiod-sys",
+    "libgpiod"
 ]

bindings/rust/libgpiod/Cargo.toml new file +0 -0

new file mode 100644
index 000000000000..f25242abb153

bindings/rust/libgpiod/Cargo.toml new file +9 -0

+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+intmap = "2.0.0"
+libc = ">=0.2.39"
+libgpiod-sys = { path = "../libgpiod-sys" }
+thiserror = "1.0"
+vmm-sys-util = "=0.10.0"

bindings/rust/libgpiod/src/chip.rs new file +0 -0

new file mode 100644
index 000000000000..4f52c3f141f4

bindings/rust/libgpiod/src/chip.rs new file +4 -0

+        if chip.is_null() {
+            return Err(Error::OperationFailed(
+                OperationType::ChipOpen,
+                Errno::last(),

bindings/rust/libgpiod/src/chip.rs new file +11 -0

+}
+
+impl Drop for Internal {
+    /// Close the chip and release all associated resources.
+    fn drop(&mut self) {
+        unsafe { gpiod::gpiod_chip_close(self.chip) }
+    }
+}
+
+/// GPIO chip
+///

bindings/rust/libgpiod/src/chip.rs new file +23 -0

+        Ok(Self { ichip, info })
+    }
+
+    /// Get the chip name as represented in the kernel.
+    pub fn name(&self) -> Result<&str> {
+        self.info.name()
+    }
+
+    /// Get the chip label as represented in the kernel.
+    pub fn label(&self) -> Result<&str> {
+        self.info.label()
+    }
+
+    /// Get the number of GPIO lines exposed by the chip.
+    pub fn num_lines(&self) -> usize {
+        self.info.num_lines()
+    }
+
+    /// Get the path used to find the chip.
+    pub fn path(&self) -> Result<&str> {
+        // SAFETY: The string returned by libgpiod is guaranteed to live as long
+        // as the `struct Chip`.
+        let path = unsafe { gpiod::gpiod_chip_get_path(self.ichip.chip()) };

bindings/rust/libgpiod/src/chip.rs new file +69 -0

+
+    /// Get a snapshot of information about the line.
+    pub fn line_info(&self, offset: Offset) -> Result<line::Info> {
+        line::Info::new(self.ichip.clone(), offset)
+    }
+
+    /// Get the current snapshot of information about the line at given offset and start watching
+    /// it for future changes.
+    pub fn watch_line_info(&self, offset: Offset) -> Result<line::Info> {
+        line::Info::new_watch(self.ichip.clone(), offset)
+    }
+
+    /// Stop watching a line
+    pub fn unwatch(&self, offset: Offset) {
+        unsafe {
+            gpiod::gpiod_chip_unwatch_line_info(self.ichip.chip(), offset);
+        }
+    }
+
+    /// Get the file descriptor associated with the chip.
+    ///
+    /// The returned file descriptor must not be closed by the caller, else other methods for the
+    /// `struct Chip` may fail.
+    pub fn fd(&self) -> Result<u32> {
+        let fd = unsafe { gpiod::gpiod_chip_get_fd(self.ichip.chip()) };
+
+        if fd < 0 {
+            Err(Error::OperationFailed(
+                OperationType::ChipGetFd,
+                Errno::last(),
+            ))
+        } else {
+            Ok(fd as u32)
+        }
+    }
+
+    /// Wait for line status events on any of the watched lines on the chip.
+    pub fn wait_info_event(&self, timeout: Option<Duration>) -> Result<bool> {
+        let timeout = match timeout {
+            Some(x) => x.as_nanos() as i64,
+            // Block indefinitely
+            None => -1,
+        };
+
+        let ret = unsafe { gpiod::gpiod_chip_wait_info_event(self.ichip.chip(), timeout) };
+
+        match ret {
+            -1 => Err(Error::OperationFailed(
+                OperationType::ChipWaitInfoEvent,
+                Errno::last(),
+            )),
+            0 => Ok(false),
+            _ => Ok(true),
+        }
+    }
+
+    /// Read a single line status change event from the chip. If no events are
+    /// pending, this function will block.
+    pub fn read_info_event(&self) -> Result<info::Event> {
+        info::Event::new(&self.ichip)
+    }
+
+    /// Map a GPIO line's name to its offset within the chip.
+    pub fn line_offset_from_name(&self, name: &str) -> Result<Offset> {
+        // Null-terminate the string
+        let name = name.to_owned() + "\0";
+
+        let ret = unsafe {
+            gpiod::gpiod_chip_get_line_offset_from_name(

bindings/rust/libgpiod/src/chip.rs new file +11 -0

+        } else {
+            Ok(ret as u32)
+        }
+    }
+
+    /// Request a set of lines for exclusive usage.
+    pub fn request_lines(
+        &self,
+        rconfig: &request::Config,
+        lconfig: &line::Config,
+    ) -> Result<line::Request> {

bindings/rust/libgpiod/src/chip.rs new file +35 -0

+
+    /// Get the GPIO chip name as represented in the kernel.
+    pub(crate) fn name(&self) -> Result<&str> {
+        // SAFETY: The string returned by libgpiod is guaranteed to live as long
+        // as the `struct Chip`.
+        let name = unsafe { gpiod::gpiod_chip_info_get_name(self.info) };
+
+        // SAFETY: The string is guaranteed to be valid here by the C API.
+        str::from_utf8(unsafe { slice::from_raw_parts(name as *const u8, strlen(name) as usize) })
+            .map_err(Error::StringNotUtf8)
+    }
+
+    /// Get the GPIO chip label as represented in the kernel.
+    pub(crate) fn label(&self) -> Result<&str> {
+        // SAFETY: The string returned by libgpiod is guaranteed to live as long
+        // as the `struct Chip`.
+        let label = unsafe { gpiod::gpiod_chip_info_get_label(self.info) };
+
+        // SAFETY: The string is guaranteed to be valid here by the C API.
+        str::from_utf8(unsafe { slice::from_raw_parts(label as *const u8, strlen(label) as usize) })
+            .map_err(Error::StringNotUtf8)
+    }
+
+    /// Get the number of GPIO lines exposed by the chip.
+    pub(crate) fn num_lines(&self) -> usize {
+        unsafe { gpiod::gpiod_chip_info_get_num_lines(self.info) as usize }
+    }
+}
+
+impl Drop for Info {
+    /// Close the GPIO chip info and release all associated resources.
+    fn drop(&mut self) {
+        unsafe { gpiod::gpiod_chip_info_free(self.info) }
+    }
+}

bindings/rust/libgpiod/src/edge_event.rs new file +101 -0

new file mode 100644
index 000000000000..12c0fd73f778
@@ -0,0 +1,101 @@
+// SPDX-License-Identifier: Apache-2.0 AND BSD-3-Clause
+//
+// Copyright 2022 Linaro Ltd. All Rights Reserved.
+//     Viresh Kumar <[email protected]>
+
+use std::time::Duration;
+
+use vmm_sys_util::errno::Error as Errno;
+
+use super::{edge::event::Buffer, gpiod, EdgeKind, Error, Offset, OperationType, Result};
+
+/// Line edge events handling
+///
+/// An edge event object contains information about a single line edge event.
+/// It contains the event type, timestamp and the offset of the line on which
+/// the event occurred as well as two sequence numbers (global for all lines
+/// in the associated request and local for this line only).
+///
+/// Edge events are stored into an edge-event buffer object to improve
+/// performance and to limit the number of memory allocations when a large
+/// number of events are being read.
+
+#[derive(Debug, Eq, PartialEq)]
+pub struct Event<'b> {
+    buffer: Option<&'b Buffer>,
+    event: *mut gpiod::gpiod_edge_event,
+}
+
+impl<'b> Event<'b> {
+    /// Get an event stored in the buffer.
+    pub(crate) fn new(buffer: &'b Buffer, index: u64) -> Result<Self> {
+        let event = unsafe { gpiod::gpiod_edge_event_buffer_get_event(buffer.buffer(), index) };
+        if event.is_null() {
+            return Err(Error::OperationFailed(
+                OperationType::EdgeEventBufferGetEvent,
+                Errno::last(),
+            ));
+        }
+
+        Ok(Self {
+            buffer: Some(buffer),
+            event,
+        })
+    }
+
+    pub fn event_clone(event: &Event) -> Result<Self> {
+        let event = unsafe { gpiod::gpiod_edge_event_copy(event.event) };
+        if event.is_null() {
+            return Err(Error::OperationFailed(
+                OperationType::EdgeEventCopy,
+                Errno::last(),
+            ));
+        }
+
+        Ok(Self {
+            buffer: None,
+            event,
+        })
+    }
+
+    /// Get the event type.
+    pub fn event_type(&self) -> Result<EdgeKind> {
+        EdgeKind::new(unsafe { gpiod::gpiod_edge_event_get_event_type(self.event) } as u32)
+    }
+
+    /// Get the timestamp of the event.
+    pub fn timestamp(&self) -> Duration {
+        Duration::from_nanos(unsafe { gpiod::gpiod_edge_event_get_timestamp_ns(self.event) })
+    }
+
+    /// Get the offset of the line on which the event was triggered.
+    pub fn line_offset(&self) -> Offset {
+        unsafe { gpiod::gpiod_edge_event_get_line_offset(self.event) }
+    }
+
+    /// Get the global sequence number of the event.
+    ///
+    /// Returns sequence number of the event relative to all lines in the
+    /// associated line request.
+    pub fn global_seqno(&self) -> u64 {
+        unsafe { gpiod::gpiod_edge_event_get_global_seqno(self.event) }
+    }
+
+    /// Get the event sequence number specific to concerned line.
+    ///
+    /// Returns sequence number of the event relative to the line within the
+    /// lifetime of the associated line request.
+    pub fn line_seqno(&self) -> u64 {
+        unsafe { gpiod::gpiod_edge_event_get_line_seqno(self.event) }
+    }
+}
+
+impl<'b> Drop for Event<'b> {
+    /// Free the edge event.
+    fn drop(&mut self) {
+        // Free the event only if a copy is made
+        if self.buffer.is_none() {
+            unsafe { gpiod::gpiod_edge_event_free(self.event) };
+        }
+    }
+}

bindings/rust/libgpiod/src/event_buffer.rs new file +6 -0

new file mode 100644
index 000000000000..11c8b5e1d7c9
@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: Apache-2.0 AND BSD-3-Clause
+//
+// Copyright 2022 Linaro Ltd. All Rights Reserved.
+//     Viresh Kumar <[email protected]>
+
+use std::os::raw::c_ulong;

bindings/rust/libgpiod/src/event_buffer.rs new file +12 -0

+
+impl Buffer {
+    /// Create a new edge event buffer.
+    ///
+    /// If capacity equals 0, it will be set to a default value of 64. If
+    /// capacity is larger than 1024, it will be limited to 1024.
+    pub fn new(capacity: usize) -> Result<Self> {
+        let buffer = unsafe { gpiod::gpiod_edge_event_buffer_new(capacity as c_ulong) };
+        if buffer.is_null() {
+            return Err(Error::OperationFailed(
+                OperationType::EdgeEventBufferNew,
+                Errno::last(),

bindings/rust/libgpiod/src/event_buffer.rs new file +18 -0

+
+    /// Get the number of events the buffer contains.
+    pub fn len(&self) -> usize {
+        unsafe { gpiod::gpiod_edge_event_buffer_get_num_events(self.buffer()) as usize }
+    }
+
+    /// Check if buffer is empty.
+    pub fn is_empty(&self) -> bool {
+        self.len() == 0
+    }
+}
+
+impl Drop for Buffer {
+    /// Free the edge event buffer and release all associated resources.
+    fn drop(&mut self) {
+        unsafe { gpiod::gpiod_edge_event_buffer_free(self.buffer) };
+    }
+}

bindings/rust/libgpiod/src/info_event.rs new file +17 -0

new file mode 100644
index 000000000000..d8be87df6679
@@ -0,0 +1,68 @@
+// SPDX-License-Identifier: Apache-2.0 AND BSD-3-Clause
+//
+// Copyright 2022 Linaro Ltd. All Rights Reserved.
+//     Viresh Kumar <[email protected]>
+
+use std::sync::Arc;
+use std::time::Duration;
+
+use vmm_sys_util::errno::Error as Errno;
+
+use super::{chip, gpiod, line, Error, InfoChangeKind, OperationType, Result};
+
+/// Line status watch events
+///
+/// Accessors for the info event objects allowing to monitor changes in GPIO
+/// line state.
+///

bindings/rust/libgpiod/src/info_event.rs new file +28 -0

+
+    /// Private helper, Returns gpiod_info_event
+    pub(crate) fn event(&self) -> *mut gpiod::gpiod_info_event {
+        self.event
+    }
+
+    /// Get the event type of the status change event.
+    pub fn event_type(&self) -> Result<InfoChangeKind> {
+        InfoChangeKind::new(unsafe { gpiod::gpiod_info_event_get_event_type(self.event) } as u32)
+    }
+
+    /// Get the timestamp of the event, read from the monotonic clock.
+    pub fn timestamp(&self) -> Duration {
+        Duration::from_nanos(unsafe { gpiod::gpiod_info_event_get_timestamp_ns(self.event) })
+    }
+
+    /// Get the line-info object associated with the event.
+    pub fn line_info(&self) -> Result<line::Info> {
+        line::Info::new_from_event(self)
+    }
+}
+
+impl Drop for Event {
+    /// Free the info event object and release all associated resources.
+    fn drop(&mut self) {
+        unsafe { gpiod::gpiod_info_event_free(self.event) }
+    }
+}

bindings/rust/libgpiod/src/lib.rs new file +12 -0

new file mode 100644
index 000000000000..c5d974a9f4ea
@@ -0,0 +1,471 @@
+// SPDX-License-Identifier: Apache-2.0 AND BSD-3-Clause
+//
+// Rust wrappers for GPIOD APIs
+//
+// Copyright 2022 Linaro Ltd. All Rights Reserved.
+//     Viresh Kumar <[email protected]>
+
+//! libgpiod public API
+//!
+//! This is the complete documentation of the public Rust API made available to
+//! users of libgpiod.
+//!

bindings/rust/libgpiod/src/lib.rs new file +90 -0

+
+mod request_config;
+
+/// GPIO chip request related definitions.
+pub mod request {
+    pub use crate::request_config::*;
+}
+
+use libgpiod_sys as gpiod;
+
+use intmap::IntMap;
+use libc::strlen;
+use std::fs;
+use std::os::raw::c_char;
+use std::path::Path;
+use std::time::Duration;
+use std::{fmt, slice, str};
+
+use thiserror::Error as ThisError;
+use vmm_sys_util::errno::Error as Errno;
+
+/// Operation types, used with OperationFailed() Error.
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub enum OperationType {
+    ChipOpen,
+    ChipGetFd,
+    ChipWaitInfoEvent,
+    ChipGetLine,
+    ChipGetLineInfo,
+    ChipInfoGet,
+    ChipReadInfoEvent,
+    ChipWatchLineInfo,
+    EdgeEventBufferGetEvent,
+    EdgeEventCopy,
+    EdgeEventBufferNew,
+    InfoEventGetLineInfo,
+    LineConfigNew,
+    LineConfigAddSettings,
+    LineConfigGetOffsets,
+    LineConfigGetSetting,
+    LineRequest,
+    LineRequestReconfigLines,
+    LineRequestGetVal,
+    LineRequestGetValSubset,
+    LineRequestSetVal,
+    LineRequestSetValSubset,
+    LineRequestReadEdgeEvent,
+    LineRequestWaitEdgeEvent,
+    LineSettingsNew,
+    LineSettingsCopy,
+    LineSettingsGetOutVal,
+    LineSettingsSetDirection,
+    LineSettingsSetEdgeDetection,
+    LineSettingsSetBias,
+    LineSettingsSetDrive,
+    LineSettingsSetActiveLow,
+    LineSettingsSetDebouncePeriod,
+    LineSettingsSetEventClock,
+    LineSettingsSetOutputValue,
+    RequestConfigNew,
+    RequestConfigGetConsumer,
+    SimBankGetVal,
+    SimBankNew,
+    SimBankSetLabel,
+    SimBankSetNumLines,
+    SimBankSetLineName,
+    SimBankSetPull,
+    SimBankHogLine,
+    SimCtxNew,
+    SimDevNew,
+    SimDevEnable,
+    SimDevDisable,
+}
+
+impl fmt::Display for OperationType {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "{:?}", self)
+    }
+}
+
+/// Result of libgpiod operations.
+pub type Result<T> = std::result::Result<T, Error>;
+
+/// Error codes for libgpiod operations.
+#[derive(Copy, Clone, Debug, PartialEq, ThisError)]
+pub enum Error {
+    #[error("Failed to get {0}")]
+    NullString(&'static str),
+    #[error("String not utf8: {0:?}")]
+    StringNotUtf8(str::Utf8Error),

bindings/rust/libgpiod/src/lib.rs new file +10 -0

+/// Value settings.
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub enum Value {
+    /// Active
+    Active,
+    /// Inactive
+    InActive,
+}
+
+/// Maps offset to Value.

bindings/rust/libgpiod/src/lib.rs new file +274 -0

+
+    fn value(&self) -> i32 {
+        match self {
+            Value::Active => 1,
+            Value::InActive => 0,
+        }
+    }
+}
+
+/// Offset type.
+pub type Offset = u32;
+
+/// Direction settings.
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub enum Direction {
+    /// Request the line(s), but don't change direction.
+    AsIs,
+    /// Direction is input - for reading the value of an externally driven GPIO line.
+    Input,
+    /// Direction is output - for driving the GPIO line.
+    Output,
+}
+
+impl Direction {
+    fn new(dir: u32) -> Result<Self> {
+        match dir {
+            gpiod::GPIOD_LINE_DIRECTION_AS_IS => Ok(Direction::AsIs),
+            gpiod::GPIOD_LINE_DIRECTION_INPUT => Ok(Direction::Input),
+            gpiod::GPIOD_LINE_DIRECTION_OUTPUT => Ok(Direction::Output),
+            _ => Err(Error::InvalidEnumValue("Direction", dir)),
+        }
+    }
+
+    fn gpiod_direction(&self) -> u32 {
+        match self {
+            Direction::AsIs => gpiod::GPIOD_LINE_DIRECTION_AS_IS,
+            Direction::Input => gpiod::GPIOD_LINE_DIRECTION_INPUT,
+            Direction::Output => gpiod::GPIOD_LINE_DIRECTION_OUTPUT,
+        }
+    }
+}
+
+/// Internal bias settings.
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub enum Bias {
+    /// The internal bias is disabled.
+    Disabled,
+    /// The internal pull-up bias is enabled.
+    PullUp,
+    /// The internal pull-down bias is enabled.
+    PullDown,
+}
+
+impl Bias {
+    fn new(bias: u32) -> Result<Option<Self>> {
+        match bias {
+            gpiod::GPIOD_LINE_BIAS_UNKNOWN => Ok(None),
+            gpiod::GPIOD_LINE_BIAS_AS_IS => Ok(None),
+            gpiod::GPIOD_LINE_BIAS_DISABLED => Ok(Some(Bias::Disabled)),
+            gpiod::GPIOD_LINE_BIAS_PULL_UP => Ok(Some(Bias::PullUp)),
+            gpiod::GPIOD_LINE_BIAS_PULL_DOWN => Ok(Some(Bias::PullDown)),
+            _ => Err(Error::InvalidEnumValue("Bias", bias)),
+        }
+    }
+
+    fn gpiod_bias(bias: Option<Bias>) -> u32 {
+        match bias {
+            None => gpiod::GPIOD_LINE_BIAS_AS_IS,
+            Some(bias) => match bias {
+                Bias::Disabled => gpiod::GPIOD_LINE_BIAS_DISABLED,
+                Bias::PullUp => gpiod::GPIOD_LINE_BIAS_PULL_UP,
+                Bias::PullDown => gpiod::GPIOD_LINE_BIAS_PULL_DOWN,
+            },
+        }
+    }
+}
+
+/// Drive settings.
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub enum Drive {
+    /// Drive setting is push-pull.
+    PushPull,
+    /// Line output is open-drain.
+    OpenDrain,
+    /// Line output is open-source.
+    OpenSource,
+}
+
+impl Drive {
+    fn new(drive: u32) -> Result<Self> {
+        match drive {
+            gpiod::GPIOD_LINE_DRIVE_PUSH_PULL => Ok(Drive::PushPull),
+            gpiod::GPIOD_LINE_DRIVE_OPEN_DRAIN => Ok(Drive::OpenDrain),
+            gpiod::GPIOD_LINE_DRIVE_OPEN_SOURCE => Ok(Drive::OpenSource),
+            _ => Err(Error::InvalidEnumValue("Drive", drive)),
+        }
+    }
+
+    fn gpiod_drive(&self) -> u32 {
+        match self {
+            Drive::PushPull => gpiod::GPIOD_LINE_DRIVE_PUSH_PULL,
+            Drive::OpenDrain => gpiod::GPIOD_LINE_DRIVE_OPEN_DRAIN,
+            Drive::OpenSource => gpiod::GPIOD_LINE_DRIVE_OPEN_SOURCE,
+        }
+    }
+}
+
+/// Edge detection settings.
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub enum Edge {
+    /// Line detects rising edge events.
+    Rising,
+    /// Line detects falling edge events.
+    Falling,
+    /// Line detects both rising and falling edge events.
+    Both,
+}
+
+impl Edge {
+    fn new(edge: u32) -> Result<Option<Self>> {
+        match edge {
+            gpiod::GPIOD_LINE_EDGE_NONE => Ok(None),
+            gpiod::GPIOD_LINE_EDGE_RISING => Ok(Some(Edge::Rising)),
+            gpiod::GPIOD_LINE_EDGE_FALLING => Ok(Some(Edge::Falling)),
+            gpiod::GPIOD_LINE_EDGE_BOTH => Ok(Some(Edge::Both)),
+            _ => Err(Error::InvalidEnumValue("Edge", edge)),
+        }
+    }
+
+    fn gpiod_edge(edge: Option<Edge>) -> u32 {
+        match edge {
+            None => gpiod::GPIOD_LINE_EDGE_NONE,
+            Some(edge) => match edge {
+                Edge::Rising => gpiod::GPIOD_LINE_EDGE_RISING,
+                Edge::Falling => gpiod::GPIOD_LINE_EDGE_FALLING,
+                Edge::Both => gpiod::GPIOD_LINE_EDGE_BOTH,
+            },
+        }
+    }
+}
+
+/// Line setting kind.
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub enum SettingKind {
+    /// Line direction.
+    Direction,
+    /// Bias.
+    Bias,
+    /// Drive.
+    Drive,
+    /// Edge detection.
+    EdgeDetection,
+    /// Active-low setting.
+    ActiveLow,
+    /// Debounce period.
+    DebouncePeriod,
+    /// Event clock type.
+    EventClock,
+    /// Output value.
+    OutputValue,
+}
+
+/// Line settings.
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub enum SettingVal {
+    /// Line direction.
+    Direction(Direction),
+    /// Bias.
+    Bias(Option<Bias>),
+    /// Drive.
+    Drive(Drive),
+    /// Edge detection.
+    EdgeDetection(Option<Edge>),
+    /// Active-low setting.
+    ActiveLow(bool),
+    /// Debounce period.
+    DebouncePeriod(Duration),
+    /// Event clock type.
+    EventClock(EventClock),
+    /// Output value.
+    OutputValue(Value),
+}
+
+impl fmt::Display for SettingVal {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "{:?}", self)
+    }
+}
+
+/// Event clock settings.
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub enum EventClock {
+    /// Line uses the monotonic clock for edge event timestamps.
+    Monotonic,
+    /// Line uses the realtime clock for edge event timestamps.
+    Realtime,
+    /// Line uses the hardware timestamp engine clock for edge event timestamps.
+    HTE,
+}
+
+impl EventClock {
+    fn new(clock: u32) -> Result<Self> {
+        match clock {
+            gpiod::GPIOD_LINE_EVENT_CLOCK_MONOTONIC => Ok(EventClock::Monotonic),
+            gpiod::GPIOD_LINE_EVENT_CLOCK_REALTIME => Ok(EventClock::Realtime),
+            gpiod::GPIOD_LINE_EVENT_CLOCK_HTE => Ok(EventClock::HTE),
+            _ => Err(Error::InvalidEnumValue("Eventclock", clock)),
+        }
+    }
+
+    fn gpiod_clock(&self) -> u32 {
+        match self {
+            EventClock::Monotonic => gpiod::GPIOD_LINE_EVENT_CLOCK_MONOTONIC,
+            EventClock::Realtime => gpiod::GPIOD_LINE_EVENT_CLOCK_REALTIME,
+            EventClock::HTE => gpiod::GPIOD_LINE_EVENT_CLOCK_HTE,
+        }
+    }
+}
+
+/// Line status change event types.
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub enum InfoChangeKind {
+    /// Line has been requested.
+    LineRequested,
+    /// Previously requested line has been released.
+    LineReleased,
+    /// Line configuration has changed.
+    LineConfigChanged,
+}
+
+impl InfoChangeKind {
+    fn new(kind: u32) -> Result<Self> {
+        match kind {
+            gpiod::GPIOD_INFO_EVENT_LINE_REQUESTED => Ok(InfoChangeKind::LineRequested),
+            gpiod::GPIOD_INFO_EVENT_LINE_RELEASED => Ok(InfoChangeKind::LineReleased),
+            gpiod::GPIOD_INFO_EVENT_LINE_CONFIG_CHANGED => Ok(InfoChangeKind::LineConfigChanged),
+            _ => Err(Error::InvalidEnumValue("InfoChangeKind", kind)),
+        }
+    }
+}
+
+/// Edge event types.
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub enum EdgeKind {
+    /// Rising edge event.
+    Rising,
+    /// Falling edge event.
+    Falling,
+}
+
+impl EdgeKind {
+    fn new(kind: u32) -> Result<Self> {
+        match kind {
+            gpiod::GPIOD_EDGE_EVENT_RISING_EDGE => Ok(EdgeKind::Rising),
+            gpiod::GPIOD_EDGE_EVENT_FALLING_EDGE => Ok(EdgeKind::Falling),
+            _ => Err(Error::InvalidEnumValue("EdgeEvent", kind)),
+        }
+    }
+}
+
+/// Various libgpiod-related functions.
+
+/// Check if the file pointed to by path is a GPIO chip character device.
+///
+/// Returns true if the file exists and is a GPIO chip character device or a
+/// symbolic link to it.
+pub fn is_gpiochip_device<P: AsRef<Path>>(path: &P) -> bool {
+    // Null-terminate the string
+    let path = path.as_ref().to_string_lossy() + "\0";
+
+    unsafe { gpiod::gpiod_is_gpiochip_device(path.as_ptr() as *const c_char) }
+}
+
+/// Iterator for GPIO devices.

bindings/rust/libgpiod/src/lib.rs new file +7 -0

+
+    Ok(chips)
+}
+
+/// Get the API version of the library as a human-readable string.
+pub fn version_string() -> Result<&'static str> {
+    // SAFETY: The string returned by libgpiod is guaranteed to live forever.

bindings/rust/libgpiod/src/line_config.rs new file +11 -0

new file mode 100644
index 000000000000..ea25452fd1d6
@@ -0,0 +1,118 @@
+// SPDX-License-Identifier: Apache-2.0 AND BSD-3-Clause
+//
+// Copyright 2022 Linaro Ltd. All Rights Reserved.
+//     Viresh Kumar <[email protected]>
+
+use std::os::raw::c_ulong;
+use std::slice::from_raw_parts;
+
+use vmm_sys_util::errno::Error as Errno;
+
+use super::{gpiod, line::Settings, Error, Offset, OperationType, Result};

bindings/rust/libgpiod/src/line_config.rs new file +44 -0

+impl Config {
+    /// Create a new line config object.
+    pub fn new() -> Result<Self> {
+        let config = unsafe { gpiod::gpiod_line_config_new() };
+
+        if config.is_null() {
+            return Err(Error::OperationFailed(
+                OperationType::LineConfigNew,
+                Errno::last(),
+            ));
+        }
+
+        Ok(Self { config })
+    }
+
+    /// Private helper, Returns gpiod_line_config
+    pub(crate) fn config(&self) -> *mut gpiod::gpiod_line_config {
+        self.config
+    }
+
+    /// Resets the entire configuration stored in the object. This is useful if
+    /// the user wants to reuse the object without reallocating it.
+    pub fn reset(&mut self) {
+        unsafe { gpiod::gpiod_line_config_reset(self.config) }
+    }
+
+    /// Add line settings for a set of offsets.
+    pub fn add_line_settings(&self, offsets: &[Offset], settings: Settings) -> Result<()> {
+        let ret = unsafe {
+            gpiod::gpiod_line_config_add_line_settings(
+                self.config,
+                offsets.as_ptr(),
+                offsets.len() as c_ulong,
+                settings.settings(),
+            )
+        };
+
+        if ret == -1 {
+            Err(Error::OperationFailed(
+                OperationType::LineConfigAddSettings,
+                Errno::last(),
+            ))
+        } else {
+            Ok(())

bindings/rust/libgpiod/src/line_config.rs new file +32 -0

+                Errno::last(),
+            ));
+        }
+
+        Ok(Settings::new_with_settings(settings))
+    }
+
+    /// Get configured offsets.
+    pub fn offsets(&self) -> Result<Vec<Offset>> {
+        let mut num: u64 = 0;
+        let mut offsets: *mut Offset = std::ptr::null_mut();
+
+        let ret =
+            unsafe { gpiod::gpiod_line_config_get_offsets(self.config, &mut num, &mut offsets) };
+
+        if ret == -1 {
+            Err(Error::OperationFailed(
+                OperationType::LineConfigGetOffsets,
+                Errno::last(),
+            ))
+        } else {
+            Ok(unsafe { from_raw_parts(offsets as *const Offset, num as usize).to_vec() })
+        }
+    }
+}
+
+impl Drop for Config {
+    /// Free the line config object and release all associated resources.
+    fn drop(&mut self) {
+        unsafe { gpiod::gpiod_line_config_free(self.config) }
+    }
+}

bindings/rust/libgpiod/src/line_info.rs new file +22 -0

new file mode 100644
index 000000000000..9db51fc30efd
@@ -0,0 +1,180 @@
+// SPDX-License-Identifier: Apache-2.0 AND BSD-3-Clause
+//
+// Copyright 2022 Linaro Ltd. All Rights Reserved.
+//     Viresh Kumar <[email protected]>
+
+use libc::strlen;
+use std::sync::Arc;
+use std::time::Duration;
+use std::{slice, str};
+
+use vmm_sys_util::errno::Error as Errno;
+
+use super::{
+    chip, gpiod, info, Bias, Direction, Drive, Edge, Error, EventClock, Offset, OperationType,
+    Result,
+};
+
+/// Line info
+///
+/// Exposes functions for retrieving kernel information about both requested and
+/// free lines.  Line info object contains an immutable snapshot of a line's status.
+///

bindings/rust/libgpiod/src/line_info.rs new file +7 -0

+impl Info {
+    /// Get a snapshot of information about the line and optionally start watching it for changes.
+    pub(crate) fn new(ichip: Arc<chip::Internal>, offset: Offset) -> Result<Self> {
+        let info = unsafe { gpiod::gpiod_chip_get_line_info(ichip.chip(), offset) };
+
+        if info.is_null() {
+            return Err(Error::OperationFailed(

bindings/rust/libgpiod/src/line_info.rs new file +6 -0

+
+    pub(crate) fn new_watch(ichip: Arc<chip::Internal>, offset: Offset) -> Result<Self> {
+        let info = unsafe { gpiod::gpiod_chip_watch_line_info(ichip.chip(), offset) };
+
+        if info.is_null() {
+            return Err(Error::OperationFailed(

bindings/rust/libgpiod/src/line_info.rs new file +7 -0

+
+    /// Get the Line info object associated with an event.
+    pub(crate) fn new_from_event(event: &info::Event) -> Result<Self> {
+        let info = unsafe { gpiod::gpiod_info_event_get_line_info(event.event()) };
+
+        if info.is_null() {
+            return Err(Error::OperationFailed(

bindings/rust/libgpiod/src/line_info.rs new file +98 -0

+
+    /// Get the offset of the line within the GPIO chip.
+    ///
+    /// The offset uniquely identifies the line on the chip. The combination of the chip and offset
+    /// uniquely identifies the line within the system.
+
+    pub fn offset(&self) -> Offset {
+        unsafe { gpiod::gpiod_line_info_get_offset(self.info) }
+    }
+
+    /// Get GPIO line's name.
+    pub fn name(&self) -> Result<&str> {
+        // SAFETY: The string returned by libgpiod is guaranteed to live as long
+        // as the `struct Info`.
+        let name = unsafe { gpiod::gpiod_line_info_get_name(self.info) };
+        if name.is_null() {
+            return Err(Error::NullString("GPIO line's name"));
+        }
+
+        // SAFETY: The string is guaranteed to be valid here by the C API.
+        str::from_utf8(unsafe { slice::from_raw_parts(name as *const u8, strlen(name) as usize) })
+            .map_err(Error::StringNotUtf8)
+    }
+
+    /// Returns True if the line is in use, false otherwise.
+    ///
+    /// The user space can't know exactly why a line is busy. It may have been
+    /// requested by another process or hogged by the kernel. It only matters that
+    /// the line is used and we can't request it.
+    pub fn is_used(&self) -> bool {
+        unsafe { gpiod::gpiod_line_info_is_used(self.info) }
+    }
+
+    /// Get the GPIO line's consumer name.
+    pub fn consumer(&self) -> Result<&str> {
+        // SAFETY: The string returned by libgpiod is guaranteed to live as long
+        // as the `struct Info`.
+        let name = unsafe { gpiod::gpiod_line_info_get_consumer(self.info) };
+        if name.is_null() {
+            return Err(Error::NullString("GPIO line's consumer name"));
+        }
+
+        // SAFETY: The string is guaranteed to be valid here by the C API.
+        str::from_utf8(unsafe { slice::from_raw_parts(name as *const u8, strlen(name) as usize) })
+            .map_err(Error::StringNotUtf8)
+    }
+
+    /// Get the GPIO line's direction.
+    pub fn direction(&self) -> Result<Direction> {
+        Direction::new(unsafe { gpiod::gpiod_line_info_get_direction(self.info) } as u32)
+    }
+
+    /// Returns true if the line is "active-low", false otherwise.
+    pub fn is_active_low(&self) -> bool {
+        unsafe { gpiod::gpiod_line_info_is_active_low(self.info) }
+    }
+
+    /// Get the GPIO line's bias setting.
+    pub fn bias(&self) -> Result<Option<Bias>> {
+        Bias::new(unsafe { gpiod::gpiod_line_info_get_bias(self.info) } as u32)
+    }
+
+    /// Get the GPIO line's drive setting.
+    pub fn drive(&self) -> Result<Drive> {
+        Drive::new(unsafe { gpiod::gpiod_line_info_get_drive(self.info) } as u32)
+    }
+
+    /// Get the current edge detection setting of the line.
+    pub fn edge_detection(&self) -> Result<Option<Edge>> {
+        Edge::new(unsafe { gpiod::gpiod_line_info_get_edge_detection(self.info) } as u32)
+    }
+
+    /// Get the current event clock setting used for edge event timestamps.
+    pub fn event_clock(&self) -> Result<EventClock> {
+        EventClock::new(unsafe { gpiod::gpiod_line_info_get_event_clock(self.info) } as u32)
+    }
+
+    /// Returns true if the line is debounced (either by hardware or by the
+    /// kernel software debouncer), false otherwise.
+    pub fn is_debounced(&self) -> bool {
+        unsafe { gpiod::gpiod_line_info_is_debounced(self.info) }
+    }
+
+    /// Get the debounce period of the line.
+    pub fn debounce_period(&self) -> Duration {
+        Duration::from_micros(unsafe { gpiod::gpiod_line_info_get_debounce_period_us(self.info) })
+    }
+}
+
+impl Drop for Info {
+    fn drop(&mut self) {
+        // We must not free the Line info object created from `struct info::Event` by calling
+        // libgpiod API.
+        if !self.info_event {
+            unsafe { gpiod::gpiod_line_info_free(self.info) }
+        }
+    }
+}

bindings/rust/libgpiod/src/line_request.rs new file +14 -0

new file mode 100644
index 000000000000..e4ff951aef29
@@ -0,0 +1,246 @@
+// SPDX-License-Identifier: Apache-2.0 AND BSD-3-Clause
+//
+// Copyright 2022 Linaro Ltd. All Rights Reserved.
+//     Viresh Kumar <[email protected]>
+
+use libc::EINVAL;
+use std::os::raw::c_ulong;
+use std::sync::Arc;
+use std::time::Duration;
+
+use vmm_sys_util::errno::Error as Errno;
+
+use super::{
+    chip, edge, gpiod, line, request, Error, Offset, OperationType, Result, Value, ValueMap,

bindings/rust/libgpiod/src/line_request.rs new file +4 -0

+impl Request {
+    /// Request a set of lines for exclusive usage.
+    pub(crate) fn new(
+        ichip: &Arc<chip::Internal>,

bindings/rust/libgpiod/src/line_request.rs new file +104 -0

+
+    /// Get the number of lines in the request.
+    pub fn num_lines(&self) -> usize {
+        unsafe { gpiod::gpiod_line_request_get_num_lines(self.request) as usize }
+    }
+
+    /// Get the offsets of lines in the request.
+    pub fn offsets(&self) -> Vec<Offset> {
+        let mut offsets = vec![0; self.num_lines() as usize];
+
+        unsafe { gpiod::gpiod_line_request_get_offsets(self.request, offsets.as_mut_ptr()) };
+        offsets
+    }
+
+    /// Get the value (0 or 1) of a single line associated with the request.
+    pub fn value(&self, offset: Offset) -> Result<Value> {
+        let value = unsafe { gpiod::gpiod_line_request_get_value(self.request, offset) };
+
+        if value != 0 && value != 1 {
+            Err(Error::OperationFailed(
+                OperationType::LineRequestGetVal,
+                Errno::last(),
+            ))
+        } else {
+            Value::new(value)
+        }
+    }
+
+    /// Get values of a subset of lines associated with the request.
+    pub fn values_subset(&self, offsets: &[Offset]) -> Result<ValueMap> {
+        let mut values = vec![0; offsets.len()];
+
+        let ret = unsafe {
+            gpiod::gpiod_line_request_get_values_subset(
+                self.request,
+                offsets.len() as c_ulong,
+                offsets.as_ptr(),
+                values.as_mut_ptr(),
+            )
+        };
+
+        if ret == -1 {
+            Err(Error::OperationFailed(
+                OperationType::LineRequestGetValSubset,
+                Errno::last(),
+            ))
+        } else {
+            let mut map = ValueMap::new();
+
+            for (i, val) in values.iter().enumerate() {
+                map.insert(offsets[i].into(), Value::new(*val)?);
+            }
+
+            Ok(map)
+        }
+    }
+
+    /// Get values of all lines associated with the request.
+    pub fn values(&self) -> Result<ValueMap> {
+        self.values_subset(&self.offsets())
+    }
+
+    /// Set the value of a single line associated with the request.
+    pub fn set_value(&self, offset: Offset, value: Value) -> Result<()> {
+        let ret =
+            unsafe { gpiod::gpiod_line_request_set_value(self.request, offset, value.value()) };
+
+        if ret == -1 {
+            Err(Error::OperationFailed(
+                OperationType::LineRequestSetVal,
+                Errno::last(),
+            ))
+        } else {
+            Ok(())
+        }
+    }
+
+    /// Get values of a subset of lines associated with the request.
+    pub fn set_values_subset(&self, map: ValueMap) -> Result<()> {
+        let mut offsets = Vec::new();
+        let mut values = Vec::new();
+
+        for (offset, value) in map {
+            offsets.push(offset as u32);
+            values.push(value.value());
+        }
+
+        let ret = unsafe {
+            gpiod::gpiod_line_request_set_values_subset(
+                self.request,
+                offsets.len() as c_ulong,
+                offsets.as_ptr(),
+                values.as_ptr(),
+            )
+        };
+
+        if ret == -1 {
+            Err(Error::OperationFailed(
+                OperationType::LineRequestSetValSubset,
+                Errno::last(),
+            ))
+        } else {
+            Ok(())
+        }

bindings/rust/libgpiod/src/line_request.rs new file +28 -0

+
+        let mut new_values = Vec::new();
+        for value in values {
+            new_values.push(value.value());
+        }
+
+        let ret =
+            unsafe { gpiod::gpiod_line_request_set_values(self.request, new_values.as_ptr()) };
+
+        if ret == -1 {
+            Err(Error::OperationFailed(
+                OperationType::LineRequestSetVal,
+                Errno::last(),
+            ))
+        } else {
+            Ok(())
+        }
+    }
+
+    /// Update the configuration of lines associated with the line request.
+    pub fn reconfigure_lines(&self, lconfig: &line::Config) -> Result<()> {
+        let ret =
+            unsafe { gpiod::gpiod_line_request_reconfigure_lines(self.request, lconfig.config()) };
+
+        if ret == -1 {
+            Err(Error::OperationFailed(
+                OperationType::LineRequestReconfigLines,
+                Errno::last(),

bindings/rust/libgpiod/src/line_request.rs new file +15 -0

+
+    /// Wait for edge events on any of the lines associated with the request.
+    pub fn wait_edge_event(&self, timeout: Option<Duration>) -> Result<bool> {
+        let timeout = match timeout {
+            Some(x) => x.as_nanos() as i64,
+            // Block indefinitely
+            None => -1,
+        };
+
+        let ret = unsafe { gpiod::gpiod_line_request_wait_edge_event(self.request, timeout) };
+
+        match ret {
+            -1 => Err(Error::OperationFailed(
+                OperationType::LineRequestWaitEdgeEvent,
+                Errno::last(),

bindings/rust/libgpiod/src/line_request.rs new file +25 -0

+        let ret = unsafe {
+            gpiod::gpiod_line_request_read_edge_event(
+                self.request,
+                buffer.buffer(),
+                buffer.capacity() as u64,
+            )
+        };
+
+        if ret == -1 {
+            Err(Error::OperationFailed(
+                OperationType::LineRequestReadEdgeEvent,
+                Errno::last(),
+            ))
+        } else {
+            Ok(ret as u32)
+        }
+    }
+}
+
+impl Drop for Request {
+    /// Release the requested lines and free all associated resources.
+    fn drop(&mut self) {
+        unsafe { gpiod::gpiod_line_request_release(self.request) }
+    }
+}

bindings/rust/libgpiod/src/line_settings.rs new file +19 -0

new file mode 100644
index 000000000000..2c3090132ea5
@@ -0,0 +1,277 @@
+// SPDX-License-Identifier: Apache-2.0 AND BSD-3-Clause
+//
+// Copyright 2022 Linaro Ltd. All Rights Reserved.
+//     Viresh Kumar <[email protected]>
+
+use std::time::Duration;
+
+use vmm_sys_util::errno::Error as Errno;
+
+use super::{
+    gpiod, Bias, Direction, Drive, Edge, Error, EventClock, OperationType, Result, SettingKind,
+    SettingVal, Value,
+};
+
+/// Line settings objects.
+///
+/// Line settings object contains a set of line properties that can be used
+/// when requesting lines or reconfiguring an existing request.
+///

bindings/rust/libgpiod/src/line_settings.rs new file +13 -0

+impl Settings {
+    /// Create a new line settings object.
+    pub fn new() -> Result<Self> {
+        let settings = unsafe { gpiod::gpiod_line_settings_new() };
+
+        if settings.is_null() {
+            return Err(Error::OperationFailed(
+                OperationType::LineSettingsNew,
+                Errno::last(),
+            ));
+        }
+
+        Ok(Self { settings })

bindings/rust/libgpiod/src/line_settings.rs new file +8 -0

+
+    /// Resets the line settings object to its default values.
+    pub fn reset(&mut self) {
+        unsafe { gpiod::gpiod_line_settings_reset(self.settings) }
+    }
+
+    /// Makes copy of the settings object.
+    pub fn settings_clone(&self) -> Result<Self> {

bindings/rust/libgpiod/src/line_settings.rs new file +5 -0

+        for value in values {
+            match value {
+                SettingVal::Direction(val) => self.set_direction(*val)?,
+                SettingVal::EdgeDetection(val) => self.set_edge_detection(*val)?,
+                SettingVal::Bias(val) => self.set_bias(*val)?,

bindings/rust/libgpiod/src/line_settings.rs new file +23 -0

+
+    /// Get the line prop setting.
+    pub fn prop(&self, property: SettingKind) -> Result<SettingVal> {
+        Ok(match property {
+            SettingKind::Direction => SettingVal::Direction(self.direction()?),
+            SettingKind::EdgeDetection => SettingVal::EdgeDetection(self.edge_detection()?),
+            SettingKind::Bias => SettingVal::Bias(self.bias()?),
+            SettingKind::Drive => SettingVal::Drive(self.drive()?),
+            SettingKind::ActiveLow => SettingVal::ActiveLow(self.active_low()),
+            SettingKind::DebouncePeriod => SettingVal::DebouncePeriod(self.debounce_period()?),
+            SettingKind::EventClock => SettingVal::EventClock(self.event_clock()?),
+            SettingKind::OutputValue => SettingVal::OutputValue(self.output_value()?),
+        })
+    }
+
+    /// Set the line direction.
+    fn set_direction(&mut self, direction: Direction) -> Result<()> {
+        let ret = unsafe {
+            gpiod::gpiod_line_settings_set_direction(
+                self.settings,
+                direction.gpiod_direction() as i32,
+            )
+        };

bindings/rust/libgpiod/src/line_settings.rs new file +156 -0

+
+    /// Get the direction setting.
+    fn direction(&self) -> Result<Direction> {
+        Direction::new(unsafe { gpiod::gpiod_line_settings_get_direction(self.settings) } as u32)
+    }
+
+    /// Set the edge event detection setting.
+    fn set_edge_detection(&mut self, edge: Option<Edge>) -> Result<()> {
+        let ret = unsafe {
+            gpiod::gpiod_line_settings_set_edge_detection(
+                self.settings,
+                Edge::gpiod_edge(edge) as i32,
+            )
+        };
+
+        if ret == -1 {
+            Err(Error::OperationFailed(
+                OperationType::LineSettingsSetEdgeDetection,
+                Errno::last(),
+            ))
+        } else {
+            Ok(())
+        }
+    }
+
+    /// Get the edge event detection setting.
+    fn edge_detection(&self) -> Result<Option<Edge>> {
+        Edge::new(unsafe { gpiod::gpiod_line_settings_get_edge_detection(self.settings) } as u32)
+    }
+
+    /// Set the bias setting.
+    fn set_bias(&mut self, bias: Option<Bias>) -> Result<()> {
+        let ret = unsafe {
+            gpiod::gpiod_line_settings_set_bias(self.settings, Bias::gpiod_bias(bias) as i32)
+        };
+
+        if ret == -1 {
+            Err(Error::OperationFailed(
+                OperationType::LineSettingsSetBias,
+                Errno::last(),
+            ))
+        } else {
+            Ok(())
+        }
+    }
+
+    /// Get the bias setting.
+    fn bias(&self) -> Result<Option<Bias>> {
+        Bias::new(unsafe { gpiod::gpiod_line_settings_get_bias(self.settings) } as u32)
+    }
+
+    /// Set the drive setting.
+    fn set_drive(&mut self, drive: Drive) -> Result<()> {
+        let ret = unsafe {
+            gpiod::gpiod_line_settings_set_drive(self.settings, drive.gpiod_drive() as i32)
+        };
+
+        if ret == -1 {
+            Err(Error::OperationFailed(
+                OperationType::LineSettingsSetDrive,
+                Errno::last(),
+            ))
+        } else {
+            Ok(())
+        }
+    }
+
+    /// Get the drive setting.
+    fn drive(&self) -> Result<Drive> {
+        Drive::new(unsafe { gpiod::gpiod_line_settings_get_drive(self.settings) } as u32)
+    }
+
+    /// Set active-low setting.
+    fn set_active_low(&mut self, active_low: bool) {
+        unsafe { gpiod::gpiod_line_settings_set_active_low(self.settings, active_low) }
+    }
+
+    /// Check the active-low setting.
+    fn active_low(&self) -> bool {
+        unsafe { gpiod::gpiod_line_settings_get_active_low(self.settings) }
+    }
+
+    /// Set the debounce period setting.
+    fn set_debounce_period(&mut self, period: Duration) {
+        unsafe {
+            gpiod::gpiod_line_settings_set_debounce_period_us(
+                self.settings,
+                period.as_micros() as u64,
+            )
+        }
+    }
+
+    /// Get the debounce period.
+    fn debounce_period(&self) -> Result<Duration> {
+        Ok(Duration::from_micros(unsafe {
+            gpiod::gpiod_line_settings_get_debounce_period_us(self.settings)
+        }))
+    }
+
+    /// Set the event clock setting.
+    fn set_event_clock(&mut self, clock: EventClock) -> Result<()> {
+        let ret = unsafe {
+            gpiod::gpiod_line_settings_set_event_clock(self.settings, clock.gpiod_clock() as i32)
+        };
+
+        if ret == -1 {
+            Err(Error::OperationFailed(
+                OperationType::LineSettingsSetEventClock,
+                Errno::last(),
+            ))
+        } else {
+            Ok(())
+        }
+    }
+
+    /// Get the event clock setting.
+    fn event_clock(&self) -> Result<EventClock> {
+        EventClock::new(unsafe { gpiod::gpiod_line_settings_get_event_clock(self.settings) } as u32)
+    }
+
+    /// Set the output value setting.
+    fn set_output_value(&mut self, value: Value) -> Result<()> {
+        let ret =
+            unsafe { gpiod::gpiod_line_settings_set_output_value(self.settings, value.value()) };
+
+        if ret == -1 {
+            Err(Error::OperationFailed(
+                OperationType::LineSettingsSetOutputValue,
+                Errno::last(),
+            ))
+        } else {
+            Ok(())
+        }
+    }
+
+    /// Get the output value, 0 or 1.
+    fn output_value(&self) -> Result<Value> {
+        let value = unsafe { gpiod::gpiod_line_settings_get_output_value(self.settings) };
+
+        if value != 0 && value != 1 {
+            Err(Error::OperationFailed(
+                OperationType::LineSettingsGetOutVal,
+                Errno::last(),
+            ))
+        } else {
+            Value::new(value)
+        }
+    }
+}
+
+impl Drop for Settings {
+    /// Free the line settings object and release all associated resources.
+    fn drop(&mut self) {
+        unsafe { gpiod::gpiod_line_settings_free(self.settings) }
+    }
+}

bindings/rust/libgpiod/src/request_config.rs new file +15 -0

new file mode 100644
index 000000000000..760d9c755c86
@@ -0,0 +1,96 @@
+// SPDX-License-Identifier: Apache-2.0 AND BSD-3-Clause
+//
+// Copyright 2022 Linaro Ltd. All Rights Reserved.
+//     Viresh Kumar <[email protected]>
+
+use libc::strlen;
+use std::os::raw::{c_char, c_ulong};
+use std::{slice, str};
+
+use vmm_sys_util::errno::Error as Errno;
+
+use super::{gpiod, Error, OperationType, Result};
+
+/// Request configuration objects
+///

bindings/rust/libgpiod/src/request_config.rs new file +9 -0

+impl Config {
+    /// Create a new request config object.
+    pub fn new() -> Result<Self> {
+        let config = unsafe { gpiod::gpiod_request_config_new() };
+        if config.is_null() {
+            return Err(Error::OperationFailed(
+                OperationType::RequestConfigNew,
+                Errno::last(),
+            ));

bindings/rust/libgpiod/src/request_config.rs new file +52 -0

+    /// Set the consumer name for the request.
+    ///
+    /// If the consumer string is too long, it will be truncated to the max
+    /// accepted length.
+    pub fn set_consumer(&self, consumer: &str) {
+        // Null-terminate the string
+        let consumer = consumer.to_owned() + "\0";
+
+        unsafe {
+            gpiod::gpiod_request_config_set_consumer(
+                self.config,
+                consumer.as_ptr() as *const c_char,
+            )
+        }
+    }
+
+    /// Get the consumer name configured in the request config.
+    pub fn consumer(&self) -> Result<&str> {
+        // SAFETY: The string returned by libgpiod is guaranteed to live as long
+        // as the `struct Config`.
+        let consumer = unsafe { gpiod::gpiod_request_config_get_consumer(self.config) };
+        if consumer.is_null() {
+            return Err(Error::OperationFailed(
+                OperationType::RequestConfigGetConsumer,
+                Errno::last(),
+            ));
+        }
+
+        // SAFETY: The string is guaranteed to be valid here by the C API.
+        str::from_utf8(unsafe {
+            slice::from_raw_parts(consumer as *const u8, strlen(consumer) as usize)
+        })
+        .map_err(Error::StringNotUtf8)
+    }
+
+    /// Set the size of the kernel event buffer for the request.
+    pub fn set_event_buffer_size(&self, size: usize) {
+        unsafe { gpiod::gpiod_request_config_set_event_buffer_size(self.config, size as c_ulong) }
+    }
+
+    /// Get the edge event buffer size setting for the request config.
+    pub fn event_buffer_size(&self) -> usize {
+        unsafe { gpiod::gpiod_request_config_get_event_buffer_size(self.config) as usize }
+    }
+}
+
+impl Drop for Config {
+    /// Free the request config object and release all associated resources.
+    fn drop(&mut self) {
+        unsafe { gpiod::gpiod_request_config_free(self.config) }
+    }
+}

Signature · 1 line

2.31.1.272.g89b43f80a514

Quoted 1 line · Viresh Kumar

+use vmm_sys_util::errno::Error as Errno;

Why vmm_sys_util::errno::Error rather than, say, errno::Errno?

Quoted 6 lines

bindings/rust/libgpiod/src/chip.rs new file +6 -0

+/// GPIO chip
+///
+/// A GPIO chip object is associated with an open file descriptor to the GPIO
+/// character device. It exposes basic information about the chip and allows
+/// callers to retrieve information about each line, watch lines for state
+/// changes and make line requests.

bindings/rust/libgpiod/src/chip.rs line 63

Quoted 6 lines

bindings/rust/libgpiod/src/chip.rs new file +6 -0

+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct Chip {
+    ichip: Arc<Internal>,
+    info: Info,
+}
+

Doesn't info need an Arc as well? (see struct Info below).

Actually, does it make sense to be able to Clone the Chip?

Two threads could then watch different lines and wait_info_event() from the one chip.
That isn't going to work, at least not the way you would want.

bindings/rust/libgpiod/src/chip.rs line 66

Quoted 3 lines

bindings/rust/libgpiod/src/chip.rs new file +3 -0

+unsafe impl Send for Chip {}
+unsafe impl Sync for Chip {}
+

Send makes sense to me, but not Sync, due to the waiting for info events. Similarly for line_request::Request.
At least not without some additional synchronisation/locking, and I'm not sure we want to go there.

bindings/rust/libgpiod/src/chip.rs line 72

Quoted 6 lines

bindings/rust/libgpiod/src/chip.rs new file +6 -0

+impl Chip {
+    /// Find a chip by path.
+    pub fn open<P: AsRef<Path>>(path: &P) -> Result<Self> {
+        let ichip = Arc::new(Internal::open(path)?);
+        let info = Info::new(ichip.clone())?;
+

info is not always necessary, e.g. if the user just want to request a line. Maybe lazy load it? Assuming you want to keep a copy cached with the Chip at all.

Quoted 38 lines

bindings/rust/libgpiod/src/chip.rs new file +36 -0

+        Ok(Self { ichip, info })
+    }
+
+    /// Get the chip name as represented in the kernel.
+    pub fn name(&self) -> Result<&str> {
+        self.info.name()
+    }
+
+    /// Get the chip label as represented in the kernel.
+    pub fn label(&self) -> Result<&str> {
+        self.info.label()
+    }
+
+    /// Get the number of GPIO lines exposed by the chip.
+    pub fn num_lines(&self) -> usize {
+        self.info.num_lines()
+    }
 
 
+impl Buffer {
+    /// Create a new edge event buffer.
+    ///
+    /// If capacity equals 0, it will be set to a default value of 64. If
+    /// capacity is larger than 1024, it will be limited to 1024.
+    pub fn new(capacity: usize) -> Result<Self> {
+        let buffer = unsafe { gpiod::gpiod_edge_event_buffer_new(capacity as c_ulong) };
+        if buffer.is_null() {
+            return Err(Error::OperationFailed(
+                OperationType::EdgeEventBufferNew,
+                Errno::last(),
+            ));
+        }
+
+        Ok(Self { buffer })
+    }
+
+    /// Private helper, Returns gpiod_edge_event_buffer
+    pub(crate) fn buffer(&self) -> *mut gpiod::gpiod_edge_event_buffer {

bindings/rust/libgpiod/src/event_buffer.rs line 38

Quoted 2 lines

bindings/rust/libgpiod/src/event_buffer.rs new file +2 -0

+        self.buffer
+    }

Just make self.buffer pub(crate)? Why is the idea of passing a raw pointer around making my skin crawl?
Or even better, move the guts of line_request::Request::read_edge_events() into a helper function here that it can call so it doesn't need access to self.buffer.

Quoted 6 lines

bindings/rust/libgpiod/src/event_buffer.rs new file +6 -0

+
+    /// Get the capacity of the event buffer.
+    pub fn capacity(&self) -> usize {
+        unsafe { gpiod::gpiod_edge_event_buffer_get_capacity(self.buffer()) as usize }
+    }
+

bindings/rust/libgpiod/src/event_buffer.rs line 48

Quoted 4 lines

bindings/rust/libgpiod/src/event_buffer.rs new file +4 -0

+    /// Read an event stored in the buffer.
+    pub fn event(&self, index: u64) -> Result<edge::Event> {
+        edge::Event::new(self, index)
+    }

What is to prevent reading an event from a slot that has not yet been populated? I realise doing that is possible in C, but it should be prevented in the Rust bindings.

Not sure why event_buffer needs to be nested inside an event module. event_buffer should be in the request module.

edge_event is a tougher call, either line or request. Probably the latter.

Quoted 7 lines

bindings/rust/libgpiod/src/lib.rs new file +7 -0

+/// Iterator for GPIO devices.
+pub fn gpiochip_devices<P: AsRef<Path>>(path: &P) -> Result<Vec<chip::Chip>> {
+    let mut chips = Vec::new();
+
+    for entry in fs::read_dir(path).map_err(|_| Error::IoError)?.flatten() {
+        let path = entry.path();
+

bindings/rust/libgpiod/src/lib.rs line 454

Quoted 4 lines

bindings/rust/libgpiod/src/lib.rs new file +4 -0

+        if is_gpiochip_device(&path) {
+            chips.push(chip::Chip::open(&path)?);
+        }
+    }

If there is a symlink to a device both in the path, or multiple symlinks to the same device, you will get the same chip several times in the returned Vec?

Some mention of the order in which devices are returned?

If you are returning a Vec then sorted might be nice, else state they are not sorted.

Quoted 7 lines

bindings/rust/libgpiod/src/lib.rs new file +7 -0

+/// Get the API version of the library as a human-readable string.
+pub fn version_string() -> Result<&'static str> {
+    // SAFETY: The string returned by libgpiod is guaranteed to live forever.
+    let version = unsafe { gpiod::gpiod_version_string() };
+
+    if version.is_null() {
+        return Err(Error::NullString("GPIO library version"));

bindings/rust/libgpiod/src/lib.rs line 471

Quoted 6 lines

bindings/rust/libgpiod/src/lib.rs new file +6 -0

+    }
+
+    // SAFETY: The string is guaranteed to be valid here by the C API.
+    str::from_utf8(unsafe { slice::from_raw_parts(version as *const u8, strlen(version) as usize) })
+        .map_err(Error::StringNotUtf8)
+}

What if the Rust bindings version differ from the libgpiod version?

bindings/rust/libgpiod/src/line_request.rs line 221

Quoted 4 lines

bindings/rust/libgpiod/src/line_request.rs new file +4 -0

+    /// Get a number of edge events from a line request.
+    ///
+    /// This function will block if no event was queued for the line.
+    pub fn read_edge_events(&self, buffer: &mut edge::event::Buffer) -> Result<u32> {

What is to stop the user requesting events between the len returned here and the end of the buffer? Why knows what state they are in.