1 <!-- Copyright (C) 2003 Red Hat, Inc. -->
2 <!-- This material may be distributed only subject to the terms -->
3 <!-- and conditions set forth in the Open Publication License, v1.0 -->
4 <!-- or later (the latest version is presently available at -->
5 <!-- http://www.opencontent.org/openpub/). -->
6 <!-- Distribution of the work or derivative of the work in any -->
7 <!-- standard (paper) book form is prohibited unless prior -->
8 <!-- permission is obtained from the copyright holder. -->
13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
19 TITLE="The eCos Component Writer's Guide"
20 HREF="cdl-guide.html"><LINK
22 TITLE="The eCos Component Writer's Guide"
23 HREF="cdl-guide.html"><LINK
25 TITLE="Why Configurability?"
26 HREF="overview.configurability.html"></HEAD
37 SUMMARY="Header navigation table"
49 > Component Writer's Guide</TH
71 HREF="overview.configurability.html"
84 NAME="OVERVIEW">Chapter 1. Overview</H1
94 HREF="overview.html#OVERVIEW.TERMINOLOGY"
99 HREF="overview.configurability.html"
100 >Why Configurability?</A
104 HREF="overview.approaches.html"
105 >Approaches to Configurability</A
109 HREF="overview.degress.html"
110 >Degrees of Configurability</A
114 HREF="overview.warning.html"
123 > was designed from the very beginning as a configurable
124 component architecture. The core <SPAN
127 > system consists of a number of
128 different components such as the kernel, the C library, an
129 infrastructure package. Each of these provides a large number of
130 configuration options, allowing application developers to build a
131 system that matches the requirements of their particular application.
132 To manage the potential complexity of multiple components and lots of
133 configuration options, <SPAN
136 > comes with a component framework: a
137 collection of tools specifically designed to support configuring
138 multiple components. Furthermore this component framework is
139 extensible, allowing additional components to be added to the system
146 NAME="OVERVIEW.TERMINOLOGY">Terminology</H1
151 > component architecture involves a number of key concepts.</P
157 NAME="CONCEPTS.TERMINOLOGY.FRAMEWORK">Component Framework</H2
163 >component framework</SPAN
165 > is used to describe
166 the collection of tools that allow users to configure a system and
167 administer a component repository. This includes the <SPAN
170 > command line tool, the
171 graphical configuration tool, and the package administration tool.
172 Both the command line and graphical tools are based on a single
173 underlying library, the <SPAN
183 NAME="CONCEPTS.TERMINOLOGY.OPTION">Configuration Option</H2
185 >The option is the basic unit of configurability. Typically each option
186 corresponds to a single choice that a user can make. For example there
187 is an option to control whether or not assertions are enabled, and the
188 kernel provides an option corresponding to the number of scheduling
189 priority levels in the system. Options can control very small amounts
190 of code such as whether or not the C library's
194 > gets inlined. They can also control quite
195 large amounts of code, for example whether or not the
199 > supports floating point conversions.</P
201 >Many options are straightforward, and the user only gets to choose
202 whether the option is enabled or disabled. Some options are more
203 complicated, for example the number of scheduling priority levels is a
204 number that should be within a certain range. Options should always
205 start off with a sensible default setting, so that it is not necessary
206 for users to make hundreds of decisions before any work can start on
207 developing the application. Once the application is running the
208 various configuration options can be used to tune the system for the
209 specific needs of the application.</P
211 >The component framework allows for options that are not directly
212 user-modifiable. Consider the case of processor endianness: some
213 processors are always big-endian or always little-endian, while with
214 other processors there is a choice. Depending on the user's choice of
215 target hardware, endianness may or may not be user-modifiable.</P
222 NAME="CONCEPTS.TERMINOLOGY.COMPONENT">Component</H2
224 >A component is a unit of functionality such as a particular kernel
225 scheduler or a device driver for a specific device. A component is
226 also a configuration option in that users may want to enable
227 or disable all the functionality in a component. For example, if a
228 particular device on the target hardware is not going to be used by
229 the application, directly or indirectly, then there is no point in
230 having a device driver for it. Furthermore disabling the device driver
231 should reduce the memory requirements for both code and data.</P
233 >Components may contain further configuration options. In the case of a
234 device driver, there may be options to control the exact behavior of
235 that driver. These will of course be irrelevant if the driver as a
236 whole is disabled. More generally options and components live in a
237 hierarchy, where any component can contain options specific to that
238 component and further sub-components. It is possible to view the
242 > kernel as one big component, containing sub-components
243 for scheduling, exception handling, synchronization primitives, and so
244 on. The synchronization primitives component can contain further
245 sub-components for mutexes, semaphores, condition variables, event
246 flags, and so on. The mutex component can contain configuration
247 options for issues like priority inversion support.</P
254 NAME="CONCEPTS.TERMINOLOGY.PACKAGE">Package</H2
256 >A package is a special type of component. Specifically, a package is
257 the unit of distribution of components. It is possible to create a
258 distribution file for a package containing all of the source code,
259 header files, documentation, and other relevant files. This
260 distribution file can then be installed using the appropriate tool.
261 Afterwards it is possible to uninstall that package, or to install a
262 later version. The core <SPAN
265 > distribution comes with a number of
266 packages such as the kernel and the infrastructure. Other packages
267 such as network stacks can come from various different sources and can
268 be installed alongside the core distribution.</P
270 >Packages can be enabled or disabled, but the user experience is a
271 little bit different. Generally it makes no sense for the tools to
272 load the details of every single package that has been installed. For
273 example, if the target hardware uses an ARM processor then there is no
274 point in loading the HAL packages for other architectures and
275 displaying choices to the user which are not relevant. Therefore
276 enabling a package means loading its configuration data into the
277 appropriate tool, and disabling a package is an unload operation. In
278 addition, packages are not just enabled or disabled: it is also
279 possible to select the particular version of a package that should be
287 NAME="CONCEPTS.TERMINOLOGY.CONFIGURATION">Configuration</H2
289 >A configuration is a collection of user choices. The various
290 tools that make up the component framework deal with entire
291 configurations. Users can create a new configuration, output a
292 savefile (by default <TT
296 configuration, and use a configuration to generate a build tree prior
300 > and any other packages that have been selected.
301 A configuration includes details such as which packages have been
302 selected, in addition to finer-grained information such as which
303 options in those packages have been enabled or disabled by the user. </P
310 NAME="CONCEPTS.TERMINOLOGY.TARGET">Target</H2
312 >The target is the specific piece of hardware on which the application
313 is expected to run. This may be an off-the-shelf evaluation board, a
314 piece of custom hardware intended for a specific application, or it
315 could be something like a simulator. One of the steps when creating a
316 new configuration is need to specify the target. The component
317 framework will map this on to a set of packages that are used to
318 populate the configuration, typically HAL and device driver packages,
319 and in addition it may cause certain options to be changed from their
320 default settings to something more appropriate for the
328 NAME="CONCEPTS.TERMINOLOGY.TEMPLATE">Template</H2
330 >A template is a partial configuration, aimed at providing users with
331 an appropriate starting point. <SPAN
334 > is shipped with a small number
335 of templates, which correspond closely to common ways of using the
336 system. There is a minimal template which provides very little
337 functionality, just enough to bootstrap the hardware and then jump
338 directly to application code. The default template adds additional
339 functionality, for example it causes the kernel and C library packages
340 to be loaded as well. The uitron template adds further functionality
341 in the form of a µITRON compatibility layer. Creating a new
342 configuration typically involves specifying a template as well as a
343 target, resulting in a configuration that can be built and linked with
344 the application code and that will run on the actual hardware. It is
345 then possible to fine-tune configuration options to produce something
346 that better matches the specific requirements of the application.</P
353 NAME="CONCEPTS.TERMINOLOGY.PROPERTIES">Properties</H2
355 >The component framework needs a certain amount of information about
356 each option. For example it needs to know what the legal values are,
357 what the default should be, where to find the on-line documentation if
358 the user needs to consult that in order to make a decision, and so on.
359 These are all properties of the option. Every option (including
360 components and packages) consists of a name and a set of properties.</P
367 NAME="CONCEPTS.TERMINOLOGY.CONSEQUENCES">Consequences</H2
369 >Choices must have consequences. For an <SPAN
372 > configuration the main
373 end product is a library that can be linked with application code, so
374 the consequences of a user choice must affect the build process. This
375 happens in two main ways. First, options can affect which files get
376 built and end up in the library. Second, details of the current option
377 settings get written into various configuration header files using C
381 > directives, and package source
385 > these configuration headers and
386 adapt accordingly. This allows options to affect a package at a very
387 fine grain, at the level of individual lines in a source file if
388 desired. There may be other consequences as well, for example there
389 are options to control the compiler flags that get used during the
397 NAME="CONCEPTS.TERMINOLOGY.CONSTRAINTS">Constraints</H2
399 >Configuration choices are not independent. The C library can provide
400 thread-safe implementations of functions like
404 >, but only if the kernel provides support for
405 per-thread data. This is a constraint: the C library option has a
406 requirement on the kernel. A typical configuration involves a
407 considerable number of constraints, of varying complexity: many
408 constraints are straightforward, option <TT
422 >. Other constraints can be more
423 complicated, for example option <TT
427 presence of a kernel scheduler but does not care whether it is the
428 bitmap scheduler, the mlqueue scheduler, or something else.</P
430 >Another type of constraint involves the values that can be used for
431 certain options. For example there is a kernel option related to the
432 number of scheduling levels, and there is a legal values constraint on
433 this option: specifying zero or a negative number for the number of
434 scheduling levels makes no sense.</P
441 NAME="CONCEPTS.TERMINOLOGY.CONFLICTS">Conflicts</H2
443 >As the user manipulates options it is possible to end up with an
444 invalid configuration, where one or more constraints are not
445 satisfied. For example if kernel per-thread data is disabled but the C
446 library's thread-safety options are left enabled then there are
447 unsatisfied constraints, also known as conflicts. Such conflicts will
448 be reported by the configuration tools. The presence of conflicts does
449 not prevent users from attempting to build <SPAN
453 consequences are undefined: there may be compile-time failures, there
454 may be link-time failures, the application may completely fail to run,
455 or the application may run most of the time but once in a while there
456 will be a strange failure… Typically users will want to resolve
457 all conflicts before continuing.</P
459 >To make things easier for the user, the configuration tools contain an
460 inference engine. This can examine a conflict in a particular
461 configuration and try to figure out some way of resolving the
462 conflict. Depending on the particular tool being used, the inference
463 engine may get invoked automatically at certain times or the user may
464 need to invoke it explicitly. Also depending on the tool, the
465 inference engine may apply any solutions it finds automatically or it
466 may request user confirmation.</P
473 NAME="CONCEPTS.TERMINOLOGY.CDL">CDL</H2
475 >The configuration tools require information about the various options
476 provided by each package, their consequences and constraints, and
477 other properties such as the location of on-line documentation. This
478 information has to be provided in the form of <SPAN
482 is short for Component Definition Language, and is specifically
483 designed as a way of describing configuration options.</P
485 >A typical package contains the following:</P
492 >Some number of source files which will end up in a library. The
493 application code will be linked with this library to produce an
494 executable. Some source files may serve other purposes, for example to
495 provide a linker script.</P
499 >Exported header files which define the interface provided by the
504 >On-line documentation, for example reference pages for each exported
509 >Some number of test cases, shipped in source format, allowing users to
510 check that the package is working as expected on their particular
511 hardware and in their specific configuration.</P
518 > scripts describing the package to the configuration
523 >Not all packages need to contain all of these. For example some
524 packages such as device drivers may not provide a new interface,
525 instead they just provide another implementation of an existing
526 interface. However all packages must contain a <SPAN
530 describes the package to the configuration tools.</P
537 NAME="CONCEPTS.TERMINOLOGY.REPO">Component Repository</H2
542 > installations include a component repository. This is a
543 directory structure where all the packages get installed. The
544 component framework comes with an administration tool that allows new
545 packages or new versions of a package to be installed, old packages to
546 be removed, and so on. The component repository includes a simple
547 database, maintained by the administration tool, which contains
548 details of the various packages.</P
550 >Generally application developers do not need to modify anything inside
551 the component repository, except by means of the administration tool.
552 Instead their work involves separate build and install trees. This
553 allows the component repository to be treated as a read-only resource
554 that can be shared by multiple projects and multiple users. Component
555 writers modifying one of the packages do need to manipulate files in
556 the component repository.</P
565 SUMMARY="Footer navigation table"
576 HREF="cdl-guide.html"
585 HREF="cdl-guide.html"
594 HREF="overview.configurability.html"
607 > Component Writer's Guide</TD
617 >Why Configurability?</TD