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 * ======== Assert.xdc ========
15 */
16
17 /*!
18 * ======== Assert ========
19 * Runtime assertion manager
20 *
21 * The `Assert` module provides configurable diagnostics to the program.
22 * Similar to the standard C `assert()` macro, `Assert` methods are
23 * interspersed with other code to add diagnostics to a program. Unlike
24 * the standard C assert support, the `Assert` module provides greater
25 * flexibility in managing the messages displayed, the message string
26 * space overhead, and the runtime handling of failures. In addition,
27 * because the `Assert` methods build atop the Diags module, you can
28 * precisely control which asserts remain in the final application, if any.
29 *
30 * The `Assert` module works in conjunction with the `{@link Diags}` module.
31 * `Assert` statements are added to the code using the
32 * `{@link #isTrue Assert_isTrue()}` function. Execution of assert
33 * statements is controlled by the `{@link Diags#ASSERT}` and
34 * `{@link Diags#INTERNAL}` bits in a module's diagnostics mask. By default,
35 * all module's `Diags_ASSERT` bit is enabled and the `Diags_INTERNAL` bit
36 * is disabled. See `{@link Types#Common$ Types.Common$}` for the
37 * declaration of the bits in the diagnostics mask and
38 * `{@link Defaults#common$ Default.common$}` for the default module settings.
39 *
40 * Two types of asserts are supported: public asserts and internal asserts.
41 *
42 * @p(blist) 43 * - Public asserts have an assert ID and are, by default, controlled
44 * by the `{@link Diags#ASSERT}` bit.
45 * - Internal asserts don't have an assert ID (other than NULL) and
46 * are active only when both the `{@link Diags#ASSERT}` and
47 * `{@link Diags#INTERNAL}` bits of the module's diagnostics mask are set.
48 * @p 49 *
50 * `Assert` IDs are small integer values that index into a table of
51 * assertion descriptors. These descriptors hold an error message
52 * and a diagnostics mask that is used to enable and disable the
53 * assertion at runtime.
54 *
55 * You can remap individual public asserts to different bits in the
56 * diagnostics mask, or can disable the assert altogether. This is
57 * done by setting the mask property of the assert ID. Setting the
58 * mask to 0 disables the assert. In all other cases, the `Diags.ASSERT`
59 * bit is OR'd together with the mask to define the controlling bits.
60 * For example, the module's diagnostics mask must have the `Diags.ASSERT`
61 * bit set and any other bit specified in the mask property of the
62 * assert ID in order to activate the assert.
63 *
64 * @a(Examples) 65 * Example 1: The following C code adds an assert to application code
66 * which is not in a module. This assert does not have an assert
67 * identifier (the second argument is NULL); this makes it an internal
68 * assert.
69 *
70 * @p(code) 71 * // file.c
72 * #include <xdc/runtime/Assert.h>
73 *
74 * Assert_isTrue(count > 0, NULL);
75 * @p 76 *
77 * The following XDC configuration statements set both the ASSERT and
78 * INTERNAL bits in the diagnostics mask to enable the internal assert
79 * created in the previous C code. Since the C code is not in a module,
80 * you must set the bits in the diagnostics mask of the
81 * `{@link xdc.runtime.Main xdc.runtime.Main}` module. The Main module
82 * is used to control all `{@link Log}` and `Assert` statements that are
83 * not part of the implementation of a module; for example, top-level
84 * application code or any existing sources that simply call the `Log` or
85 * `Assert` methods.
86 *
87 * @p(code) 88 * // program.cfg
89 * var Assert = xdc.useModule('xdc.runtime.Assert');
90 * var Diags = xdc.useModule('xdc.runtime.Diags');
91 * var Main = xdc.useModule('xdc.runtime.Main');
92 *
93 * Main.common$.diags_ASSERT = Diags.ALWAYS_ON;
94 * Main.common$.diags_INTERNAL = Diags.ALWAYS_ON;
95 * @p 96 *
97 * @p(html) 98 * <hr />
99 * @p 100 *
101 * Example 2: The following example shows how to use and configure an
102 * assert ID that is declared by a module. It adds that assert to the
103 * application's C source code, and configures the application to
104 * execute the assert.
105 *
106 * This is part of the XDC file for the module that declares an `Assert` Id:
107 *
108 * @p(code) 109 * // Mod.xdc
110 * import xdc.runtime.Assert;
111 * import xdc.runtime.Diags;
112 *
113 * config Assert.Id A_nonZero = {
114 * msg: "A_nonZero: value must be non-zero"
115 * };
116 * @p 117 *
118 * This is part of the C code for the application:
119 *
120 * @p(code) 121 * // Mod.c
122 * #include <xdc/runtime/Assert.h>
123 *
124 * Assert_isTrue(x != 0, Mod_A_nonZero);
125 * @p 126 *
127 * This is part of the XDC configuration file for the application:
128 *
129 * @p(code) 130 * // program.cfg
131 * var Diags = xdc.useModule('xdc.runtime.Diags');
132 * var Mod = xdc.useModule('my.pkg.Mod');
133 * Mod.common$.diags_ASSERT = Diags.ALWAYS_ON;
134 * @p 135 */
136
137 @CustomHeader
138
139 module Assert {
140
141 /*!
142 * ======== Assert_Desc ========
143 * Assert descriptor
144 *
145 * Each public assert is defined with an assert descriptor. This
146 * structure defines which bits in the module's diagnostics mask
147 * control this assert, and the message raised when the assert fails.
148 * The mask property is optional, it defaults to the
149 * `{@link Diags#ASSERT}` bit.
150 *
151 * @field(mask) Specifies which bits enable the assert.
152 * @field(msg) The message printed when the assert fails.
153 */
154 metaonlystruct Desc {
155 Diags.Mask mask;
156 String msg;
157 };
158
159 /*!
160 * ======== Assert_Id ========
161 * Assert identifier
162 *
163 * Each metaonly assert descriptor is encoded into a target accessable
164 * assert Id type which can be passed to the `{@link #isTrue}` function.
165 */
166 @Encoded typedef Desc Id;
167
168 /*!
169 * ======== E_assertFailed ========
170 * The `{@link Error#Id}` raised when an assertion violation is detected
171 *
172 * When an assertion violation is triggered, an error is raised via
173 * `Error_raise()`. `E_assert_Failed` is the `{@link Error#Id}` passed
174 * to `Error_raise()`.
175 *
176 * The first string argument (%s) will be either "", if the assertion Id
177 * is `NULL` (for internal asserts), or ": " (for public asserts).
178 * The second string argument (%s) is the
179 * `Assert.Desc.msg` string associated with the assertion Id; if the
180 * Id is `NULL` (an internal assert) or if text is not loaded
181 * (`!{@link Text#isLoaded}()`), this string is "".
182 *
183 * @see #isTrue
184 * @see Error#Id
185 */
186 readonlyconfig Error.Id E_assertFailed = {msg: "assertion failure%s%s"};
187
188 /*!
189 * ======== Assert_isTrue ========
190 * Test an assertion
191 *
192 * `Assert_isTrue()` statements may be conditionally enabled (disabled)
193 * on a per module basis by setting the calling module's
194 * `{@link IModule#$common $common.diags_ASSERT}` configuration
195 * parameter. If
196 * the `Assert_isTrue()` statement is not in a module, the calling
197 * module is the `{@link Main}` module. You must enable the
198 * `{@link Diags#ASSERT}` bit in the module's diagnostics mask for this
199 * call to be enabled. If a `NULL` assert id is specified, then you
200 * must enable the `{@link Diags#INTERNAL}` in addition to the
201 * `ASSERT` bit.
202 *
203 * If the `Assert_isTrue()` statement is enabled and `expr` evaluates to
204 * false, the assert specified by `id` is raised; i.e., the
205 * `{@link #E_assertFailed}` error is raised with a `NULL`
206 * error block. In other words, the standard `{@link Error#raise}`
207 * handling hooks will be run, `{@link System#abort()}` will be called,
208 * and control does not return to the caller. The `id` may be `null`, in
209 * which case you will get a generic assert message.
210 *
211 * @param(expr) the expression which should evaluate to true
212 * @param(id) identifies the assert being raised
213 *
214 * @a(Examples) 215 * C Code
216 * @p(code) 217 * #include <xdc/runtime/Assert.h>
218 *
219 * Assert_isTrue(count > 0, NULL);
220 * @p 221 */
222 @Macro Void isTrue(Bool expr, Id id);
223
224 internal:
225
226 Void raise(Types.ModuleId mod, String file, Int line, Id id);
227
228 }
229 /*
230 * @(#) xdc.runtime; 2, 1, 0,289; 8-20-2010 17:21:07; /db/ztree/library/trees/xdc/xdc-v48x/src/packages/
231 */
232