mware/resource.h

   1 #ifndef MWARE_RESOURCE_H
   2 #define MWARE_RESOURCE_H
   3
   4 #include <drv/timer.h> // time_t
   5 #include <kern/sem.h>
   6
   7 /*
   8  * Abstract locking primitives used by host OS.
   9  */
  10 #if CONFIG_KERNEL
  11
  12         typedef Semaphore ResourceLock;
  13         #define ResMan_sleep()         timer_delay(1)
  14         #define ResMan_time_t          mtime_t
  15
  16 #else /* FreeRTOS */
  17
  18         #include <freertos.h>
  19         #include <semphr.h>
  20         #include <task.h> // vTaskDelay()
  21
  22         #define ResMan_sleep()        vTaskDelay((portTickType)1 * portTICK_RATE_MS)
  23         #define ResMan_time_t         portTickType
  24 #endif
  25
  26
  27 // Forward decl
  28 struct Observer;
  29
  30 /**
  31  * Hold context information for a resource such as an audio channel.
  32  *
  33  * Each driver registers one or more Resource instances with the
  34  * ResMan using ResMan_Register().
  35  *
  36  * Clients can then allocate the resource through ResMan_Alloc()
  37  * providing a desired priority and an Observer for asynchronous
  38  * notification.
  39  *
  40  * Allocated resources can be stolen by other clients asking for a
  41  * higher priority.  ResMan notifies a preemption request by invoking
  42  * the Observer of the current owner.
  43  *
  44  * The Observer callback must take whatever action is needed to
  45  * release the resource as soon as possible to avoid blocking the
  46  * new owner.
  47  */
  48 typedef struct Resource
  49 {
  50 //Private
  51         /// Control access to fields below.
  52         Semaphore lock;
  53
  54         /// Pointer to current owner's observer.  NULL if resource is free.
  55         struct Observer *owner;
  56
  57         /// Priority of current owner (higher values mean higher priority).
  58         int pri;
  59
  60         /// Queue of processes waiting to obtain the resource.
  61         List queue;
  62 } Resource;
  63
  64 /// Event sent by ResMan to owners when to request resource release.
  65 enum { EVENT_RELEASE = 1 };
  66
  67 /// Try to allocate a resource \a res with priority \a pri for at most \a timeout ticks.
  68 bool ResMan_Alloc(Resource *res, int pri, ResMan_time_t timeout, struct Observer *releaseRequest);
  69
  70 /// Free resource \a res.  Will eventually wake-up other queued owners.
  71 void ResMan_Free(Resource *res);
  72
  73 void ResMan_Init(Resource *res);
  74
  75 #endif /* MWARE_RESOURCE_H */