1 2 3 4 5 6 7 8 9 10 11 12
13 14 15
16 import xdc.runtime.Error;
17 import xdc.runtime.Assert;
18 import xdc.runtime.knl.ISync;
19
20 /*!
21 * ======== Sync ========
22 * Provides synchronization APIs when an ISync.Handle is available
23 *
24 * The application must first obtain an ISync.Handle.
25 * It can get such a handle by directly calling {@link SyncGeneric#create} or
26 * {@link SyncSemThread#create}. Then the application can use the generic
27 * APIs provided by this module.
28 */
29
30 module Sync
31 {
32 /*!
33 * ======== WaitStatus ========
34 * Error codes returned by Sync_wait
35 */
36 enum WaitStatus {
37 WaitStatus_ERROR = -1,
38 WaitStatus_TIMEOUT = 0,
39 WaitStatus_SUCCESS = 1
40 };
41
42 /*!
43 * ======== WAIT_FOREVER ========
44 * Used to wait forever
45 */
46 const UInt WAIT_FOREVER = ISync.WAIT_FOREVER;
47
48 /*!
49 * ======== NO_WAIT ========
50 * Used to specify no waiting
51 */
52 const UInt NO_WAIT = ISync.NO_WAIT;
53
54 /*!
55 * ======== Proxy ========
56 * Platform-specific implementation
57 *
58 * If ALL `ISync.Handles` were created using the same module
59 * (e.g SyncSemProcess), then setting `Proxy` to `SyncSemProcess` and
60 * `Sync.Proxy.abstractInstances$` to `false` will improve the
61 * performance of the `Sync` APIs.
62 */
63 proxy Proxy inherits ISync;
64
65 /*!
66 * ======== query ========
67 * Query for a particular quality
68 *
69 * FALSE is returned if quality not supported.
70 *
71 * @param(sync) sync handle
72 * @param(qual) quality
73 *
74 * @a(returns) TRUE or FALSE.
75 */
76 Bool query(ISync.Handle sync, Int qual);
77
78 /*!
79 * ======== signal ========
80 * Called at completion of an activity.
81 *
82 * This function is non-blocking. It is also required that the underlying
83 * sync be binary in nature.
84 *
85 * @param(sync) sync handle
86 */
87 Void signal(ISync.Handle sync);
88
89 /*!
90 * ======== wait ========
91 * Called to wait/poll for completion of an activity.
92 *
93 * This function can block and typically waits for a semaphore to become
94 * available.
95 *
96 * Non-blocking implementations should return {@link #WaitStatus_TIMEOUT}.
97 *
98 * @param(sync) sync handle
99 * @param(timeout) timeout in microseconds
100 *
101 * @a(returns)
102 * @p(blist)
103 * -{@link #WaitStatus_ERROR} if an error occured.
104 * -{@link #WaitStatus_TIMEOUT} denotes timeout.
105 * -{@link #WaitStatus_SUCCESS} semaphore was decremented.
106 * @p
107 */
108 Int wait(ISync.Handle sync, UInt timeout, Error.Block *eb);
109 }
110 111 112
113