Struct gpiocdev::request::Request

pub struct Request { /* private fields */ }

An active request of a set of lines.

Requests are built by the Builder, which itself can be constructed by builder.

Output Lifetime

The value of an output line is only guaranteed for the lifetime of the request. If the request is dropped then the output value becomes indeterminate - it may remain unchanged or it may reset to the default value (depending on a number of factors including the kernel driver for your hardware and whether other lines on the chip are still requested).

So keep the request alive to be sure of the output value.

Event Buffering

Events are buffered both in the kernel and in user space. The purpose of the kernel event buffer is to store events that may occur in a burst at a faster rate than they can be handled by the user space process. The kernel event buffer can be customised to some extent by the with_kernel_event_buffer_size option.

A number of options are available for user space buffering, i.e. where the events are to be written when they are read from the kernel.

The read_edge_event reads a single event onto the stack.

The EdgeEventBuffer provides buffering on the heap, and can reduce reading overheads by reading multiple events from the kernel at once. The edge_events iterator uses an EdgeEventBuffer, the size of which is controlled by with_user_event_buffer_size

It is also possible to read multiple events into a user specified location using read_edge_events_into_slice. As with EdgeEventBuffer this may reduce read overheads when reading a burst of events from the kernel. The edge_event_size method provides the size required to store a single event to allow sizing of custom slices.

Reading Output Values

Note that reading back output values using value or values is dependent on driver and hardware support and so cannot be guaranteed to work, though frequently it does. Test with your particular hardware to be sure.

Implementations

impl Request

pub fn builder() -> Builder

Start building a new request.

Examples

let req = gpiocdev::Request::builder()
    .on_chip("/dev/gpiochip0")
    .with_lines(&[3,5])
    .request()?;
let mut values = Values::default();
req.values(&mut values)?;

pub fn from_config(config: Config) -> Builder

Start building a new request using the provided config.

Examples

let mut cfg = Config::default();
cfg.with_line(5).as_output(Value::Active);
let req = gpiocdev::Request::from_config(cfg)
    .on_chip("/dev/gpiochip0")
    .request()?;

pub fn values(&self, values: &mut Values) -> Result<()>

Get the values for a subset of the requested lines.

The keys indicate the lines to get. Keys that are not requested offsets are ignored. If no keys are set then all requested lines are returned.

Examples

let req = gpiocdev::Request::builder()
    .on_chip("/dev/gpiochip0")
    .with_lines(&[3,5,6,8])
    .request()?;
// subset of lines
let mut values = Values::from_offsets(&[3,8]);
req.values(&mut values)?;
// all requested lines
let mut values = Values::default();
req.values(&mut values)?;

pub fn value(&self, offset: Offset) -> Result<Value>

Get the value for one line in the request.

Examples

let req = gpiocdev::Request::builder()
    .on_chip("/dev/gpiochip0")
    .with_lines(&[3,5])
    .request()?;
let v5 = req.value(5)?;

pub fn set_values(&self, values: &Values) -> Result<()>

Set the values for a subset of the requested lines.

Examples

let req = gpiocdev::Request::builder()
    .on_chip("/dev/gpiochip0")
    .with_lines(&[3,5,6,8])
    .as_output(Active)
    .request()?;
let mut values = Values::default();
values.set(5, Inactive).set(6, Inactive);
req.set_values(&values)?;

pub fn set_value(&self, offset: Offset, value: Value) -> Result<()>

Set the value for one line in the request.

Examples

let mut cfg = Config::default();
cfg.with_line(5).as_output(Value::Active);
let req = gpiocdev::Request::from_config(cfg)
    .on_chip("/dev/gpiochip0")
    .request()?;
req.set_value(5,Value::Inactive)?;

pub fn chip_path(&self) -> PathBuf

Return the path of the chip for this request.

pub fn config(&self) -> Config

Get a snapshot of the requested configuration.

This is the configuration currently applied to the hardware.

pub fn line_config(&self, offset: Offset) -> Option<Config>

Get a snapshot of the requested configuration for a particular line.

This is the configuration currently applied to the line.

pub fn reconfigure(&self, new_cfg: &Config) -> Result<()>

Reconfigure the request with the an updated configuration.

Note that lines cannot be added or removed from the request. Any additional lines in new_cfg will be ignored, and any missing lines will retain their existing configuration.

pub fn edge_events(&self) -> EdgeEventBuffer<'_>

An iterator for events from the request.

By default the events are read from the kernel individually.

The iterator can be backed by a user space buffer using the Builder.with_user_event_buffer_size option in the builder.

Examples

let req = Request::builder()
    .on_chip("/dev/gpiochip0")
    .with_consumer("watcher")
    .with_line(23)
    .with_edge_detection(EdgeDetection::BothEdges)
    .request()?;

for event in req.edge_events() {
    println!("{:?}", event?);
}

pub fn has_edge_event(&self) -> Result<bool>

Returns true when the request has edge events available to read using read_edge_event.

pub fn wait_edge_event(&self, timeout: Duration) -> Result<bool>

Wait for an edge event to be available.

Returns true if read_edge_event will return an event without blocking.

pub fn read_edge_event(&self) -> Result<EdgeEvent>

Read a single edge event from the request.

Will block until an edge event is available.

This is a convenience function. Reading events using edge_events or a buffer created using new_edge_event_buffer may be more performant.

pub fn new_edge_event_buffer(&self, capacity: usize) -> EdgeEventBuffer<'_>

Create an edge event buffer.

• capacity - The number of events that can be buffered.

pub fn read_edge_events_into_slice(&self, buf: &mut [u64]) -> Result<usize>

Read edge events from the kernel into a user space [u64] slice.

This is a helper function for the special case where the user prefers to manage the buffer containing raw events, e.g. to place it in a specific location in memory.

The slice is u64 to satisfy alignment requirements on 32bit platforms.

This will read in edge_event_size sized chunks so buf must be at least as large as one event. e.g. vec![0_u64; edge_event_u64_size()]

This function will block if no events are available to read.

Returns the number of u64 words read.

• buf - The slice to contain the raw events.

pub fn edge_event_from_slice(&self, buf: &[u64]) -> Result<EdgeEvent>

Read an edge event from a [u64] slice.

This is a helper function for the special case where the user prefers to manage the buffer containing raw events, e.g. to place it in a specific location in memory.

Assumes the buffer has been previously populated by a call to read_edge_events_into_slice.

• buf - The slice containing the raw event.

pub fn edge_event_u64_size(&self) -> usize

The number of u64s required to buffer a single event read from the request.

This can be used to size an external [u64] slice to read events into. The slice size should be a multiple of this size. e.g. vec![0_u64; edge_event_u64_size()] is a buffer large enough for one event.

pub fn edge_event_size(&self) -> usize

The number of bytes required to buffer a single event read from the request.

This can be used to size an external [u64] slice to read events into. The slice size should be a multiple of this size. e.g. vec![0_u64; edge_event_size()] is a buffer large enough for 8 events.

Trait Implementations

impl AsFd for Request

fn as_fd(&self) -> BorrowedFd<'_>

Borrows the file descriptor.

impl AsRawFd for Request

fn as_raw_fd(&self) -> i32

Extracts the raw file descriptor.

impl AsRef<Request> for AsyncRequest

fn as_ref(&self) -> &Request

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<Request> for AsyncRequest

fn as_ref(&self) -> &Request

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<Request> for Request

fn as_ref(&self) -> &Request

Converts this type into a shared reference of the (usually inferred) input type.

impl Debug for Request

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl From<AsyncRequest> for Request

fn from(r: AsyncRequest) -> Request

Converts to this type from the input type.

impl From<AsyncRequest> for Request

fn from(r: AsyncRequest) -> Request

Converts to this type from the input type.

impl From<Request> for AsyncRequest

fn from(r: Request) -> AsyncRequest

Converts to this type from the input type.

impl From<Request> for AsyncRequest

fn from(r: Request) -> AsyncRequest

Converts to this type from the input type.