1 /*
2 * Copyright (c) 2008 Texas Instruments. All rights reserved.
3 * This program and the accompanying materials are made available under the
4 * terms of the Eclipse Public License v1.0 and Eclipse Distribution License
5 * v. 1.0 which accompanies this distribution. The Eclipse Public License is
6 * available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
7 * Distribution License is available at
8 * http://www.eclipse.org/org/documents/edl-v10.php.
9 *
10 * Contributors:
11 * Texas Instruments - initial implementation
12 * */
13 /*
14 * ======== ISync.xdc ========
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 * @(#) xdc.runtime.knl; 1, 0, 0,16; 6-9-2009 20:09:51; /db/ztree/library/trees/xdc-t50x/src/packages/
123 */
124