📄 ref.cdl-interface.html
字号:
<!-- 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"><METANAME="GENERATOR"CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+"><LINKREL="HOME"TITLE="The eCos Component Writer's Guide"HREF="cdl-guide.html"><LINKREL="UP"TITLE="CDL Language Specification"HREF="reference.html"><LINKREL="PREVIOUS"TITLE="cdl_package"HREF="ref.cdl-package.html"><LINKREL="NEXT"TITLE="active_if"HREF="ref.active-if.html"></HEAD><BODYCLASS="REFENTRY"BGCOLOR="#FFFFFF"TEXT="#000000"LINK="#0000FF"VLINK="#840084"ALINK="#0000FF"><DIVCLASS="NAVHEADER"><TABLESUMMARY="Header navigation table"WIDTH="100%"BORDER="0"CELLPADDING="0"CELLSPACING="0"><TR><THCOLSPAN="3"ALIGN="center">The <SPANCLASS="APPLICATION">eCos</SPAN> Component Writer's Guide</TH></TR><TR><TDWIDTH="10%"ALIGN="left"VALIGN="bottom"><AHREF="ref.cdl-package.html"ACCESSKEY="P">Prev</A></TD><TDWIDTH="80%"ALIGN="center"VALIGN="bottom"></TD><TDWIDTH="10%"ALIGN="right"VALIGN="bottom"><AHREF="ref.active-if.html"ACCESSKEY="N">Next</A></TD></TR></TABLE><HRALIGN="LEFT"WIDTH="100%"></DIV><H1><ANAME="REF.CDL-INTERFACE"><TTCLASS="LITERAL">cdl_interface</TT></H1><DIVCLASS="REFNAMEDIV"><ANAME="AEN3484"></A><H2>Name</H2>Command <TTCLASS="LITERAL">cdl_interface</TT> -- Define an interface, functionality that can be provided bya number of different implementations.</DIV><DIVCLASS="REFSYNOPSISDIV"><ANAME="AEN3488"><H2>Synopsis</H2><TABLEBORDER="5"BGCOLOR="#E0E0F0"WIDTH="70%"><TR><TD><PRECLASS="SYNOPSIS">cdl_interface <name> { …}</PRE></TD></TR></TABLE></DIV><DIVCLASS="REFSECT1"><ANAME="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 <SPANCLASS="APPLICATION">CDL</SPAN>expressions. As an example, suppose that some package relies on thepresence of code that implements the standard kernel schedulinginterface. However the requirement is no more stringent than this, sothe constraint can be satisfied by the mlqueue scheduler, the bitmapscheduler, or any additional schedulers that may get implemented infuture. A first attempt at expressing the dependency might be:</P><TABLEBORDER="5"BGCOLOR="#E0E0F0"WIDTH="70%"><TR><TD><PRECLASS="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 newscheduler were to be added to the system. Interfaces provide a way ofexpressing more general relationships:</P><TABLEBORDER="5"BGCOLOR="#E0E0F0"WIDTH="70%"><TR><TD><PRECLASS="PROGRAMLISTING"> requires CYGINT_KERNEL_SCHEDULER</PRE></TD></TR></TABLE><P>The interface <TTCLASS="LITERAL">CYGINT_KERNEL_SCHEDULER</TT> is<SPANCLASS="emphasis"><ICLASS="EMPHASIS">implemented</I></SPAN> by both the mlqueue and bitmapschedulers, and may be implemented by future schedulers as well. Thevalue of an interface is the number of implementors that are activeand enabled, so in a typical configuration only one scheduler will bein use and the value of the interface will be <TTCLASS="LITERAL">1</TT>. Ifall schedulers are disabled then the interface will have a value<TTCLASS="LITERAL">0</TT> and the <SPANCLASS="PROPERTY">requires</SPAN> constraint will not besatisfied.</P><P>Some component writers may prefer to use the first <SPANCLASS="PROPERTY">requires</SPAN>constraint on the grounds that the code will only have been testedwith the mlqueue and bitmap schedulers and cannot be guaranteed towork with any new schedulers. Other component writers may take a moreoptimistic view and assume that their code will work with anyscheduler until proven otherwise.</P><P>Interfaces must be defined in CDL scripts, just like options,components and packages. This involves the command <TTCLASS="LITERAL">cdl_interface</TT>which takes two arguments, a name and a body. The name must be a validC 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 avoidedbecause they may clash with system packages or with identifiersreserved for use by the compiler. Within a single configuration, namesmust be unique. If a configuration contained two packages whichdefined the same entity <TTCLASS="LITERAL">CYGIMP_SOME_OPTION</TT>, anyreferences to that entity in a <SPANCLASS="PROPERTY">requires</SPAN> property or any otherexpression would be ambiguous. It is possible for a given name to beused by two different packages if those packages should never beloaded into a single configuration. For example, architectural HALpackages are allowed to re-use names because a single configurationcannot target two different architectures. For a recommended namingconvention see <AHREF="package.contents.html">the Section called <I>Package Contents and Layout</I> in Chapter 2</A>.</P><P>The second argument to <TTCLASS="LITERAL">cdl_interface</TT> is a body of properties,typically surrounded by braces so that the Tcl interpreter treats itas a single argument. This body will be processed by a recursiveinvocation of the Tcl interpreter, extended with additional commandsfor the various properties that are allowed inside a <TTCLASS="LITERAL">cdl_interface</TT>.The valid properties are a subset of those for a <TTCLASS="LITERAL">cdl_option</TT>.</P><P></P><DIVCLASS="VARIABLELIST"><DL><DT><AHREF="ref.active-if.html"><SPANCLASS="PROPERTY">active_if</SPAN></A></DT><DD><P>Allow additional control over the active state of this interface.</P></DD><DT><AHREF="ref.compile.html"><SPANCLASS="PROPERTY">compile</SPAN></A></DT><DD><P>List the source files that should be built if this interface is active.</P></DD><DT><AHREF="ref.define.html"><SPANCLASS="PROPERTY">define</SPAN></A></DT><DD><P>Specify additional <TTCLASS="LITERAL">#define</TT> symbols that should gointo the owning package's configuration header file.</P></DD><DT><AHREF="ref.define-format.html"><SPANCLASS="PROPERTY">define_format</SPAN></A></DT><DD><P>Control how the interface's value will appear in the configuration headerfile.</P></DD><DT><AHREF="ref.define-proc.html"><SPANCLASS="PROPERTY">define_proc</SPAN></A></DT><DD><P>Use a fragment of Tcl code to output additional data toconfiguration header files.</P></DD><DT><AHREF="ref.description.html"><SPANCLASS="PROPERTY">description</SPAN></A></DT><DD><P>Provide a textual description for this interface.</P></DD><DT><AHREF="ref.display.html"><SPANCLASS="PROPERTY">display</SPAN></A></DT><DD><P>Provide a short string describing this interface.</P></DD><DT><AHREF="ref.doc.html"><SPANCLASS="PROPERTY">doc</SPAN></A></DT><DD><P>The location of on-line documentation for this interface.</P></DD><DT><AHREF="ref.flavor.html"><SPANCLASS="PROPERTY">flavor</SPAN></A></DT><DD><P>Interfaces have the <TTCLASS="LITERAL">data</TT> flavor by default, butthey can also be given the <TTCLASS="LITERAL">bool</TT> or<TTCLASS="LITERAL">booldata</TT> flavor when necessary. A<TTCLASS="LITERAL">bool</TT> interface is disabled if there are no activeand enabled implementors, otherwise it is enabled. A<TTCLASS="LITERAL">booldata</TT> interface is also disabled if there are noactive and enabled implementors, otherwise it is enabled and the datais a number corresponding to the number of these implementors.</P></DD><DT><AHREF="ref.if-define.html"><SPANCLASS="PROPERTY">if_define</SPAN></A></DT><DD><P>Output a common preprocessor construct to a configuration header file. </P></DD><DT><AHREF="ref.implements.html"><SPANCLASS="PROPERTY">implements</SPAN></A></DT><DD><P>If this interface is active it provides one instance of a more generalinterface. </P></DD><DT><AHREF="ref.legal-values.html"><SPANCLASS="PROPERTY">legal_values</SPAN></A></DT><DD><P>Interfaces always have a small numerical value. The <SPANCLASS="PROPERTY">legal_values</SPAN> canbe used to apply additional constraints such as an upper limit.</P></DD><DT><AHREF="ref.make.html"><SPANCLASS="PROPERTY">make</SPAN></A></DT><DD><P>An additional custom build step associated with this option, resultingin a target that should not go directly into a library.</P></DD><DT><AHREF="ref.make-object.html"><SPANCLASS="PROPERTY">make_object</SPAN></A></DT><DD><P>An additional custom build step associated with this option, resultingin an object file that should go into a library.</P></DD><DT><AHREF="ref.no-define.html"><SPANCLASS="PROPERTY">no_define</SPAN></A></DT><DD><P>Suppress the normal generation of a preprocessor<TTCLASS="LITERAL">#define</TT> symbol in a configuration header file.</P></DD><DT><AHREF="ref.parent.html"><SPANCLASS="PROPERTY">parent</SPAN></A></DT><DD><P>Control the location of this option in the configuration hierarchy. </P></DD><DT><AHREF="ref.requires.html"><SPANCLASS="PROPERTY">requires</SPAN></A></DT><DD><P>List constraints that the configuration should satisfy if this option isactive and enabled.</P></DD></DL></DIV><P>A number of properties are not applicable to interfaces:</P><P></P><DIVCLASS="VARIABLELIST"><DL><DT><AHREF="ref.calculated.html"><SPANCLASS="PROPERTY">calculated</SPAN></A></DT><DD><P>Interfaces are always calculated, based on the number of active andenabled entities that implement the interface.</P></DD><DT><AHREF="ref.default-value.html"><SPANCLASS="PROPERTY">default_value</SPAN></A></DT><DD><P>Interface values are calculated so a <SPANCLASS="PROPERTY">default_value</SPAN> property would bemeaningless.</P></DD></DL></DIV><P>Interfaces are not containers, so they cannot hold other entities suchas options or components.</P><P>A commonly used constraint on interface values takes the form:</P><TABLEBORDER="5"BGCOLOR="#E0E0F0"WIDTH="70%"><TR><TD><PRECLASS="PROGRAMLISTING"> requires CYGINT_KERNEL_SCHEDULER == 1</PRE></TD></TR></TABLE><P>This constraint specifies that there can be only one scheduler in thesystem. In some circumstances it is possible for the configurationtools to detect this pattern and act accordingly, so for exampleenabling the bitmap scheduler would automatically disable the mlqueuescheduler.</P></DIV><DIVCLASS="REFSECT1"><ANAME="AEN3644"></A><H2>Example</H2><TABLEBORDER="5"BGCOLOR="#E0E0F0"WIDTH="70%"><TR><TD><PRECLASS="PROGRAMLISTING">cdl_interface CYGINT_KERNEL_SCHEDULER { display "Number of schedulers in this configuration" requires 1 == CYGINT_KERNEL_SCHEDULER}</PRE></TD></TR></TABLE></DIV><DIVCLASS="REFSECT1"><ANAME="AEN3647"></A><H2>See Also</H2><P>Property <AHREF="ref.implements.html"><SPANCLASS="PROPERTY">implements</SPAN></A>,command <AHREF="ref.cdl-option.html"><TTCLASS="LITERAL">cdl_option</TT></A>.command <AHREF="ref.cdl-component.html"><TTCLASS="LITERAL">cdl_component</TT></A>,command <AHREF="ref.cdl-package.html"><TTCLASS="LITERAL">cdl_package</TT></A>.</P></DIV><DIVCLASS="NAVFOOTER"><HRALIGN="LEFT"WIDTH="100%"><TABLESUMMARY="Footer navigation table"WIDTH="100%"BORDER="0"CELLPADDING="0"CELLSPACING="0"><TR><TDWIDTH="33%"ALIGN="left"VALIGN="top"><AHREF="ref.cdl-package.html"ACCESSKEY="P">Prev</A></TD><TDWIDTH="34%"ALIGN="center"VALIGN="top"><AHREF="cdl-guide.html"ACCESSKEY="H">Home</A></TD><TDWIDTH="33%"ALIGN="right"VALIGN="top"><AHREF="ref.active-if.html"ACCESSKEY="N">Next</A></TD></TR><TR><TDWIDTH="33%"ALIGN="left"VALIGN="top"><TTCLASS="LITERAL">cdl_package</TT></TD><TDWIDTH="34%"ALIGN="center"VALIGN="top"><AHREF="reference.html"ACCESSKEY="U">Up</A></TD><TDWIDTH="33%"ALIGN="right"VALIGN="top"><SPANCLASS="PROPERTY">active_if</SPAN></TD></TR></TABLE></DIV></BODY></HTML>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -