language.sgml

ecos实时嵌入式操作系统

<!-- {{{ Banner                 -->

<!-- =============================================================== -->
<!--                                                                 -->
<!--     language.sgml                                               -->
<!--                                                                 -->
<!--     The CDL language.                                           -->
<!--                                                                 -->
<!-- =============================================================== -->
<!-- ####COPYRIGHTBEGIN####                                          -->
<!--                                                                 -->
<!-- =============================================================== -->
<!-- Copyright (C) 2000, 2001, 2002 Red Hat, Inc.                    -->
<!--                                                                 -->
<!-- This material may be distributed only subject to the terms      -->
<!-- and conditions set forth in the Open Publication License, v1.0  -->
<!-- or later (the latest version is presently available at          -->
<!-- http://www.opencontent.org/openpub/)                            -->
<!-- Distribution of the work or derivative of the work in any       -->
<!-- standard (paper) book form is prohibited unless prior           -->
<!-- permission obtained from the copyright holder                   -->
<!-- =============================================================== -->
<!--                                                                 -->      
<!-- ####COPYRIGHTEND####                                            -->
<!-- =============================================================== -->
<!-- #####DESCRIPTIONBEGIN####                                       -->
<!--                                                                 -->
<!-- Author(s):   bartv                                              -->
<!-- Contact(s):  bartv                                              -->
<!-- Date:        2000/02/06                                         -->
<!-- Version:     0.01                                               -->
<!--                                                                 -->
<!-- ####DESCRIPTIONEND####                                          -->
<!-- =============================================================== -->

<!-- }}} -->

<chapter id="language">
<title>The CDL Language</title>

<!-- {{{ Introit                -->

<para>
The &CDL; language is a key part of the &eCos; component framework.
All packages must come with at least one &CDL; script, to describe
that package to the framework. The information in that script includes
details of all the configuration options and how to build the package.
Implementing a new component or turning some existing code into an
&eCos; component always involves writing corresponding &CDL;. This
chapter provides a description of the &CDL; language. Detailed
information on specific parts of the language can be found in <xref
linkend="reference">.
</para>

<!-- }}} -->
<!-- {{{ Language overview      -->

<sect1 id="language.overview">
<title>Language Overview</title>
<para>
A very simple &CDL; script would look like this:
</para>
<programlisting width=72>
cdl_package CYGPKG_ERROR {
    display       "Common error code support"
    compile       strerror.cxx
    include_dir   cyg/error
    description   "
        This package contains the common list of error and
        status codes. It is held centrally to allow
        packages to interchange error codes and status
        codes in a common way, rather than each package
        having its own conventions for error/status
        reporting. The error codes are modelled on the
        POSIX style naming e.g. EINVAL etc. This package
        also provides the standard strerror() function to
        convert error codes to textual representation."
}
</programlisting>
<para>
This describes a single package, the error code package, which does
not have any sub-components or configuration options. The package has
an internal name, <varname>CYGPKG_ERROR</varname>, which can be
referenced in other &CDL; scripts using e.g.
<literal>requires&nbsp;CYGPKG_ERROR</literal>. There will also be a
<literal>#define</literal> for this symbol in a configuration header
file. In addition to the package name, this script provides a number
of properties for the package as a whole. The &display; property
provides a short description. The &description; property involves a
rather longer one, for when users need a bit more information. The
&compile; and &include-dir; properties list the consequences of this
package at build-time. The package appears to lack any on-line
documentation. 
</para>
<para>
Packages could be even simpler than this. If the package only provides
an interface and there are no files to be compiled then there is no
need for a &compile; property. Alternatively if there are no exported
header files, or if the exported header files should go to the
top-level of the <filename
class="directory">install/include</filename> directory, then there is
no need for an &include-dir; property. Strictly speaking the
&description; and &display; properties are optional as well, although
application developers would not appreciate the resulting lack of
information about what the package is supposed to do.
</para>
<para>
However many packages tend to be a bit more complicated than the error
package, containing various sub-components and configuration options.
These are also defined in the &CDL; scripts and in much the same way
as the package. For example, the following excerpt comes from the
infrastructure package:
</para>
<programlisting width=72>
cdl_component CYGDBG_INFRA_DEBUG_TRACE_ASSERT_BUFFER {
    display       "Buffered tracing"
    default_value 1
    active_if     CYGDBG_USE_TRACING
    description   "
        An output module which buffers output from tracing and
        assertion events. The stored messages are output when an
        assert fires, or CYG_TRACE_PRINT() (defined in
        &lt;cyg/infra/cyg_trac.h&gt;) is called. Of course, there will
        only be stored messages if tracing per se (CYGDBG_USE_TRACING)
        is enabled above."

    cdl_option CYGDBG_INFRA_DEBUG_TRACE_BUFFER_SIZE {
        display       "Trace buffer size"
        flavor        data
        default_value 32
        legal_values  5 to 65535
        description   "
            The size of the trace buffer. This counts the number of
            trace records stored. When the buffer fills it either
            wraps, stops recording, or generates output."
    }

    &hellip;
}
</programlisting>
<para>
Like a &cdl-package;, a &cdl-component; has a name and a body. The
body contains various properties for that component, and may also
contain sub-components or options. Similarly a &cdl-option; has a
name and a body of properties. This example lists a number of
new properties: &default-value;, &active-if;, &flavor; and
&legal-values;. The meaning of most of these should be fairly obvious.
The next sections describe the various &CDL; commands and properties. 
</para>
<para>
There is one additional and very important point: &CDL; is not a
completely new language; instead it is implemented as an extension of
the existing &Tcl; scripting language. The syntax of a &CDL; script is
&Tcl; syntax, which is described below. In addition some of the more
advanced facilities of &CDL; involve embedded fragments of &Tcl; code,
for example there is a &define-proc; property which specifies some
code that needs to be executed when the component framework generates
the configuration header files.
</para>

</sect1>

<!-- }}} -->
<!-- {{{ CDL commands           -->

<sect1 id="language.commands">
<title>CDL Commands</title>
<para>
There are four &CDL;-related commands which can occur at the top-level
of a &CDL; script: &cdl-package;, &cdl-component;, &cdl-option; and
&cdl-interface;. These correspond to the basic building blocks of the
language (CDL interfaces are described in <xref
linkend="language.interface">). All of these take the same basic form:
</para>
<programlisting width=72>
cdl_package &lt;name&gt; {
    &hellip;
}

cdl_component &lt;name&gt; {
    &hellip;
}

cdl_option &lt;name&gt; {
    &hellip;
}

cdl_interface &lt;name&gt; {
    &hellip;
}
</programlisting>
<para>
The command is followed by a name and by a body of properties, the
latter enclosed in braces. Packages and components can contain other
entities, so the &cdl-package; and &cdl-component; can also have
nested commands in their bodies. All names must be unique within a
given configuration. If say the C library package and a TCP/IP stack
both defined an option with the same name then it would not be
possible to load both of them into a single configuration. There is a
<link linkend="language.naming">naming convention</link> which should
make accidental name clashes very unlikely.
</para>
<para>
It is possible for two packages to use the same name if there are no
reasonable circumstances under which both packages could be loaded at
the same time. One example would be architectural HAL packages: a
given &eCos; configuration can be used on only one processor, so the
architectural HAL packages <varname>CYGPKG_HAL_ARM</varname> and
<varname>CYGPKG_HAL_I386</varname> can re-use option names; in fact
in some cases they are expected to.
</para>
<para>
Each package has one top-level &CDL; script, which is specified in the
packages <link
linkend="language.database"><database>ecos.db</database> database
entry</link>. Typically the name of this top-level script is related to
the package, so the kernel package uses
<filename>kernel.cdl</filename>, but this is just a convention. The
first command in the top-level script should be &cdl-package;, and the
name used should be the same as in the <database>ecos.db</database>
database. There should be only one &cdl-package; command per package.
</para>
<para>
The various &CDL; entities live in a hierarchy. For example the kernel
package contains a scheduling component, a synchronization primitives
component, and a number of others. The synchronization component
contains various options such as whether or not mutex priority
inheritance is enabled. There is no upper bound on how far components
can be nested, but it is rarely necessary to go more than three or
four levels deeper than the package level. Since the naming convention
incorporates bits of the hierarchy, this has the added advantage of
keeping the names down to a more manageable size.
</para>
<para>
The hierarchy serves two purposes. It allows options to be controlled
en masse, so disabling a component automatically disables all the
options below it in the hierarchy. It also permits a much simpler
representation of the configuration in the graphical configuration
tool, facilitating navigation and modification.
</para>
<para>
By default a package is placed at the top-level of the hierarchy, but
it is possible to override this using a &parent; property. For example
an architectural HAL package such as <varname>CYGPKG_HAL_SH</varname>
typically re-parents itself below <varname>CYGPKG_HAL</varname>, and a
platform HAL package would then re-parent itself below the
architectural HAL. This makes it a little bit easier for users to
navigate around the hierarchy. Components, options and interfaces can
also be re-parented, but this is less common.
</para>
<para>
All components, options and interfaces that are defined directly in
the top-level script will be placed below the package in the hierarchy.
Alternatively they can be nested in the body of the &cdl-package;
command. The following two script fragments are equivalent:
</para>
<programlisting width=72>
cdl_package CYGPKG_LIBC {
    &hellip;
}

cdl_component CYGPKG_LIBC_STRING {
    &hellip;
}

cdl_option CYGPKG_LIBC_CTYPE_INLINES {
    &hellip;
}
</programlisting>
<para>
and:
</para>
<programlisting width=72>
cdl_package CYGPKG_LIBC {
    &hellip;

    cdl_component CYGPKG_LIBC_STRING {
        &hellip;
    }

    cdl_option CYGPKG_LIBC_CTYPE_INLINES {
        &hellip;
    }
}
</programlisting>
<para>
If a script defines options both inside and outside the body of the
&cdl-package; then the ones inside will be processed first. Language
purists may argue that it would have been better if all contained
options and components had to go into the body, but in practice it is
often convenient to be able to skip this level of nesting and the
resulting behavior is still well-defined.
</para>
<para>
Components can also contain options and other &CDL; entities, in fact
that is what distinguishes them from options. These can be defined in
the body of the &cdl-component; command:
</para>
<programlisting width=72>
cdl_component CYGPKG_LIBC_STDIO {

    cdl_component CYGPKG_LIBC_STDIO_FLOATING_POINT {
        &hellip;
    }

    cdl_option CYGSEM_LIBC_STDIO_THREAD_SAFE_STREAMS {
        &hellip;
    }
}
</programlisting>
<para>
Nesting options inside the bodies of components like this is fine for
simple packages with only a limited number of configuration options,
but it becomes unsatisfactory as the number of options increases.
Instead it is possible to split the &CDL; data into multiple &CDL;
scripts, on a per-component basis. The &script; property should be
used for this. For example, in the case of the C library all
stdio-related configuration options could be put into
<filename>stdio.cdl</filename>, and the top-level CDL script
<filename>libc.cdl</filename> would contain the following:
</para>
<programlisting width=72>
cdl_package CYGPKG_LIBC {
    &hellip;

    cdl_component CYGPKG_LIBC_STDIO {
        &hellip;