Merge pull request #51 from eldruin/rdwr-ioctl-2

Transactional read/write via I2C_RDWR ioctl - take 2

Author: posborne

examples/pca9956b.rs

@@ -0,0 +1,79 @@
+// Copyright 2018, Piers Finlayson <piers@piersandkatie.com>
+//
+// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+// http://www.apache.org/license/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
+// option.  This file may not be copied, modified, or distributed
+// except according to those terms.extern crate i2cdev;
+
+extern crate i2cdev;
+extern crate docopt;
+
+#[cfg(any(target_os = "linux", target_os = "android"))]
+use i2cdev::core::{I2CTransfer, I2CMessage};
+#[cfg(any(target_os = "linux", target_os = "android"))]
+use i2cdev::linux::{LinuxI2CBus, LinuxI2CMessage};
+
+use std::env::args;
+use docopt::Docopt;
+
+const USAGE: &str = "
+Reads registers from a PCA9956B IC via Linux i2cdev.
+
+Assumes the PCA9956B is using address 0x20.
+
+Usage:
+  pca9956b <device>
+  pca9956b (-h | --help)
+  pca9956b --version
+
+Options:
+  -h --help    Show this help text.
+  --version    Show version.
+";
+
+const ADDR: u16 = 0x20;
+
+#[cfg(any(target_os = "linux", target_os = "android"))]
+fn main() {
+    let args = Docopt::new(USAGE)
+        .and_then(|d| d.argv(args()).parse())
+        .unwrap_or_else(|e| e.exit());
+    let path = args.get_str("<device>");
+    let mut bus = match LinuxI2CBus::new(path) {
+        Ok(bus) => bus,
+        Err(_e) => {
+            println!("Error opening I2C Bus {} {}", path, _e);
+            return;
+        }
+    };
+    println!("Opened I2C Bus OK: {}", path);
+
+    // Build two I2C messages:
+    // 1) Write the MODE1 register address, with top bit indcating auto-
+    //    increment should be enabled
+    // 2) Read 10 bytes from the current register onwards
+    let mut data = [0; 10];
+    let mut msgs = [
+        LinuxI2CMessage::write(&[0b1000_0000]).with_address(ADDR),
+        LinuxI2CMessage::read(&mut data).with_address(ADDR),
+    ];
+
+    // Send the messages to the kernel to process
+    match bus.transfer(&mut msgs) {
+        Ok(rc) => println!("Successful transfer call: {} messages processed", rc),
+        Err(_e) => {
+            println!("Error reading/writing {}", _e);
+            return;
+        }
+    }
+
+    // Print the data read from the device.  A recently reset PCA9956B should
+    // return:
+    // 0x8005000000000000ff00
+    let mut output = "Result: 0x".to_string();
+    for byte in &data {
+        output = format!("{}{:02x}", output, byte);
+    }
+    println!("{}", output);
+}

src/core.rs

@@ -111,3 +111,33 @@ pub trait I2CDevice {
     /// 1 to 31 bytes of data from it.
     fn smbus_process_block(&mut self, register: u8, values: &[u8]) -> Result<Vec<u8>, Self::Error>;
 }
+
+/// Interface to an I2C Bus from an I2C Master
+///
+/// This is used when the client wants to interact directly with the bus
+/// without specifying an I2C slave address up-front, either because it needs
+/// to communicate with multiple addresses without creatings separate
+/// I2CDevice objects, or because it wants to make used of the I2C_RDWR ioctl
+/// which allows the client to send and transmit multiple sets I2C data in a
+/// single operation, potentially to different I2C slave addresses.
+///
+/// Typical implementations will store state with references to the bus
+/// in use.  The trait is based on the Linux i2cdev interface.
+pub trait I2CTransfer<'a> {
+    type Error: Error;
+    type Message: I2CMessage<'a>;
+
+    // Performs multiple serially chained I2C read/write transactions.  On
+    // success the return code is the number of successfully executed
+    // transactions
+    fn transfer(&mut self, msgs: &'a mut [Self::Message]) -> Result<u32, Self::Error>;
+}
+
+/// Read/Write I2C message
+pub trait I2CMessage<'a> {
+    /// Read data from device
+    fn read(data: &'a mut [u8]) -> Self;
+
+    /// Write data to device
+    fn write(data: &'a [u8]) -> Self;
+}

src/ffi.rs

@@ -14,41 +14,22 @@ use std::mem;
 use std::ptr;
 use std::io::Cursor;
 use std::os::unix::prelude::*;
+use std::marker::PhantomData;
 use byteorder::{NativeEndian, ReadBytesExt, WriteBytesExt};
+use libc::c_int;
 
 pub type I2CError = nix::Error;
 
-bitflags! {
-    struct I2CMsgFlags: u16 {
-        /// this is a ten bit chip address
-        const I2C_M_TEN = 0x0010;
-        /// read data, from slave to master
-        const I2C_M_RD = 0x0001;
-        /// if I2C_FUNC_PROTOCOL_MANGLING
-        const I2C_M_STOP = 0x8000;
-        /// if I2C_FUNC_NOSTART
-        const I2C_M_NOSTART = 0x4000;
-        /// if I2C_FUNC_PROTOCOL_MANGLING
-        const I2C_M_REV_DIR_ADDR = 0x2000;
-        /// if I2C_FUNC_PROTOCOL_MANGLING
-        const I2C_M_IGNORE_NAK = 0x1000;
-        /// if I2C_FUNC_PROTOCOL_MANGLING
-        const I2C_M_NO_RD_ACK = 0x0800;
-        /// length will be first received byte
-        const I2C_M_RECV_LEN = 0x0400;
-    }
-}
-
 #[repr(C)]
-struct i2c_msg {
+pub struct i2c_msg {
     /// slave address
-    addr: u16,
+    pub(crate) addr: u16,
     /// serialized I2CMsgFlags
-    flags: u16,
+    pub(crate) flags: u16,
     /// msg length
-    len: u16,
+    pub(crate) len: u16,
     /// pointer to msg data
-    buf: *mut u8,
+    pub(crate) buf: *const u8,
 }
 
 bitflags! {
@@ -163,23 +144,25 @@ pub struct i2c_smbus_ioctl_data {
 }
 
 /// This is the structure as used in the I2C_RDWR ioctl call
+// see linux/i2c-dev.h
 #[repr(C)]
-struct i2c_rdwr_ioctl_data {
+pub struct i2c_rdwr_ioctl_data {
     // struct i2c_msg __user *msgs;
     msgs: *mut i2c_msg,
     // __u32 nmsgs;
     nmsgs: u32,
 }
 
 mod ioctl {
-    use super::{I2C_SLAVE, I2C_SMBUS};
+    use super::{I2C_SLAVE, I2C_SMBUS, I2C_RDWR};
     pub use super::i2c_smbus_ioctl_data;
+    pub use super::i2c_rdwr_ioctl_data;
 
     ioctl_write_int_bad!(set_i2c_slave_address, I2C_SLAVE);
     ioctl_write_ptr_bad!(i2c_smbus, I2C_SMBUS, i2c_smbus_ioctl_data);
+    ioctl_write_ptr_bad!(i2c_rdwr, I2C_RDWR, i2c_rdwr_ioctl_data);
 }
 
-
 pub fn i2c_set_slave_address(fd: RawFd, slave_address: u16) -> Result<(), nix::Error> {
     unsafe {
         ioctl::set_i2c_slave_address(fd, slave_address as i32)?;
@@ -429,3 +412,17 @@ pub fn i2c_smbus_process_call_block(fd: RawFd, register: u8, values: &[u8]) -> R
     let count = data.block[0];
     Ok((&data.block[1..(count + 1) as usize]).to_vec())
 }
+
+#[inline]
+pub fn i2c_rdwr(fd: RawFd, values: &mut [i2c_msg]) -> Result<u32, I2CError> {
+    let i2c_data = i2c_rdwr_ioctl_data {
+        msgs: values.as_mut_ptr(),
+        nmsgs: values.len() as u32,
+    };
+
+    let n;
+    unsafe {
+        n = ioctl::i2c_rdwr(fd, &i2c_data)?;
+    }
+    Ok(n as u32)
+}

src/lib.rs

@@ -14,15 +14,15 @@
 //! https://www.kernel.org/doc/Documentation/i2c/dev-interface
 //! ```rust,no_run
 //! extern crate i2cdev;
-//! 
+//!
 //! use std::thread;
 //! use std::time::Duration;
 //!
 //! use i2cdev::core::*;
 //! use i2cdev::linux::{LinuxI2CDevice, LinuxI2CError};
 //!
 //! const NUNCHUCK_SLAVE_ADDR: u16 = 0x52;
-//! 
+//!
 //! // real code should probably not use unwrap()
 //! fn i2cfun() -> Result<(), LinuxI2CError> {
 //!     let mut dev = LinuxI2CDevice::new("/dev/i2c-1", NUNCHUCK_SLAVE_ADDR)?;
@@ -41,6 +41,58 @@
 //!     }
 //! }
 //! ```
+//!
+//! ```rust,no_run
+//! extern crate i2cdev;
+//!
+//! use std::thread;
+//! use std::time::Duration;
+//!
+//! use i2cdev::core::*;
+//! use i2cdev::linux::{LinuxI2CDevice, LinuxI2CError, LinuxI2CMessage};
+//!
+//! const SLAVE_ADDR: u16 = 0x57;
+//!
+//! fn write_read_transaction() -> Result<(), LinuxI2CError> {
+//!     let mut dev = LinuxI2CDevice::new("/dev/i2c-1", SLAVE_ADDR)?;
+//!
+//!     let mut read_data = [0; 2];
+//!     let mut msgs = [
+//!         LinuxI2CMessage::write(&[0x01]),
+//!         LinuxI2CMessage::read(&mut read_data)
+//!     ];
+//!     dev.transfer(&mut msgs)?;
+//!
+//!     println!("Reading: {:?}", read_data);
+//!     Ok(())
+//! }
+//! ```
+//!
+//! ```rust,no_run
+//! extern crate i2cdev;
+//!
+//! use std::thread;
+//! use std::time::Duration;
+//!
+//! use i2cdev::core::*;
+//! use i2cdev::linux::{LinuxI2CBus, LinuxI2CError, LinuxI2CMessage};
+//!
+//! const SLAVE_ADDR: u16 = 0x57;
+//!
+//! fn write_read_transaction_using_bus() -> Result<(), LinuxI2CError> {
+//!     let mut dev = LinuxI2CBus::new("/dev/i2c-1")?;
+//!
+//!     let mut read_data = [0; 2];
+//!     let mut msgs = [
+//!         LinuxI2CMessage::write(&[0x01]).with_address(SLAVE_ADDR),
+//!         LinuxI2CMessage::read(&mut read_data).with_address(SLAVE_ADDR)
+//!     ];
+//!     dev.transfer(&mut msgs)?;
+//!
+//!     println!("Reading: {:?}", read_data);
+//!     Ok(())
+//! }
+//! ```
 
 #![crate_name = "i2cdev"]
 #![crate_type = "lib"]