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

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

Enumerations
enum	eBSP430resourceWait { eBSP430resourceWait_NONE, eBSP430resourceWait_FIFO, eBSP430resourceWait_LIFO }

Functions
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.

Homepage

http://github.com/pabigot/bsp430

Copyright

Copyright 2013-2014, Peter A. Bigot. Licensed under BSD-3-Clause

Typedef Documentation

typedef enum eBSP430resourceWait eBSP430resourceWait

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

typedef struct sBSP430resource* hBSP430resource

A handle for a specific system resource

typedef struct sBSP430resourceWaiter* hBSP430resourceWaiter

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.

Parameters

resource	the resource that has just been released
waiter	the waiter record provided by the subsystem that wishes to be notified on resource availability.

Returns

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.

typedef struct sBSP430resource sBSP430resource

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.

typedef struct sBSP430resourceReleaseFlag sBSP430resourceReleaseFlag

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.

typedef struct sBSP430resourceWaiter sBSP430resourceWaiter

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

Enumeration Type Documentation

enum eBSP430resourceWait

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

Enumerator
eBSP430resourceWait_NONE	Indicate that iBSP430resourceClaim_ni() does not register a waiter if the resource is already in use
eBSP430resourceWait_FIFO	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.
eBSP430resourceWait_LIFO	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.

Note

There is no validation (and no penalty) if waiter is not on the resource wait list.

Parameters

resource	a pointer to the structure associated with a shared resource
waiter	the wait handle used for notification when the resource becomes available.

Returns

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.

Note

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.

Parameters

resource	a pointer to the structure associated with a resource that may be shared among subsystems.
self	an 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_type	How waiter should be prioritized relative to any other waiters that may already be in the queue
waiter	An 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.

Returns

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.

Parameters

resource	a pointer to the structure associated with a resource that may be shared among subsystems.
self	as 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).

Returns

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.

Parameters

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

Returns

BSP430_HAL_ISR_CALLBACK_EXIT_LPM