URL
https://opencores.org/ocsvn/openrisc_2011-10-31/openrisc_2011-10-31/trunk
Subversion Repositories openrisc_2011-10-31
[/] [openrisc/] [trunk/] [rtos/] [ecos-2.0/] [doc/] [html/] [cdl-guide/] [ref.cdl-interface.html] - Rev 369
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_interface</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="CDL Language Specification"
HREF="reference.html"><LINK
REL="PREVIOUS"
TITLE="cdl_package"
HREF="ref.cdl-package.html"><LINK
REL="NEXT"
TITLE="active_if"
HREF="ref.active-if.html"></HEAD
><BODY
CLASS="REFENTRY"
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="ref.cdl-package.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="ref.active-if.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><H1
><A
NAME="REF.CDL-INTERFACE"><TT
CLASS="LITERAL"
>cdl_interface</TT
></H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN3484"
></A
><H2
>Name</H2
>Command <TT
CLASS="LITERAL"
>cdl_interface</TT
> -- Define an interface, functionality that can be provided by
a number of different implementations.</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN3488"><H2
>Synopsis</H2
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="SYNOPSIS"
>cdl_interface <name> {
…
}</PRE
></TD
></TR
></TABLE
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN3490"
></A
><H2
>Description</H2
><P
>An interface is a special type of calculated configuration option.
It provides an abstraction mechanism that is often useful in <SPAN
CLASS="APPLICATION"
>CDL</SPAN
>
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:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
> requires CYGSEM_KERNEL_SCHED_MLQUEUE || CYGSEM_KERNEL_SCHED_BITMAP</PRE
></TD
></TR
></TABLE
><P
>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:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
> requires CYGINT_KERNEL_SCHEDULER</PRE
></TD
></TR
></TABLE
><P
>The interface <TT
CLASS="LITERAL"
>CYGINT_KERNEL_SCHEDULER</TT
> is
<SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>implemented</I
></SPAN
> 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 <TT
CLASS="LITERAL"
>1</TT
>. If
all schedulers are disabled then the interface will have a value
<TT
CLASS="LITERAL"
>0</TT
> and the <SPAN
CLASS="PROPERTY"
>requires</SPAN
> constraint will not be
satisfied.</P
><P
>Some component writers may prefer to use the first <SPAN
CLASS="PROPERTY"
>requires</SPAN
>
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.</P
><P
>Interfaces must be defined in CDL scripts, just like options,
components and packages. This involves the command <TT
CLASS="LITERAL"
>cdl_interface</TT
>
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 <TT
CLASS="LITERAL"
>CYGIMP_SOME_OPTION</TT
>, any
references to that entity in a <SPAN
CLASS="PROPERTY"
>requires</SPAN
> 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 <A
HREF="package.contents.html"
>the Section called <I
>Package Contents and Layout</I
> in Chapter 2</A
>.</P
><P
>The second argument to <TT
CLASS="LITERAL"
>cdl_interface</TT
> 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 <TT
CLASS="LITERAL"
>cdl_interface</TT
>.
The valid properties are a subset of those for a <TT
CLASS="LITERAL"
>cdl_option</TT
>.</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><A
HREF="ref.active-if.html"
><SPAN
CLASS="PROPERTY"
>active_if</SPAN
></A
></DT
><DD
><P
>Allow additional control over the active state of this interface.</P
></DD
><DT
><A
HREF="ref.compile.html"
><SPAN
CLASS="PROPERTY"
>compile</SPAN
></A
></DT
><DD
><P
>List the source files that should be built if this interface is active.</P
></DD
><DT
><A
HREF="ref.define.html"
><SPAN
CLASS="PROPERTY"
>define</SPAN
></A
></DT
><DD
><P
>Specify additional <TT
CLASS="LITERAL"
>#define</TT
> symbols that should go
into the owning package's configuration header file.</P
></DD
><DT
><A
HREF="ref.define-format.html"
><SPAN
CLASS="PROPERTY"
>define_format</SPAN
></A
></DT
><DD
><P
>Control how the interface's value will appear in the configuration header
file.</P
></DD
><DT
><A
HREF="ref.define-proc.html"
><SPAN
CLASS="PROPERTY"
>define_proc</SPAN
></A
></DT
><DD
><P
>Use a fragment of Tcl code to output additional data to
configuration header files.</P
></DD
><DT
><A
HREF="ref.description.html"
><SPAN
CLASS="PROPERTY"
>description</SPAN
></A
></DT
><DD
><P
>Provide a textual description for this interface.</P
></DD
><DT
><A
HREF="ref.display.html"
><SPAN
CLASS="PROPERTY"
>display</SPAN
></A
></DT
><DD
><P
>Provide a short string describing this interface.</P
></DD
><DT
><A
HREF="ref.doc.html"
><SPAN
CLASS="PROPERTY"
>doc</SPAN
></A
></DT
><DD
><P
>The location of on-line documentation for this interface.</P
></DD
><DT
><A
HREF="ref.flavor.html"
><SPAN
CLASS="PROPERTY"
>flavor</SPAN
></A
></DT
><DD
><P
>Interfaces have the <TT
CLASS="LITERAL"
>data</TT
> flavor by default, but
they can also be given the <TT
CLASS="LITERAL"
>bool</TT
> or
<TT
CLASS="LITERAL"
>booldata</TT
> flavor when necessary. A
<TT
CLASS="LITERAL"
>bool</TT
> interface is disabled if there are no active
and enabled implementors, otherwise it is enabled. A
<TT
CLASS="LITERAL"
>booldata</TT
> 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.</P
></DD
><DT
><A
HREF="ref.if-define.html"
><SPAN
CLASS="PROPERTY"
>if_define</SPAN
></A
></DT
><DD
><P
>Output a common preprocessor construct to a configuration header file. </P
></DD
><DT
><A
HREF="ref.implements.html"
><SPAN
CLASS="PROPERTY"
>implements</SPAN
></A
></DT
><DD
><P
>If this interface is active it provides one instance of a more general
interface. </P
></DD
><DT
><A
HREF="ref.legal-values.html"
><SPAN
CLASS="PROPERTY"
>legal_values</SPAN
></A
></DT
><DD
><P
>Interfaces always have a small numerical value. The <SPAN
CLASS="PROPERTY"
>legal_values</SPAN
> can
be used to apply additional constraints such as an upper limit.</P
></DD
><DT
><A
HREF="ref.make.html"
><SPAN
CLASS="PROPERTY"
>make</SPAN
></A
></DT
><DD
><P
>An additional custom build step associated with this option, resulting
in a target that should not go directly into a library.</P
></DD
><DT
><A
HREF="ref.make-object.html"
><SPAN
CLASS="PROPERTY"
>make_object</SPAN
></A
></DT
><DD
><P
>An additional custom build step associated with this option, resulting
in an object file that should go into a library.</P
></DD
><DT
><A
HREF="ref.no-define.html"
><SPAN
CLASS="PROPERTY"
>no_define</SPAN
></A
></DT
><DD
><P
>Suppress the normal generation of a preprocessor
<TT
CLASS="LITERAL"
>#define</TT
> symbol in a configuration header file.</P
></DD
><DT
><A
HREF="ref.parent.html"
><SPAN
CLASS="PROPERTY"
>parent</SPAN
></A
></DT
><DD
><P
>Control the location of this option in the configuration hierarchy. </P
></DD
><DT
><A
HREF="ref.requires.html"
><SPAN
CLASS="PROPERTY"
>requires</SPAN
></A
></DT
><DD
><P
>List constraints that the configuration should satisfy if this option is
active and enabled.</P
></DD
></DL
></DIV
><P
>A number of properties are not applicable to interfaces:</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><A
HREF="ref.calculated.html"
><SPAN
CLASS="PROPERTY"
>calculated</SPAN
></A
></DT
><DD
><P
>Interfaces are always calculated, based on the number of active and
enabled entities that implement the interface.</P
></DD
><DT
><A
HREF="ref.default-value.html"
><SPAN
CLASS="PROPERTY"
>default_value</SPAN
></A
></DT
><DD
><P
>Interface values are calculated so a <SPAN
CLASS="PROPERTY"
>default_value</SPAN
> property would be
meaningless.</P
></DD
></DL
></DIV
><P
>Interfaces are not containers, so they cannot hold other entities such
as options or components.</P
><P
>A commonly used constraint on interface values takes the form:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
> requires CYGINT_KERNEL_SCHEDULER == 1</PRE
></TD
></TR
></TABLE
><P
>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.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN3644"
></A
><H2
>Example</H2
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>cdl_interface CYGINT_KERNEL_SCHEDULER {
display "Number of schedulers in this configuration"
requires 1 == CYGINT_KERNEL_SCHEDULER
}</PRE
></TD
></TR
></TABLE
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN3647"
></A
><H2
>See Also</H2
><P
>Property <A
HREF="ref.implements.html"
><SPAN
CLASS="PROPERTY"
>implements</SPAN
></A
>,
command <A
HREF="ref.cdl-option.html"
><TT
CLASS="LITERAL"
>cdl_option</TT
></A
>.
command <A
HREF="ref.cdl-component.html"
><TT
CLASS="LITERAL"
>cdl_component</TT
></A
>,
command <A
HREF="ref.cdl-package.html"
><TT
CLASS="LITERAL"
>cdl_package</TT
></A
>.</P
></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="ref.cdl-package.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="ref.active-if.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><TT
CLASS="LITERAL"
>cdl_package</TT
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="reference.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><SPAN
CLASS="PROPERTY"
>active_if</SPAN
></TD
></TR
></TABLE
></DIV
></BODY
></HTML
> Go to most recent revision | Compare with Previous | Blame | View Log