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
43 interface ISync
44 {
45 /*!
46 * ======== WaitStatus ========
47 * Error codes returned by ISync_wait
48 */
49 enum WaitStatus {
50 WaitStatus_ERROR = -1,
51 WaitStatus_TIMEOUT = 0,
52 WaitStatus_SUCCESS = 1
53 };
54
55 /*!
56 * ======== Q_BLOCKING ========
57 * Blocking quality
58 *
59 * Implementations with this "quality" may cause the calling thread to
60 * block;
61 */
62 const Int Q_BLOCKING = 1;
63
64 /*! Used to wait forever */
65 const UInt WAIT_FOREVER = ~(0);
66
67 /*! Used to specify no waiting */
68 const UInt NO_WAIT = 0;
69
70 instance:
71 /*!
72 * ======== create ========
73 * Create an ISync instance.
74 */
75 create();
76
77 /*!
78 * ======== query ========
79 * Query for a particular quality.
80 *
81 * FALSE is returned if quality not supported.
82 *
83 * @param(qual) quality
84 * @b(returns) TRUE or FALSE.
85 */
86 Bool query(Int qual);
87
88 /*!
89 * ======== signal ========
90 * Called at completion of an activity.
91 *
92 * This function is non-blocking. It is also required that the underlying
93 * sync be binary in nature.
94 *
95 * This function does not take an Error.Block intentionally because
96 * it can be called from ISR context.
97 */
98 Void signal();
99
100 /*!
101 * ======== wait ========
102 * Called to wait/poll for completion of an activity.
103 *
104 * This function can block. Non-blocking implementations should return
105 * WaitStatus_TIMEOUT to indicate a timeout.
106 *
107 * @p(blist)
108 * -{@link #WaitStatus_ERROR} if an error occured.
109 * -{@link #WaitStatus_TIMEOUT} denotes timeout.
110 * -{@link #WaitStatus_SUCCESS} semaphore was decremented.
111 * @p
112 *
113 * @param(timeout) Timeout in microseconds
114 * @param(eb)Hist Pointer to Error.Block
115 * @b(returns) Refer to description above
116 */
117 Int wait(UInt timeout, Error.Block *eb);
118 }
119 120 121
122