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