reference.sgml

ecos实时嵌入式操作系统

            diag.cxx tcdiag.cxx memcpy.c memset.c delete.cxx
}

</programlisting>
</refsect1>

<refsect1><title>See Also</title>
<para>
Command <link linkend="ref.cdl-option">&cdl-option;</link>,
command <link linkend="ref.cdl-component">&cdl-component;</link>,
command <link linkend="ref.cdl-interface">&cdl-interface;</link>.
</para>
</refsect1>

</refentry>

<!-- }}} -->
<!-- {{{ cdl_interface  -->

<refentry id="ref.cdl-interface">
<refmeta>
<refentrytitle>&cdl-interface;</refentrytitle>
</refmeta>

<refnamediv>
<refname>Command &cdl-interface;</refname>
<refpurpose>Define an interface, functionality that can be provided by
a number of different implementations.</refpurpose>
</refnamediv>

<refsynopsisdiv>
<synopsis>
cdl_interface &lt;name&gt; {
    &hellip;
}
</synopsis>
</refsynopsisdiv>

<refsect1><title>Description</title>
<para>
An interface is a special type of calculated configuration option.
It provides an abstraction mechanism that is often useful in &CDL;
expressions. As an example, suppose that some package relies on the
presence of code that implements the standard kernel scheduling
interface. However the requirement is no more stringent than this, so
the constraint can be satisfied by the mlqueue scheduler, the bitmap
scheduler, or any additional schedulers that may get implemented in
future. A first attempt at expressing the dependency might be:
</para>
<programlisting width=72>
    requires CYGSEM_KERNEL_SCHED_MLQUEUE || CYGSEM_KERNEL_SCHED_BITMAP
</programlisting>
<para>
This constraint is limited, it may need to be changed if a new
scheduler were to be added to the system. Interfaces provide a way of
expressing more general relationships:
</para>
<programlisting width=72>
    requires CYGINT_KERNEL_SCHEDULER
</programlisting>
<para>
The interface <literal>CYGINT_KERNEL_SCHEDULER</literal> is
<emphasis>implemented</emphasis> by both the mlqueue and bitmap
schedulers, and may be implemented by future schedulers as well. The
value of an interface is the number of implementors that are active
and enabled, so in a typical configuration only one scheduler will be
in use and the value of the interface will be <literal>1</literal>. If
all schedulers are disabled then the interface will have a value
<literal>0</literal> and the &requires; constraint will not be
satisfied.
</para>
<para>
Some component writers may prefer to use the first &requires;
constraint on the grounds that the code will only have been tested
with the mlqueue and bitmap schedulers and cannot be guaranteed to
work with any new schedulers. Other component writers may take a more
optimistic view and assume that their code will work with any
scheduler until proven otherwise.
</para>
<para>
Interfaces must be defined in CDL scripts, just like options,
components and packages. This involves the command &cdl-interface;
which takes two arguments, a name and a body. The name must be a valid
C preprocessor identifier: a sequence of upper or lower case letters,
digits or underscores, starting with a non-digit character;
identifiers beginning with an underscore should normally be avoided
because they may clash with system packages or with identifiers
reserved for use by the compiler. Within a single configuration, names
must be unique. If a configuration contained two packages which
defined the same entity <literal>CYGIMP_SOME_OPTION</literal>, any
references to that entity in a &requires; property or any other
expression would be ambiguous. It is possible for a given name to be
used by two different packages if those packages should never be
loaded into a single configuration. For example, architectural HAL
packages are allowed to re-use names because a single configuration
cannot target two different architectures. For a recommended naming
convention see <xref linkend="package.contents">.
</para>
<para>
The second argument to &cdl-interface; is a body of properties,
typically surrounded by braces so that the Tcl interpreter treats it
as a single argument. This body will be processed by a recursive
invocation of the Tcl interpreter, extended with additional commands
for the various properties that are allowed inside a &cdl-interface;.
The valid properties are a subset of those for a &cdl-option;.
</para>

<variablelist TermLength=16>

<varlistentry><term><link linkend="ref.active-if">&active-if;</link></term>
<listitem><para>
Allow additional control over the active state of this interface.
</para></listitem></varlistentry>

<varlistentry><term><link linkend="ref.compile">&compile;</link></term>
<listitem><para>
List the source files that should be built if this interface is active.
</para></listitem></varlistentry>

<varlistentry><term><link linkend="ref.define">&define;</link></term>
<listitem><para>
Specify additional <literal>#define</literal> symbols that should go
into the owning package's configuration header file.
</para></listitem></varlistentry>

<varlistentry><term><link linkend="ref.define-format">&define-format;</link></term>
<listitem><para>
Control how the interface's value will appear in the configuration header
file.
</para></listitem></varlistentry>

<varlistentry><term><link linkend="ref.define-proc">&define-proc;</link></term>
<listitem><para>
Use a fragment of Tcl code to output additional data to
configuration header files.
</para></listitem></varlistentry>

<varlistentry><term><link linkend="ref.description">&description;</link></term>
<listitem><para>
Provide a textual description for this interface.
</para></listitem></varlistentry>

<varlistentry><term><link linkend="ref.display">&display;</link></term>
<listitem><para>
Provide a short string describing this interface.
</para></listitem></varlistentry>

<varlistentry><term><link linkend="ref.doc">&doc;</link></term>
<listitem><para>
The location of on-line documentation for this interface.
</para></listitem></varlistentry>

<varlistentry><term><link linkend="ref.flavor">&flavor;</link></term>
<listitem><para>
Interfaces have the <literal>data</literal> flavor by default, but
they can also be given the <literal>bool</literal> or
<literal>booldata</literal> flavor when necessary. A
<literal>bool</literal> interface is disabled if there are no active
and enabled implementors, otherwise it is enabled. A
<literal>booldata</literal> interface is also disabled if there are no
active and enabled implementors, otherwise it is enabled and the data
is a number corresponding to the number of these implementors.
</para></listitem></varlistentry>

<varlistentry><term><link linkend="ref.if-define">&if-define;</link></term>
<listitem><para>
Output a common preprocessor construct to a configuration header file. 
</para></listitem></varlistentry>

<varlistentry><term><link linkend="ref.implements">&implements;</link></term>
<listitem><para>
If this interface is active it provides one instance of a more general
interface. 
</para></listitem></varlistentry>

<varlistentry><term><link linkend="ref.legal-values">&legal-values;</link></term>
<listitem><para>
Interfaces always have a small numerical value. The &legal-values; can
be used to apply additional constraints such as an upper limit.
</para></listitem></varlistentry>

<varlistentry><term><link linkend="ref.make">&make;</link></term>
<listitem><para>
An additional custom build step associated with this option, resulting
in a target that should not go directly into a library.
</para></listitem></varlistentry>

<varlistentry><term><link linkend="ref.make-object">&make-object;</link></term>
<listitem><para>
An additional custom build step associated with this option, resulting
in an object file that should go into a library.
</para></listitem></varlistentry>

<varlistentry><term><link linkend="ref.no-define">&no-define;</link></term>
<listitem><para>
Suppress the normal generation of a preprocessor
<literal>#define</literal> symbol in a configuration header file.
</para></listitem></varlistentry>

<varlistentry><term><link linkend="ref.parent">&parent;</link></term>
<listitem><para>
Control the location of this option in the configuration hierarchy. 
</para></listitem></varlistentry>

<varlistentry><term><link linkend="ref.requires">&requires;</link></term>
<listitem><para>
List constraints that the configuration should satisfy if this option is
active and enabled.
</para></listitem></varlistentry>

</variablelist>

<para>
A number of properties are not applicable to interfaces:
</para>
<variablelist>

<varlistentry><term><link linkend="ref.calculated">&calculated;</link></term>
<listitem><para>
Interfaces are always calculated, based on the number of active and
enabled entities that implement the interface.
</para></listitem></varlistentry>

<varlistentry><term><link linkend="ref.default-value">&default-value;</link></term>
<listitem><para>
Interface values are calculated so a &default-value; property would be
meaningless.
</para></listitem></varlistentry>

</variablelist>

<para>
Interfaces are not containers, so they cannot hold other entities such
as options or components.
</para>
<para>
A commonly used constraint on interface values takes the form:
</para>
<programlisting width=72>
    requires CYGINT_KERNEL_SCHEDULER == 1
</programlisting>
<para>
This constraint specifies that there can be only one scheduler in the
system. In some circumstances it is possible for the configuration
tools to detect this pattern and act accordingly, so for example
enabling the bitmap scheduler would automatically disable the mlqueue
scheduler.
</para>

</refsect1>

<refsect1><title>Example</title>
<programlisting width=72>
cdl_interface CYGINT_KERNEL_SCHEDULER {
    display  "Number of schedulers in this configuration"
    requires 1 == CYGINT_KERNEL_SCHEDULER
}
</programlisting>
</refsect1>

<refsect1><title>See Also</title>
<para>
Property <link linkend="ref.implements">&implements;</link>,
command <link linkend="ref.cdl-option">&cdl-option;</link>.
command <link linkend="ref.cdl-component">&cdl-component;</link>,
command <link linkend="ref.cdl-package">&cdl-package;</link>.
</para>
</refsect1>

</refentry>

<!-- }}} -->

<!-- {{{ active_if      -->

<refentry id="ref.active-if">
<refmeta>
<refentrytitle>&active-if;</refentrytitle>
</refmeta>

<refnamediv>
<refname>Property &active-if;</refname>
<refpurpose>Allow additional control over the active state of an
option or other CDL entity.</refpurpose>
</refnamediv>

<refsynopsisdiv>
<synopsis>
cdl_option &lt;name&gt; {
    active_if &lt;condition&gt;
    &hellip;
}
</synopsis>
</refsynopsisdiv>

<refsect1><title>Description</title>
<para>
Configuration options or other entities may be either active or
inactive. Typically this is controlled by the option's location in the
overall hierarchy. Consider the option
<literal>CYGDBG_INFRA_DEBUG_PRECONDITIONS</literal>, which exists
below the component <literal>CYGDBG_USE_ASSERT</literal>. If the whole
component is disabled then the options it contains are inactive: there
is no point in enabling preconditions unless there is generic
assertion support; any &requires; constraints associated with
preconditions are irrelevant; any &compile; property or other
build-related property is ignored.
</para>
<para>
In some cases the hierarchy does not provide sufficient control over
whether or not a particular option should be active. For example, the
math library could have support for floating point exceptions which
is only worthwhile if the hardware implements appropriate
functionality, as specified by the architectural HAL. The relevant
math library configuration options should remain below the
<literal>CYGPKG_LIBM</literal> package in the overall hierarchy, but
should be inactive unless there is appropriate hardware support. In
cases like this an &active-if; property is appropriate.
</para>
<para>
Another common use of &active-if; properties is to avoid excessive
nesting in the configuration hierarchy. If some option B is only
relevant if option A is enabled, it is possible to turn A into a
component that contains B. However adding another level to the
hierarchy for a component which will contain just one entry may be
considered excessive. In such cases it is possible for B to have an
&active-if; dependency on A.
</para>
<para>
&active-if; takes a goal expression as argument. For details of goal
expression syntax see <xref linkend="language.goal-expression">. In
most cases the goal expression will be very simple, often involving
just one other option, but more complicated expressions can be used
when appropriate. It is also possible to have multiple &active-if;
conditions in a single option, in which case all of the conditions
have to be satisfied if the option is to be active.
</para>
<para>
The &active-if; and &requires; properties have certain similarities,
but they serve a different purpose. Suppose there are two options A
and B, and option B relies on functionality provided by A. This could
be expressed as either <literal>active_if&nbsp;A</literal> or as
<literal>requires&nbsp;A</literal>. The points to note are:
</para>
<itemizedlist>

<listitem><para>
If <literal>active_if&nbsp;A</literal> is used and A is disabled or
inactive, then graphical tools will generally prevent any attempt at
modifying B. For example the text for B could be grayed out, and the
associated checkbutton (if B is a boolean option) would be disabled.
If the user needs the functionality provided by option B then it is
necessary to go to option A first and manipulate it appropriately.
</para></listitem>

<listitem><para>
If <literal>requires&nbsp;A</literal> is used and A is disabled or