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