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