doc/html/cdl-guide/ref.legal-values.html

   1 <!-- Copyright (C) 2003 Red Hat, Inc.                                -->
   2 <!-- This material may be distributed only subject to the terms      -->
   3 <!-- and conditions set forth in the Open Publication License, v1.0  -->
   4 <!-- or later (the latest version is presently available at          -->
   5 <!-- http://www.opencontent.org/openpub/).                           -->
   6 <!-- Distribution of the work or derivative of the work in any       -->
   7 <!-- standard (paper) book form is prohibited unless prior           -->
   8 <!-- permission is obtained from the copyright holder.               -->
   9 <HTML
  10 ><HEAD
  11 ><TITLE
  12 >legal_values</TITLE
  13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
  14 <META
  15 NAME="GENERATOR"
  16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
  17 "><LINK
  18 REL="HOME"
  19 TITLE="The eCos Component Writer's Guide"
  20 HREF="cdl-guide.html"><LINK
  21 REL="UP"
  22 TITLE="CDL Language Specification"
  23 HREF="reference.html"><LINK
  24 REL="PREVIOUS"
  25 TITLE="include_files"
  26 HREF="ref.include-files.html"><LINK
  27 REL="NEXT"
  28 TITLE="library"
  29 HREF="ref.library.html"></HEAD
  30 ><BODY
  31 CLASS="REFENTRY"
  32 BGCOLOR="#FFFFFF"
  33 TEXT="#000000"
  34 LINK="#0000FF"
  35 VLINK="#840084"
  36 ALINK="#0000FF"
  37 ><DIV
  38 CLASS="NAVHEADER"
  39 ><TABLE
  40 SUMMARY="Header navigation table"
  41 WIDTH="100%"
  42 BORDER="0"
  43 CELLPADDING="0"
  44 CELLSPACING="0"
  45 ><TR
  46 ><TH
  47 COLSPAN="3"
  48 ALIGN="center"
  49 >The <SPAN
  50 CLASS="APPLICATION"
  51 >eCos</SPAN
  52 > Component Writer's Guide</TH
  53 ></TR
  54 ><TR
  55 ><TD
  56 WIDTH="10%"
  57 ALIGN="left"
  58 VALIGN="bottom"
  59 ><A
  60 HREF="ref.include-files.html"
  61 ACCESSKEY="P"
  62 >Prev</A
  63 ></TD
  64 ><TD
  65 WIDTH="80%"
  66 ALIGN="center"
  67 VALIGN="bottom"
  68 ></TD
  69 ><TD
  70 WIDTH="10%"
  71 ALIGN="right"
  72 VALIGN="bottom"
  73 ><A
  74 HREF="ref.library.html"
  75 ACCESSKEY="N"
  76 >Next</A
  77 ></TD
  78 ></TR
  79 ></TABLE
  80 ><HR
  81 ALIGN="LEFT"
  82 WIDTH="100%"></DIV
  83 ><H1
  84 ><A
  85 NAME="REF.LEGAL-VALUES"><SPAN
  86 CLASS="PROPERTY"
  87 >legal_values</SPAN
  88 ></H1
  89 ><DIV
  90 CLASS="REFNAMEDIV"
  91 ><A
  92 NAME="AEN4615"
  93 ></A
  94 ><H2
  95 >Name</H2
  96 >Property <SPAN
  97 CLASS="PROPERTY"
  98 >legal_values</SPAN
  99 >&nbsp;--&nbsp;Impose constraints on the possible values for an option.</DIV
 100 ><DIV
 101 CLASS="REFSYNOPSISDIV"
 102 ><A
 103 NAME="AEN4619"><H2
 104 >Synopsis</H2
 105 ><TABLE
 106 BORDER="5"
 107 BGCOLOR="#E0E0F0"
 108 WIDTH="70%"
 109 ><TR
 110 ><TD
 111 ><PRE
 112 CLASS="SYNOPSIS"
 113 >cdl_option &lt;name&gt; {
 114     legal_values &lt;list expression&gt;
 115     &#8230;
 116 }</PRE
 117 ></TD
 118 ></TR
 119 ></TABLE
 120 ></DIV
 121 ><DIV
 122 CLASS="REFSECT1"
 123 ><A
 124 NAME="AEN4621"
 125 ></A
 126 ><H2
 127 >Description</H2
 128 ><P
 129 >Options with the <TT
 130 CLASS="LITERAL"
 131 >data</TT
 132 > or
 133 <TT
 134 CLASS="LITERAL"
 135 >booldata</TT
 136 > flavors can have an arbitrary sequence of
 137 characters as their data. In nearly all cases some restrictions have
 138 to be imposed, for example the data should correspond to a number
 139 within a certain range, or it should be one of a small number of
 140 constants. The <SPAN
 141 CLASS="PROPERTY"
 142 >legal_values</SPAN
 143 > property can be used to impose such
 144 constraints. The arguments to the property should be a <SPAN
 145 CLASS="APPLICATION"
 146 >CDL</SPAN
 147 > list
 148 expression, see <A
 149 HREF="language.values.html#LANGUAGE.LIST-EXPRESSION"
 150 >the Section called <I
 151 >List Expressions</I
 152 > in Chapter 3</A
 153 > for the
 154 syntactic details. Common examples include:</P
 155 ><TABLE
 156 BORDER="5"
 157 BGCOLOR="#E0E0F0"
 158 WIDTH="70%"
 159 ><TR
 160 ><TD
 161 ><PRE
 162 CLASS="PROGRAMLISTING"
 163 >    legal_values 0 to 0x7fff
 164     legal_values 9600 19200 38400
 165     legal_values { "RAM" "ROM" }</PRE
 166 ></TD
 167 ></TR
 168 ></TABLE
 169 ><P
 170 >The <SPAN
 171 CLASS="PROPERTY"
 172 >legal_values</SPAN
 173 > property can only be used for options with the
 174 <TT
 175 CLASS="LITERAL"
 176 >data</TT
 177 > or <TT
 178 CLASS="LITERAL"
 179 >booldata</TT
 180 > flavors, since
 181 it makes little sense to further constrain the legal values of a
 182 boolean option. An option can have at most one <SPAN
 183 CLASS="PROPERTY"
 184 >legal_values</SPAN
 185 >
 186 property.</P
 187 ><DIV
 188 CLASS="TIP"
 189 ><BLOCKQUOTE
 190 CLASS="TIP"
 191 ><P
 192 ><B
 193 >Tip: </B
 194 >If the first entry in a <SPAN
 195 CLASS="PROPERTY"
 196 >legal_values</SPAN
 197 > list expression is a negative
 198 number, for example
 199 <TT
 200 CLASS="LITERAL"
 201 >legal_values&nbsp;-1&nbsp;to&nbsp;1</TT
 202 >  then this can
 203 be misinterpreted as an option instead of as part of the expression.
 204 Currently the <SPAN
 205 CLASS="PROPERTY"
 206 >legal_values</SPAN
 207 > property does not take any options, but
 208 this may change in future. Option processing halts at the sequence
 209 <TT
 210 CLASS="LITERAL"
 211 >--</TT
 212 >, so the desired range can be expressed safely
 213 using <TT
 214 CLASS="LITERAL"
 215 >legal_values&nbsp;--&nbsp;-1&nbsp;to&nbsp;1</TT
 216 ></P
 217 ></BLOCKQUOTE
 218 ></DIV
 219 ><DIV
 220 CLASS="NOTE"
 221 ><BLOCKQUOTE
 222 CLASS="NOTE"
 223 ><P
 224 ><B
 225 >Note: </B
 226 >Architectural HAL packages should provide constants which can be used
 227 in <SPAN
 228 CLASS="PROPERTY"
 229 >legal_values</SPAN
 230 > list expressions. For example it should be possible
 231 to specify a numeric range such as
 232 <TT
 233 CLASS="LITERAL"
 234 >0&nbsp;to&nbsp;CYGARC_MAXINT</TT
 235 >, rather than
 236 hard-wiring numbers such as <TT
 237 CLASS="LITERAL"
 238 >0x7fffffff</TT
 239 > which may
 240 not be valid on all targets. Current HAL packages do not define such
 241 constants. </P
 242 ></BLOCKQUOTE
 243 ></DIV
 244 ><DIV
 245 CLASS="NOTE"
 246 ><BLOCKQUOTE
 247 CLASS="NOTE"
 248 ><P
 249 ><B
 250 >Note: </B
 251 >The <SPAN
 252 CLASS="PROPERTY"
 253 >legal_values</SPAN
 254 > property is restricted mainly to numerical ranges
 255 and simple enumerations, and cannot cope with more complicated data
 256 items. Future versions of the configuration system will provide
 257 additional data validation facilities, for example a
 258 <TT
 259 CLASS="LITERAL"
 260 >check_proc</TT
 261 > property which specifies a Tcl script
 262 that can be used to perform the validation.</P
 263 ></BLOCKQUOTE
 264 ></DIV
 265 ></DIV
 266 ><DIV
 267 CLASS="REFSECT1"
 268 ><A
 269 NAME="AEN4651"
 270 ></A
 271 ><H2
 272 >Example</H2
 273 ><TABLE
 274 BORDER="5"
 275 BGCOLOR="#E0E0F0"
 276 WIDTH="70%"
 277 ><TR
 278 ><TD
 279 ><PRE
 280 CLASS="PROGRAMLISTING"
 281 >cdl_option CYGNUM_LIBC_TIME_STD_DEFAULT_OFFSET {
 282     display       "Default Standard Time offset"
 283     flavor        data
 284     legal_values  -- -90000 to 90000
 285     default_value -- 0
 286     description   "
 287         This option controls the offset from UTC in
 288         seconds when in local Standard Time. This
 289         value can be positive or negative. It
 290         can also be set at run time using the
 291         cyg_libc_time_setzoneoffsets() function."
 292 }</PRE
 293 ></TD
 294 ></TR
 295 ></TABLE
 296 ></DIV
 297 ><DIV
 298 CLASS="REFSECT1"
 299 ><A
 300 NAME="AEN4654"
 301 ></A
 302 ><H2
 303 >See Also</H2
 304 ><P
 305 >Properties <A
 306 HREF="ref.calculated.html"
 307 ><SPAN
 308 CLASS="PROPERTY"
 309 >calculated</SPAN
 310 ></A
 311 >,
 312 <A
 313 HREF="ref.default-value.html"
 314 ><SPAN
 315 CLASS="PROPERTY"
 316 >default_value</SPAN
 317 ></A
 318 >, and
 319 <A
 320 HREF="ref.flavor.html"
 321 ><SPAN
 322 CLASS="PROPERTY"
 323 >flavor</SPAN
 324 ></A
 325 >.</P
 326 ></DIV
 327 ><DIV
 328 CLASS="NAVFOOTER"
 329 ><HR
 330 ALIGN="LEFT"
 331 WIDTH="100%"><TABLE
 332 SUMMARY="Footer navigation table"
 333 WIDTH="100%"
 334 BORDER="0"
 335 CELLPADDING="0"
 336 CELLSPACING="0"
 337 ><TR
 338 ><TD
 339 WIDTH="33%"
 340 ALIGN="left"
 341 VALIGN="top"
 342 ><A
 343 HREF="ref.include-files.html"
 344 ACCESSKEY="P"
 345 >Prev</A
 346 ></TD
 347 ><TD
 348 WIDTH="34%"
 349 ALIGN="center"
 350 VALIGN="top"
 351 ><A
 352 HREF="cdl-guide.html"
 353 ACCESSKEY="H"
 354 >Home</A
 355 ></TD
 356 ><TD
 357 WIDTH="33%"
 358 ALIGN="right"
 359 VALIGN="top"
 360 ><A
 361 HREF="ref.library.html"
 362 ACCESSKEY="N"
 363 >Next</A
 364 ></TD
 365 ></TR
 366 ><TR
 367 ><TD
 368 WIDTH="33%"
 369 ALIGN="left"
 370 VALIGN="top"
 371 ><SPAN
 372 CLASS="PROPERTY"
 373 >include_files</SPAN
 374 ></TD
 375 ><TD
 376 WIDTH="34%"
 377 ALIGN="center"
 378 VALIGN="top"
 379 ><A
 380 HREF="reference.html"
 381 ACCESSKEY="U"
 382 >Up</A
 383 ></TD
 384 ><TD
 385 WIDTH="33%"
 386 ALIGN="right"
 387 VALIGN="top"
 388 ><SPAN
 389 CLASS="PROPERTY"
 390 >library</SPAN
 391 ></TD
 392 ></TR
 393 ></TABLE
 394 ></DIV
 395 ></BODY
 396 ></HTML
 397 >