From d0ddc322e378e498743121121c8849260d2f1726 Mon Sep 17 00:00:00 2001 From: Jorge Aparicio Date: Fri, 21 Apr 2017 21:38:39 -0500 Subject: [PATCH] rename `borrow` to `access` --- src/lib.rs | 73 +++++++++++++++++++++--------------------- tests/cfail/access.rs | 37 +++++++++++++++++++++ tests/cfail/borrow.rs | 37 --------------------- tests/cfail/ceiling.rs | 4 +-- tests/cfail/lock.rs | 6 ++-- tests/cfail/race-1.rs | 4 +-- tests/cfail/race-2.rs | 4 +-- 7 files changed, 83 insertions(+), 82 deletions(-) create mode 100644 tests/cfail/access.rs delete mode 100644 tests/cfail/borrow.rs diff --git a/src/lib.rs b/src/lib.rs index a0c8a3bac3..74fcebe8e6 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -420,20 +420,17 @@ impl Local { unsafe impl Sync for Local {} /// A resource with ceiling `C` -/// -/// Only tasks with priority equal to or smaller than `C` can access this -/// resource pub struct Resource { _ceiling: PhantomData, data: UnsafeCell, } -impl Resource> +impl Resource> where - CEILING: GreaterThanOrEqual, - CEILING: LessThanOrEqual, + RC: GreaterThanOrEqual, + RC: LessThanOrEqual, { - /// 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 Resource> { - /// Borrows the resource for the duration of a critical section +impl Resource> { + /// 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 - /// resource ceiling can access the resource. - pub fn borrow<'cs, PRIORITY, CCEILING>( + /// # Requirements + /// + /// 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, - _current_ceiling: &'cs C, + _priority: &P, + _current_ceiling: &'cs C, ) -> Ref<'cs, T> where - CCEILING: GreaterThanOrEqual, - CEILING: GreaterThanOrEqual, + RC: GreaterThanOrEqual, + SC: GreaterThanOrEqual, { unsafe { Ref::new(&*self.data.get()) } } @@ -492,16 +495,16 @@ where } } -impl Peripheral> { - /// See [Resource.borrow](./struct.Resource.html#method.borrow) - pub fn borrow<'cs, PRIORITY, CCEILING>( +impl Peripheral> { + /// See [Resource.access](./struct.Resource.html#method.access) + pub fn access<'cs, TP, SC>( &'static self, - _priority: &P, - _current_ceiling: &'cs C, + _priority: &P, + _system_ceiling: &'cs C, ) -> Ref<'cs, Periph> where - CCEILING: GreaterThanOrEqual, - CEILING: GreaterThanOrEqual, + RC: GreaterThanOrEqual, + SC: GreaterThanOrEqual, { unsafe { Ref::new(&*self.peripheral.get()) } } @@ -569,19 +572,17 @@ pub struct C { _marker: PhantomData, } -impl C { - /// Raises the ceiling to match `resource`'s ceiling - pub fn raise(&self, _resource: &'static RES, f: F) -> R +impl C { + /// Raises the system ceiling to match the `resource` ceiling + pub fn raise(&self, _resource: &'static RES, f: F) -> R where - RES: ResourceLike, - HIGHER: Cmp, - HIGHER: Cmp, - HIGHER: Unsigned, - F: FnOnce(&C) -> R, + RES: ResourceLike, + RC: Cmp + Cmp + Unsigned, + F: FnOnce(&C) -> 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 ResourceLike for Peripheral> { - type Ceiling = CEILING; +unsafe impl ResourceLike for Peripheral> { + type Ceiling = RC; } -unsafe impl ResourceLike for Resource> { - type Ceiling = CEILING; +unsafe impl ResourceLike for Resource> { + type Ceiling = RC; } /// Type-level `>=` operator diff --git a/tests/cfail/access.rs b/tests/cfail/access.rs new file mode 100644 index 0000000000..db776025b0 --- /dev/null +++ b/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 = Resource::new(0); +static R2: Resource = Resource::new(0); +static R3: Resource = Resource::new(0); +static R4: Resource = Resource::new(0); +static R5: Resource = Resource::new(0); +static R6: Resource = 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); + } + ); +} diff --git a/tests/cfail/borrow.rs b/tests/cfail/borrow.rs deleted file mode 100644 index 6f9e1a863a..0000000000 --- a/tests/cfail/borrow.rs +++ /dev/null @@ -1,37 +0,0 @@ -extern crate cortex_m_rtfm as rtfm; - -use rtfm::{C1, C2, C3, C4, C5, P2, Resource}; - -static R1: Resource = Resource::new(0); -static R2: Resource = Resource::new(0); -static R3: Resource = Resource::new(0); -static R4: Resource = Resource::new(0); -static R5: Resource = Resource::new(0); -static R6: Resource = 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); - } - ); -} diff --git a/tests/cfail/ceiling.rs b/tests/cfail/ceiling.rs index b13be80239..cf3b70921c 100644 --- a/tests/cfail/ceiling.rs +++ b/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); } diff --git a/tests/cfail/lock.rs b/tests/cfail/lock.rs index ca4ea73c4d..073e1dd9ca 100644 --- a/tests/cfail/lock.rs +++ b/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 = 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()); } diff --git a/tests/cfail/race-1.rs b/tests/cfail/race-1.rs index 9037ed44f9..a4d9b68931 100644 --- a/tests/cfail/race-1.rs +++ b/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 }, ); diff --git a/tests/cfail/race-2.rs b/tests/cfail/race-2.rs index 6bd957e5dc..71f44fb968 100644 --- a/tests/cfail/race-2.rs +++ b/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 } );