Merge pull request #2 from RusPiRo/feature/new_data_lock

add DataLock

Author: 2ndTaleStudio

.travis.yml

@@ -11,14 +11,15 @@ matrix:
 
   include:
     - rust: nightly
-      env: 
-        - TARGET=armv7-unknown-linux-gnueabihf
-        - CFLAGS='-std=c11 -mfpu=neon-fp-armv8 -mfloat-abi=hard -march=armv8-a -Wall -O3 -nostartfiles -ffreestanding -mtune=cortex-a53'
-        - RUSTFLAGS='-C target-cpu=cortex-a53 -C target-feature=+a53,+fp-armv8,+v8,+vfp3,+d16,+thumb2,+neon'
 
-script:
-  cargo build --target armv7-unknown-linux-gnueabihf --verbose
+script: ./travis-build.sh
 
 install:
+# install cross compiler toolchain
   - sudo apt-get install gcc-arm-linux-gnueabihf g++-arm-linux-gnueabihf
-  - rustup target add armv7-unknown-linux-gnueabihf
+# install cargo xbuild to proper cross compile  
+  - cargo install cargo-xbuild
+# add the build target used for Raspbarry Pi targeting builds
+  - rustup target add armv7-unknown-linux-gnueabihf
+  - rustup component add rust-src
+  - sudo chmod ugo+x ./travis-build.sh

Cargo.lock

@@ -1,18 +1,27 @@
 [package]
 name = "ruspiro-lock"
 authors = ["André Borrmann <[email protected]>"]
-version = "0.1.0" # remember to update html_root_url
-description = "This crates provide 2 simple atomic locks to be used to ensure safe atomic access to data. This is Spinlock and Semaphore"
+version = "0.2.0" # remember to update html_root_url
+description = """
+Simple atomic locking and safe data access (mutual exclusive) cross cores on Raspberry Pi.
+"""
 license = "Apache-2.0"
-repository = "https://github.com/RusPiRo/ruspiro-lock/tree/v0.1.0"
-documentation = "https://docs.rs/ruspiro-lock/0.1.0"
+repository = "https://github.com/RusPiRo/ruspiro-lock/tree/v0.2.0"
+documentation = "https://docs.rs/ruspiro-lock/0.2.0"
 readme = "README.md"
-keywords = ["RusPiRo", "spinlock", "semaphore", "raspberrypi"]
+keywords = ["RusPiRo", "spinlock", "semaphore", "datalock", "raspberrypi"]
 categories = ["no-std", "embedded"]
 edition = "2018"
 
+[badges]
+travis-ci = { repository = "RusPiRo/ruspiro-lock", branch = "master" }
+maintenance = { status = "actively-developed" }
+
 [lib]
 
 [dependencies]
+ruspiro-interrupt-core = "0.2"
 
 [features]
+default = ["ruspiro_pi3"]
+ruspiro_pi3 = []

Cargo.toml

@@ -1,6 +1,9 @@
 # RusPiRo Lock crate
 
-This crates provide two simple abstractions on low level atomic locks. The ``Spinlock`` and the ``Semaphore``.
+Simple to use abstractions on low level atomic locks:
+ - ``Spinlock``: blocking lock to secure cross core mutual exclusive access (requires a configured MMU on Raspberry Pi)
+ - ``Semaphore``: counting blocking or nonblocking lock to secure cross core exclusive access
+ - ``DataLock``: data container guarded by a nonblocking atomic lock to secure cross core mutual exclusive access
 
 [![Travis-CI Status](https://api.travis-ci.org/RusPiRo/ruspiro-lock.svg?branch=master)](https://travis-ci.org/RusPiRo/ruspiro-lock)
 [![Latest Version](https://img.shields.io/crates/v/ruspiro-lock.svg)](https://crates.io/crates/ruspiro-lock)
@@ -12,7 +15,7 @@ This crates provide two simple abstractions on low level atomic locks. The ``Spi
 To use this crate simply add the dependency to your ``Cargo.toml`` file:
 ```
 [dependencies]
-ruspiro-lock = "0.1.0"
+ruspiro-lock = "0.2"
 ```
 
 Once done the definition and usage of the locks is as follows:
@@ -48,5 +51,26 @@ fn main() {
 }
 ```
 
+Using data container with atmic lock guard:
+```
+use ruspiro_lock::*;
+
+static DATA: DataLock<u32> = DataLock::new(0);
+
+fn main() {
+    if let Some(mut data) = DATA.try_lock() {
+        *data = 20;
+    }
+    // once the data goes ot of scope the lock will be released
+    if let Some(data) = DATA.try_lock() {
+        println!("data: {}", *data);
+    
+        // another lock should fail inside this scope
+        assert_eq!(DATA.try_lock(), None);
+    }
+}
+```
+
+
 ## License
 Licensed under Apache License, Version 2.0, ([LICENSE](LICENSE) or http://www.apache.org/licenses/LICENSE-2.0)

README.md

@@ -0,0 +1,110 @@
+/*********************************************************************************************************************** 
+ * Copyright (c) 2019 by the authors
+ * 
+ * Author: André Borrmann 
+ * License: Apache License 2.0
+ **********************************************************************************************************************/
+
+//! # Data Lock
+//! 
+//! Enable exclusive access to data guarded by a cross core atomic lock
+//! 
+//! # Example
+//! ```
+//! static DATA: DataLock<u32> = DataLock::new(0);
+//! 
+//! fn main() {
+//!     if let Some(mut data) = DATA.try_lock() {
+//!         *data = 20;
+//!     }
+//!     // once the data goes ot of scope the lock will be released
+//!     if let Some(data) = DATA.try_lock() {
+//!         println!("data: {}", *data);
+//!     
+//!         // another lock should fail inside this scope
+//!         assert_eq!(DATA.try_lock(), None);
+//!     }
+//! }
+//! ```
+//! 
+
+use core::sync::atomic::{AtomicBool, Ordering};
+use core::cell::UnsafeCell;
+use core::ops::{Deref, DerefMut};
+
+/// An exclusive access lock around the given data
+pub struct DataLock<T> {
+    locked: AtomicBool,
+    data: UnsafeCell<T>,
+}
+
+/// Result of trying to access the data using ``try_lock`` on the data lock
+/// If the result goes out of scope the lock is released
+pub struct TryDataLock<'a, T> {
+    _data: &'a DataLock<T>,
+}
+
+impl<T> DataLock<T> {
+    /// Create a new data access guarding lock
+    pub fn new(value: T) -> Self {
+        DataLock {
+            locked: AtomicBool::new(false),
+            data: UnsafeCell::new(value),
+        }
+    }
+
+    /// Try to lock the guarded data for mutual exclusive access. Returns ``None`` if the lock failes
+    /// or ``Some(TryDataLock)``. The actual data, the TryDataLock wraps could be conviniently accessed by
+    /// dereferencing it.
+    /// 
+    /// # Example
+    /// ```
+    /// # fn doc() {
+    ///     let secure_data: DataLock<u32> = DataLock::new(10);
+    /// 
+    ///     if let Some(data) = secure_data.try_lock() {
+    ///         assert_eq!(*data, 10);
+    ///     }
+    /// # }
+    /// ```
+    pub fn try_lock(&self) -> Option<TryDataLock<T>> {
+        // do the atomic operation to set the lock
+        crate::disable_interrupts();
+        let data_lock = if !self.locked.swap(true, Ordering::SeqCst) {
+            // has been false previously means we now have the lock
+            Some(TryDataLock{
+                _data: self,
+            })
+        } else {
+            // we couldn't set the lock
+            None
+        };
+        crate::re_enable_interrupts();
+        data_lock
+    }
+}
+
+// when the TryDataLock is dropped release the owning lock
+impl<T> Drop for TryDataLock<'_, T> {
+    fn drop(&mut self) {
+        self._data.locked.swap(false, Ordering::SeqCst);
+    }
+}
+
+// dereferencing the value contained in the TryDataLock
+// this ok as the TryDataLock does only exist if the exclusive access to the data could
+// be ensures. Therefore also only one ``TryDataLock`` could ever exist for one specific ``DataLock``, which makes it
+// safe to return immutable and mutable references.
+impl <T> Deref for TryDataLock<'_, T> {
+    type Target = T;
+
+    fn deref(&self) -> &T {
+        unsafe { &*self._data.data.get() }
+    }
+}
+
+impl <T> DerefMut for TryDataLock<'_, T> {
+    fn deref_mut(&mut self) -> &mut T {
+        unsafe { &mut *self._data.data.get() }
+    }
+}

Xargo.toml

@@ -4,7 +4,7 @@
  * Author: André Borrmann 
  * License: Apache License 2.0
  **********************************************************************************************************************/
-#![doc(html_root_url = "https://docs.rs/ruspiro-lock/0.1.0")]
+#![doc(html_root_url = "https://docs.rs/ruspiro-lock/0.2.0")]
 #![no_std]
 #![feature(asm)]
 
@@ -31,7 +31,7 @@
 //! }
 //! ```
 //! 
-//! using a Semaphore to specify how often specific access is valid
+//! Using a Semaphore to specify how often specific access is valid.
 //! 
 //! ```
 //! use ruspriro_lock::*;
@@ -49,9 +49,38 @@
 //! }
 //! ```
 //! 
+//! Using data container with atmic lock guard.
+//! ```
+//! use ruspiro_lock::*;
+//! 
+//! static DATA: DataLock<u32> = DataLock::new(0);
+//! 
+//! fn main() {
+//!     if let Some(mut data) = DATA.try_lock() {
+//!         *data = 20;
+//!     }
+//!     // once the data goes ot of scope the lock will be released
+//!     if let Some(data) = DATA.try_lock() {
+//!         println!("data: {}", *data);
+//!     
+//!         // another lock should fail inside this scope
+//!         assert_eq!(DATA.try_lock(), None);
+//!     }
+//! }
+//! ```
+//! 
 
+
+// re-export the spinlock
 pub mod spinlock;
-pub use self::spinlock::*;
+pub use spinlock::*;
 
+// re-export the semaphore
 pub mod semaphore;
-pub use self::semaphore::*;
+pub use semaphore::*;
+
+// re-export the data-lock
+pub mod datalock;
+pub use datalock::*;
+
+use ruspiro_interrupt_core::*;