1 2 3 4 5 6 7 8 9 10 11 12
13 14 15
16
17 import xdc.runtime.Error;
18
19 /*!
20 * ======== ISync ========
21 * OS independent synchronization
22 *
23 * This interface allows clients to select method of synchronization in an OS
24 * independent way.
25 *
26 * Modules that require the user to pick a synchronization method, will
27 * request a `{@link #Handle}`. Clients of such modules can pick a blocking
28 * `ISync` implementation or a non-blocking implementation.
29 *
30 * This interface specifies two main functions `{@link #signal}` and
31 * `{@link #wait}`. These two functions are always used in pairs in modules
32 * that use `ISync` instances. The `signal()` function is used to signal
33 * completion of an activity. The `wait()` function will allow the module to
34 * block or poll for completion of the same activity.
35 *
36 * `ISync` mandates that the sync mechanism be binary and not support counters.
37 * Although the `wait()` function seems meaningless in the case of
38 * non-blocking sync, it allows modules to be written generically and support
39 * all `ISync` implementations. For non-blocking `ISync` the `wait()` function
40 * will return `WaitStatus_TIMEOUT` to denote timeout.
41 */
42 @DirectCall
43
44 interface ISync
45 {
46 /*!
47 * ======== WaitStatus ========
48 * Error codes returned by ISync_wait
49 */
50 enum WaitStatus {
51 WaitStatus_ERROR = -1,
52 WaitStatus_TIMEOUT = 0,
53 WaitStatus_SUCCESS = 1
54 };
55
56 /*!
57 * ======== Q_BLOCKING ========
58 * Blocking quality
59 *
60 * Implementations with this "quality" may cause the calling thread to
61 * block;
62 */
63 const Int Q_BLOCKING = 1;
64
65 /*! Used to wait forever */
66 const UInt WAIT_FOREVER = ~(0);
67
68 /*! Used to specify no waiting */
69 const UInt NO_WAIT = 0;
70
71 instance:
72 /*!
73 * ======== create ========
74 * Create an ISync instance.
75 */
76 create();
77
78 /*!
79 * ======== query ========
80 * Query for a particular quality.
81 *
82 * FALSE is returned if quality not supported.
83 *
84 * @param(qual) quality
85 * @b(returns) TRUE or FALSE.
86 */
87 Bool query(Int qual);
88
89 /*!
90 * ======== signal ========
91 * Called at completion of an activity.
92 *
93 * This function is non-blocking. It is also required that the underlying
94 * sync be binary in nature.
95 *
96 * This function does not take an Error.Block intentionally because
97 * it can be called from ISR context.
98 */
99 Void signal();
100
101 /*!
102 * ======== wait ========
103 * Called to wait/poll for completion of an activity.
104 *
105 * This function can block. Non-blocking implementations should return
106 * WaitStatus_TIMEOUT to indicate a timeout.
107 *
108 * @p(blist)
109 * -{@link #WaitStatus_ERROR} if an error occured.
110 * -{@link #WaitStatus_TIMEOUT} denotes timeout.
111 * -{@link #WaitStatus_SUCCESS} semaphore was decremented.
112 * @p
113 *
114 * @param(timeout) Timeout in microseconds
115 * @param(eb)Hist Pointer to Error.Block
116 * @b(returns) Refer to description above
117 */
118 Int wait(UInt timeout, Error.Block *eb);
119 }
120 121 122
123