rename borrow to access

src/lib.rs

@@ -420,20 +420,17 @@ impl<T, TASK> Local<T, TASK> {
 unsafe impl<T, TASK> Sync for Local<T, TASK> {}
 
 /// A resource with ceiling `C`
-///
-/// Only tasks with priority equal to or smaller than `C` can access this
-/// resource
 pub struct Resource<T, C> {
     _ceiling: PhantomData<C>,
     data: UnsafeCell<T>,
 }
 
-impl<T, CEILING> Resource<T, C<CEILING>>
+impl<T, RC> Resource<T, C<RC>>
 where
-    CEILING: GreaterThanOrEqual<U0>,
+    RC: GreaterThanOrEqual<U0>,
-    CEILING: LessThanOrEqual<UMAX>,
+    RC: LessThanOrEqual<UMAX>,
 {
-    /// Creates a new resource with the specified `CEILING`
+    /// Creates a new resource
     pub const fn new(data: T) -> Self {
         Resource {
             _ceiling: PhantomData,
@@ -442,21 +439,27 @@ where
     }
 }
 
-impl<T, CEILING> Resource<T, C<CEILING>> {
+impl<T, RC> Resource<T, C<RC>> {
-    /// Borrows the resource for the duration of a critical section
+    /// Grants data race free and deadlock free access to the resource data
     ///
     /// This operation is zero cost and doesn't impose any additional blocking.
     ///
-    /// **NOTE** Only tasks with a priority equal to or smaller than the
+    /// # Requirements
-    /// resource ceiling can access the resource.
+    ///
-    pub fn borrow<'cs, PRIORITY, CCEILING>(
+    /// To access the resource data these conditions must be met:
+    ///
+    /// - The resource ceiling must be greater than or equal to the task
+    ///   priority
+    /// - The system ceiling must be greater than or equal to the resource
+    ///   ceiling
+    pub fn access<'cs, TP, SC>(
         &'static self,
-        _priority: &P<PRIORITY>,
+        _priority: &P<TP>,
-        _current_ceiling: &'cs C<CCEILING>,
+        _current_ceiling: &'cs C<SC>,
     ) -> Ref<'cs, T>
     where
-        CCEILING: GreaterThanOrEqual<CEILING>,
+        RC: GreaterThanOrEqual<TP>,
-        CEILING: GreaterThanOrEqual<PRIORITY>,
+        SC: GreaterThanOrEqual<RC>,
     {
         unsafe { Ref::new(&*self.data.get()) }
     }
@@ -492,16 +495,16 @@ where
     }
 }
 
-impl<Periph, CEILING> Peripheral<Periph, C<CEILING>> {
+impl<Periph, RC> Peripheral<Periph, C<RC>> {
-    /// See [Resource.borrow](./struct.Resource.html#method.borrow)
+    /// See [Resource.access](./struct.Resource.html#method.access)
-    pub fn borrow<'cs, PRIORITY, CCEILING>(
+    pub fn access<'cs, TP, SC>(
         &'static self,
-        _priority: &P<PRIORITY>,
+        _priority: &P<TP>,
-        _current_ceiling: &'cs C<CCEILING>,
+        _system_ceiling: &'cs C<SC>,
     ) -> Ref<'cs, Periph>
     where
-        CCEILING: GreaterThanOrEqual<CEILING>,
+        RC: GreaterThanOrEqual<TP>,
-        CEILING: GreaterThanOrEqual<PRIORITY>,
+        SC: GreaterThanOrEqual<RC>,
     {
         unsafe { Ref::new(&*self.peripheral.get()) }
     }
@@ -569,19 +572,17 @@ pub struct C<T> {
     _marker: PhantomData<T>,
 }
 
-impl<CURRENT> C<CURRENT> {
+impl<SC> C<SC> {
-    /// Raises the ceiling to match `resource`'s ceiling
+    /// Raises the system ceiling to match the `resource` ceiling
-    pub fn raise<HIGHER, RES, R, F>(&self, _resource: &'static RES, f: F) -> R
+    pub fn raise<RC, RES, R, F>(&self, _resource: &'static RES, f: F) -> R
     where
-        RES: ResourceLike<Ceiling = HIGHER>,
+        RES: ResourceLike<Ceiling = RC>,
-        HIGHER: Cmp<CURRENT, Output = Greater>,
+        RC: Cmp<SC, Output = Greater> + Cmp<UMAX, Output = Less> + Unsigned,
-        HIGHER: Cmp<UMAX, Output = Less>,
+        F: FnOnce(&C<RC>) -> R,
-        HIGHER: Unsigned,
-        F: FnOnce(&C<HIGHER>) -> R,
     {
         unsafe {
             let old_basepri = basepri::read();
-            basepri_max::write(logical2hw(HIGHER::to_u8()));
+            basepri_max::write(logical2hw(RC::to_u8()));
             barrier!();
             let ret = f(&C { _marker: PhantomData });
             barrier!();
@@ -614,12 +615,12 @@ pub unsafe trait ResourceLike {
     type Ceiling;
 }
 
-unsafe impl<P, CEILING> ResourceLike for Peripheral<P, C<CEILING>> {
+unsafe impl<P, RC> ResourceLike for Peripheral<P, C<RC>> {
-    type Ceiling = CEILING;
+    type Ceiling = RC;
 }
 
-unsafe impl<T, CEILING> ResourceLike for Resource<T, C<CEILING>> {
+unsafe impl<T, RC> ResourceLike for Resource<T, C<RC>> {
-    type Ceiling = CEILING;
+    type Ceiling = RC;
 }
 
 /// Type-level `>=` operator

tests/cfail/access.rs

@@ -0,0 +1,37 @@
+extern crate cortex_m_rtfm as rtfm;
+
+use rtfm::{C1, C2, C3, C4, C5, P2, Resource};
+
+static R1: Resource<i32, C4> = Resource::new(0);
+static R2: Resource<i32, C3> = Resource::new(0);
+static R3: Resource<i32, C4> = Resource::new(0);
+static R4: Resource<i32, C5> = Resource::new(0);
+static R5: Resource<i32, C1> = Resource::new(0);
+static R6: Resource<i32, C2> = Resource::new(0);
+
+fn j1(prio: P2) {
+    let ceil = prio.as_ceiling();
+
+    ceil.raise(
+        &R1, |ceil| {
+            // NOTE SC = System Ceiling, P = task Priority
+
+            // CAN access a resource with ceiling RC when SC > RC
+            let r2 = R2.access(&prio, ceil);
+
+            // CAN access a resource with ceiling RC when SC == RC
+            let r3 = R3.access(&prio, ceil);
+
+            // CAN'T access a resource with ceiling RC when SC < RC
+            let r4 = R4.access(&prio, ceil);
+            //~^ error
+
+            // CAN'T access a resource with ceiling RC when RC < P
+            let r5 = R5.access(&prio, ceil);
+            //~^ error
+
+            // CAN access a resource with ceiling RC when RC == P
+            let r6 = R6.access(&prio, ceil);
+        }
+    );
+}

tests/cfail/borrow.rs

@@ -1,37 +0,0 @@
-extern crate cortex_m_rtfm as rtfm;
-
-use rtfm::{C1, C2, C3, C4, C5, P2, Resource};
-
-static R1: Resource<i32, C4> = Resource::new(0);
-static R2: Resource<i32, C3> = Resource::new(0);
-static R3: Resource<i32, C4> = Resource::new(0);
-static R4: Resource<i32, C5> = Resource::new(0);
-static R5: Resource<i32, C1> = Resource::new(0);
-static R6: Resource<i32, C2> = Resource::new(0);
-
-fn j1(prio: P2) {
-    let ceil = prio.as_ceiling();
-
-    ceil.raise(
-        &R1, |ceil| {
-            // NOTE CC = Current Ceiling, P = task Priority
-
-            // CAN borrow a resource with ceiling RC when CC > RC
-            let r2 = R2.borrow(&prio, ceil);
-
-            // CAN borrow a resource with ceiling RC when CC == RC
-            let r3 = R3.borrow(&prio, ceil);
-
-            // CAN'T borrow a resource with ceiling RC when CC < RC
-            let r4 = R4.borrow(&prio, ceil);
-            //~^ error
-
-            // CAN'T borrow a resource with ceiling RC when RC < P
-            let r5 = R5.borrow(&prio, ceil);
-            //~^ error
-
-            // CAN borrow a resource with ceiling RC when RC == P
-            let r6 = R6.borrow(&prio, ceil);
-        }
-    );
-}

tests/cfail/ceiling.rs

@@ -15,7 +15,7 @@ fn j1(prio: P2) {
     );
 
     // Would be bad: lockless access to a resource with ceiling = 3
-    let r2 = R1.borrow(&prio, c3);
+    let r2 = R1.access(&prio, c3);
 }
 
 fn j2(prio: P0) {
@@ -27,5 +27,5 @@ fn j2(prio: P0) {
     );
 
     // Would be bad: lockless access to a resource with ceiling = 16
-    let r1 = R1.borrow(&prio, c16);
+    let r1 = R1.access(&prio, c16);
 }

tests/cfail/lock.rs

@@ -21,7 +21,7 @@ fn j2(prio: P2) {
     //~^ error
 
     // OK
-    let r1 = R1.borrow(&prio, ceil);
+    let r1 = R1.access(&prio, ceil);
 }
 
 // You CAN access a resource with ceiling C from a task with priority P if C > P
@@ -30,7 +30,7 @@ fn j3(prio: P1) {
     let ceil = prio.as_ceiling();
 
     // OK
-    ceil.raise(&R1, |ceil| { let r1 = R1.borrow(&prio, ceil); })
+    ceil.raise(&R1, |ceil| { let r1 = R1.access(&prio, ceil); })
 }
 
 static R2: Resource<i32, C16> = Resource::new(0);
@@ -46,5 +46,5 @@ fn j4(prio: P1) {
 // Only tasks with priority P16 can access a resource with ceiling C16
 fn j5(prio: P16) {
     // OK
-    let r2 = R2.borrow(&prio, prio.as_ceiling());
+    let r2 = R2.access(&prio, prio.as_ceiling());
 }

tests/cfail/race-1.rs

@@ -9,7 +9,7 @@ fn j1(prio: P1) {
 
     ceil.raise(
         &R1, |ceil| {
-            let r1 = R1.borrow(&prio, ceil);
+            let r1 = R1.access(&prio, ceil);
 
             // `j2` preempts this critical section
             rtfm::request(j2);
@@ -22,7 +22,7 @@ fn j2(_task: Task, prio: P3) {
         |ceil| {
             // OK  C2 (R1's ceiling) <= C16 (system ceiling)
             // BAD C2 (R1's ceiling) <  P3 (j2's priority)
-            let r1 = R1.borrow(&prio, &ceil);
+            let r1 = R1.access(&prio, &ceil);
             //~^ error
         },
     );

tests/cfail/race-2.rs

@@ -10,7 +10,7 @@ fn j1(prio: P1) {
 
     ceil.raise(
         &R1, |ceil| {
-            let r1 = R1.borrow(&prio, ceil);
+            let r1 = R1.access(&prio, ceil);
 
             // `j2` preempts this critical section
             rtfm::request(j2);
@@ -25,7 +25,7 @@ fn j2(_task: Task, prio: P3) {
         &R2, |ceil| {
             // OK  C2 (R1's ceiling) <= C4 (system ceiling)
             // BAD C2 (R1's ceiling) <  P3 (j2's priority)
-            let r1 = R1.borrow(&prio, ceil);
+            let r1 = R1.access(&prio, ceil);
             //~^ error
         }
     );