BSP430  20141115
Board Support Package for MSP430 microcontrollers
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
Data Structures | Typedefs | Enumerations | Functions
resource.h File Reference

Support for resource management in BSP430. More...

#include <bsp430/core.h>

Go to the source code of this file.

Data Structures

struct  sBSP430resource
struct  sBSP430resourceWaiter
struct  sBSP430resourceReleaseFlag


typedef struct sBSP430resource sBSP430resource
typedef struct sBSP430resourcehBSP430resource
typedef int(* iBSP430resourceWaitCallback_ni) (hBSP430resource resource, struct sBSP430resourceWaiter *waiter)
typedef struct sBSP430resourceWaiter sBSP430resourceWaiter
typedef enum eBSP430resourceWait eBSP430resourceWait
typedef struct sBSP430resourceWaiterhBSP430resourceWaiter
typedef struct sBSP430resourceReleaseFlag sBSP430resourceReleaseFlag


enum  eBSP430resourceWait { eBSP430resourceWait_NONE, eBSP430resourceWait_FIFO, eBSP430resourceWait_LIFO }


int iBSP430resourceClaim_ni (hBSP430resource resource, void *self, eBSP430resourceWait wait_type, hBSP430resourceWaiter waiter)
int iBSP430resourceRelease_ni (hBSP430resource resource, void *self)
int iBSP430resourceCancelWait_ni (hBSP430resource resource, hBSP430resourceWaiter waiter)
int iBSP430resourceSetFlagOnRelease (hBSP430resource resource, hBSP430resourceWaiter waiter)

Detailed Description

Support for resource management in BSP430.

BSP430 allows a large number of peripheral resources to be shared among subsystems with loose coupling. For example, different source modules can share the interrupt capabilities of a digital port vector without requiring that the interrupt handler be modified. In this case the resource is a pin on the port, and that resource itself is not normally shared among different subsystems.

Experience has indicated that in some cases other peripherals, such as a SPI or I2C bus, may need to perform asynchronous activities using a resource without explicit coordination between systems.

In the original conception of BSP430 this was achieved by making all uses of the resource non-interruptible and run-to-completion. This has proved to be inadequate, especially in cases where the resource may be used for an extended period during which realtime needs require that interrupts be processed promptly.

The sBSP430resource structure and the API defined in this file support sharing these resources with a mutual exclusion capability similar to semaphores. Atomicity is ensured by disabling interrupts during all manipulation of resource structures. While the resource infrastructure itself will not block, it does provide a mechanism for subsystems to register a callback so they are notified of changes in the resource allocation state.


Typedef Documentation

Instructions for how a subsystem may prioritize itself on a list of sBSP430resourceWaiter instances. Used in iBSP430resourceClaim_ni().

A handle for a specific system resource

A handle for a structure holding information on a subsystem awaiting a resource

typedef int(* iBSP430resourceWaitCallback_ni) (hBSP430resource resource, struct sBSP430resourceWaiter *waiter)

The callback to provide a subsystem notification of a change in a resource's state.

This callback is invoked by iBSP430resourceRelease_ni() when a resource is released, or if the wait list changes so that a new head may be able to claim the resource (possibly recursively). The API specifically does not guarantee that the resource is in fact available when the callback is invoked.

The callback is explicitly permitted to invoke iBSP430resourceClaim_ni() in an attempt to claim the resource. Alternatively, it may set a flag and make the attempt to claim or decision to release at a later time, or invoke iBSP430resourceCancelWait_ni() if it no longer needs to be on the wait queue.

resourcethe resource that has just been released
waiterthe waiter record provided by the subsystem that wishes to be notified on resource availability.
An integral value consistent with Interrupt Callback Return Values that allows the notified subsystem to affect subsequent execution if the resource was released during an ISR top half.

Structure holding mutual exclusion data associated with some system resource.

Each resource structure should be initialized to all zeros prior to any possible reference to it.

A record identifying a flag and the bits in it that should be set when a resource is released.

A pointer to an instance of this type should be stored in the sBSP430resourceWaiter::context field of a waiter that uses iBSP430resourceSetFlagOnRelease() as its sBSP430resourceWaiter::callback_ni.

Structure registering a subsystem that needs to be informed when a resource is released.

Enumeration Type Documentation

Instructions for how a subsystem may prioritize itself on a list of sBSP430resourceWaiter instances. Used in iBSP430resourceClaim_ni().


Indicate that iBSP430resourceClaim_ni() does not register a waiter if the resource is already in use


Indicate that iBSP430resourceClaim_ni() should add this waiter to the end of the queue if the resource is already in use.

If the waiter is already in the queue its position is not changed.


Indicate that iBSP430resourceClaim_ni() should add this waiter to the beginning of the queue if the resource is already in use.

If the waiter is already in the queue its position is not changed.

Function Documentation

int iBSP430resourceCancelWait_ni ( hBSP430resource  resource,
hBSP430resourceWaiter  waiter 

Remove waiter from the queue for resource.

This function is used when a subsystem that has requested a resource determines that the resource is no longer needed.

If waiter was at the head of the resource's wait queue the callback of the new head of the queue (if any) will be recursively invoked and its return value used as the return value of this function. This ensures that invocation of this function from within an iBSP430resourceWaitCallback_ni() will not cause the notification of availability to be lost, and that recursive resource allocation is satisfied as soon as possible.

There is no validation (and no penalty) if waiter is not on the resource wait list.
resourcea pointer to the structure associated with a shared resource
waiterthe wait handle used for notification when the resource becomes available.
The return value from the callback to the new head if that was invoked, or zero.
int iBSP430resourceClaim_ni ( hBSP430resource  resource,
void *  self,
eBSP430resourceWait  wait_type,
hBSP430resourceWaiter  waiter 

Attempt to claim the right to use a resource.

This is a non-blocking call. The caller is granted the right to use the resource if the resource is not in use, or if the holder of the resource is self. In either case, sBSP430resource::count is incremented, and 0 is returned.

If the resource is in use by another holder, the attempt to claim fails and -1 is returned.

If the resource claim succeeds, any appearance of waiter is removed from the resource sBSP430resource::waiter list prior to return. If the resource claim fails and waiter is not a null pointer, waiter is added into the sBSP430resource::waiter waiter list in the order specified by wait_type if absent from that list, and left in its original position if already present in the list.

BSP430 does not aspire to be an RTOS, and the weak prioritization supported by wait_type is not affected by repeated failed resource claim attempts. If necessary the waiter can be reprioritized by removing it and making another attempt to claim the resource.
resourcea pointer to the structure associated with a resource that may be shared among subsystems.
selfan identifier unique to the requesting subsystem. If this is a null pointer, attempts to claim the resource will succeed only if it is not in use; in that situation, in a successful claim the holder is set to be the resource itself. In many cases, waiter is an appropriate unique value to use for self when a recursive mutex is required, and NULL when a non-recursive mutex is required.
wait_typeHow waiter should be prioritized relative to any other waiters that may already be in the queue
waiterAn optional structure that can be used to notify the calling subsystem when the resource may be available. A null pointer is used when the caller will retry as needed without a notification.
0 if the resource was successfully claimed. A negative value if it could not be claimed.
int iBSP430resourceRelease_ni ( hBSP430resource  resource,
void *  self 

Release a resource held by a subsystem.

Note that the return value does not indicate whether the resource is still held by this subsystem. If the resource was released, the first waiter on the resource's waiter list (if any) will be notified.

resourcea pointer to the structure associated with a resource that may be shared among subsystems.
selfas in iBSP430resourceClaim_ni(). If self does not match the holder of the resource the application will spin in place (if BSP430_CORE_NDEBUG is zero) or return a negative error code (if BSP430_CORE_NDEBUG is nonzero).
A negative value if an error occurs; 0 if the release was successful and there are no subsystems queued to be notified on release; otherwise the result of invoking the sBSP430resourceWaiter::callback_ni function of the highest-priority waiter.
int iBSP430resourceSetFlagOnRelease ( hBSP430resource  resource,
hBSP430resourceWaiter  waiter 

Function conforming to iBSP430resourceWaitCallback_ni

In many cases the release of a resource can be communicated to a waiting subsystem by setting a flag in the subsystem's event set and waking the system to process pending events.

resourcethe resource that is being released
waiterthe waiter record provided by the subsystem in an unsuccessful call to iBSP430resourceClaim_ni().