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