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