URL
https://opencores.org/ocsvn/openrisc_me/openrisc_me/trunk
Subversion Repositories openrisc_me
[/] [openrisc/] [trunk/] [rtos/] [ecos-2.0/] [doc/] [html/] [cdl-guide/] [language.commands.html] - Rev 441
Go to most recent revision | Compare with Previous | Blame | View Log
<!-- Copyright (C) 2003 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 is obtained from the copyright holder. --> <HTML ><HEAD ><TITLE >CDL Commands</TITLE ><meta name="MSSmartTagsPreventParsing" content="TRUE"> <META NAME="GENERATOR" CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+ "><LINK REL="HOME" TITLE="The eCos Component Writer's Guide" HREF="cdl-guide.html"><LINK REL="UP" TITLE="The CDL Language" HREF="language.html"><LINK REL="PREVIOUS" TITLE="The CDL Language" HREF="language.html"><LINK REL="NEXT" TITLE="CDL Properties" HREF="language.properties.html"></HEAD ><BODY CLASS="SECT1" BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#840084" ALINK="#0000FF" ><DIV CLASS="NAVHEADER" ><TABLE SUMMARY="Header navigation table" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" ><TR ><TH COLSPAN="3" ALIGN="center" >The <SPAN CLASS="APPLICATION" >eCos</SPAN > Component Writer's Guide</TH ></TR ><TR ><TD WIDTH="10%" ALIGN="left" VALIGN="bottom" ><A HREF="language.html" ACCESSKEY="P" >Prev</A ></TD ><TD WIDTH="80%" ALIGN="center" VALIGN="bottom" >Chapter 3. The CDL Language</TD ><TD WIDTH="10%" ALIGN="right" VALIGN="bottom" ><A HREF="language.properties.html" ACCESSKEY="N" >Next</A ></TD ></TR ></TABLE ><HR ALIGN="LEFT" WIDTH="100%"></DIV ><DIV CLASS="SECT1" ><H1 CLASS="SECT1" ><A NAME="LANGUAGE.COMMANDS">CDL Commands</H1 ><P >There are four <SPAN CLASS="APPLICATION" >CDL</SPAN >-related commands which can occur at the top-level of a <SPAN CLASS="APPLICATION" >CDL</SPAN > script: <TT CLASS="LITERAL" >cdl_package</TT >, <TT CLASS="LITERAL" >cdl_component</TT >, <TT CLASS="LITERAL" >cdl_option</TT > and <TT CLASS="LITERAL" >cdl_interface</TT >. These correspond to the basic building blocks of the language (CDL interfaces are described in <A HREF="language.interface.html" >the Section called <I >Interfaces</I ></A >). All of these take the same basic form:</P ><TABLE BORDER="5" BGCOLOR="#E0E0F0" WIDTH="70%" ><TR ><TD ><PRE CLASS="PROGRAMLISTING" >cdl_package <name> { … } cdl_component <name> { … } cdl_option <name> { … } cdl_interface <name> { … }</PRE ></TD ></TR ></TABLE ><P >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 <TT CLASS="LITERAL" >cdl_package</TT > and <TT CLASS="LITERAL" >cdl_component</TT > 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 <A HREF="language.naming.html" >naming convention</A > which should make accidental name clashes very unlikely.</P ><P >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 <SPAN CLASS="APPLICATION" >eCos</SPAN > configuration can be used on only one processor, so the architectural HAL packages <TT CLASS="VARNAME" >CYGPKG_HAL_ARM</TT > and <TT CLASS="VARNAME" >CYGPKG_HAL_I386</TT > can re-use option names; in fact in some cases they are expected to.</P ><P >Each package has one top-level <SPAN CLASS="APPLICATION" >CDL</SPAN > script, which is specified in the packages <A HREF="language.database.html" ><SPAN CLASS="DATABASE" >ecos.db</SPAN > database entry</A >. Typically the name of this top-level script is related to the package, so the kernel package uses <TT CLASS="FILENAME" >kernel.cdl</TT >, but this is just a convention. The first command in the top-level script should be <TT CLASS="LITERAL" >cdl_package</TT >, and the name used should be the same as in the <SPAN CLASS="DATABASE" >ecos.db</SPAN > database. There should be only one <TT CLASS="LITERAL" >cdl_package</TT > command per package.</P ><P >The various <SPAN CLASS="APPLICATION" >CDL</SPAN > 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.</P ><P >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.</P ><P >By default a package is placed at the top-level of the hierarchy, but it is possible to override this using a <SPAN CLASS="PROPERTY" >parent</SPAN > property. For example an architectural HAL package such as <TT CLASS="VARNAME" >CYGPKG_HAL_SH</TT > typically re-parents itself below <TT CLASS="VARNAME" >CYGPKG_HAL</TT >, 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.</P ><P >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 <TT CLASS="LITERAL" >cdl_package</TT > command. The following two script fragments are equivalent:</P ><TABLE BORDER="5" BGCOLOR="#E0E0F0" WIDTH="70%" ><TR ><TD ><PRE CLASS="PROGRAMLISTING" >cdl_package CYGPKG_LIBC { … } cdl_component CYGPKG_LIBC_STRING { … } cdl_option CYGPKG_LIBC_CTYPE_INLINES { … }</PRE ></TD ></TR ></TABLE ><P >and:</P ><TABLE BORDER="5" BGCOLOR="#E0E0F0" WIDTH="70%" ><TR ><TD ><PRE CLASS="PROGRAMLISTING" >cdl_package CYGPKG_LIBC { … cdl_component CYGPKG_LIBC_STRING { … } cdl_option CYGPKG_LIBC_CTYPE_INLINES { … } }</PRE ></TD ></TR ></TABLE ><P >If a script defines options both inside and outside the body of the <TT CLASS="LITERAL" >cdl_package</TT > 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.</P ><P >Components can also contain options and other <SPAN CLASS="APPLICATION" >CDL</SPAN > entities, in fact that is what distinguishes them from options. These can be defined in the body of the <TT CLASS="LITERAL" >cdl_component</TT > command:</P ><TABLE BORDER="5" BGCOLOR="#E0E0F0" WIDTH="70%" ><TR ><TD ><PRE CLASS="PROGRAMLISTING" >cdl_component CYGPKG_LIBC_STDIO { cdl_component CYGPKG_LIBC_STDIO_FLOATING_POINT { … } cdl_option CYGSEM_LIBC_STDIO_THREAD_SAFE_STREAMS { … } }</PRE ></TD ></TR ></TABLE ><P >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 <SPAN CLASS="APPLICATION" >CDL</SPAN > data into multiple <SPAN CLASS="APPLICATION" >CDL</SPAN > scripts, on a per-component basis. The <SPAN CLASS="PROPERTY" >script</SPAN > property should be used for this. For example, in the case of the C library all stdio-related configuration options could be put into <TT CLASS="FILENAME" >stdio.cdl</TT >, and the top-level CDL script <TT CLASS="FILENAME" >libc.cdl</TT > would contain the following:</P ><TABLE BORDER="5" BGCOLOR="#E0E0F0" WIDTH="70%" ><TR ><TD ><PRE CLASS="PROGRAMLISTING" >cdl_package CYGPKG_LIBC { … cdl_component CYGPKG_LIBC_STDIO { … script stdio.cdl } }</PRE ></TD ></TR ></TABLE ><P >The <TT CLASS="VARNAME" >CYGPKG_LIBC_STDIO_FLOATING_POINT</TT > component and the <TT CLASS="VARNAME" >CYGSEM_LIBC_STDIO_THREAD_SAFE_STREAMS</TT > option can then be placed at the top-level of <TT CLASS="FILENAME" >stdio.cdl</TT >. It is possible to have some options nested in the body of a <TT CLASS="LITERAL" >cdl_component</TT > command and other options in a separate file accessed by the <SPAN CLASS="PROPERTY" >script</SPAN > property. In such a case the nested options would be processed first, and then the other script would be read in. A script specified by a <SPAN CLASS="PROPERTY" >script</SPAN > property should only define new options, components or interfaces: it should not contain any additional properties for the current component.</P ><P >It is possible for a component's <SPAN CLASS="APPLICATION" >CDL</SPAN > script to have a sub-component which also has a <SPAN CLASS="PROPERTY" >script</SPAN > property, and so on. In practice excessive nesting like this is rarely useful. It is also possible to ignore the <SPAN CLASS="APPLICATION" >CDL</SPAN > language support for constructing hierarchies automatically and use the <SPAN CLASS="PROPERTY" >parent</SPAN > property explicitly for every single option and component. Again this is not generally useful.</P ><DIV CLASS="NOTE" ><BLOCKQUOTE CLASS="NOTE" ><P ><B >Note: </B >At the time of writing interfaces cannot act as containers. This may change in a future version of the component framework. If the change is made then interfaces would support the <SPAN CLASS="PROPERTY" >script</SPAN > property, just like components.</P ></BLOCKQUOTE ></DIV ></DIV ><DIV CLASS="NAVFOOTER" ><HR ALIGN="LEFT" WIDTH="100%"><TABLE SUMMARY="Footer navigation table" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" ><TR ><TD WIDTH="33%" ALIGN="left" VALIGN="top" ><A HREF="language.html" ACCESSKEY="P" >Prev</A ></TD ><TD WIDTH="34%" ALIGN="center" VALIGN="top" ><A HREF="cdl-guide.html" ACCESSKEY="H" >Home</A ></TD ><TD WIDTH="33%" ALIGN="right" VALIGN="top" ><A HREF="language.properties.html" ACCESSKEY="N" >Next</A ></TD ></TR ><TR ><TD WIDTH="33%" ALIGN="left" VALIGN="top" >The CDL Language</TD ><TD WIDTH="34%" ALIGN="center" VALIGN="top" ><A HREF="language.html" ACCESSKEY="U" >Up</A ></TD ><TD WIDTH="33%" ALIGN="right" VALIGN="top" >CDL Properties</TD ></TR ></TABLE ></DIV ></BODY ></HTML >
Go to most recent revision | Compare with Previous | Blame | View Log