diff options
| author | Michael Gielda <mgielda@antmicro.com> | 2014-04-03 14:53:04 +0200 |
|---|---|---|
| committer | Michael Gielda <mgielda@antmicro.com> | 2014-04-03 14:53:04 +0200 |
| commit | ae1e4e08a1005a0c487f03ba189d7536e7fdcba6 (patch) | |
| tree | f1c296f8a966a9a39876b0e98e16d9c5da1776dd /ecos/doc | |
| parent | f157da5337118d3c5cd464266796de4262ac9dbd (diff) | |
Added the OS files
Diffstat (limited to 'ecos/doc')
61 files changed, 14729 insertions, 0 deletions
diff --git a/ecos/doc/ChangeLog b/ecos/doc/ChangeLog new file mode 100644 index 0000000..c60bc36 --- /dev/null +++ b/ecos/doc/ChangeLog @@ -0,0 +1,238 @@ +2014-02-13 Ilija Kocho <ilijak@siva.com.mk> + + * sgml/doclist: Add Freescale eDMA entry. + +2013-07-01 Ilija Kocho <ilijak@siva.com.mk> + + * sgml/doclist: Add K60F120M entry (document body provided by Mike Jones) + +2013-06-12 John Dallaway <john@dallaway.org.uk> + + * sgml/doclist: Add STM32F4-Discovery documentation. + +2013-05-09 John Dallaway <john@dallaway.org.uk> + + * sgml/makemakefile: Update copyright dates. + +2012-05-18 Ilija Kocho <ilijak@siva.com.mk> + + * sgml/doclist: Add Freescale Kinetis documentation. + +2012-03-13 John Dallaway <john@dallaway.org.uk> + + * sgml/doclist: Add Actel SmartFusion documentation. + * sgml/makemakefile: Update copyright dates. + +2011-02-09 John Dallaway <john@dallaway.org.uk> + + * sgml/makemakefile: Update copyright dates. + +2011-02-09 Christophe Coutand <ccoutand@stmi.com> + + * sgml/doclist: Add EK-LM3S811 documentation. + +2010-11-13 John Dallaway <john@dallaway.org.uk> + + * sgml/doclist: Add USB mass storage documentation. + +2010-02-25 John Dallaway <john@dallaway.org.uk> + + * sgml/makemakefile: Update copyright dates. + +2009-08-24 Uwe Kindler <uwe_kindler@web.de> + + * sgml/doclist: Add uSTL documentation. + * sgml/makemakefile: Update copyright dates. + +2008-12-10 John Dallaway <jld@ecoscentric.com> + + * sgml/doclist: reference all documentation files. + +2008-11-23 Bart Veer <bartv@ecoscentric.com> + + * sgml/doclist: add M68K/ColdFire documentation. + +2008-11-17 Jonathan Larmour <jifl@eCosCentric.com> + + * sgml/doclist: Add AMD AM29XXXXX and Intel StrataFlash v2 flash + driver documentation. + +2008-10-08 Bart Veer <bartv@ecoscentric.com> + + * sgml/doclist: added generic framebuffer and synthetic target + framebuffer driver documentation. + +2008-08-08 Nick Garnett <nickg@ecoscentric.com> + + * sgml/doclist: Added ADC documentation. + +2008-07-12 Andrew Lunn <andrew.lunn@ascom.ch> + + * sgml/doclist: added USB Serial documentation + +2006-12-16 Uwe.Kindler <uwe.kindler@cetoni.de> + + * sgml/doclist: Added CAN documentation. + +2006-09-25 Andrew Lunn <andrew.lunn@ascom.ch> + + * sgml/doclist: added MMC disk documentation + +2006-06-16 Anthony Tonizzo <atonizzo@gmail.com> + + * sgml/doclist: add ATHTTPD documentation + +2005-04-21 Bart Veer <bartv@ecoscentric.com> + + * sgml/doclist: add I2C and DS1307 documentation + +2005-03-27 Andrew Lunn <andrew.lunn@ascom.ch> + + * sgml/doclist: added memalloc documentation. + +2004-08-25 Bart Veer <bartv@ecoscentric.com> + + * sgml/doclist: add SPI documentation + +2004-06-20 Andrew Lunn <andrew.lunn@ascom.ch> + + * sgml/doclist: Added flash API documentation. + +2004-06-15 Jonathan Larmour <jifl@eCosCentric.com> + + * sgml/makemakefile: Replace plusses with x'es in all entities. + +2004-04-19 John Dallaway <jld@ecoscentric.com> + + * sgml/doclist: Remove RedBoot documentation which is now built + separately. + +2004-04-14 Nick Garnett <nickg@calivar.com> + + * sgml/doclist: Added PPP package documentation. + +2003-11-25 Manu Sharma <manu.sharma@ascom.com> + + * sgml/doclist: Add OpenBSD specific documentation. + +2003-11-22 Andrew Lunn <andrew.lunn@ascom.ch> + + * sgml/doclist: Added ipsec packages documentation + * sgml/makemakefile: Added another set of man pages to the kludge. + +2003-11-08 Andrew Lunn <andrew.lunn@ascom.ch> + + * sgml/user-guide/programming.sgml: Suggest Unix users may prefer + ecosconfig rather than the GUI. + * sgml/user-guide/makefile: Listed the other .sgml files so + dependency checking works + +2003-09-11 Gary Thomas <gary@mlbassoc.com> + + * sgml/doclist: Add ethernet PHY documentation. + +2003-07-09 Jonathan Larmour <jifl@eCosCentric.com> + + * sgml/makemakefile: Update trademark info and sort. + +2003-05-01 Jonathan Larmour <jifl@eCosCentric.com> + + * sgml/jadetex.cfg: Add this to configure PDF output nicely with index + and coloured links. + +2003-03-23 Iztok Zupet <iz@vsr.si> + + * sgml/makemakefile: modified copyfiles to copy png-s instead of + gif-s. + * sgml/README-PDF: Comment on pdfjadetext failure and workaround. + +2003-03-27 Thomas Koeller <thomas.koeller@baslerweb.com> + + * sgml/makemakefile: Modified to generate makefile that can + be used to build docs in arbitrary directory. + +2003-02-25 Andrew Lunn <andrew.lunn@ascom.ch> + + * sgml/doclist: Added the simple network time protocol client + documentation. + +2003-02-24 Jonathan Larmour <jifl@eCosCentric.com> + + * sgml/doclist: Reorder in a slightly more logical order with + related bits grouped together. + Add docs for power management, USB (slave, eth slave, and SA11x0 + and NEC uPD8985xx drivers), and synthetic target HAL, eth and + watchdog drivers. + + * sgml/.cvsignore: Add gifs and rename ecos.* to ecos-ref.* + + * sgml/makemakefile: Rename ecos.sgml/html/etc. to ecos-ref. + Copy over GIFs where they exist. + Don't treat porting guide specially at the top... treat it only as + specially as the other special cases. + Update (C) holders. + Update licence/warranty blurb. + +2003-01-30 Andrew Lunn <andrew.lunn@ascom.ch> + + * sgml/doclist: Added snmp-manpages.sgml + * sgml/makemakefile: Extend the kludge to include snmp-manpages.sgml + +2003-01-22 John Dallaway <jld@ecoscentric.com> + + * sgml/makemakefile: Allow eCos package version to be specified + (when not "current") as the first command line parameter. + +2003-01-04 Jonathan Larmour <jifl@eCosCentric.com> + + * sgml/makemakefile: Oops, use new entity consistently in generated + ecos.sgml. + +2003-01-03 Jonathan Larmour <jifl@eCosCentric.com> + + * sgml/makemakefile: Try to shorten generated entity names. + * sgml/doclist: add terminating LF. + +2002-12-22 Nick Garnett <nickg@ecoscentric.com> + + * sgml/doclist: Added HTTPD package documentation. + + * sgml/.cvsignore: Added files generated during PDF build. + +2002-10-28 Andrew Lunn <andrew.lunn@ascom.ch> + + * sgml/makemakefile: Removed the second OTHER_SGML which clobbers + the first correct definition, so stopping dependencies working. + +2002-10-15 Iztok Zupet <iz@vsr.si> + + * sgml/README-PDF: added + * sgml/makemakefile: defined MAIN_PDF + +2002-10-15 Jonathan Larmour <jifl@eCosCentric.com> + + * sgml/makemakefile: Only put ecos.sgml in MAIN_SGML. Put all others + in OTHER_SGML. From Bart Veer. + +2002-09-02 Andrew Lunn <andrew.lunn@ascom.ch + + * sgml/tutorial/makefile: changed ecc to packages + * sgml/user-guide/makefile: changed ecc to packages + +2002-08-15 Andrew Lunn <andrew.lunn@ascom.ch> + + * sgml/doclist: Added the CPU load package documentation. + +2002-08-09 Andrew Lunn <andrew.lunn@ascom.ch> + + * sgml/doclist: Added the CRC package documentation. + +2002-08-09 Andrew Lunn <andrew.lunn@ascom.ch> + + * sgml/.cvsignore: Ignore the generated html files etc. + +2002-08-07 Andrew Lunn <andrew.lunn@ascom.ch> + + * sgml/makemakefile: Replaced the old internal RedHat ecc + directory name with the new name "packages" + diff --git a/ecos/doc/sgml/.cvsignore b/ecos/doc/sgml/.cvsignore new file mode 100644 index 0000000..a41a6e6 --- /dev/null +++ b/ecos/doc/sgml/.cvsignore @@ -0,0 +1,10 @@ +ecos-ref.sgml +ecos-ref.tex +ecos-ref.log +ecos-ref.aux +ecos-ref.out +ecos-ref.pdf +makefile +*.html +*.gif +*.png
\ No newline at end of file diff --git a/ecos/doc/sgml/README-PDF b/ecos/doc/sgml/README-PDF new file mode 100644 index 0000000..c584fc2 --- /dev/null +++ b/ecos/doc/sgml/README-PDF @@ -0,0 +1,31 @@ +To build the PDF version of docs (on Linux), simply use: +make pdfa4 for A4 size or +make pdfletter for US letter size + +If Your pdfjadetex complains with + > ! TeX capacity exceeded, sorry [save size=5000]. +then define + save_size.pdfjadetex=10000 (at least) in + /usr/share/texmf/web2c/texmf.cnf instead of 5000. + +If Your pdfjadetex complains with + > ! TeX capacity exceeded, sorry [number of strings=55000]. +then define + max_strings.pdfjadetex=155000 (for instance) in + /usr/share/texmf/web2c/texmf.cnf instead of 5000. + +If You don't get coloured links in Your output, or if You +wish to modify the pdfjadetex default behaviour then add +a file named jadetex.cfg into each directory where the build +takes place and put something like that into: + +\hypersetup{pdfpagemode=None, pdfauthor=eCos (pdfjadetex) , colorlinks=true, + linkcolor=blue, pdfstartview=FitH} + +Regards +Iztok +<iz@vsr.si> + + + + diff --git a/ecos/doc/sgml/doclist b/ecos/doc/sgml/doclist new file mode 100644 index 0000000..3785c0c --- /dev/null +++ b/ecos/doc/sgml/doclist @@ -0,0 +1,75 @@ +kernel/current/doc/kernel.sgml +hal/common/current/doc/hal.sgml +hal/common/current/doc/porting.sgml +language/c/libc/common/current/doc/libc.sgml +language/cxx/ustl/current/doc/ustl.sgml +io/common/current/doc/io.sgml +io/fileio/current/doc/fileio.sgml +io/pci/current/doc/pci.sgml +io/flash/current/doc/flash.sgml +io/spi/current/doc/spi.sgml +io/i2c/current/doc/i2c.sgml +io/can/current/doc/can.sgml +io/adc/current/doc/adc.sgml +io/framebuf/current/doc/framebuf.sgml +compat/posix/current/doc/posix.sgml +compat/uitron/current/doc/uitron.sgml +net/common/current/doc/tcpip.sgml +net/common/current/doc/tcpip-manpages.sgml +net/bsd_tcpip/current/doc/freebsd.sgml +net/tcpip/current/doc/openbsd.sgml +net/tcpip/current/doc/openbsd-manpages-bridge.sgml +net/tcpip/current/doc/openbsd-manpages-netintro.sgml +net/tcpip/current/doc/openbsd-manpages-stp.sgml +net/ns/dns/current/doc/dns.sgml +net/common/current/doc/ipsec.sgml +net/ipsec/libipsec/current/doc/libipsec-manpages.sgml +net/ppp/current/doc/ppp.sgml +io/eth/current/doc/ethdrv.sgml +devs/eth/phy/current/doc/eth_phy.sgml +net/snmp/agent/current/doc/snmp.sgml +net/snmp/agent/current/doc/snmp-manpages.sgml +net/httpd/current/doc/httpd.sgml +net/ftpclient/current/doc/ftpclient.sgml +net/sntp/current/doc/sntp.sgml +net/athttpd/current/doc/athttpd.sgml +services/memalloc/common/current/doc/memalloc.sgml +services/crc/current/doc/crc.sgml +services/cpuload/current/doc/cpuload.sgml +services/profile/gprof/current/doc/profile.sgml +services/power/common/current/doc/power.sgml +io/usb/slave/current/doc/usbs.sgml +io/usb/eth/slave/current/doc/usbseth.sgml +io/usb/serial/slave/current/doc/usbs_serial.sgml +io/usb/msd/slave/current/doc/usbs_msd.sgml +hal/synth/arch/current/doc/synth.sgml +hal/m68k/arch/current/doc/m68k.sgml +hal/m68k/mcf52xx/var/current/doc/mcf52xx.sgml +hal/m68k/mcf52xx/mcf5272/proc/current/doc/mcf5272.sgml +hal/m68k/mcf52xx/mcf5272/m5272c3/current/doc/m5272c3.sgml +hal/cortexm/kinetis/var/current/doc/kinetis_begin.sgml +hal/cortexm/kinetis/var/current/doc/kinetis.sgml +hal/cortexm/kinetis/twr_k70f120m/current/doc/twr_k70f120m.sgml +hal/cortexm/kinetis/twr_k60n512/current/doc/twr_k60n512.sgml +hal/cortexm/kinetis/twr_k60f120m/current/doc/twr_k60f120m.sgml +hal/cortexm/kinetis/twr_k40x256/current/doc/twr_k40x256.sgml +hal/cortexm/kinetis/var/current/doc/kinetis_end.sgml +hal/cortexm/a2fxxx/a2f200_eval/current/doc/a2f200e.sgml +hal/cortexm/lm3s/ek_lm3s811/current/doc/ek_lm3s811.sgml +hal/cortexm/stm32/stm32f4discovery/current/doc/stm32f4discovery.sgml +hal/sh/sh4_202_md/current/doc/sh4_202_md.sgml +devs/usb/sa11x0/current/doc/usbs_sa11x0.sgml +devs/usb/nec_upd985xx/current/doc/usbs_upd985xx.sgml +devs/eth/synth/ecosynth/current/doc/syntheth.sgml +devs/eth/m68k/mcf5272/current/doc/mcf5272_eth.sgml +devs/serial/m68k/mcf52xx/current/doc/mcf52xx_ser.sgml +devs/watchdog/synth/current/doc/synth_watchdog.sgml +devs/wallclock/dallas/ds1307/current/doc/ds1307.sgml +devs/disk/generic/mmc/current/doc/disk_mmc.sgml +devs/framebuf/synth/current/doc/synth_framebuf.sgml +devs/flash/amd/am29xxxxxv2/current/doc/am29xxxxx.sgml +devs/flash/intel/stratav2/current/doc/strata.sgml +devs/i2c/m68k/mcf52xx/current/doc/mcf52xx_i2c.sgml +hal/misc/freescale/edma/current/doc/freescale_begin.sgml +hal/misc/freescale/edma/current/doc/edma.sgml +hal/misc/freescale/edma/current/doc/freescale_end.sgml diff --git a/ecos/doc/sgml/jadetex.cfg b/ecos/doc/sgml/jadetex.cfg new file mode 100644 index 0000000..f5c94ec --- /dev/null +++ b/ecos/doc/sgml/jadetex.cfg @@ -0,0 +1 @@ +\hypersetup{pdfauthor=eCos (pdfjadetex) , colorlinks=true, linkcolor=blue, pdfstartview=FitH} diff --git a/ecos/doc/sgml/makemakefile b/ecos/doc/sgml/makemakefile new file mode 100755 index 0000000..cc7b2c4 --- /dev/null +++ b/ecos/doc/sgml/makemakefile @@ -0,0 +1,232 @@ +#!/bin/sh + +touch ecos-ref.sgml +touch makefile +chmod +w ecos-ref.sgml +chmod +w makefile + +sgmldir="`dirname $0`" +doclist="${sgmldir}/doclist" +toplvl="${sgmldir}/../.." + +cat > makefile <<EOF +#============================================================================= +# +# makefile +# +# For building the eCos docs +# +#============================================================================= +# ####ECOSGPLCOPYRIGHTBEGIN#### +# ------------------------------------------- +# This file is part of eCos, the Embedded Configurable Operating System. +# Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2009, 2010, 2011, 2012, 2013 Free Software Foundation, Inc. +# +# eCos is free software; you can redistribute it and/or modify it under +# the terms of the GNU General Public License as published by the Free +# Software Foundation; either version 2 or (at your option) any later +# version. +# +# eCos is distributed in the hope that it will be useful, but WITHOUT +# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +# for more details. +# +# You should have received a copy of the GNU General Public License +# along with eCos; if not, write to the Free Software Foundation, Inc., +# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. +# +# As a special exception, if other files instantiate templates or use +# macros or inline functions from this file, or you compile this file +# and link it with other works to produce a work based on this file, +# this file does not by itself cause the resulting work to be covered by +# the GNU General Public License. However the source code for this file +# must still be made available in accordance with section (3) of the GNU +# General Public License v2. +# +# This exception does not invalidate any other reasons why a work based +# on this file might be covered by the GNU General Public License. +# ------------------------------------------- +# ####ECOSGPLCOPYRIGHTEND#### +#============================================================================= +#####DESCRIPTIONBEGIN#### +# +# Author(s): jlarmour +# Date: 2002-02-05 +#####DESCRIPTIONEND#### +#============================================================================= + +TOPLEVEL := ${toplvl}/packages +EOF +/bin/echo MAIN_SGML := ecos-ref.sgml >> makefile +/bin/echo -n OTHER_SGML := >> makefile + +cat >ecos-ref.sgml <<EOF +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [ + +<!-- Begin Document Specific Declarations --> +<!ENTITY ui "µITRON"> +<!ENTITY versiondir CDATA "v2_0"> +<!ENTITY version CDATA "2.0"> +<!ENTITY lt SDATA "[lt ]"> +EOF + +PACKAGEVER=${1:-'current'} + +for i in `cat ${doclist}`; do + line="`echo $i | sed 's/#.*//;'`" + if (test ! -z $line); then + /bin/echo -n " ${toplvl}/packages/$i" | sed "s@/current/@/${PACKAGEVER}/@g" >> makefile + entityi="`echo $i | sed 's@\+@x@g; s@/@-@g; s@\.@-@g; s@_@-@g; s@-current-doc@@g; s@-current@@g'`" + echo "<!ENTITY $entityi SYSTEM \"${toplvl}/packages/$i\">" | sed "s@/current/@/${PACKAGEVER}/@g" >> ecos-ref.sgml + fi +done + +# Go through again but find GIFs and PNGs to copy +for i in `for j in \`cat ${doclist}\` ; do dirname $j ; done | sort | uniq` ; do + diri=`echo ${toplvl}/packages/$i | sed "s@/current/@/${PACKAGEVER}/@g"` + dirigifs=`ls $diri/*.gif $diri/*.png 2>/dev/null | tr '\n' ' '` + if [ x"$dirigifs" != x ]; then + copyfiles="$copyfiles $dirigifs" + fi +done + +cat >> makefile <<EOF + +MAIN_HTML := ecos-ref.html +MAIN_PDF := ecos-ref.pdf +PICTURES := +COPYFILES := $copyfiles + +include \$(TOPLEVEL)/pkgconf/rules.doc +EOF + +cat >> ecos-ref.sgml <<EOF +<!-- End Document Specific Declarations --> +]> + +<BOOK ID="ECOS-REF"> + <bookinfo> + <TITLE>eCos Reference Manual</TITLE> + + <copyright> + <year>1998</year> + <year>1999</year> + <year>2000</year> + <year>2001</year> + <year>2002</year> + <year>2003</year> + <year>2004</year> + <year>2005</year> + <year>2006</year> + <year>2007</year> + <year>2008</year> + <year>2009</year> + <year>2010</year> + <year>2011</year> + <year>2012</year> + <year>2013</year> + <holder>Free Software Foundation, Inc.</holder> + </copyright> + + <legalnotice> + <title>Documentation licensing terms</title> +<para>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 +<ulink url="http://www.opencontent.org/openpub/">http://www.opencontent.org/openpub/</ulink>). +</para> +<para> +Distribution of substantively modified versions of this +document is prohibited without the explicit permission of the +copyright holder.</para> +<para> +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. +</para> + </legalnotice> + <legalnotice> + <title>Trademarks</title> +<para>Altera® and Excalibur™ are trademarks of Altera Corporation.</para> +<para>AMD® is a registered trademark of Advanced Micro Devices, Inc.</para> +<para>ARM®, StrongARM®, Thumb®, ARM7™, ARM9™ is a registered trademark of Advanced RISC Machines, Ltd.</para> +<para>Cirrus Logic® and Maverick™ are registered trademarks of Cirrus Logic, Inc.</para> +<para>Cogent™ is a trademark of Cogent Computer Systems, Inc.</para> +<para>Compaq® is a registered trademark of the Compaq Computer Corporation.</para> +<para>eCos® is a registered trademark of eCosCentric Limited.</para> +<para>Fujitsu® is a registered trademark of Fujitsu Limited.</para> +<para>IBM®, and PowerPC™ are trademarks of International Business Machines Corporation.</para> +<para>IDT® is a registered trademark of Integrated Device Technology Inc.</para> +<para>Intel®, i386™, Pentium®, StrataFlash® and XScale™ are trademarks of Intel Corporation.</para> +<para>Intrinsyc® and Cerf™ are trademarks of Intrinsyc Software, Inc.</para> +<para>Linux® is a registered trademark of Linus Torvalds. </para> +<para>Matsushita™ and Panasonic® are trademarks of the Matsushita Electric Industrial Corporation.</para> +<para>Microsoft®, Windows®, Windows NT® and Windows XP® are registered trademarks of Microsoft Corporation, Inc. </para> +<para>MIPS®, MIPS32™ MIPS64™, 4K&trade, 5K™ Atlas™ and Malta™ are trademarks of MIPS Technologies, Inc.</para> +<para>Motorola®, ColdFire® is a trademark of Motorola, Inc.</para> +<para>NEC® V800™, V850™, V850/SA1™, V850/SB1™, VR4300™, and VRC4375™ are trademarks of NEC Corporation.</para> +<para>PMC-Sierra® RM7000™ and Ocelot™ are trademarks of PMC-Sierra Incorporated. </para> +<para>Red Hat, RedBoot™, GNUPro®, and Insight™ are trademarks of Red Hat, Inc. </para> +<para>Samsung® and CalmRISC™ are trademarks or registered trademarks of Samsung, Inc. </para> +<para>Sharp® is a registered trademark of Sharp Electronics Corp.</para> +<para>SPARC® is a registered trademark of SPARC International, Inc., and is used under license by Sun Microsystems, Inc. </para> +<para>Sun Microsystems® and Solaris® are registered trademarks of Sun Microsystems, Inc. </para> +<para>SuperH™ and Renesas™ are trademarks owned by Renesas Technology Corp.</para> +<para>Texas Instruments®, OMAP™ and Innovator™ are trademarks of Texas Instruments Incorporated.</para> +<para>Toshiba® is a registered trademark of the Toshiba Corporation.</para> +<para>UNIX® is a registered trademark of The Open Group. </para> +<para>All other brand and product names, trademarks, and copyrights are the +property of their respective owners. </para> + </legalnotice> + <legalnotice> +<title>Warranty</title> +<para>eCos and RedBoot are open source software, covered by a +modified version of the <ulink url="http://www.gnu.org/copyleft/gpl.html">GNU +General Public Licence</ulink>, +and you are welcome to change it and/or distribute copies of it under certain +conditions. See <ulink +url="http://ecos.sourceware.org/license-overview.html">http://ecos.sourceware.org/license-overview.html +</ulink> for more information about the license.</para> +<para>eCos and RedBoot software have NO WARRANTY. </para> +<para>Because this software is licensed free of charge, there are no warranties +for it, to the extent permitted by applicable law. Except when otherwise stated +in writing, the copyright holders and/or other parties provide the software +“as is” without warranty of any kind, either expressed or implied, +including, but not limited to, the implied warranties of merchantability and +fitness for a particular purpose. The entire risk as to the quality and performance +of the software is with you. Should the software prove defective, you assume +the cost of all necessary servicing, repair or correction.</para> +<para> In no event, unless required by applicable law or agreed to in writing, +will any copyright holder, or any other party who may modify and/or redistribute +the program as permitted above, be liable to you for damages, including any +general, special, incidental or consequential damages arising out of the use +or inability to use the program (including but not limited to loss of data +or data being rendered inaccurate or losses sustained by you or third parties +or a failure of the program to operate with any other programs), even if such +holder or other party has been advised of the possibility of such damages. +</para> + </legalnotice> + </bookinfo> +<toc id="ecos-toc"></toc> +EOF + +for i in `cat ${doclist}`; do + line="`echo $i | sed 's/#.*//;'`" + if (test ! -z $line); then + entityi="`echo $i | sed 's@\+@x@g; s@/@-@g; s@\.@-@g; s@_@-@g; s@-current-doc@@g; s@-current@@g'`" + # special kludge + if [ "`basename $i`" != "tcpip-manpages.sgml" -a \ + "`basename $i`" != "snmp-manpages.sgml" -a \ + "`basename $i`" != "libipsec.sgml" -a \ + "`basename $i`" != "libipsec-manpages.sgml" -a \ + "`basename $i`" != "openbsd-manpages-bridge.sgml" -a \ + "`basename $i`" != "openbsd-manpages-netintro.sgml" -a \ + "`basename $i`" != "openbsd-manpages-stp.sgml" -a \ + "`basename $i`" != "porting.sgml" ]; then + echo "&$entityi;" >> ecos-ref.sgml + fi + fi +done + +echo '</book>' >> ecos-ref.sgml diff --git a/ecos/doc/sgml/user-guide/.cvsignore b/ecos/doc/sgml/user-guide/.cvsignore new file mode 100644 index 0000000..0b84df0 --- /dev/null +++ b/ecos/doc/sgml/user-guide/.cvsignore @@ -0,0 +1 @@ +*.html
\ No newline at end of file diff --git a/ecos/doc/sgml/user-guide/ChangeLog b/ecos/doc/sgml/user-guide/ChangeLog new file mode 100644 index 0000000..0d7c317 --- /dev/null +++ b/ecos/doc/sgml/user-guide/ChangeLog @@ -0,0 +1,184 @@ +2011-08-25 John Dallaway <john@dallaway.org.uk> + + * target-setup.sgml: Add instructions for booting with GRUB2. + Patch from Stephen Polkowski. [ Bugzilla 1001254 ] + * user-guide.sgml: Update copyright dates. + +2010-02-17 John Dallaway <john@dallaway.org.uk> + + * introduction.sgml: Mention PPP, lwIP and uSTL. Mention + Cortex-M and FR30 architectural support. + * programming-concepts-techniques.sgml: Extend list of kernel + instrumention event classes. + * user-guide.sgml: Update copyright dates. + +2009-03-20 John Dallaway <john@dallaway.org.uk> + + * installation.sgml: Update supported host list to include + Microsoft Windows Vista. + +2004-06-15 Roland Cassebohn <Roland.Cassebohm@VisionSystems.de> + + * target-setup.sgml: + * real-time-characterization.sgml: + Added documentation for the aim711 module + +2003-10-17 Alex Schuilenburg <alex@schuilenburg.org> + * user-guide/installation.sgml: + * user-guide/introduction.sgml: + * user-guide/makefile: + * user-guide/target-setup.sgml: + Brought URLs up to date and amended header which was incaccurate + (referred to alternative licenses no longer available) + +2003-07-09 Jonathan Larmour <jifl@eCosCentric.com> + + * user-guide.sgml: Update trademark info and sort. + + * real-time-characterization.sgml: real-time characterization is + discussed in ref manual, not user guide. + +2003-05-04 John Dallaway <jld@ecoscentric.com> + + * installation.sgml: Refer to installation instructions on the + eCos website. + +2003-05-01 Jonathan Larmour <jifl@eCosCentric.com> + + * jadetex.cfg: Add this to configure PDF output nicely with index + and coloured links. + + * pix/*.gif: Delete as they are now unused. + * introduction.sgml: Add ID for notation and conventions chap. + +2003-03-03 John Dallaway <jld@ecoscentric.com> + + * programming-concepts-techniques.sgml: + PKG_INSTALL_DIR -> INSTALL_DIR + +2003-02-12 Nick Garnett <nickg@calivar.com> + + * user-guide.sgml: + * config-tool.sgml: + * configuration.sgml: + Files extensively modified to bring them up to date. Essentially + the old Tutorial document has been merged in with the User Guide + to give a single document from which to start with eCos. + + * introduction.sgml: + * installation.sgml: + * programming.sgml: + * programming-concepts-techniques.sgml: + * target-setup.sgml: + * real-time-characterization.sgml: + New files containing both fresh text and text merged in from the + old tutorial, which is now obsolete. + + * pix/templates01.png: + * pix/ARMStartup01.png: + * pix/build-lib01.png: + * pix/build-tests01.png: + * pix/twothreads2.png: + Graphics copied here from old tutorial. + + +2002-10-15 Iztok Zupet <iz@vsr.si> + + * user-guide.sgml: pictures (gif==>png) + * pix/*.png: generated from gifs with gimp + * makefile: defined MAIN_PDF + +2002-09-23 Andrew Lunn <andrew.lunn@ascom.ch> + + * .cvsignore: Ignore the generated html files. + +2002-02-26 Julian Smart <julians@redhat.com> + + * config-tool.sgml: updated further text and graphics + for Windows/Unix configtool. + +2002-02-15 Julian Smart <julians@redhat.com> + + * user-guide.sgml: added further GIF files + * config-tool.sgml: started to updated text and graphics + to encompass Windows and Linux tools. + +2002-02-07 Jonathan Larmour <jlarmour@redhat.com> + + * user-guide.sgml: Move special topics to kernel doc. + * special-topics.sgml: delete. + + * config-tool.sgml: Add ids to all <sect1>s and <chapter>s + * configuration.sgml: ditto. + * programming-concepts-techniques.sgml: ditto. + * special-topics.sgml: ditto. + +2001-12-21 Jonathan Larmour <jlarmour@redhat.com> + + * user-guide.sgml: Move pictures to pix/ subdirectory. + +2001-12-17 Mark Galassi <rosalia@galassi.org> + + * added legal stuff and contact information. + +2001-11-28 Jonathan Larmour <jlarmour@redhat.com> + + * configuration.sgml: Many cosmetic fixes, to bring the document in + line with the version on sources.redhat.com, including adding a little + missing content. + * config-tool.sgml: Ditto. + * programming-concepts-techniques.sgml: Ditto. + + * config-tool.sgml: Fix fig1 title. + +2001-11-23 Mark Galassi <rosalia@galassi.org> + + * configuration.sgml: took care of the <programlisting> tags. + +2001-11-21 Mark Galassi <rosalia@galassi.org> + + * programming-concepts-techniques.sgml: restored the two tables in + this part. + + * config-tool.sgml: reinstated the keyboard shortcut table. + + * config-tool.sgml, configuration.sgml, + programming-concepts-techniques.sgml, special-topics.sgml: the new + files with the individual parts. + + * user-guide.sgml: split each part into its own file to make + editing more manageable. + +2001-10-31 Mark Galassi <rosalia@galassi.org> + + * user-guide-not-normalized.sgml: this is the deprecated + original hand-edited file. + + * user-guide.sgml: this is now the normalized file and the active + one. + + * user-duide-normalized.sgml: removed this file. + + * user-guide.sgml: last change (update the DTD) before I replace + this had-edited version with the normalized one. + +2001-10-29 Mark Galassi <rosalia@galassi.org> + + * user-guide-normalized.sgml: put this in because it satisfies all + the little nitpicks on other systems. + +2001-10-21 Mark Galassi <rosalia@galassi.org> + + * user-guide.sgml: more fixes; the HTML seems quite correct. + + * *.gif: added all .gif files to CVS. + + * user-guide.sgml: validates!! + + * user-guide.sgml: 85% validates now. + +2001-10-20 Mark Galassi <rosalia@galassi.org> + + * user-guide.sgml: now into part III for the touch-up work. + + * user-guide.sgml: did more fixing up. diff --git a/ecos/doc/sgml/user-guide/config-tool.sgml b/ecos/doc/sgml/user-guide/config-tool.sgml new file mode 100755 index 0000000..8a400da --- /dev/null +++ b/ecos/doc/sgml/user-guide/config-tool.sgml @@ -0,0 +1,1518 @@ +<!-- {{{ Banner --> + +<!-- =============================================================== --> +<!-- --> +<!-- config-tool.sgml --> +<!-- --> +<!-- eCos User Guide --> +<!-- --> +<!-- =============================================================== --> +<!-- ####ECOSDOCCOPYRIGHTBEGIN#### --> +<!-- =============================================================== --> +<!-- Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002 Free Software Foundation, 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 --> +<!-- =============================================================== --> +<!-- ####ECOSDOCCOPYRIGHTEND#### --> +<!-- =============================================================== --> +<!-- #####DESCRIPTIONBEGIN#### --> +<!-- --> +<!-- ####DESCRIPTIONEND#### --> +<!-- =============================================================== --> + +<!-- }}} --> + +<part ID="THE-ECOS-CONFIGURATION-TOOL"> +<TITLE>The eCos Configuration Tool</TITLE> + +<!-- {{{ Getting Started --> + +<CHAPTER id="config-tool-getting-started"> +<TITLE>Getting Started</TITLE> + +<!-- ====================================================================== --> + +<SECT1 id="config-tool-getting-started-intro"> +<TITLE>Introduction</TITLE> + +<PARA> The <productname>eCos</productname> <application>Configuration Tool</application> is used + to tailor <productname>eCos</productname> at source level, prior to compilation or + assembly, and provides a configuration file and a set of + files used to build user applications. The sources and other + files used for building a configuration are provided in a + <EMPHASIS>component repository</EMPHASIS>, which is loaded + when the <productname>eCos</productname> <APPLICATION>Configuration Tool</APPLICATION> + is invoked. The component repository includes a set of files + defining the structure of relationships between the + <application>Configuration Tool</application> and other components, and is written in a + <FIRSTTERM>Component Definition Language</FIRSTTERM> (<ACRONYM>CDL</ACRONYM>). + For a description of the concepts underlying component + configuration, see <xref linkend="cdl-concepts">.</PARA> +</SECT1> + +<!-- ====================================================================== --> + +<SECT1 id="config-tool-invoking"> +<TITLE>Invoking the <productname>eCos</productname> <application>Configuration Tool</application></TITLE> + +<SECT2> +<TITLE>On Linux</TITLE> + +<PARA>Add the <productname>eCos</productname> <application>Configuration Tool</application> install directory to your PATH, for example:</PARA> + +<PROGRAMLISTING> +export PATH=/opt/ecos/ecos<replaceable>&Version;</replaceable>/bin:$PATH +</PROGRAMLISTING> + +<PARA>You may run configtool with zero, one or two arguments. You can specify the <productname>eCos</productname> repository + location, and/or an <productname>eCos</productname> save file (extension .ecc) on the command line. The ordering of these +two arguments is not significant. For example:</PARA> + +<PROGRAMLISTING> +configtool /opt/ecos/ecos<replaceable>&Version;</replaceable>/packages myfile.ecc +</PROGRAMLISTING> + +<PARA>The <application>Configuration Tool</application> will be displayed (see <xref linkend="figure-configuration-tool">).</PARA> +</SECT2> + +<SECT2> +<TITLE>On Windows</TITLE> + +<PARA>There are two ways in which to invoke the <productname>eCos</productname> <application>Configuration Tool</application>:</PARA> +<ITEMIZEDLIST> +<LISTITEM> +<PARA> from the desktop explorer or program set up at installation + time (by default + <EMPHASIS>Start</EMPHASIS> + -> + <EMPHASIS>Programs</EMPHASIS> + -> + <EMPHASIS>eCos</EMPHASIS> + -> + <EMPHASIS>Configuration Tool</EMPHASIS> + ).</PARA> +</LISTITEM> +<LISTITEM> +<PARA>type (at a command prompt or in the + <EMPHASIS>Start</EMPHASIS> + menu’s + <EMPHASIS>Run</EMPHASIS> + item): <foldername>\ConfigTool.exe where <foldername> is + the full path of the directory in which you installed the <productname>eCos</productname> + <application>Configuration Tool</application>.</PARA> +<!-- +<para> +XXXXX Change location of configtool in line with installation + instructions. XXXXX +</para> +--> + +</LISTITEM> +<LISTITEM> +<PARA>The + <application>Configuration Tool</application> + will be displayed (see <xref linkend="figure-configuration-tool">).</PARA> +</LISTITEM> +</ITEMIZEDLIST> + +<PARA> +You may run configtool with zero, one or two arguments. You can specify the <productname>eCos</productname> repository +location, and/or an <productname>eCos</productname> save file (extension .ecc) on the command line. The ordering of these +two arguments is not significant. For example:</PARA> + +<PROGRAMLISTING> +configtool "c:\Program Files\eCos\packages" myfile.ecc +</PROGRAMLISTING> + +<!-- + <para> +XXXXX Change location of eCos in line with installation instructions. XXXXX + </para> +--> + +<PARA>If you invoke the configuration tool from the command line with +<EMPHASIS>--help</EMPHASIS>, you will see this output:</PARA> + +<PROGRAMLISTING> +Usage: eCos Configuration Tool [-h] [-e] [-v] [-c] [input file 1] [input file 2] + -h --help displays help on the command line parameters + -e --edit-only edit save file only + -v --version print version + -c --compile-help compile online help only +</PROGRAMLISTING> + +<PARA>This summarizes valid parameters and switches. Switches are shown with +both short form and long form.</PARA> + +<PARA><EMPHASIS>--help</EMPHASIS> shows valid options and parameters, as above.</PARA> + +<PARA><EMPHASIS>--edit-only</EMPHASIS> runs the <application>Configuration Tool</application> in a mode that +suppresses creation of a build tree, in case you only want to create and edit save files.</PARA> + +<PARA><EMPHASIS>--version</EMPHASIS> shows version and build date information, and exits.</PARA> + +<PARA><EMPHASIS>--compile-help</EMPHASIS> compiles help contents files from the HTML documentation +files that the tool finds in the <productname>eCos</productname> repository, and exits.</PARA> + +<FIGURE id="figure-configuration-tool"> +<TITLE><application>Configuration Tool</application></TITLE> +<GRAPHIC ENTITYREF="graphic1"></GRAPHIC> +</FIGURE> +</SECT2> +</SECT1> + +<!-- ====================================================================== --> + + +<SECT1 id="config-tool-component-repository"> +<TITLE>The Component Repository</TITLE> +<PARA>When you invoke the <productname>eCos</productname> <application>Configuration Tool</application>, it accesses the Component + Repository, a read-only location of configuration + information. For an explanation of “Component + Repository” see <xref linkend="cdl-concepts">.</PARA> +<PARA>The <productname>eCos</productname> <application>Configuration Tool</application> will look + for a component repository using (in descending order of preference):</PARA> +<ITEMIZEDLIST> +<LISTITEM> +<PARA>A location specified on the command line +</PARA> +</LISTITEM> +<LISTITEM> +<PARA>The component repository most recently used by the +current user</PARA> +</LISTITEM> +<LISTITEM> +<PARA>An <productname>eCos</productname> distribution under <filename>/opt/ecos</filename> (under +Linux) or a default location set by the installation procedure (under +Windows)</PARA> +</LISTITEM> +<LISTITEM> +<PARA>User input</PARA> +</LISTITEM> +</ITEMIZEDLIST> +<PARA>The final case above will normally only occur if the previous + repository has been moved or (under Windows) installation information stored in + the Windows registry has been modified; it will result in a dialog box +being displayed that allows you to specify the repository location:</PARA> +<FIGURE> +<TITLE>Repository relocation dialog box</TITLE> +<GRAPHIC ENTITYREF="graphic2"></GRAPHIC> +</FIGURE> +<PARA>Note that in order to use the <productname>eCos</productname> <application>Configuration Tool</application> you are obliged to provide a + valid repository location. </PARA> +<PARA>In the rare event that you subsequently wish to change + the component location, select + <EMPHASIS>Build</EMPHASIS>-><EMPHASIS>Repository</EMPHASIS> + and the above dialog box will then be displayed.</PARA> +<PARA>You can check the location of the current repository, the current save file +path, and the current hardware template and default package, +by selecting <EMPHASIS>Help</EMPHASIS>-><EMPHASIS>Repository Information...</EMPHASIS>. +A summary will be displayed.</PARA> +</SECT1> + +<!-- ====================================================================== --> + + +<SECT1 ID="config-tool-documents"> +<TITLE><productname>eCos</productname> <application>Configuration Tool</application> Documents</TITLE> +<SECT2> +<TITLE>Configuration Save File</TITLE> +<PARA><productname>eCos</productname> configuration settings and other information + (such as disabled conflicts) that are set using the + <productname>eCos</productname> <application>Configuration Tool</application> are saved to + a file between sessions. By default, when the + <productname>eCos</productname> <application>Configuration Tool</application> is first + invoked, it reads and displays information from the + Component Registry and displays the information in an + untitled blank document. You can perform the following + operations on a document:</PARA> +<SECT3> +<TITLE>Save the currently active document</TITLE> +<PARA>Use the “<EMPHASIS>File->Save</EMPHASIS>” menu + item or click the <EMPHASIS>Save Document</EMPHASIS> icon on the + toolbar; if the current document is unnamed, you will be prompted + to supply a name for the configuration save file.</PARA> +<FIGURE> +<TITLE>Save As dialog box</TITLE> +<GRAPHIC ENTITYREF="graphic3"></GRAPHIC> +</FIGURE> +</SECT3> +<SECT3> +<TITLE>Open an existing document</TITLE> +<PARA>Select <EMPHASIS>File</EMPHASIS>-><EMPHASIS>Open</EMPHASIS>, + or click the <EMPHASIS>Open Document</EMPHASIS> icon on the toolbar. + You will be prompted to supply a name for the configuration save + file. </PARA> +<FIGURE> +<TITLE>Open dialog box</TITLE> +<GRAPHIC ENTITYREF="graphic4"></GRAPHIC> +</FIGURE> +</SECT3> +<SECT3> +<TITLE>Open a document you have used recently</TITLE> +<PARA>Click its name at the bottom of the + <EMPHASIS>File</EMPHASIS> menu. </PARA> +<PARA>Documents may also be opened by:</PARA> +<ITEMIZEDLIST> +<LISTITEM> +<PARA>double-clicking a Configuration Save File in the desktop +explorer (Windows only);</PARA> +</LISTITEM> +<LISTITEM> +<PARA>invoking the <productname>eCos</productname> +<application>Configuration Tool</application> +with the name of a Configuration File as command-line argument, +or by creating a shortcut to the <productname>eCos</productname> <application>Configuration Tool</application> with such an argument +(under Windows or a suitable Linux desktop environment).</PARA> +</LISTITEM> +</ITEMIZEDLIST> +</SECT3> +<SECT3> +<TITLE>Create a new blank document based on the Component + Registry</TITLE> +<PARA>Select <EMPHASIS>File</EMPHASIS>-><EMPHASIS>New</EMPHASIS>, +or click the <EMPHASIS>New Document</EMPHASIS> icon on the toolbar.</PARA> +</SECT3> +<SECT3> +<TITLE>Save to a different file name</TITLE> +<PARA>Select <EMPHASIS>File</EMPHASIS>-><EMPHASIS>Save + As</EMPHASIS>. You will be prompted to supply a new + name for the configuration save file.</PARA> +</SECT3> +</SECT2> +<SECT2> +<TITLE>Build and Install Trees</TITLE> +<PARA>The location of the build and install trees are + derived from the <productname>eCos</productname> save file name as illustrated in the + following example:</PARA> +<PARA>Save file name = “c:\My + eCos\config1.ecc”</PARA> +<PARA>Install tree folder = “c:\My + eCos\config1_install”</PARA> +<PARA>Build tree folder = “c:\My + eCos\config1_build”</PARA> +<PARA>These names are automatically generated from the name + of the save file.</PARA> +<PARA>See also <xref linkend="cdl-concepts">.</PARA> +</SECT2> +</SECT1> +</CHAPTER> + +<!-- }}} --> +<!-- {{{ Getting Help --> + +<CHAPTER id="config-tool-getting-help"> +<TITLE>Getting Help</TITLE> + +<PARA>The <productname>eCos</productname> <application>Configuration Tool</application> contains +several methods for accessing online help.</PARA> + +<!-- ================================================== --> + +<SECT1 id="config-tool-context-help-dialogs"> + +<TITLE>Context-sensitive Help for Dialogs</TITLE> +<PARA>Most dialogs displayed by the <productname>eCos</productname> <application>Configuration Tool</application> are supplied +with context-sensitive help. You can then get help relating +to any control within the current dialog box by</PARA> + +<ITEMIZEDLIST> +<LISTITEM> +<PARA>Right-clicking the control (or pressing + <EMPHASIS>F1</EMPHASIS> + )</PARA> +<PARA>A “What’s This?” popup menu will + be displayed. Click the menu to display a brief description of the + function of the selected control.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Clicking the question mark icon in the dialog + caption bar (Windows) or the question mark button on the dialog (Linux).</PARA> +<PARA>A question mark cursor will be displayed. Click on + any control to display a brief description of its + function.</PARA> +</LISTITEM> +</ITEMIZEDLIST> +<PARA>Some dialogs may have a <EMPHASIS>Help</EMPHASIS> + button. You can press this to display a more general + description of the function of the dialog box as a whole. + This help will be in HTML form; for more information, see + below.</PARA> +</SECT1> + +<!-- ================================================== --> + +<SECT1 id="config-tool-context-help-otherwin"> +<TITLE>Context-sensitive Help for Other Windows</TITLE> +<PARA>In the <EMPHASIS>Help</EMPHASIS> menu, click + <EMPHASIS>Help On...</EMPHASIS> +<!-- + (or press + <EMPHASIS>F1</EMPHASIS>) +--> +and then click on a window (or click on the arrow/question mark button +on the toolbar, then click on a window). A small popup window page describing the +window will be displayed. The same thing can be achieved by right-clicking +on a window and clicking on <EMPHASIS>What's This?</EMPHASIS>. +<!-- + This help will normally be in HTML format; for more + information, see <xref linkend="methods-of-displaying-html-help">. +--> +</PARA> +</SECT1> +<SECT1 id="config-tool-context-help-config-items"> +<TITLE>Context-sensitive Help for Configuration Items</TITLE> +<PARA>In the configuration window, right-click on a configuration +item (or use <EMPHASIS>Shift+F10</EMPHASIS>). A context +menu will be displayed; select <EMPHASIS>Visit Documentation</EMPHASIS> +to display the page in the <productname>eCos</productname> documentation that most closely +corresponds to the selected item.</PARA> +</SECT1> + +<SECT1 id="methods-of-displaying-html-help"> +<TITLE>Methods of Displaying HTML Help</TITLE> + +<ORDEREDLIST> + +<LISTITEM> +<PARA> +Using the internal help system. This will show an internal viewer similar to Microsoft HTML Help, with a contents +hierarchy on the left and HTML pages on the right; see <xref linkend="figure-help-viewer">. The index is regenerated for each repository. If the documentation in +the repository has changed but the contents does not reflect this, please use the Tools Regenerate Help Index menu +item. +</PARA> +</LISTITEM> + +<LISTITEM> +<PARA> +Using the default HTML browser. On Unix, you will need a .mailcap entry similar to this: +</PARA> + +<PARA> +<PROGRAMLISTING> +text/html; netscape -no-about-splash %s +</PROGRAMLISTING> +</PARA> +</LISTITEM> + +<LISTITEM> +<PARA> +Using the specified browser. +</PARA> +</LISTITEM> + +</ORDEREDLIST> + + +<FIGURE id="figure-help-viewer"> +<TITLE>HTML Help viewer</TITLE> +<GRAPHIC ENTITYREF="graphic5"></GRAPHIC> +</FIGURE> +<PARA>If you wish, you may choose to have <EMPHASIS>HTML Help</EMPHASIS> displayed +in a browser of your choice. To do this, select <EMPHASIS>View</EMPHASIS>-><EMPHASIS>Settings</EMPHASIS> and +use the controls in the View Documentation group to select the replacement browser. +Note that the Navigation facilities of the built-in <EMPHASIS>HTML +Help</EMPHASIS> system will be unavailable if you choose this method +of displaying help.</PARA> +</SECT1> +</CHAPTER> + +<!-- }}} --> +<!-- {{{ Customization --> + +<CHAPTER id="config-tool-customization"> +<TITLE>Customization</TITLE> +<PARA>The following visual aspects of the <productname>eCos</productname> <application>Configuration Tool</application> can be changed to suit + individual preferences. These aspects are saved on a per-user + basis, so that when the <productname>eCos</productname> <application>Configuration Tool</application> is next invoked by the same + user, the appearance will be as set in the previous + session.</PARA> +<SECT1 id="config-tool-window-placement"> +<TITLE>Window Placement</TITLE> +<PARA>The relative sizes of all windows in the <productname>eCos</productname> <application>Configuration Tool</application> may be adjusted by dragging + the splitter bars that separate the windows. The chosen + sizes will be used the next time the <productname>eCos</productname> <application>Configuration Tool</application> is invoked by the current + user. </PARA> +<PARA>All windows except the <EMPHASIS>Configuration + Window</EMPHASIS> may be shown or hidden by using the + commands under the <EMPHASIS>View</EMPHASIS> menu (for + example, <EMPHASIS>View->Output</EMPHASIS>) or the + corresponding keyboard accelerators + (<EMPHASIS>Alt+1</EMPHASIS> to + <EMPHASIS>Alt+4</EMPHASIS>). +<!-- +By default the +conflicts window is hidden. +--> +</PARA> +<PARA>Your chosen set of windows (and their relative sizes) will +be preserved between invocations of the <productname>eCos</productname> <application>Configuration +Tool</application>.</PARA> +</SECT1> +<!-- +<SECT1 id="config-tool-toolbars"> +<TITLE>Toolbars</TITLE> +<PARA>Select + <EMPHASIS>View</EMPHASIS>-><EMPHASIS>Toolbars</EMPHASIS>: + each of the standard and Memory Layout toolbars may be + hidden or shown.</PARA> +</SECT1> +--> +<SECT1 id="config-tool-settings"> +<TITLE>Settings</TITLE> +<PARA>To change other visual aspects, select + <EMPHASIS>View</EMPHASIS>-><EMPHASIS>Settings</EMPHASIS> + and then select the <EMPHASIS>Display</EMPHASIS> and + <EMPHASIS>View</EMPHASIS> tabs depending on the settings + you wish to alter.. + The options are as follows: +</PARA> + + +<SECT2> +<TITLE>Settings: Display tab</TITLE> + +<FIGURE> +<TITLE>Settings dialog, Display tab</TITLE> +<GRAPHIC ENTITYREF="graphic32"></GRAPHIC> +</FIGURE> + +<SECT3> +<TITLE>Labels</TITLE> + +<PARA>In the configuration window, you can choose to have + either <EMPHASIS>descriptive names</EMPHASIS> (the + default) or <EMPHASIS>macro names</EMPHASIS> displayed as + tree item labels. Descriptive names are generally more + comprehensible, but macro names are used in some contexts + such as conflict resolution and may be directly related to + the source code of the configuration. Note that it is + possible to search for an item in the configuration view + by selecting + <EMPHASIS>Find</EMPHASIS>-><EMPHASIS>Edit</EMPHASIS> + (see <xref linkend="config-tool-searching">). Both + descriptive names and macro names can be searched.</PARA> +</SECT3> + +<SECT3> +<TITLE>Integer Items</TITLE> +<PARA>You can choose to have integer items in the + Configuration Window displayed in decimal or hexadecimal + format.</PARA> +</SECT3> + +<SECT3> +<TITLE>Font</TITLE> + +<PARA> +Change the font for a particular window by selecting the window name using the drop-down list, +then clicking on <EMPHASIS>Change Font</EMPHASIS> to select a font for that +window. The changes will be applied when the press <EMPHASIS>OK</EMPHASIS> to dismiss the Settings dialog. +If you never make font changes, then the windows will take +the default setting determined by your current Windows or Unix environment. +</PARA> +</SECT3> + +<SECT3> +<TITLE>Miscellaneous</TITLE> + +<PARA> +If the <EMPHASIS>Splash Screen</EMPHASIS> checkbox is checked, a <EMPHASIS>splash</EMPHASIS> +window will appear as the application is loading. Uncheck this to eliminate the splash screen. +</PARA> + +</SECT3> +</SECT2> + +<SECT2> +<TITLE>Settings: Viewers tab</TITLE> + +<FIGURE> +<TITLE>Settings dialog, Viewers tab</TITLE> +<GRAPHIC ENTITYREF="graphic6"></GRAPHIC> +</FIGURE> + +<SECT3> +<TITLE>View header files</TITLE> + +<PARA>You can change the viewer used to display header files.</PARA> +</SECT3> + +<SECT3> +<TITLE>View documentation</TITLE> + +<PARA>You can change the viewer used to display HTML files. +See <xref linkend="methods-of-displaying-html-help">. +</PARA> + + + +</SECT3> + +</SECT2> + +</SECT1> +</CHAPTER> + +<!-- }}} --> +<!-- {{{ Screen Layout --> + +<CHAPTER id="config-tool-screen-layout"> +<TITLE>Screen Layout</TITLE> +<PARA>The following windows are available within the + <productname>eCos</productname> <application> Configuration + Tool</application>: + </PARA> +<ITEMIZEDLIST> +<LISTITEM> +<PARA> Configuration Window</PARA> +</LISTITEM> +<LISTITEM> +<PARA> Properties Window</PARA> +</LISTITEM> +<LISTITEM> +<PARA> Short Description</PARA> +</LISTITEM> +<LISTITEM> +<PARA> Conflicts</PARA> +</LISTITEM> +<LISTITEM> +<PARA> Output</PARA> +</LISTITEM> +</ITEMIZEDLIST> + +<PARA>The layout of the windows may be adjusted to suit your + preferences: see <xref linkend="config-tool-settings">.</PARA> + +<SECT1 id="config-tool-configuration-window"> +<TITLE>Configuration Window</TITLE> +<PARA>This is the principal window used to configure <productname>eCos</productname>. It + takes the form of a tree-based representation of the + configuration items within the currently loaded <productname>eCos</productname> + packages.</PARA> +<PARA>In the case of items whose values may be changed, + controls are available to set the item values. These either + take the form of check boxes or radio buttons within the + tree itself or cells to the right of the thin vertical + splitter bar. Controls in the tree may be used in the usual + way; cells, however, must first be activated.</PARA> +<PARA>To activate a cell, simply click on it: it will assume a sunken +appearance and data can then be edited in the cell. To terminate +in-cell editing, click elsewhere in the configuration window or +press <EMPHASIS>ENTER</EMPHASIS>. To discard the partial results +of in-cell editing and revert to the previous value, press <EMPHASIS>ESCAPE</EMPHASIS>. +<!-- Not yet implemented +Note that an asterisk appears against configuration items which have changed since the configuration +was last saved. +--> +</PARA> +<PARA><GRAPHIC ENTITYREF="graphic7"></GRAPHIC></PARA> +<PARA>Cells come in three varieties, according to the type of + data they accept:</PARA> +<TABLE> +<TITLE>Cell types</TITLE> +<TGROUP COLS="2"> +<THEAD> +<ROW> +<ENTRY>Cell Type</ENTRY> +<ENTRY><PARA>Data Accepted</PARA></ENTRY> +</ROW> +</THEAD> +<TBODY> +<ROW> +<ENTRY>Integer</ENTRY> +<ENTRY>Decimal or hexadecimal values</ENTRY> +</ROW> +<ROW> +<ENTRY>Floating Point</ENTRY> +<ENTRY>Floating point values</ENTRY> +</ROW> +<ROW> +<ENTRY>String</ENTRY> +<ENTRY>Any</ENTRY> +</ROW> +</TBODY> +</TGROUP> +</TABLE><!-- +<row> +<cell><normal>Integer</normal></cell><cell><normal>Decimal or hexadecimal +values</normal></cell></row> +<row> +<cell><normal>Floating Point</normal></cell><cell><normal>Floating +point values</normal></cell></row> +<row> +<cell><normal>String</normal></cell><cell><normal>Any</normal></cell></row> +</body></formata> +--> +<PARA>In the case of string cells, you can double-click the cell +to display a dialog box containing a larger region in which to edit +the string value. This is useful in the case of long strings, or +those spanning multiple lines.</PARA> +<SECT2> +<TITLE>Disabled items</TITLE> +<PARA>Some items will appear disabled. In this case the item + label and any associated controls and cells will be + grayed. It is not be possible to change the values of + disabled items.</PARA> +<SECT3> +<TITLE>Right-Clicking</TITLE> +<PARA>You can right-click on an item in the configuration + window item to display a pop-up menu which (depending on + the type of the item selected) allows you to:</PARA> +<ITEMIZEDLIST> +<LISTITEM> +<PARA> <EMPHASIS>Properties</EMPHASIS> – + information relating to the currently selected item + is displayed. The information is equivalent to that + displayed in the Properties + Window.</PARA> +</LISTITEM> +<LISTITEM> +<PARA> <EMPHASIS>Restore Defaults</EMPHASIS> - + the default value of the currently selected item is + restored.</PARA> +</LISTITEM> +<LISTITEM> +<PARA><EMPHASIS>Visit Documentation</EMPHASIS> + - causes the HTML page most closely relating to the + currently selected item to be displayed. This has + the same effect as double-clicking the URL property + in the Properties Window.</PARA> +</LISTITEM> +<LISTITEM> +<PARA> <EMPHASIS>View Header File</EMPHASIS> + – this causes the file containing the items to + be displayed. This is equivalent to double-clicking + on the File property in the Properties Window. The + viewer used for this purpose may be changed using + the <EMPHASIS>View->Settings</EMPHASIS> menu item + (see <xref linkend="config-tool-settings">). + Note that this operation is only possible when the + current configuration is saved, in order to avoid + the possibility of changing the source + repository.</PARA> +</LISTITEM> +<LISTITEM> +<PARA><EMPHASIS>Unload Package</EMPHASIS> - + this is equivalent to using the + <EMPHASIS>Build->Packages</EMPHASIS> menu item to + select and unload the package in + question.</PARA> +</LISTITEM> +</ITEMIZEDLIST> +</SECT3> +</SECT2> +<SECT2> +<TITLE>Conflicts Window</TITLE> +<PARA>This window exists to display any configuration item + conflicts. Conflicts are the result of failures to meet + the requirements between configuration items expressed in + the CDL. See <xref linkend="cdl-conflicts"> <!--in “CDL + Concepts” on page 45 -->.<GRAPHIC ENTITYREF="graphic8"></GRAPHIC></PARA> +<PARA>The window comprises three columns:</PARA> +<ITEMIZEDLIST> +<LISTITEM> +<PARA> <EMPHASIS>Item</EMPHASIS></PARA> +<PARA>This is the macro name of the first item involved + in the conflict.</PARA> +</LISTITEM> +<LISTITEM> +<PARA> + <EMPHASIS>Conflict</EMPHASIS></PARA> +<PARA>This is a description of the conflict type. The currently + supported types are “unresolved”, “illegal + value”, “evaluation exception”, “goal + unsatisfied” and “bad data”.</PARA> +</LISTITEM> +<LISTITEM> +<PARA> + <EMPHASIS>Property</EMPHASIS></PARA> +<PARA>This contains a description of the configuration + item’s property that caused the conflict.</PARA> +<PARA>Within the conflicts window you can right-click on + any item to display a context menu which allows you to + choose from one of the following options:</PARA> +</LISTITEM> +</ITEMIZEDLIST> + +<PARA>To locate the item involved in the +conflict, double-click in the first or third column, or +right-click over the item and choose <EMPHASIS>Locate</EMPHASIS> +from the popup menu. +</PARA> + +<PARA>You can use the <EMPHASIS>Tools->Resolve Conflicts</EMPHASIS> menu +item, or right-click over the item and select <EMPHASIS>Resolve</EMPHASIS> from the popup menu, +to resolve conflicts — <xref linkend="resolving-conflicts">.</PARA> +<SECT3> +<TITLE>Output Window</TITLE> +<PARA>This window displays any output generated by + execution of external tools and any error messages that + are not suitable for display in other forms (for + example, as message boxes).</PARA> +<PARA>Within the output window you can right-click to display a +context menu which allows you to:</PARA> +<ITEMIZEDLIST> +<LISTITEM> +<PARA>Save the contents of the window to a + file</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Clear the contents of the + window</PARA> +</LISTITEM> +</ITEMIZEDLIST> +</SECT3> +<SECT3> +<TITLE>Properties Window</TITLE> +<PARA>This window displays the CDL properties of the item + currently selected in the configuration window. The same + information may be displayed by right-clicking the item + and selecting “properties”.</PARA> +<PARA> <GRAPHIC ENTITYREF="graphic9"></GRAPHIC></PARA> +<PARA>Two properties may be double-clicked as + follows:</PARA> +<ITEMIZEDLIST> +<LISTITEM> +<PARA><EMPHASIS>URL</EMPHASIS> – + double-clicking on a URL property causes the + referenced HTML page to be displayed. This has the + same effect as right-clicking on the item and + choosing “Visit + Documentation”.</PARA> +</LISTITEM> +<LISTITEM> +<PARA><EMPHASIS>File</EMPHASIS> – + double-clicking on a File property in a saved + configuration causes the File to be displayed. The + viewer used for this purpose may be changed using + the <EMPHASIS>View->Settings</EMPHASIS> menu + item. Note that this operation is only possible when + the current configuration is saved, in order to + avoid the possibility of changing the source + repository.</PARA> +</LISTITEM> +</ITEMIZEDLIST> +</SECT3> +<SECT3> +<TITLE>Short Description Window</TITLE> +<PARA>This window displays a short description of the item + currently selected in the configuration window. More + extensive documentation may be available by + right-clicking on the item and choosing “Visit + Documentation”.</PARA> +</SECT3> +</SECT2> +</SECT1> +</CHAPTER> + +<!-- }}} --> +<!-- {{{ Updating and Configuration --> + +<CHAPTER id="config-tool-updating-configuration"> +<TITLE>Updating the Configuration</TITLE> +<SECT1 id="config-tool-adding-removing-packages"> +<TITLE>Adding and Removing Packages</TITLE> +<PARA>To add or remove packages from the configuration, select + <EMPHASIS>Build</EMPHASIS>-><EMPHASIS>Packages</EMPHASIS>.<!--<conditionaltext>--> + The following dialog box will be displayed:</PARA> +<FIGURE> +<TITLE>Packages dialog box</TITLE> +<GRAPHIC ENTITYREF="graphic14"></GRAPHIC> +</FIGURE> +<PARA>The left-hand list shows those packages that are available to + be loaded. The right-hand list shows those that are + currently loaded. In order to transfer packages from one + list to another (that is, to load or unload packages) + double-click the selection or click the + <EMPHASIS>Add</EMPHASIS> or <EMPHASIS>Remove</EMPHASIS> + buttons.</PARA> + +<PARA>The version drop-down list displays the versions of the + selected packages. When loading packages, this control may + be used to load versions other than the most recent + (current). Note that if more than one package is selected, + the version drop-down list will display only the versions + common to all the selected packages.</PARA> + +<PARA>The window under the version displays a brief + description of the selected package. If more than one + package is selected, this window will be blank.</PARA> + +<PARA> + Under the description window there is a <EMPHASIS>Keywords</EMPHASIS> +control into which you can type a string to be matched against +package names, macro names and descriptions. The lists are updated +a second or so after typing has stopped. +If you type several separate words, +all of these words must be associated with a given package +for that package to be displayed. If you select +the <EMPHASIS>Match exactly</EMPHASIS> checkbox, then the string +is taken to be a complete fragment and matched against the beginning +of a name, macro name or descriptions. All matches are done +case-insensitively.</PARA> + +<PARA> +If you check <EMPHASIS>Omit hardware packages</EMPHASIS>, only +non-hardware packages will be shown. +</PARA> + +</SECT1> +<SECT1 id="config-tool-platform-selection"> +<TITLE>Platform Selection</TITLE> +<PARA>To add, modify or remove entries in the list of + platforms used for running tests, select + <EMPHASIS>Tools->Platforms</EMPHASIS>. The following + dialog will be displayed:</PARA> +<FIGURE> +<TITLE>Platforms dialog box</TITLE> +<GRAPHIC ENTITYREF="graphic15"></GRAPHIC> +</FIGURE> +<PARA>You may add, modify or remove platform entries as you + wish, but in order to run tests, a platform must be defined + to correspond to the currently loaded hardware template. The + information associated with each platform name is used to + run tests.</PARA> +<PARA>To modify a platform, click the + <EMPHASIS>Modify</EMPHASIS> button with the appropriate + platform selected, or double-click on an entry in the list. + A dialog will be displayed that allows you to change the + command prefix, platform type and arguments for + <EMPHASIS>GDB</EMPHASIS>. </PARA> +<FIGURE> +<TITLE>Platform Modify dialog box</TITLE> +<GRAPHIC ENTITYREF="graphic16"></GRAPHIC> +</FIGURE> +<PARA>To add a new platform, click the + <EMPHASIS>Add</EMPHASIS> button. A similar dialog will be + displayed that allows you to define a new platform. To + remove a platform, click the <EMPHASIS>Delete</EMPHASIS> + button or press the <EMPHASIS>DEL</EMPHASIS> key with the + appropriate platform selected.</PARA> + +<PARA>The command prefix is used when running tests in order + to determine the names of the executables (such as gdb) to + be used. For example, if the gdb executable name is + “arm-elf-gdb.exe” the prefix should be set to + “arm-elf”.</PARA> +<PARA>The platform type indicates the capabilities of the platform +- whether it is hardware or a simulator, and whether breakpoints +are supported.</PARA> +<PARA>The arguments for the <EMPHASIS>GDB</EMPHASIS> field allow +additional arguments to be passed to gdb when it is used to run +a test. This is typically used in the case of simulators linked +to gdb in order to define memory layout.</PARA> +</SECT1> +<SECT1 id="config-tool-using-templates"> +<TITLE>Using Templates</TITLE> +<PARA>To load a configuration based on a template, select + <EMPHASIS>Build</EMPHASIS>-><EMPHASIS>Templates</EMPHASIS>.<!--<conditionaltext>--></PARA> +<PARA>The following dialog box will be displayed:</PARA> +<FIGURE> +<TITLE>Templates dialog box</TITLE> +<GRAPHIC ENTITYREF="graphic18"></GRAPHIC> +</FIGURE> +<PARA>Change the hardware template, the packages template, or + both. To select a hardware template, choose from the first + drop-list. To choose a packages template, choose from the + second. Brief descriptions of each kind of template are + provided in the corresponding edit boxes.</PARA> +<SECT2 id="resolving-conflicts"> +<TITLE>Resolving conflicts</TITLE> +<PARA>During the process of configuring <productname>eCos</productname> it is possible + that conflicts will be created. For more details of the + meaning of conflicts, see <xref linkend="cdl-concepts">.</PARA> +<PARA>The Conflicts Window displays all conflicts in the + current configuration. Additionally, a window in the + status bar displays a count of the conflicts. Because the + resolution of conflicts can be time-consuming, a mechanism + exists whereby conflicts can be resolved + automatically.</PARA> +<PARA>You can choose to have a conflicts resolution dialog + box displayed by means of the <EMPHASIS>View->Settings... + <!--<conditionaltext>--></EMPHASIS>menu item, on the <EMPHASIS>Conflict Resolution</EMPHASIS> +tab of the dialog.</PARA> +<FIGURE> +<TITLE>Options</TITLE> +<GRAPHIC ENTITYREF="graphic19"></GRAPHIC> +</FIGURE> +<PARA>You can choose to have conflicts checked under the + following circumstances:</PARA> +<ITEMIZEDLIST> +<LISTITEM> +<PARA>After any item is changed (in other words, + as soon as the conflict is created)</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Before saving the configuration (including + building)</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Never</PARA> +</LISTITEM> +</ITEMIZEDLIST> +<PARA>The method you chose depends on how much you need + your configuration to be free of conflicts. You may + want to avoid having to clean up all the conflicts at + once, or you may want to keep the configuration + consistent at all times. If you have major changes to + implement, which may resolve the conflicts, then you + might want to wait until after you have completed + these changes before you check for conflicts.</PARA> +<!-- <label>NOTE</label> --> +<NOTE> +<PARA>If you choose to check conflicts after any item + is changed, only newly arising conflicts are displayed. + If you choose to check for conflicts before saving the + configuration, the complete set is + displayed.</PARA> +</NOTE> +</SECT2> +<SECT2> +<TITLE>Automatic resolution</TITLE> +<PARA>If you check the “Automatically suggest + fixes” check box, a conflicts resolution dialog box + will be displayed whenever new conflicts are created. The + same dialog box may be displayed at any stage by means of + the <EMPHASIS>Tools->Resolve Conflicts</EMPHASIS> + <EMPHASIS><!--<conditionaltext>--></EMPHASIS>menu item. + </PARA> +<PARA>The conflicts resolution dialog box contains two major windows. </PARA> +<FIGURE> +<TITLE>Resolve conflicts window</TITLE> +<GRAPHIC ENTITYREF="graphic20"></GRAPHIC> +</FIGURE> +<PARA>The upper contains the set of conflicts to be addressed; the +format of the data being as that of the Conflicts Window. The lower +window contains a set of proposed resolutions – each entry +is a suggested configuration item value change that as a whole may +be expected to lead to the currently selected conflict being resolved. </PARA> +<PARA>Note that there is no guarantee:</PARA> +<ITEMIZEDLIST> +<LISTITEM> +<PARA>that automatic resolutions will be determinable for every +conflict.</PARA> +</LISTITEM> +<LISTITEM> +<PARA> that the resolutions for separate conflicts will be independent. +In other words, the resolution of one conflict may serve to prevent +the resolution of another.</PARA> +</LISTITEM> +<LISTITEM> +<PARA> that the resolution conflicts will not create further +conflicts.</PARA> +</LISTITEM> +</ITEMIZEDLIST> +<PARA>The above warnings are, however, conservative. In practice +(so long as the number and extent of conflicts are limited) automatic +conflict resolution may be used to good effect to correct problems +without undue amounts of programmer intervention.</PARA> +<PARA>In order to select the conflicts to be applied, select or +clear the check boxes against the resolutions for each proposed +resolution. By default all resolutions are selected; you can return +to the default state (in other words, cause all check boxes for +each conflict to again become checked) by pressing the “Reset” button. +Note that multiple selection may be used in the resolutions control +to allow ranges of check boxes to be toggled in one gesture.</PARA> +<PARA>When you are happy to apply the selected resolutions for each +conflict displayed, click <EMPHASIS>Apply</EMPHASIS>; this will +apply the resolutions. Alternatively you may cancel from the dialog +box without any resolutions being applied.</PARA> +</SECT2> +</SECT1> +</CHAPTER> + +<!-- }}} --> +<!-- {{{ Searching --> + +<CHAPTER id="config-tool-searching"> +<TITLE>Searching</TITLE> +<PARA>Select <EMPHASIS>Edit </EMPHASIS>--> <EMPHASIS>Find</EMPHASIS>. +You will be presented with a Find dialog box:</PARA> +<FIGURE> +<TITLE>Find dialog box</TITLE> +<GRAPHIC ENTITYREF="graphic21"></GRAPHIC> +</FIGURE> +<PARA>Using this dialog box you can search for an exact text string +in any one of three ways, as specified by your selection in the “Search +in” drop-list:</PARA> +<ITEMIZEDLIST> +<LISTITEM> +<PARA>Macro names - the search is for a text match within +configuration item macro names</PARA> +</LISTITEM> +<LISTITEM> +<PARA> Item names - the search is for a text match within +configuration item descriptive names</PARA> +</LISTITEM> +<LISTITEM> +<PARA> Short descriptions - the search is for a text match +within configuration item short descriptions</PARA> +</LISTITEM> +</ITEMIZEDLIST> +<PARA>Note that to invoke <EMPHASIS>Find</EMPHASIS> you can also +click the <EMPHASIS>Find</EMPHASIS> icon on the toolbar. </PARA> +</CHAPTER> + +<!-- }}} --> +<!-- {{{ Building --> + +<CHAPTER id="config-tool-building"> +<TITLE>Building</TITLE> +<PARA>When you have configured <productname>eCos</productname>, you may build the configuration.</PARA> +<PARA><!--<conditionaltext>-->On the <EMPHASIS>Build</EMPHASIS> menu, click:</PARA> +<ITEMIZEDLIST> +<LISTITEM> +<PARA> +<EMPHASIS>Library</EMPHASIS> + (or click the Build Library icon on the toolbar) – this +causes the <productname>eCos</productname> configuration to be built. The result of a successful +build will be (among other things) a library against which user +code can be linked</PARA> +</LISTITEM> +<LISTITEM> +<PARA> +<EMPHASIS>Tests</EMPHASIS> + – this causes the <productname>eCos</productname> configuration to be built, and +additionally builds the relevant test cases linked against the <productname>eCos</productname> library</PARA> +</LISTITEM> +<LISTITEM> +<PARA> +<EMPHASIS>Clean</EMPHASIS> + – this removes all intermediate files, thus causing a +subsequent build/library or build/tests operation +to cause recompilation of all relevant files.</PARA> +</LISTITEM> +<LISTITEM> +<PARA> +<EMPHASIS>Stop</EMPHASIS> + – this causes a currently executing build (any of the +above steps) to be interrupted</PARA> +</LISTITEM> +</ITEMIZEDLIST> +<PARA>Build options may be displayed by using the <EMPHASIS>Build->Options</EMPHASIS> menu +item. This displays a dialog box containing a drop-list control +and two windows. The drop-list control allows you to select the +type of build option to be displayed (for example “LDFLAGS” are +the options applied at link-time. The left-hand window is a tree +view of the packages loaded in the current configuration. The right-hand +window is a list of the build options that will be used for the +currently selected package.</PARA> +<PARA>Note that this dialog box currently affords only read-only +access to the build options. In order to change build options you +must edit the relevant string configuration item.</PARA> +<PARA>A single level of inheritance is supported: each package’s +build options are combined with the global options (these are to +be found in the “Global build options” folder +in the configuration view).</PARA> +<PARA><GRAPHIC ENTITYREF="graphic22"></GRAPHIC></PARA> +<SECT1 id="config-tool-selecting-build-tools"> +<TITLE>Selecting Build Tools</TITLE> +<PARA>Normally the installation process will supply the information +required for the <productname>eCos</productname><APPLICATION>Configuration Tool</APPLICATION> to +locate the build tools (compiler, linker, etc.) necessary +to perform a build. However if this information is not registered, +or it is necessary to specify the location manually (for example, +when a new toolchain installation has been made), select <EMPHASIS>Tools</EMPHASIS>-><EMPHASIS>Paths</EMPHASIS>-><EMPHASIS>Build +Tools</EMPHASIS>. The following dialog box will be displayed:</PARA> +<FIGURE> +<TITLE>Build tools</TITLE> +<GRAPHIC ENTITYREF="graphic23"></GRAPHIC> +</FIGURE> +<PARA>This dialog box allows you to locate the folder containing +the build tools. </PARA> +</SECT1> +<SECT1 id="config-tool-selecting-user-tools"> +<TITLE>Selecting User Tools</TITLE> +<PARA>Normally the installation process will supply the information +required for the <productname>eCos</productname><APPLICATION>Configuration Tool</APPLICATION> to +locate the user tools (cat, ls, etc.) necessary to perform +a build. However if this information is not registered, or it is +necessary to specify the location manually (for example, when a +new toolchain installation has been made), select <EMPHASIS>Tools</EMPHASIS>-><EMPHASIS>Paths</EMPHASIS>-><EMPHASIS>User +Tools</EMPHASIS>. The following dialog box will be displayed:</PARA> +<FIGURE> +<TITLE>User tools</TITLE> +<GRAPHIC ENTITYREF="graphic24"></GRAPHIC> +</FIGURE> +</SECT1> +</CHAPTER> + +<!-- }}} --> +<!-- {{{ Execution --> + +<CHAPTER id="config-tool-test-execution"><!--<conditionaltext>--> +<TITLE>Execution</TITLE> +<PARA>Test executables that have been linked using the Build/Tests +operation against the current configuration can be executed by selecting <!--<conditionaltext>--><EMPHASIS>Tools</EMPHASIS>-><EMPHASIS>Run +Tests<!--<conditionaltext>--></EMPHASIS>.</PARA> +<PARA>When tests are run, the <application>Configuration Tool</application> looks +for a platform name corresponding to the currently loaded hardware template. +If no such platform is found, a dialog will be displayed for you +to define one; this dialog is similar to that displayed by the <EMPHASIS>Add</EMPHASIS> function +in the <EMPHASIS>Tools->Platforms</EMPHASIS> dialog, but +in this case the platform name cannot be changed.</PARA> +<PARA>When a test run is invoked, a property sheet is displayed, +comprising three tabs: <EMPHASIS>Executables</EMPHASIS>, <EMPHASIS>Output</EMPHASIS> and <EMPHASIS>Summary</EMPHASIS>.</PARA> +<PARA>Note that the property sheet is resizable.</PARA> +<PARA>Three buttons appear on the property sheet itself: <EMPHASIS>Run/Stop</EMPHASIS>, <EMPHASIS>Close</EMPHASIS> and <EMPHASIS>Properties</EMPHASIS>.</PARA> +<PARA>The <EMPHASIS>Run</EMPHASIS> button is used to initiate a +test run. Those tests selected on the <EMPHASIS>Executables</EMPHASIS> tab +are run, and the output recorded on the <EMPHASIS>Output</EMPHASIS> and <EMPHASIS>Summary</EMPHASIS> tabs. +During the course of a run, the <EMPHASIS>Run</EMPHASIS> button +changes to “Stop”. The button may be used to interrupt +a test run at any point.</PARA> +<SECT1 id="config-tool-test-properties"> +<TITLE>Properties</TITLE> +<PARA>The <EMPHASIS>Properties</EMPHASIS> button is used to change +the connectivity properties for the test run.</PARA> +<FIGURE> +<TITLE>Properties dialog box</TITLE> +<GRAPHIC ENTITYREF="graphic25"></GRAPHIC> +</FIGURE> +<SECT2> +<TITLE>Download Timeout</TITLE> +<PARA> This group of controls serves to set the maximum time that + is allowed for downloading a test to the target board. If + the time is exceeded, the test will be deemed to have + failed for reason of “Download Timeout” and + the execution of that particular test will be abandoned. + This option only applies to tests run on hardware, not to + those executed in a simulator. Times are in units of + elapsed seconds.</PARA> +<PARA>Three options are available using the drop-down + list:</PARA> +<ITEMIZEDLIST> +<LISTITEM> +<PARA>Calculated from file size - an estimate of the maximum +time required for download is made using the (stripped) executable +size and the currently used baud rate</PARA> +</LISTITEM> +<LISTITEM> +<PARA> Specified - a user-specified value may be entered in +the adjacent edit box</PARA> +</LISTITEM> +<LISTITEM> +<PARA> None - no maximum download time is to be applied.</PARA> +</LISTITEM> +</ITEMIZEDLIST> +</SECT2> +<SECT2> +<TITLE>Run time Timeout</TITLE> +<PARA>This group of controls serves to set the maximum time + that is allowed for executing a test on the target board + or in a simulator. If the time is exceeded, the test will + be deemed to have failed for reason of + “Timeout” and the execution of that particular + test will be abandoned. In the case of hardware, the time + is measured in elapsed seconds: in the case of a simulator + it is in CPU seconds.</PARA> +<PARA>Three options are available using the drop-down + list:</PARA> +<ITEMIZEDLIST> +<LISTITEM> +<PARA>None - no maximum download time is to be + applied.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Specified - a user-specified value may be + entered in the adjacent edit box</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Default - a default value of 30 seconds is + used</PARA> +</LISTITEM> +</ITEMIZEDLIST> +</SECT2> +<SECT2> +<TITLE>Connection</TITLE> +<PARA>The <EMPHASIS>Connection</EMPHASIS> controls may be used + to specify how the target board is to be accessed.</PARA> + +<PARA>If the target board is connected using a serial cable, the <EMPHASIS>Serial</EMPHASIS> radio +button should be checked. In this case you can select a port (COM1, +COM2, …) and an appropriate baud rate using drop-list boxes.</PARA> +<PARA>If the target board is accessed remotely using GDB remote +protocol, the “TCP/IP” radio button should +be checked. In this case you can select a host name and TCP/IP port +number using edit boxes.</PARA> +</SECT2> +<SECT2> +<TITLE>Executables Tab</TITLE> +<PARA>This is used to adjust the set of tests available for execution. +A check box against each executable name indicates whether that +executable will be included when the <EMPHASIS>Run</EMPHASIS> button +is pressed. The <EMPHASIS>Check All</EMPHASIS> and <EMPHASIS>Uncheck +All</EMPHASIS> buttons may be used to check or uncheck all items.</PARA> +<PARA>When the property sheet is first displayed, it will be pre-populated +with those test executables that have been linked using the Build/Tests +operation against the current configuration. </PARA> +<FIGURE> +<TITLE>Run tests </TITLE> +<GRAPHIC ENTITYREF="graphic27"></GRAPHIC> +</FIGURE> +<PARA>You can right-click in the window to display a context menu +containing <EMPHASIS>Add</EMPHASIS> and <EMPHASIS>Remove</EMPHASIS> items. +Clicking <EMPHASIS>Remove</EMPHASIS> will remove those executables +selected. Clicking <EMPHASIS>Add</EMPHASIS> will display a dialog +box that allows you to add to the set of items. Equivalently the <EMPHASIS>Add</EMPHASIS> button +may be used to add executables, and the <EMPHASIS>DEL</EMPHASIS> key +may be used to remove them.</PARA> +<PARA>You can use the <EMPHASIS>Add from Folder</EMPHASIS> button +to add a number of executables in a specified folder (optionally +including subfolders, if you click on <EMPHASIS>Yes</EMPHASIS> when +asked).</PARA> +<FIGURE> +<TITLE>Add files from folder </TITLE> +<GRAPHIC ENTITYREF="graphic28"></GRAPHIC> +</FIGURE> + +<!-- +<PARA>The “Add from subfolders” check box should +be checked if you wish the search for executables to descend into +subfolders (in the example above the whole of the C drive would +be searched).</PARA> + +<PARA>The “Files of type” edit box should be used +to specify the extension of those files to be matched [for +example, “*.exe”].</PARA> +--> +</SECT2> +<SECT2> +<TITLE>Output Tab</TITLE> +<PARA>This tab is used to display the output from running tests. +The output can be saved to a file or cleared by means of the popup +menu displayed when you right-click in the window.</PARA> +</SECT2> +<SECT2> +<TITLE>Summary Tab</TITLE> +<PARA>This tab is used to display a record, in summary form, of +those tests executed. For each execution, the following information +is displayed:</PARA> +<ITEMIZEDLIST> +<LISTITEM> +<PARA> <EMPHASIS>Time</EMPHASIS> - the date and time of execution</PARA> +</LISTITEM> +<LISTITEM> +<PARA> <EMPHASIS>Host</EMPHASIS> - the host name of the machine +from which the test was downloaded</PARA> +</LISTITEM> +<LISTITEM> +<PARA> <EMPHASIS>Platform</EMPHASIS> - the platform on which +the test was executed</PARA> +</LISTITEM> +<LISTITEM> +<PARA> <EMPHASIS>Executable</EMPHASIS> - the executable (file +name) of the test executed</PARA> +</LISTITEM> +<LISTITEM> +<PARA> <EMPHASIS>Status</EMPHASIS> - the result of executing +the test. This will be one of the following:</PARA> +</LISTITEM> +<LISTITEM> +<PARA> Not started</PARA> +</LISTITEM> +<LISTITEM> +<PARA>No result</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Inapplicable</PARA> +</LISTITEM> +<LISTITEM> +<PARA> Pass</PARA> +</LISTITEM> +<LISTITEM> +<PARA>DTimeout</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Timeout</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Cancelled</PARA> +</LISTITEM> +<LISTITEM> +<PARA> Fail</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Assert fail</PARA> +</LISTITEM> +<LISTITEM> +<PARA> <EMPHASIS>Size</EMPHASIS> - the size [stripped/unstripped] of +the test executed</PARA> +</LISTITEM> +<LISTITEM> +<PARA> <EMPHASIS>Download</EMPHASIS> - the download time [mm:ss/mm:ss] used. +The first of the two times displayed represents the actual time +used: the second the limit time.</PARA> +</LISTITEM> +<LISTITEM> +<PARA> <EMPHASIS>Elapsed</EMPHASIS> - the elapsed time [mm:ss] used.</PARA> +</LISTITEM> +<LISTITEM> +<PARA> <EMPHASIS>Execution</EMPHASIS> - the execution time + [mm:ss/mm:ss] used. The first of the +two times displayed represents the actual time used: the second +the limit time.</PARA> +</LISTITEM> +</ITEMIZEDLIST> +<PARA>The output can be saved to a file or cleared by means of the +popup menu displayed when you right-click in the window.</PARA> +</SECT2> +</SECT1> +</CHAPTER> + +<!-- }}} --> +<!-- {{{ Creating a Shell --> + +<CHAPTER id="config-tool-creating-a-shell"> +<TITLE>Creating a Shell</TITLE> +<PARA>To call up a shell window, select <EMPHASIS>Tools</EMPHASIS>-><EMPHASIS>Shell</EMPHASIS>. +Under Windows, you will get a Cygwin shell similar to the one below. On Linux, you will +get a standard Linux shell window.</PARA> +<GRAPHIC ENTITYREF="graphic29"></GRAPHIC> +<SECT1 id="config-tool-keyboard-accelerators"> +<TITLE>Keyboard Accelerators</TITLE> +<PARA>The following table presents the list of keyboard accelerators +that can be used with the <application>Configuration Tool</application>. </PARA> + +<table id="keyboard-accelerators"><title>Keyboard accelerators</title> +<tgroup cols="2"> + <thead> + <row> + <entry>Accelerator</entry> + <entry>Action</entry> + <entry>Remarks</entry> + </row> + </thead> +<tbody> + +<row> +<entry><emphasis>Alt+1</emphasis></entry> +<entry>hide/show properties window</entry> +<entry></entry> +</row> + +<row> +<entry><emphasis>Alt+2</emphasis></entry> +<entry>hide/show output window</entry> +<entry></entry></row> + +<row> +<entry><emphasis>Alt+3</emphasis></entry> +<entry>hide/show short description window</entry> +<entry></entry></row> + +<row> +<entry><emphasis>Alt+4</emphasis></entry> +<entry>hide/show conflicts window</entry> +<entry></entry> +</row> + +<row> +<entry><emphasis>Ctrl+A</emphasis></entry> +<entry>select all</entry><entry>output +window and in-cell editing</entry></row> +<row> +<entry><emphasis>Ctrl+C</emphasis></entry> +<entry>copy</entry><entry>output window +and in-cell editing</entry></row> +<row> +<entry><emphasis>Ctrl+F</emphasis></entry> +<entry>Edit->Find</entry><entry></entry></row> +<row> +<entry><emphasis>Ctrl+N</emphasis></entry> +<entry>File->New</entry><entry></entry></row> +<row> +<entry><emphasis>Ctrl+O</emphasis></entry> +<entry>File->Open</entry><entry></entry></row> +<row> +<entry><emphasis>Ctrl+S</emphasis></entry> +<entry>File->Save</entry><entry></entry></row> +<row> +<entry><emphasis>Ctrl+V</emphasis></entry> +<entry>Paste</entry><entry>in-cell editing +only</entry></row> +<row> +<entry><emphasis>Ctrl+X</emphasis></entry> +<entry>Cut</entry><entry>in-cell-editing +only</entry></row> +<row> +<entry><emphasis>Ctrl+Z</emphasis></entry> +<entry>Undo</entry><entry>in-cell editing +only</entry></row> +<row> +<entry><emphasis>F1</emphasis></entry> +<entry>Context-sensitive help</entry><entry></entry></row> +<row> +<entry><emphasis>F3</emphasis></entry> +<entry>Find next</entry><entry></entry></row> +<row> +<entry><emphasis>F7</emphasis></entry> +<entry>Build->Library</entry><entry></entry></row> +<row> +<entry><emphasis>Shift+F7</emphasis></entry> +<entry>Build->Tests</entry><entry></entry></row> +<row> +<entry><emphasis>Alt+F6</emphasis></entry> +<entry>View->Next window</entry> +<entry></entry></row> +<row> +<entry><emphasis>Shift+Alt+0</emphasis></entry> +<entry>View->Previous window</entry> +<entry></entry></row> +<row> +<entry><emphasis>Shift+Ins</emphasis></entry> +<entry>Paste</entry><entry>in-cell editing +only</entry></row> +<row> +<entry><emphasis>Shift+F10</emphasis></entry> +<entry>Display context menu</entry><entry>Configuration +window</entry></row> +<row> +<entry><emphasis>Alt+Enter</emphasis></entry> +<entry>Display properties dialog box</entry> +<entry>Configuration window</entry></row> +<row> +<entry><emphasis>></emphasis></entry> +<entry>Increment item value</entry><entry>Configuration +window</entry></row> +<row> +<entry><</entry><entry>Decrement +item value</entry><entry>Configuration window</entry></row> +<row> +<entry><emphasis>Space</emphasis></entry> +<entry>Toggle item value</entry><entry>Configuration +window</entry></row> + </tbody> + </tgroup> + </table> + +</SECT1> +</CHAPTER> + +<!-- }}} --> + + +</PART> +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:nil +sgml-shorttag:t +sgml-namecase-general:t +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:2 +sgml-indent-data:t +sgml-parent-document:("user-guide.sgml" "book" "part") +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> diff --git a/ecos/doc/sgml/user-guide/configuration.sgml b/ecos/doc/sgml/user-guide/configuration.sgml new file mode 100644 index 0000000..c06fa89 --- /dev/null +++ b/ecos/doc/sgml/user-guide/configuration.sgml @@ -0,0 +1,2021 @@ +<!-- {{{ Banner --> + +<!-- =============================================================== --> +<!-- --> +<!-- configuration.sgml --> +<!-- --> +<!-- eCos User Guide --> +<!-- --> +<!-- =============================================================== --> +<!-- ####ECOSDOCCOPYRIGHTBEGIN#### --> +<!-- =============================================================== --> +<!-- Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002 Free Software Foundation, 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 --> +<!-- =============================================================== --> +<!-- ####ECOSDOCCOPYRIGHTEND#### --> +<!-- =============================================================== --> +<!-- #####DESCRIPTIONBEGIN#### --> +<!-- --> +<!-- ####DESCRIPTIONEND#### --> +<!-- =============================================================== --> + +<!-- }}} --> + +<PART id="configuration-and-the-package-repository"> +<TITLE>Configuration and the Package Repository</TITLE> +<PARTINTRO> +<PARA>The following chapters contain information on running + <COMMAND>ecosconfig</COMMAND> (the command line tool that + manipulates configurations and constructs build trees) and on + managing a source repository across multiple versions of + <productname>eCos</productname>. </PARA> +</PARTINTRO> +<CHAPTER id="manual-configuration"> +<TITLE>Manual Configuration</TITLE> + + <PARA><productname>eCos</productname> developers will generally use the graphical + Configuration Tool for configuring an <productname>eCos</productname> system and building + the target library. However, some user prefer to use command + line tools. These command line tools can also be used for batch + operations on all platforms, for example as part of a nightly + rebuild and testing procedure. + </PARA> + +<PARA>In the current release of the system the command line tools + do not provide exactly the same functionality as the graphical + tool. Most importantly, there is no facility to resolve + configuration conflicts interactively.</PARA> +<PARA>The <productname>eCos</productname> configuration system, both graphical and command + line tools, are under constant development and enhancement. + Developers should note that the procedures described may change + considerably in future releases. </PARA> + +<SECT1 id="directory-tree-structure"> +<TITLE>Directory Tree Structure</TITLE> +<PARA>When building <productname>eCos</productname> there are three main directory trees to + consider: the source tree, the build tree, and the install + tree.</PARA> +<PARA>The source tree, also known as the component repository, + is read-only. It is possible to use a single component + repository for any number of different configurations, and + it is also possible to share a component repository between + multiple users by putting it on a network drive.</PARA> +<PARA>The build tree contains everything that is specific to a + particular configuration, including header and other files + that contain configuration data, and the object files that + result from compiling the system sources for this + configuration. </PARA> +<PARA>The install tree is usually located in the <filename>install</filename> subdirectory +of the build tree. Once an <productname>eCos</productname> system has been built, the install +tree contains all the files needed for application development including +the header files and the target library. By making copies of the +install tree after a build it is possible to separate application +development and system configuration, which may be desirable for +some organizations. </PARA> +</SECT1> + +<SECT1 id="creating-build-tree"> +<TITLE>Creating the Build Tree</TITLE> +<PARA>Generating a build tree is a non-trivial operation and + should not be attempted manually. Instead, <productname>eCos</productname> is shipped + with a tool called <COMMAND>ecosconfig</COMMAND> that should + be used to create a build tree.</PARA> +<PARA>Usually <command>ecosconfig</command> will be +run inside the build tree itself. If you are creating a new build +tree then typically you will create a new empty directory using +the <command>mkdir</command> command, <command>cd</command> into +that directory, and then invoke <command>ecosconfig</command> to +create a configuration. By default, the configuration is stored +in a file <filename>ecos.ecc</filename> in the current +directory. The configuration may be modified by editing this file directly. <command>ecosconfig</command> itself +deals with a number of coarse-grained configuration options such +as the target platform and the packages that should be used.</PARA> +<PARA>The <command>ecosconfig</command> tool is also +used subsequently to generate a build tree for a configuration. +Once a build tree exists, it is possible to run <command>ecosconfig</command> again +inside the same build tree. This will be necessary if your wish +to change some of the configuration options.</PARA> +<PARA><COMMAND>ecosconfig</COMMAND> does not generate +the top-level directory of the build tree; you must do this + yourself. </PARA> +<SCREEN>$ mkdir ecos-work +$ cd ecos-work</SCREEN> +<PARA>The next step is to run <COMMAND>ecosconfig</COMMAND>: </PARA> +<SCREEN>$ ecosconfig <qualifiers> <command></SCREEN> +<SECT2> +<TITLE>ecosconfig qualifiers</TITLE> +<PARA>The available command line qualifiers for + <COMMAND>ecosconfig</COMMAND> are as follows. Multiple + qualifiers may be used on the command line: + </PARA> +<VARIABLELIST> +<VARLISTENTRY> +<TERM><OPTION>--help</OPTION></TERM> +<LISTITEM> +<PARA>Provides basic usage guidelines for the + available commands and qualifiers.</PARA> +</LISTITEM> +</VARLISTENTRY> +<VARLISTENTRY> +<TERM><OPTION>--config=<file></OPTION></TERM> +<LISTITEM> +<PARA>Specifies an <productname>eCos</productname> configuration save file for + use by the tool. By default, the file + <filename>ecos.ecc</filename> in the + current directory is used. Developers may prefer to + use a common location for all their <productname>eCos</productname> + configurations rather than keep the configuration + information in the base of the build tree.</PARA> +</LISTITEM> +</VARLISTENTRY> +<VARLISTENTRY> +<TERM><OPTION>--prefix=<dir></OPTION></TERM> +<LISTITEM> +<PARA>Specifies an alternative location for the + install tree. By default, the install tree resides + inside the <filename>install</filename> + directory in the build tree. Developers may prefer + to locate the build tree in a temporary file + hierarchy but keep the install tree in a more + permanent location.</PARA> +</LISTITEM> +</VARLISTENTRY> +<VARLISTENTRY> +<TERM><OPTION>--srcdir=<dir></OPTION></TERM> +<LISTITEM> +<PARA>Specifies the location of the component + repository. By default, the tool uses the location + specified in the + <REPLACEABLE>ECOS_REPOSITORY</REPLACEABLE> + environment variable. Developers may prefer to use + of this qualifier if they are working with more than + one repository.</PARA> +</LISTITEM> +</VARLISTENTRY> +<VARLISTENTRY> +<TERM><OPTION>--no-resolve</OPTION></TERM> +<LISTITEM> +<PARA>Disables the implicit resolution of conflicts + while manipulating the configuration data. + developers may prefer to resolve conflicts by + editing the <productname>eCos</productname> configuration save file + manually.</PARA> +</LISTITEM> +</VARLISTENTRY> +<VARLISTENTRY> +<TERM><OPTION>--ignore-errors</OPTION></TERM> +<TERM><OPTION>-i</OPTION></TERM> +<LISTITEM> +<PARA> +By default, ecosconfig will exit with an error code if the current +configuration contains any conflicts, and it is not possible to +generate or update a build tree for such configurations. This +qualifier causes ecosconfig to ignore such problems, and hence it is +possible to generate a build tree even if there are still +conflicts. Of course, there are no guarantees that the resulting +system will actually do anything. +</PARA> +</LISTITEM> +</VARLISTENTRY> +<VARLISTENTRY> +<TERM><OPTION>--verbose</OPTION></TERM> +<TERM><OPTION>-v</OPTION></TERM> +<LISTITEM> +<PARA> +Display more information. +</PARA> +</LISTITEM> +</VARLISTENTRY> +<VARLISTENTRY> +<TERM><OPTION>--quiet</OPTION></TERM> +<TERM><OPTION>-q</OPTION></TERM> +<LISTITEM> +<PARA> +Display less information. +</PARA> +</LISTITEM> +</VARLISTENTRY> +</VARIABLELIST> +<PARA> +The <OPTION>--config</OPTION>, <OPTION>--prefix</OPTION> and +<OPTION>--srcdir</OPTION> qualifiers can also be written with two arguments, +for example: +</para> +<SCREEN> +ecosconfig --srcdir <REPLACEABLE><dir></REPLACEABLE> ... +</SCREEN> +<para> +This simplifies filename completion with some shells. +</PARA> +</SECT2> +<SECT2> +<TITLE>ecosconfig commands</TITLE> +<PARA>The available commands for + <COMMAND>ecosconfig</COMMAND> are as + follows:</PARA> +<VARIABLELIST> +<VARLISTENTRY> +<TERM><COMMAND>list</COMMAND></TERM> +<LISTITEM> +<PARA>Lists the available packages, targets and + templates as installed in the <productname>eCos</productname> repository. + Aliases and package versions are also + reported.</PARA> +</LISTITEM> +</VARLISTENTRY> +<VARLISTENTRY> +<TERM><COMMAND>new <target> [<template> [<version>]]</COMMAND></TERM> +<LISTITEM> +<PARA>Creates a new <productname>eCos</productname> configuration for + the specified target hardware and saves it. A + software template may also be specified. By default, + the template named ‘default’ is used. If + the template version is not specified, the latest + version is used.</PARA> +</LISTITEM> +</VARLISTENTRY> +<VARLISTENTRY> +<TERM><COMMAND>target <target></COMMAND></TERM> +<LISTITEM> +<PARA>Changes the target hardware selection + for the <productname>eCos</productname> configuration. This has the effect of + unloading packages supporting the target selected + previously and loading the packages which support + the new hardware. This command will be used + typically when switching between a simulator and + real hardware.</PARA> +</LISTITEM> +</VARLISTENTRY> +<VARLISTENTRY> +<TERM><COMMAND>template <template> [<version>]</COMMAND></TERM> +<LISTITEM> +<PARA>Changes the template selection for the <productname>eCos</productname> + configuration. This has the effect of unloading + packages specified by the template selected + previously and loading the packages specified by the + new template. By default, the latest version of the + specified template is used.</PARA> +</LISTITEM> +</VARLISTENTRY> +<VARLISTENTRY> +<TERM><COMMAND>remove <packages></COMMAND></TERM> +<LISTITEM> +<PARA>Removes the specified packages from the <productname>eCos</productname> + configuration. This command will be used typically + when the template on which a configuration is based + contains packages which are not required.</PARA> +</LISTITEM> +</VARLISTENTRY> +<VARLISTENTRY> +<TERM><COMMAND>add <packages></COMMAND></TERM> +<LISTITEM> +<PARA>Adds the specified packages to the <productname>eCos</productname> configuration. This +command will be used typically when the template on which a +configuration is based does not contain all the packages which are +required.For example, add-on packages provided by third parties will +not be known to the standard templates, so they will have to be added +explicitly. </PARA> +</LISTITEM> +</VARLISTENTRY> +<VARLISTENTRY> +<TERM><COMMAND>version <version> <packages></COMMAND></TERM> +<LISTITEM> +<PARA>Selects the specified version of a + number of packages in the <productname>eCos</productname> configuration. By + default, the most recent version of each package is + used. This command will be used typically when an + older version of a package is required.</PARA> +</LISTITEM> +</VARLISTENTRY> +<VARLISTENTRY> +<TERM><COMMAND>check</COMMAND></TERM> +<LISTITEM> +<PARA>Presents the following information + concerning the current configuration:</PARA> +<ORDEREDLIST> +<LISTITEM> +<PARA>the selected target hardware</PARA> +</LISTITEM> +<LISTITEM> +<PARA>the selected template</PARA> +</LISTITEM> +<LISTITEM> +<PARA>additional packages</PARA> +</LISTITEM> +<LISTITEM> +<PARA>removed packages</PARA> +</LISTITEM> +<LISTITEM> +<PARA>the selected version of packages + where this is not the most recent + version</PARA> +</LISTITEM> +<LISTITEM> +<PARA>conflicts in the current configuration</PARA> +</LISTITEM> +</ORDEREDLIST> +</LISTITEM> +</VARLISTENTRY> +<VARLISTENTRY> +<TERM><COMMAND>resolve</COMMAND></TERM> +<LISTITEM> +<PARA>Resolves conflicts identified in the + current <productname>eCos</productname> configuration by invoking an inference + capability. Resolved conflicts are reported, but not + all conflicts may be resolvable. This command will + be used typically following manual editing of the + configuration.</PARA> +</LISTITEM> +</VARLISTENTRY> +<VARLISTENTRY> +<TERM><COMMAND>export <file></COMMAND></TERM> +<LISTITEM> +<PARA>Exports a minimal <productname>eCos</productname> configuration + save file with the specified name. This file + contains only those options which do not have their + default value. Such files are used typically to + transfer option values from one configuration to + another.</PARA> +</LISTITEM> +</VARLISTENTRY> +<VARLISTENTRY> +<TERM><COMMAND>import <file></COMMAND></TERM> +<LISTITEM> +<PARA>Imports a minimal <productname>eCos</productname> configuration + save file with the specified name. The values of + those options specified in the file are applied to + the current configuration.</PARA> +</LISTITEM> +</VARLISTENTRY> +<VARLISTENTRY> +<TERM><COMMAND>tree</COMMAND></TERM> +<LISTITEM> +<PARA>Generates a build tree based on the current <productname>eCos</productname> + configuration. This command will be used typically + just before building <productname>eCos</productname>.Normally a build tree can +only be generated if if the configuration has no unresolved +conflicts, but <OPTION>--ignore-errors</OPTION> can be used to override +this.</PARA> +</LISTITEM> +</VARLISTENTRY> +</VARIABLELIST> +</SECT2> +</SECT1> +<SECT1 id="conflicts-and-constraints"> +<TITLE>Conflicts and constraints</TITLE> +<PARA>Configuration options are not completely independent. For example +the C library's <FUNCTION>strtod()</FUNCTION> and <FUNCTION>atof()</FUNCTION> +functions rely on the math library package to provide certain functionality. If the math library package is removed then the C +library can no longer provide these functions. Each package describes constraints like these in CDL <EMPHASIS>"requires"</EMPHASIS> properties. If a constraint is not satisfied, then the configuration contains a conflict. For any given conflict there can +be several resolution options. For example, it would be possible to add the math library package back to the +configuration, or to disable the <FUNCTION>strtod()</FUNCTION> and <FUNCTION>atof()</FUNCTION> functions.</PARA> +<PARA> +The <productname>eCos</productname> configuration tools will report any conflicts in the current configuration. If there are any such conflicts +then the configuration is usually unsafe and it makes no sense to build and run <productname>eCos</productname> in such circumstances. In fact, +any attempt at building <productname>eCos</productname> is likely to fail. In exceptional cases it is possible to override this by using e.g. the +<OPTION>--ignore-errors</OPTION> qualifier with ecosconfig. +</PARA> +<PARA> +Many constraints are fairly simple in nature, and the configuration tools contain an inference engine which can +resolve the associated conflicts automatically. For example, if the math library package is removed then the +inference engine can resolve the resulting conflict by disabling the configuration option for <FUNCTION>strtod()</FUNCTION> and <FUNCTION>atof()</FUNCTION>. All +such changes will be reported. Sometimes the inference engine cannot resolve a conflict, for example it is not +allowed to override a change that has been made explicitly by the user. Sometimes it will find a solution which does +not match the application's requirements. +</PARA> +<PARA> +A typical session involving conflicts would look something like this: +<SCREEN> +$ ecosconfig new pid +</SCREEN>This creates a new configuration with the default template. For most targets this will not result in any conflicts, +because the default settings for the various options meet the requirements of the default template. +</PARA><PARA> For some targets +there may be conflicts and the inference engine would come into play. +<SCREEN> +$ ecosconfig remove libm +U CYGSEM_LIBC_STDIO_SCANF_FLOATING_POINT, new inferred value 0 +U CYGFUN_LIBC_strtod, new inferred value 0 +U CYGSEM_LIBC_STDIO_PRINTF_FLOATING_POINT, new inferred value 0 +</SCREEN> +ecosconfig reports that this change caused three conflicts, all in the C library. The inference engine was able to +resolve all the conflicts and update the relevant configuration options accordingly. </PARA> +<PARA>To suppress the inference engine <OPTION>--no-resolve</OPTION> can be used: +<SCREEN> +$ ecosconfig new pid +$ ecosconfig --no-resolve remove libm +C CYGSEM_LIBC_STDIO_SCANF_FLOATING_POINT, "requires" constraint not satisfied: CYGPKG_LIBM +C CYGSEM_LIBC_STDIO_PRINTF_FLOATING_POINT, "requires" constraint not satisfied: CYGPKG_LIBM +C CYGFUN_LIBC_strtod, "requires" constraint not satisfied: CYGPKG_LIBM +</SCREEN> +Three unresolved conflicts are reported. +</PARA> +<PARA>The <COMMAND>check</COMMAND> command can be used to get the current state of the +configuration, and the <OPTION>--verbose</OPTION> qualifier will provide additional information: </PARA> +<SCREEN> +$ ecosconfig --srcdir /home/bartv/ecc/ecc --verbose check +Target: pid +Template: default +Removed: + CYGPKG_LIBM +3 conflict(s): +C CYGFUN_LIBC_strtod, "requires" constraint not satisfied: CYGPKG_LIBM + Possible solution: + CYGFUN_LIBC_strtod -> 0 + CYGSEM_LIBC_STDIO_SCANF_FLOATING_POINT -> 0 +C CYGSEM_LIBC_STDIO_PRINTF_FLOATING_POINT, "requires" constraint not satisfied: CYGPKG_LIBM + Possible solution: + CYGSEM_LIBC_STDIO_PRINTF_FLOATING_POINT -> 0 +C CYGSEM_LIBC_STDIO_SCANF_FLOATING_POINT, "requires" constraint not satisfied: CYGPKG_LIBM + Possible solution: + CYGSEM_LIBC_STDIO_SCANF_FLOATING_POINT -> 0 +</SCREEN> +<PARA> +If the proposed solutions are acceptable, the resolve command can be used to apply them: +<SCREEN> +$ ecosconfig resolve +U CYGSEM_LIBC_STDIO_SCANF_FLOATING_POINT, new inferred value 0 +U CYGFUN_LIBC_strtod, new inferred value 0 +U CYGSEM_LIBC_STDIO_PRINTF_FLOATING_POINT, new inferred value 0 +</SCREEN></PARA> +<PARA>The current configuration is again conflict-free and it is possible to generate a build tree. The <OPTION>--quiet</OPTION> qualifier can +be used to suppress the change messages, if desired. +</PARA><PARA> +When changing individual configuration options by editing the ecos.ecc file (as described below), the resulting +system should be checked and any problems should be resolved. For example, if CYGFUN_LIBC_strtod is +explicitly enabled in the savefile: +<SCREEN> +$ edit ecos.ecc +$ ecosconfig check +Target: pid +Template: default +Removed: + CYGPKG_LIBM +1 conflict(s): +C CYGFUN_LIBC_strtod, "requires" constraint not satisfied: CYGPKG_LIBM +$ ecosconfig resolve +C CYGFUN_LIBC_strtod, "requires" constraint not satisfied: CYGPKG_LIBM +</SCREEN> +In this case the inference engine cannot resolve the conflict automatically because that would involve changing a +user setting. Any attempt to generate a build tree will fail: +<SCREEN> +$ ecosconfig --srcdir /home/bartv/ecc/ecc tree +C CYGFUN_LIBC_strtod, "requires" constraint not satisfied: CYGPKG_LIBM +Unable to generate build tree, this configuration still contains conflicts. +Either resolve the conflicts or use --ignore-errors +</SCREEN> +</PARA><PARA> +It is still possible to generate a build tree: +<SCREEN> +$ ecosconfig --srcdir /home/bartv/ecc/ecc --ignore-errors tree +C CYGFUN_LIBC_strtod, "requires" constraint not satisfied: CYGPKG_LIBM +$ make +</SCREEN> +In this case <productname>eCos</productname> will fail to build. In other cases of unresolved conflicts <productname>eCos</productname> may build, but may not run. In +general all conflicts should be resolved by editing the <FILENAME>ecos.ecc</FILENAME> file, by letting the inference engine make appropriate +changes, or by other means, before any attempt is made to build or run <productname>eCos</productname>. +</PARA> +</SECT1> +<SECT1 id="building-the-system"> +<TITLE>Building the System</TITLE> +<PARA>Once a build tree has been generated with + <COMMAND>ecosconfig</COMMAND>, <!-- <index></index> + -->building <productname>eCos</productname> is straightforward:</PARA> +<SCREEN>$ make</SCREEN> +<PARA>The build tree contains the subdirectories, makefiles, + and everything else that is needed to generate the default + configuration for the selected architecture and platform. + The only requirement is that the tools needed for that + architecture, for example + <COMMAND>powerpc-eabi-g++</COMMAND>, + are available using the standard search path. If this is not + the case then the <COMMAND>make</COMMAND> will + fail with an error message. If you have a multiprocessor + system then it may be more efficient to use:</PARA> +<SCREEN>$ make -j <REPLACEABLE>n</REPLACEABLE></SCREEN> +<PARA>where <REPLACEABLE>n</REPLACEABLE> is equal to the + number of processors on your system.</PARA> +<PARA>Once the <COMMAND>make</COMMAND> process + has completed, the install tree will contain the header + files and the target library that are needed for application + development. </PARA> +<PARA>It is also possible to build the system’s test cases +for the current configuration:</PARA> +<SCREEN>$ make tests</SCREEN> +<PARA>The resulting test executables will end up in a + <FILENAME>tests</FILENAME> subdirectory of the + <!-- <index></index> -->install tree. </PARA> +<PARA>If disk space is scarce then it is possible to make the copy +of the install tree for application development purposes, and then +use: </PARA> +<SCREEN>$ make clean</SCREEN> +<PARA>The build tree will now use up a minimum of disk space — the +bulk of what is left consists of configuration header files that +you may have edited and hence should not be deleted automatically. +However, it is possible to rebuild the system at any time without +re-invoking <COMMAND>ecosconfig</COMMAND>, just by +running <COMMAND>make</COMMAND> again. </PARA> +<PARA>Under exceptional circumstances it may be necessary to run <COMMAND>make +clean</COMMAND> for other reasons, such as when a new release +of the toolchain is installed. The toolchain includes a number of +header files which are closely tied to the compiler, for example <filename>limits.h</filename>, +and these header files are not and should not be duplicated by <productname>eCos</productname>. +The makefiles perform header file dependency analysis, so that when +a header file is changed all affected sources will be rebuilt during +the next <COMMAND>make</COMMAND>. This is very useful +when the configuration header files are changed, but it also means +that a build tree containing information about the locations of +header files must be rebuilt. If a new version of the toolchain +is installed and the old version is removed then this location information +is no longer accurate, and <COMMAND>make</COMMAND> will +complain that certain dependencies cannot be satisfied. Under such circumstances +it is necessary to do a <COMMAND>make clean</COMMAND> first. </PARA> +</SECT1> +<SECT1 id="ecos-packages"> +<TITLE>Packages</TITLE> +<PARA><productname>eCos</productname> is a component architecture. The system comes as a + number of <!-- <index></index> -->packages which can be + enabled or disabled as required, and new packages can be + added as they become available. Unfortunately, the packages + are not completely independent: for example the µITRON + compatibility package relies almost entirely on + functionality provided by the kernel package, and it would + not make sense to try to build µITRON if the kernel + was disabled. The C library has fewer dependencies: some + parts of the C library rely on kernel functionality, but it + is possible to disable these parts and thus build a system + that has the C library but no kernel. The + <command>ecosconfig</command> tool has the capability of + checking that all the dependencies are satisfied, but it + may still be possible to produce configurations that will + not build or (conceivably) that will build but not run. + Developers should be aware of this and take appropriate + care.</PARA> +<PARA>By default, <!-- <index></index> --><command>ecosconfig</command> will +include all packages that are appropriate for the specified hardware +in the configuration. The common <!-- <index></index> -->HAL package and +the <productname>eCos</productname> infrastructure must be present in every configuration. In +addition, it is always necessary to have one architectural HAL package +and one platform HAL package. Other packages are optional, and can +be added or removed from a configuration as required.</PARA> +<PARA>The application may not require all of the packages; for example, +it might not need the µITRON compatibility +package, or the floating point support provided by the math library. +There is a slight overhead when <productname>eCos</productname> is built because the packages +will get compiled, and there is also a small disk space penalty. +However, any unused facilities will get stripped out at link-time, +so having redundant packages will not affect the final executable. </PARA> +</SECT1> +<SECT1 id="coarse-grained-configuration"> +<TITLE>Coarse-grained Configuration</TITLE> +<PARA>Coarse-grained <!-- <index></index> -->configuration of + an <productname>eCos</productname> system means making configuration changes using the + <COMMAND>ecosconfig</COMMAND> tool. These changes + include: </PARA> +<ORDEREDLIST> +<LISTITEM> +<PARA>switching to different target hardware</PARA> +</LISTITEM> +<LISTITEM> +<PARA>switching to a different template</PARA> +</LISTITEM> +<LISTITEM> +<PARA>adding or removing a package</PARA> +</LISTITEM> +<LISTITEM> +<PARA>changing the version of a package</PARA> +</LISTITEM> +</ORDEREDLIST> +<PARA>Whenever <COMMAND>ecosconfig</COMMAND> generates or + updates an <productname>eCos</productname> configuration, it generates a configuration + save file.</PARA> +<PARA>Suppose that the configuration was first created using + the following command line: </PARA> +<SCREEN>$ ecosconfig new stdeval1</SCREEN> +<PARA>To change the target hardware to the Cogent CMA28x + PowerPC board, the following command would be needed: + </PARA> +<SCREEN>$ ecosconfig target cma28x</SCREEN> +<PARA>To switch to the PowerPC simulator instead: </PARA> +<SCREEN>$ ecosconfig target psim</SCREEN> +<PARA>As the hardware changes, hardware-related packages such as +the HAL packages and device drivers will be added to and removed +from the configuration as appropriate. </PARA> +<PARA>To remove any package from the current configuration, use +the <COMMAND>remove</COMMAND> command: </PARA> +<SCREEN>$ ecosconfig remove uitron</SCREEN> +<PARA>You can disable multiple packages using multiple arguments, +for example: </PARA> +<SCREEN>$ ecosconfig remove uitron libm</SCREEN> +<PARA>If this turns out to have been a mistake then you can + re-enable one or more packages with the + <COMMAND>add</COMMAND> command: </PARA> +<SCREEN>$ ecosconfig add libm</SCREEN> +<PARA>Changing the desired version for a package is also + straightforward:</PARA> +<SCREEN>$ ecosconfig version v2_1 kernel</SCREEN> +<PARA>It is necessary to regenerate the build tree and header + files following any changes to the configuration before + rebuilding <productname>eCos</productname>:</PARA> +<SCREEN>$ ecosconfig tree</SCREEN> +</SECT1> +<SECT1 id="fine-grained-configuration"> +<TITLE>Fine-grained Configuration</TITLE> +<PARA><COMMAND>ecosconfig</COMMAND> only provides + coarse-grained control over the configuration: the hardware, + the template and the packages that should be built. Unlike + the Configuration Tool, + <COMMAND>ecosconfig</COMMAND> does not provide + any facilities for manipulating finer-grained <!-- + <index></index> -->configuration options such as how many + priority levels the scheduler should support. There are + hundreds of these options, and manipulating them by means of + command line arguments would not be sensible. </PARA> +<PARA>In the current system fine-grained configuration options may +be manipulated by manual editing of the configuration file. When +a file has been edited in this way, the <COMMAND>ecosconfig</COMMAND> tool +should be used to check the configuration for any conflicts which +may have been introduced:</PARA> +<SCREEN>$ ecosconfig check</SCREEN> +<PARA>The <COMMAND>check</COMMAND> command will list +all conflicts and will also rewrite the configuration file, propagating +any changes which affect other options. The user may choose to resolve +the conflicts either by re-editing the configuration file manually +or by invoking the inference engine using the <COMMAND>resolve</COMMAND> command:</PARA> +<SCREEN>$ ecosconfig resolve</SCREEN> +<PARA>The <COMMAND>resolve</COMMAND> command will +list all conflicts which can be resolved and save the resulting changes +to the configuration.</PARA> +<PARA>It is necessary to regenerate the build tree and header files +following any changes to the configuration before rebuilding <productname>eCos</productname>:</PARA> +<SCREEN>$ ecosconfig tree</SCREEN> +<PARA>All the configuration options and their descriptions are listed +in the <citetitle><productname>eCos</productname> Reference Manual</citetitle>. </PARA> +</SECT1> +<SECT1 id="editing-an-ecos-savefile"> +<TITLE>Editing an <productname>eCos</productname> Savefile</TITLE> +<PARA>The <productname>eCos</productname> configuration information is held in a single + savefile, typically <FILENAME>ecos.ecc</FILENAME>, which can + be generated by either the GUI configuration tool or by the + command line <command>ecosconfig</command> tool. The file + normally exists at the top level of the build tree. It is a + text file, allowing the various configurations options to be + edited inside a suitable text editor or by other programs or + scripts, as well as in the GUI config tool.</PARA> +<PARA>An <productname>eCos</productname> savefile is actually a script in the <EMPHASIS>Tcl</EMPHASIS> programming +language, so any modifications to the file need to preserve Tcl +syntax. For most configuration options, any modifications will be +trivial and there is no need to worry about Tcl syntax. For example, +changing a 1 to a 0 to disable an option. For more complicated +options, for example<literal> CYGDAT_UITRON_TASK_EXTERNS</literal>, +which involves some lines of C code, more care has +to be taken. If an edited savefile is no longer a valid Tcl script +then the configuration tools will be unable to read back the data +for further processing, for example to generate a build tree. An +outline of Tcl syntax is given below. One point worth noting here +is that a line that begins with a “#” is +usually a comment, and the bulk of an <productname>eCos</productname> savefile actually consists +of such comments, to make it easier to edit.</PARA> +<SECT2> +<TITLE>Header</TITLE> +<PARA>An <productname>eCos</productname> savefile begins with a header, which typically + looks something like this:</PARA> +<SCREEN># eCos saved configuration +# ---- commands -------------------------------------------------------- +# This section contains information about the savefile format. +# It should not be edited. Any modifications made to this section +# may make it impossible for the configuration tools to read +# the savefile. + +cdl_savefile_version 1; +cdl_savefile_command cdl_savefile_version {}; +cdl_savefile_command cdl_savefile_command {}; +cdl_savefile_command +cdl_configuration { description hardware template package }; +cdl_savefile_command cdl_package { value_source user_value wizard_value inferred_value }; +cdl_savefile_command cdl_component { value_source user_value wizard_value inferred_value }; +cdl_savefile_command cdl_option { value_source user_value wizard_value inferred_value }; +cdl_savefile_command cdl_interface { value_source user_value wizard_value inferred_value }; + </SCREEN> +<PARA>This section of the savefile is intended for use by the + configuration system, and should not be edited. If this + section is edited then the various configuration tools may no + longer be able to read in the modified savefile.</PARA> +</SECT2> +<SECT2> +<TITLE>Toplevel Section</TITLE> +<PARA>The header is followed by a section that defines the + configuration as a whole. A typical example would + be:</PARA> +<SCREEN># ---- toplevel -------------------------------------------------------- +# This section defines the toplevel configuration object. The only +# values that can be changed are the name of the configuration and +# the description field. It is not possible to modify the target, +# the template or the set of packages simply by editing the lines +# below because these changes have wide-ranging effects. Instead +# the appropriate tools should be used to make such modifications. + +cdl_configuration eCos { +description ““ ; + +# These fields should not be modified. +hardware pid ; +template uitron ; +package -hardware CYGPKG_HAL_ARM current ; +package -hardware CYGPKG_HAL_ARM_PID current ; +package -hardware CYGPKG_IO_SERIAL current ; +package -template CYGPKG_HAL current ; +package -template CYGPKG_IO current ; +package -template CYGPKG_INFRA current ; +package -template CYGPKG_KERNEL current ; +package -template CYGPKG_UITRON current ; +package -template CYGPKG_LIBC current ; +package -template CYGPKG_LIBM current ; +package -template CYGPKG_DEVICES_WALLCLOCK current ; +package -template CYGPKG_ERROR current ; +}; + </SCREEN> +<PARA>This section allows the configuration tools to reload the +various packages that make up the configuration. Most of the information +should not be edited. If it is necessary to add a new package or +to remove an existing one then the appropriate tools should be used +for this, for example:</PARA> +<PROGRAMLISTING>$ ecosconfig remove CYGPKG_LIBM</PROGRAMLISTING> +<PARA>There are two fields which can be edited. Configurations have +a name; in this case <productname>eCos</productname>. They can also have a description, which +is some arbitrary text. The configuration tools do not make use +of these fields, they exist so that users can store additional information +about a configuration.</PARA> +</SECT2> +<SECT2> +<TITLE>Conflicts Section</TITLE> +<PARA>The toplevel section is followed by details of all the + conflicts (if any) in the configuration, for + example:</PARA> +<SCREEN># ---- conflicts ------------------------------------------------------- +# There are 2 conflicts. +# +# option CYGNUM_LIBC_TIME_DST_DEFAULT_OFFSET +# Property LegalValues +# Illegal current value 100000 +# Legal values are: -90000 to 90000 +# +# option CYGSEM_LIBC_TIME_CLOCK_WORKING +# Property Requires +# Requires constraint not satisfied: CYGFUN_KERNEL_THREADS_TIMER + </SCREEN> +<PARA>When editing a configuration you may end up with something +that is invalid. Any problems in the configuration will be reported +in the conflicts section. In this case there are two conflicts. +The option <literal>CYGNUM_LIBC_TIME_DST_DEFAULT_OFFSET</literal> has +been given an illegal value: typically this would be fixed by searching +for the definition of that option later on in the savefile and modifying +the value. The second conflict is more interesting, an unsatisfied <EMPHASIS>requires</EMPHASIS> constraint. +Configuration options are not independent: disabling some functionality +in, say, the kernel, can have an impact elsewhere; in this case +the C library. The various dependencies between the options are +specified by the component developers and checked by the configuration +system. In this case there are two obvious ways in which the conflict could +be resolved: re-enabling <literal>CYGFUN_KERNEL_THREADS_TIMER</literal>, +or disabling <literal>CYGSEM_LIBC_TIME_CLOCK_WORKING</literal>. +Both of these options will be listed later on in the file.</PARA> +<PARA>Some care has to be taken when modifying configuration options, +to avoid introducing new conflict. For instance it is possible that +there might be other options in the system which have a dependency +on <literal>CYGSEM_LIBC_TIME_CLOCK_WORKING</literal>, +so disabling that option may not be the best way to resolve the +conflict. Details of all such dependencies are provided in the appropriate +places in the savefile.</PARA> +<PARA>It is not absolutely required that a configuration be conflict-free +before generating a build tree and building <productname>eCos</productname>. It is up to the +developers of each component to decide what would happen if an attempt +is made to build <productname>eCos</productname> while there are still conflicts. In serious +cases there is likely to be a compile-time failure, or possibly +a link-time failure. In less serious cases the system may build +happily and the application can be linked with the resulting library, +but the component may not quite function as intended - although +it may still be good enough for the specific needs of the application. +It is also possible that everything builds and links, but once in +a while the system will unaccountably crash. Using a configuration +that still has conflicts is done entirely at the user’s +risk.</PARA> +</SECT2> +<SECT2> +<TITLE>Data Section</TITLE> +<PARA>The bulk of the savefile lists the various packages, + components, and options, including their values and the + various dependencies. A number of global options come + first, especially those related to the build process such + as compiler flags. These are followed by the various + packages, and the components and options within those + packages, in order.</PARA> +<PARA>Packages, components and options are organized in a + hierarchy. If a particular component is disabled then all + options and sub-components below it will be inactive: any + changes made to these will have no effect. The savefile + contains information about the hierarchy in the form of + comments, for example:</PARA> +<SCREEN>cdl_package CYGPKG_KERNEL ... +# > +cdl_component CYGPKG_KERNEL_EXCEPTIONS ... +# > +cdl_option CYGSEM_KERNEL_EXCEPTIONS_DECODE ... +cdl_option CYGSEM_KERNEL_EXCEPTIONS_GLOBAL ... +# < +cdl_component CYGPKG_KERNEL_SCHED ... +# > +cdl_option CYGSEM_KERNEL_SCHED_MLQUEUE ... +cdl_option CYGSEM_KERNEL_SCHED_BITMAP ... +# < +# < + </SCREEN> +<PARA>This corresponds to the following hierarchy:</PARA> +<SCREEN> CYGPKG_KERNEL + CYGPKG_KERNEL_EXCEPTIONS + CYGSEM_KERNEL_EXCEPTIONS_DECODE + CYGSEM_KERNEL_EXCEPTIONS_GLOBAL + CYGPKG_KERNEL_SCHED + CYGSEM_KERNEL_SCHED_MLQUEUE + CYGSEM_KERNEL_SCHED_BITMAP + </SCREEN> +<PARA>Providing the hierarchy information in this way allows + programs or scripts to analyze the savefile and readily + determine the hierarchy. It could also be used by a + sufficiently powerful editor to support structured editing + of <productname>eCos</productname> savefiles. The information is not used by the + configuration tools themselves since they obtain the + hierarchy from the original CDL scripts.</PARA> +<PARA>Each configurable entity is preceded by a comment, of + the following form:</PARA> +<SCREEN># Kernel schedulers +# doc: ref/ecos-ref/ecos-kernel-overview.html#THE-SCHEDULER +# The eCos kernel provides a choice of schedulers. In addition +# there are a number of configuration options to control the +# detailed behaviour of these schedulers. +cdl_component CYGPKG_KERNEL_SCHED { +... +}; + </SCREEN> +<PARA>This provides a short textual alias + <literal>Kernel schedulers</literal> for the + component. If online documentation is available for the + configurable entity then this will come next. Finally + there is a short description of the entity as a whole. All + this information is provided by the component + developers.</PARA> +<PARA>Each configurable entity takes the form:</PARA> +<SCREEN><type> <name> { + <data> +};</SCREEN> +<PARA>Configurable entities may not be active. This can be either +because the parent is disabled or inactive, or because there are +one or more <EMPHASIS>active_if</EMPHASIS> properties. Modifying +the value of an inactive entity has no effect on the configuration, +so this information is provided first:</PARA> +<PARA></PARA> +<SCREEN>cdl_option CYGSEM_KERNEL_EXCEPTIONS_DECODE { +# This option is not active +# The parent CYGPKG_KERNEL_EXCEPTIONS is disabled +... +}; + +... + +cdl_option CYGIMP_IDLE_THREAD_YIELD { +# This option is not active +# ActiveIf constraint: (CYGNUM_KERNEL_SCHED_PRIORITIES == 1) +# CYGNUM_KERNEL_SCHED_PRIORITIES == 32 +# --> 0 +... +}; + +</SCREEN> +<PARA>For <literal>CYGIMP_IDLE_THREAD_YIELD</literal> the +savefile lists the expression that must be satisfied if the option +is to be active, followed by the current value of all entities that +are referenced in the expression, and finally the result of evaluating +that expression.</PARA> +<PARA>Not all options are directly modifiable in the savefile. First, +the value of packages (which is the version of that package loaded +into the configuration) cannot be modified here.</PARA> +<SCREEN> + +cdl_package CYGPKG_KERNEL { +# Packages cannot be added or removed, nor can their version be changed, +# simply by editing their value. Instead the appropriate configuration +# should be used to perform these actions. +... +}; + +</SCREEN> +<PARA>The version of a package can be changed using e.g.: </PARA> +<SCREEN>$ ecosconfig version 1.3 CYGPKG_KERNEL</SCREEN> +<PARA>Even though a package’s value cannot be modified +here, it is still important for the savefile to contain the details. +In particular packages may impose constraints on other configurable +entities and may be referenced by other configurable entities. Also +it would be difficult to understand or extract the configuration’s +hierarchy if the packages were not listed in the appropriate places +in the savefile.</PARA> +<PARA>Some components (or, conceivably, options) do not have any +associated data. Typically they serve only to introduce another +level in the hierarchy, which can be useful in the context of the +GUI configuration tool.</PARA> +<SCREEN> + +cdl_component CYGPKG_HAL_COMMON_INTERRUPTS { +# There is no associated value. +}; + +</SCREEN> +<PARA>Other components or options have a calculated value. These +are not user-modifiable, but typically the value will depend on +other options which can be modified. Such calculated options can +be useful when controlling what gets built or what ends up in the +generated configuration header files. A calculated value may also +effect other parts of the configuration, for instance, via a <EMPHASIS>requires</EMPHASIS> constraint.</PARA> +<SCREEN> + +cdl_option BUFSIZ { +# Calculated value: CYGSEM_LIBC_STDIO_WANT_BUFFERED_IO ? CYGNUM_LIBC_STDIO_BUFSIZE : 0 +# CYGSEM_LIBC_STDIO_WANT_BUFFERED_IO == 1 +# CYGNUM_LIBC_STDIO_BUFSIZE == 256 +# Current_value: 256 +}; + +</SCREEN> +<PARA>A special type of calculated value is the <EMPHASIS>interface</EMPHASIS>. +The value of an interface is the number of active and enabled options +which <EMPHASIS>implement</EMPHASIS> that interface. Again the value +of an interface cannot be modified directly; only by modifying the +options which implement the interface. However, an interface can +be referenced by other parts of the configuration. </PARA> +<SCREEN>cdl_interface CYGINT_KERNEL_SCHEDULER { +# Implemented by CYGSEM_KERNEL_SCHED_MLQUEUE, active, enabled +# Implemented by CYGSEM_KERNEL_SCHED_BITMAP, active, disabled +# This value cannot be modified here. +# Current_value: 1 +# Requires: 1 == CYGINT_KERNEL_SCHEDULER +# CYGINT_KERNEL_SCHEDULER == 1 +# --> 1 + +</SCREEN> +<SCREEN># The following properties are affected by this value +# interface CYGINT_KERNEL_SCHEDULER +# Requires: 1 == CYGINT_KERNEL_SCHEDULER +}; </SCREEN> +<PARA>If the configurable entity is modifiable then there will be +lines like the following:</PARA> +<SCREEN> +cdl_option CYGSEM_KERNEL_SCHED_MLQUEUE { +... +# Flavor: bool +# No user value, uncomment the following line to provide one. +# user_value 1 +# value_source default +# Default value: 1 +... +}; + +</SCREEN> +<PARA>Configurable entities can have one of four different flavors: +none, bool, data and booldata. Flavor none indicates that there +is no data associated with the entity, typically it just acts as +a placeholder in the overall hierarchy. Flavor bool is the most +common, it is a simple yes-or-no choice. Flavor data is for more +complicated configuration choices, for instance the size of an array +or the name of a device. Flavor booldata is a combination of bool +and data: the option can be enabled or disabled, and there is some +additional data associated with the option as well.</PARA> +<PARA>In the above example the user has not modified this particular +option, as indicated by the comment and by the commented-out <literal>user_value</literal> line. +To disable this option the file should be edited to:</PARA> +<SCREEN> + +cdl_option CYGSEM_KERNEL_SCHED_MLQUEUE { +... +# Flavor: bool +# No user value, uncomment the following line to provide one. +user_value 0 +# value_source default +# Default value: 1 +... +} + +</SCREEN> +<PARA>The comment preceding the <literal>user_value +0</literal> line can be removed if desired, otherwise it +will be removed automatically the next time the file is read and +updated by the configuration tools.</PARA> +<PARA>Much the same process should be used for options with the +data flavor, for example:</PARA> +<SCREEN> +cdl_option CYGNUM_LIBC_TIME_DST_DEFAULT_OFFSET { +# Flavor: data +# No user value, uncomment the following line to provide one. +# user_value 3600 +# value_source default +# Default value: 3600 +# Legal values: -90000 to 90000 +}; + +</SCREEN> +<PARA>can be changed to:</PARA> +<SCREEN> + +cdl_option CYGNUM_LIBC_TIME_DST_DEFAULT_OFFSET { +# Flavor: data +user_value 7200 +# value_source default +# Default value: 3600 +# Legal values: -90000 to 90000 }; + +</SCREEN> +<PARA>Note that the original text provides the default value in +the <literal>user_value</literal> comment, +on the assumption that the desired new value is likely to be similar +to the default value. The <literal>value_source</literal> comment +does not need to be updated, it will be fixed up if the savefile +is fed back into the configuration system and regenerated.</PARA> +<PARA>For options with the booldata flavor, the <literal>user_value</literal> line +needs take two arguments. The first argument is for the boolean +part, the second for the data part. For example:</PARA> +<SCREEN> +cdl_component CYGNUM_LIBM_COMPATIBILITY { +# Flavor: booldata +# No user value, uncomment the following line to provide one. +# user_value 1 POSIX +# value_source default +# Default value: 1 POSIX +# Legal values: “POSIX” “IEEE” “XOPEN” “SVID” +... +}; + +</SCREEN> +<PARA>could be changed to:</PARA> +<SCREEN> +cdl_component CYGNUM_LIBM_COMPATIBILITY { +# Flavor: booldata +user_value 1 IEEE +# value_source default +# Default value: 1 POSIX +# Legal values: “POSIX” “IEEE” “XOPEN” “SVID” +... +}; + +</SCREEN> +<PARA>or alternatively, if the whole component should be disabled, +to:</PARA> +<SCREEN> +cdl_component CYGNUM_LIBM_COMPATIBILITY { +# Flavor: booldata +user_value 0 POSIX +# value_source default +# Default value: 1 POSIX +# Legal values: “POSIX” “IEEE” “XOPEN” “SVID” +... +}; + +</SCREEN> +<PARA>Some options take values that span multiple lines. An example +would be:</PARA> +<SCREEN> + +cdl_option CYGDAT_UITRON_MEMPOOLVAR_INITIALIZERS { +# Flavor: data +# No user value, uncomment the following line to provide one. +# user_value \ +# “CYG_UIT_MEMPOOLVAR( vpool1, 2000 ), \\ +# CYG_UIT_MEMPOOLVAR( vpool2, 2000 ), \\ +# CYG_UIT_MEMPOOLVAR( vpool3, 2000 ),” +# value_source default +# Default value: \ +# “CYG_UIT_MEMPOOLVAR( vpool1, 2000 ), \\ +# CYG_UIT_MEMPOOLVAR( vpool2, 2000 ), \\ +# CYG_UIT_MEMPOOLVAR( vpool3, 2000 ),” +}; + +</SCREEN> +<PARA>Setting a user value for this option involves uncommenting +and modifying all relevant lines, for example:</PARA> +<SCREEN> + +cdl_option CYGDAT_UITRON_MEMPOOLVAR_INITIALIZERS { +# Flavor: data +user_value \ +“CYG_UIT_MEMPOOLVAR( vpool1, 4000 ), \\ +CYG_UIT_MEMPOOLVAR( vpool2, 4000 ),” +# value_source default +# Default value: \ +# “CYG_UIT_MEMPOOLVAR( vpool1, 2000 ), \\ +# CYG_UIT_MEMPOOLVAR( vpool2, 2000 ), \\ +# CYG_UIT_MEMPOOLVAR( vpool3, 2000 ),” +}; + +</SCREEN> +<PARA>In such cases appropriate care has to be taken to preserve +Tcl syntax, as discussed below.</PARA> +<PARA>The configuration system has the ability to keep track of + several different values for any given option. All options + start off with a default value, in other words their value + source is set to <literal>default</literal>. If a + configuration involves conflicts and the configuration + system’s inference engine is allowed to resolve these + automatically then it may provide an + <literal>inferred</literal> value instead, for + example:</PARA> +<SCREEN> + +cdl_option CYGMFN_KERNEL_SYNCH_CONDVAR_TIMED_WAIT { +# Flavor: bool +# No user value, uncomment the following line to provide one. +# user_value 1 +# The inferred value should not be edited directly. +inferred_value 0 +# value_source inferred +# Default value: 1 +... +}; + +</SCREEN> +<PARA>Inferred values are calculated by the configuration system +and should not be edited by the user. If the inferred value is not +correct then a user value should be substituted instead:</PARA> +<SCREEN> + +cdl_option CYGMFN_KERNEL_SYNCH_CONDVAR_TIMED_WAIT { +# Flavor: bool +user_value 1 +# The inferred value should not be edited directly. +inferred_value 0 +# value_source inferred +# Default value: 1 +... +}; </SCREEN> +<PARA>The inference engine will not override a user value with an +inferred one. Making a change like this may well re-introduce a +conflict, since the inferred value was only calculated to resolve +a conflict. Another run of the inference engine may find a different +and more acceptable way of resolving the conflict, but this is not guaranteed +and it may be up to the user to examine the various dependencies +and work out an acceptable solution.</PARA> +<PARA>Inferred values are listed in the savefile because the exact +inferred value may depend on the order in which changes were made +and conflicts were resolved. If the inferred values were absent +then it is possible that reloading a savefile would not exactly +restore the configuration. Default values on the other hand are +entirely deterministic so there is no actual need for the values +to be listed in the savefile. However, the default value can be +very useful information so it is provided in a comment.</PARA> +<PARA>Occasionally the user will want to do some experimentation, +and temporarily switch an option from a user value back to a default +or inferred one to see what the effect would be. This could be achieved +by simply commenting out the user value. For instance, if the current +savefile contains:</PARA> +<SCREEN> +cdl_option CYGMFN_KERNEL_SYNCH_CONDVAR_TIMED_WAIT { +# Flavor: bool +user_value 1 +# The inferred value should not be edited directly. +inferred_value 0 +# value_source user +# Default value: 1 +... +}; + +</SCREEN> +<PARA>then the inferred value could be restored by commenting out +or removing the <literal>user_value</literal> line:</PARA> +<SCREEN> +cdl_option CYGMFN_KERNEL_SYNCH_CONDVAR_TIMED_WAIT { +# Flavor: bool +# user_value 1 +# The inferred value should not be edited directly. +inferred_value 0 +# value_source user +# Default value: 1 +... +}; + +</SCREEN> +<PARA>This is fine for simple values. However if the value is complicated +then there is a problem: commenting out the <LITERAL>user_value</LITERAL> line +or lines means that the user value becomes invisible to the configuration system, +so if the savefile is loaded and then regenerated the information +will be lost. An alternative approach is to keep the <LITERAL>user_value</LITERAL> but +explicitly set the <LITERAL>value_source</LITERAL> line, +for example:</PARA> +<SCREEN> + +cdl_option CYGMFN_KERNEL_SYNCH_CONDVAR_TIMED_WAIT { +# Flavor: bool +user_value 1 +# The inferred value should not be edited directly. +inferred_value 0 +value_source inferred +# Default value: 1 +... +}; + +</SCREEN> +<PARA>In this case the configuration system will use the inferred +value for the purposes of dependency analysis etc., even though +a user value is present. To restore the user value the <LITERAL>value_source</LITERAL> line +can be commented out again. If there is no explicit <LITERAL>value_source</LITERAL> then +the configuration system will just use the highest priority one: +the user value if it exists; otherwise the inferred value if it +exists; otherwise the default value which always exists.</PARA> +<PARA>The default value for an option can be a simple constant, +or it can be an expression involving other options. In the latter +case the expression will be listed, together with the values for +all options referenced in the expression and the current result +of evaluating that expression. This is for informational purposes +only, the default value is always recalculated deterministically +when loading in a savefile.</PARA> +<SCREEN> + +cdl_option CYGBLD_GLOBAL_COMMAND_PREFIX { +# Flavor: data +# No user value, uncomment the following line to provide one. +# user_value arm-elf +# value_source default +# Default value: CYGHWR_THUMB ? “thumb-elf” : “arm-elf” +# CYGHWR_THUMB == 0 +# --> arm-elf +}; + +</SCREEN> +<PARA>For options with the data or booldata flavor, there are likely +to be constraints on the possible values. If the value is supposed +to be a number in a given range and a user value of “<LITERAL>hello +world</LITERAL>” is provided instead then there +are likely to be compile-time failures. Component developers can +specify constraints on the legal values, and these will be listed +in the savefile.</PARA> +<SCREEN> +cdl_option X_TLOSS { +# Flavor: data +# No user value, uncomment the following line to provide one. +# user_value 1.41484755040569E+16 +# value_source default +# Default value: 1.41484755040569E+16 +# Legal values: 1 to 1e308 +}; + +</SCREEN> +<SCREEN>cdl_component CYGNUM_LIBM_COMPATIBILITY { +# Flavor: booldata +# No user value, uncomment the following line to provide one. +# user_value 1 POSIX +# value_source default +# Default value: 1 POSIX +# Legal values: “POSIX” “IEEE” “XOPEN” “SVID” +... +}; + +</SCREEN> +<PARA>In some cases the legal values list may be an expression involving +other options. If so then the current values of the referenced options +will be listed, together with the result of evaluating the list +expression, just as for default value expressions.</PARA> +<PARA>If an illegal value is provided then this will result in a +conflict, listed in the conflicts section of the savefile. For more +complicated options a simple legal values list is not sufficient +to allow the current value to be validated, and the configuration +system will be unable to flag conflicts. This issue will be addressed in +future releases of the configuration system.</PARA> +<PARA>Following the value-related fields for a given option, any <EMPHASIS>requires</EMPHASIS> constraints belonging +to this option will be listed. These constraints are only effective +if the option is active and, for bool and booldata flavors, enabled. +If some aspect of <productname>eCos</productname> functionality is inactive or disabled then +it cannot impose any constraints on the rest of the system. As usual, +the full expression will be listed followed by the current values +of all options that are referenced and the result of evaluating +the expression:</PARA> +<SCREEN> + +cdl_option CYGSEM_LIBC_TIME_TIME_WORKING { +... +# Requires: CYGPKG_DEVICES_WALLCLOCK +# CYGPKG_DEVICES_WALLCLOCK == current +# --> 1 +}; + +</SCREEN> +<PARA>When modifying the value of an option it is useful to know +not only what constraints the option imposes on the rest of the +system but also what other options in the system depend in some +way on this one. The savefile provides this information:</PARA> +<SCREEN>cdl_option CYGFUN_KERNEL_THREADS_TIMER { +... +# The following properties are affected by this value +# option CYGMFN_KERNEL_SYNCH_CONDVAR_TIMED_WAIT +# Requires: CYGFUN_KERNEL_THREADS_TIMER +# option CYGIMP_UITRON_STRICT_CONFORMANCE +# Requires: CYGFUN_KERNEL_THREADS_TIMER +# option CYGSEM_LIBC_TIME_CLOCK_WORKING +# Requires: CYGFUN_KERNEL_THREADS_TIMER +}; + +</SCREEN> +</SECT2> +<SECT2> +<TITLE>Tcl Syntax</TITLE> +<PARA><productname>eCos</productname> savefiles are implemented as Tcl scripts, and are read +in by running the data through a standard Tcl interpreter that has +been extended with a small number of additional commands such as <LITERAL>cdl_option</LITERAL> and <LITERAL>cdl_configuration</LITERAL>. +In many cases this is an implementation detail that can be safely +ignored while editing a savefile: simply replacing a <LITERAL>1</LITERAL> with +a <LITERAL>0</LITERAL> to disable some functionality +is not going to affect whether or not the savefile is still a valid +Tcl script and can be processed by a Tcl interpreter. However, there +are more complicated cases where an understanding of Tcl syntax +is at least desirable, for example:</PARA> +<SCREEN> + +cdl_option CYGDAT_UITRON_MEMPOOLVAR_EXTERNS { + # Flavor: data + user_value \ + “static char vpool1\[ 2000 \], \\ + vpool2\[ 2000 \], \\ + vpool3\[ 2000 \];” +# value_source default +# Default value: \ + # “static char vpool1\[ 2000 \], \\ + # vpool2\[ 2000 \], \\ + # vpool3\[ 2000 \];” +}; + +</SCREEN> +<PARA>The backslash at the end of the <LITERAL>user_value</LITERAL> line +is processed by the Tcl interpreter as a line continuation character. +The quote marks around the user data are also interpreted by the +Tcl interpreter and serve to turn the entire data field into a single +argument. The backslashes preceding the opening and closing square +brackets prevent the Tcl interpreter from treating these characters +specially, otherwise there would be an attempt at <EMPHASIS>command +substitution</EMPHASIS> as described below. The double backslashes +at the end of each line of the data will be turned into a single +backslash by the Tcl interpreter, rather than escaping the newline +character, so that the actual data seen by the configuration system +is:</PARA> +<SCREEN> + +static char vpool1[ 2000 ], \ + vpool2[ 2000 ], \ + vpool3[ 2000 ]; + +</SCREEN> +<PARA>This is of course the data that should end up in the µITRON +configuration header file. The opening and closing braces surrounding +the entire body of the option data are also significant and cause +this body to be passed as a single argument to the <command>cdl_option</command> command. +The closing semicolon is optional in this example, but provides +a small amount of additional robustness if the savefile is edited +such that it is no longer a valid Tcl script. If the data contained +any <LITERAL>$</LITERAL> characters then +these would have to be treated specially as well, via a backslash escape.</PARA> +<PARA>In spite of what all the above might seem to suggest, Tcl +is actually a very simple yet powerful scripting language: the syntax +is defined by just eleven rules. On occasion this simplicity means +that Tcl’s behaviour is subtly different from other languages, +which can confuse newcomers.</PARA> +<PARA>When the Tcl interpreter is passed some data such as <LITERAL>puts +Hello</LITERAL>, it splits this data into a command and its +arguments. The command will be terminated by a newline or by a semicolon, +unless one of the quoting mechanisms is used. The command and each +of its arguments are separated by white space. So in the following +example:</PARA> +<SCREEN>puts Hello +set x 42 </SCREEN> +<PARA>will result in two separate commands being executed. The first +command is <LITERAL>puts</LITERAL> and is passed a +single argument, <LITERAL>Hello</LITERAL>. The second +command is <LITERAL>set</LITERAL> and is passed two +arguments, <LITERAL>x</LITERAL> and <LITERAL>42</LITERAL>. +The intervening newline character serves to terminate the first +command, and a semi-colon separator could be used instead: </PARA> +<programlisting>puts Hello;set x 42</programlisting> +<PARA>Any white space surrounding the semicolon is just ignored +because it does not serve to separate arguments.</PARA> +<PARA>Now consider the following:</PARA> +<SCREEN>set x Hello world</SCREEN> +<PARA>This is not valid Tcl. It is an attempt to invoke the <LITERAL>set</LITERAL> command +with three arguments: <LITERAL>x</LITERAL>, <LITERAL>Hello</LITERAL>, +and <LITERAL>world</LITERAL>. The <LITERAL>set</LITERAL> only +takes two arguments, a variable name and a value, so it is necessary +to combine the data into a single argument by quoting:</PARA> +<PROGRAMLISTING>set x “Hello world”</PROGRAMLISTING> +<PARA>When the Tcl interpreter encounters the first quote character +it treats all subsequent data up to but not including the closing +quote as part of the current argument. The quote marks are removed +by the interpreter, so the second argument passed to the <LITERAL>set</LITERAL> command +is just <LITERAL>Hello world</LITERAL> without the +quote characters. This can be significant in the context of <productname>eCos</productname> savefiles. +For instance, consider the following configuration option:</PARA> +<SCREEN> + +cdl_option CYGDAT_LIBC_STDIO_DEFAULT_CONSOLE { +# Flavor: data +# No user value, uncomment the following line to provide one. +# user_value “\”/dev/ttydiag\”” +# value_source default +# Default value: “\”/dev/ttydiag\”” +}; + +</SCREEN> +<PARA>The desired value of the configuration option should be a +valid C string, complete with quote characters. If the savefile +was edited to: </PARA> +<SCREEN> + +cdl_option CYGDAT_LIBC_STDIO_DEFAULT_CONSOLE { +# Flavor: data +user_value “/dev/ttydiag” +# value_source default +# Default value: “\”/dev/ttydiag\”” +}; + +</SCREEN> +<PARA>then the Tcl interpreter would remove the quote marks when +the savefile is read back in, so the option’s value would +not have any quote marks and would not be a valid C string. The +configuration system is not yet able to perform the required validation +so the following <LITERAL>#define</LITERAL> would +be generated in the configuration header file:</PARA> +<PROGRAMLISTING>#define CYGDAT_LIBC_STDIO_DEFAULT_CONSOLE /dev/ttydiag </PROGRAMLISTING> +<PARA>This is likely to cause a compile-time failure when building +<productname>eCos</productname>.</PARA> +<PARA>A quoted argument continues until the closing quote character +is encountered, which means that it can span multiple lines. This +can also be encountered in <productname>eCos</productname> savefiles, for instance, in the <literal>CYGDAT_UITRON_MEMPOOLVAR_EXTERNS</literal> example +mentioned earlier. Newline or semicolon characters do not terminate +the current command in such cases.</PARA> +<PARA>The Tcl interpreter supports much the same forms of backslash +substitution as other common programming languages. Some backslash +sequences such as <literal>\n</literal> will +be replaced by the appropriate character. The sequence <literal>\\</literal> will +be replaced by a single backslash. A backslash at the very end of +a line will cause that backslash, the newline character, and any +white space at the start of the next line to be replaced by a single +space. Hence the following two Tcl commands are equivalent:</PARA> +<PROGRAMLISTING>puts “Hello\nworld\n” +puts \ +“Hello +world +“</PROGRAMLISTING> +<PARA>In addition to quote and backslash characters, the Tcl interpreter +treats square brackets, the <literal>$</literal> character, +and braces specially. Square brackets are used for command substitution, +for example:</PARA> +<PROGRAMLISTING>puts “The answer is [expr 6 * 9]”</PROGRAMLISTING> +<PARA>When the Tcl interpreter encounters the square brackets it +will treat the contents as another command that should be executed +first, and the result of executing that is used when continuing +to process the script. In this case the Tcl interpreter will execute +the command <literal>expr 6 * 9</literal>, +yielding a result of 54, and then the Tcl interpreter will execute +<literal>puts “The answer is 54”</literal>. It should be noted that +the interpreter contains only one level of substitution: if the +result of performing command substitution performs further special +characters such as square brackets then these will not be treated +specially.</PARA> +<PARA>Command line substitution is very unlikely to prove useful +in the context of an <productname>eCos</productname> savefile, but it is part of the Tcl language +and hence cannot be easily suppressed while reading in a savefile. +As a result care has to be taken when savefile data involves square +brackets. Consider the following:</PARA> +<PROGRAMLISTING> + +cdl_option CYGDAT_UITRON_MEMPOOLFIXED_EXTERNS { + ... + user_value \ +“static char fpool1[ 2000 ], +fpool2[ 2000 ];” + ... +}; +</PROGRAMLISTING> +<PARA>The Tcl interpreter will interpret the square brackets as +an attempt at command substitution and hence it will attempt to +execute the command <literal>2000</literal> with no +arguments. No such command is defined by the Tcl language or by +the savefile-related extensions provided by the configuration system, +so this will result in an error when an attempt is made to read +back the savefile. Instead it is necessary to backslash-escape the +square brackets and thus suppress command substitution:</PARA> +<PROGRAMLISTING> + +cdl_option CYGDAT_UITRON_MEMPOOLFIXED_EXTERNS { + ... + user_value \ +“static char fpool1\[ 2000 \], +fpool2\[ 2000 \];” + ... +}; </PROGRAMLISTING> +<PARA>Similarly the <literal>$</literal> character +is used in Tcl scripts to perform variable substitution:</PARA> +<PROGRAMLISTING>set x [expr 6 * 9] +puts “The answer is $x” </PROGRAMLISTING> +<PARA>Variable substitution, like command substitution, is very +unlikely to prove useful in the context of an <productname>eCos</productname> savefile. Should +it be necessary to have a <literal>$</literal> character +in configuration data then again a backslash escape needs to be +used.</PARA> +<PROGRAMLISTING>cdl_option FOODAT_MONITOR_PROMPT { + ... + user_value “\$ “ + ... +};</PROGRAMLISTING> +<PARA>Braces are used to collect a sequence of characters into a +single argument, just like quotes. The difference is that variable, +command and backslash substitution do not occur inside braces (with +the sole exception of backslash substitution at the end of a line). +So, for example, the <literal>CYGDAT_UITRON_MEMPOOL_EXTERNFIXED_EXTERNS</literal> value +could be written as:</PARA> +<PROGRAMLISTING>cdl_option CYGDAT_UITRON_MEMPOOLFIXED_EXTERNS { + ... + user_value \ +{static char fpool1[ 2000 ], +fpool2[ 2000 ];} + ... +};</PROGRAMLISTING> +<PARA>The configuration system does not use this when generating +savefiles because for simple edits of a savefile by inexperienced +users the use of brace characters is likely to be a little bit more +confusing than the use of quotes.</PARA> +<PARA>At this stage it is worth noting that the basic format of +each configuration option in the savefile makes use of braces:</PARA> +<PROGRAMLISTING>cdl_option <name> { + ... +};</PROGRAMLISTING> +<PARA>The configuration system extends the Tcl language with a small +number of additional commands such as <LITERAL>cdl_option</LITERAL>. +These commands take two arguments, a name and a body, where the +body consists of all the text between the braces. First a check +is made that the specified option is actually present in the configuration. +Then the body is executed in a recursive invocation of the Tcl interpreter, +this time with additional commands such as <LITERAL>user_value</LITERAL> and <LITERAL>value_source</LITERAL>. +If, after editing, the braces are not correctly matched up then +the savefile will no longer be a valid Tcl script and errors will +be reported when the savefile is loaded again.</PARA> +<PARA>Comments in Tcl scripts are introduced by a hash character <LITERAL>#</LITERAL>. +However, a hash character only introduces a comment if it occurs +where a command is expected. Consider the following:</PARA> +<PROGRAMLISTING># This is a comment +puts “Hello” # world </PROGRAMLISTING> +<PARA>The first line is a valid comment, since the hash character +occurs right at the start where a command name is expected. The +second line does not contain a comment. Instead it is an attempt +to invoke the <LITERAL>puts</LITERAL> command with +three arguments: <LITERAL>Hello</LITERAL>, <LITERAL>#</LITERAL> and <LITERAL>world</LITERAL>. +These are not valid arguments for the <LITERAL>puts</LITERAL> command +so an error will be raised.</PARA> +<PARA>If the second line was rewritten as:</PARA> +<PROGRAMLISTING>puts “Hello”; # world</PROGRAMLISTING> +<PARA>then this is a valid Tcl script. The semicolon identifies +the end of the current command, so the hash character occurs at +a point where the next command would start and hence it is interpreted +as the start of a comment.</PARA> +<PARA>This handling of comments can lead to subtle behaviour. Consider +the following:</PARA> +<PROGRAMLISTING>cdl_option WHATEVER { + # This is a comment } + user_value 42 + ... +}</PROGRAMLISTING> +<PARA>Consider the way the Tcl interpreter processes this. The command +name and the first argument do not pose any special difficulties. +The opening brace is interpreted as the start of the next argument, +which continues until a closing brace is encountered. In this case +the closing brace occurs on the second line, so the second argument +passed to <LITERAL>cdl_option</LITERAL> is <literal>\n # This is a comment</LITERAL> . This second argument +is processed in a recursive invocation of the Tcl interpreter and +does not contain any commands, just a comment. Toplevel savefile +processing then resumes, and the next command that is encountered +is <LITERAL>user_value</LITERAL>. Since the +relevant savefile code is not currently processing a configuration +option this is an error. Later on the Tcl interpreter would encounter +a closing brace by itself, which is also an error. Fortunately this +sequence of events is very unlikely to occur when editing generated +savefiles.</PARA> +<PARA>This should be sufficient information about Tcl to allow for +safe editing of <productname>eCos</productname> savefiles. Further information is available +from a wide variety of sources, for example the book <EMPHASIS>Tcl +and the Tk Toolkit </EMPHASIS>by John K Ousterhout.</PARA> +</SECT2> +</SECT1> +<SECT1 id="editing-the-sources"> +<TITLE>Editing the Sources</TITLE> +<PARA>For many users, controlling the packages and + manipulating the available configuration options will be + sufficient to create an embedded operating system that meets + the application's requirements. However, since <productname>eCos</productname> is + shipped entirely in source form, it is possible to go + further when necessary: you can edit the <productname>eCos</productname> <!-- + <index></index> -->sources themselves. This requires some + understanding of the way the <productname>eCos</productname> build system works. + </PARA> +<PARA>The most obvious place to edit the source code is directly +in the <!-- <index></index> -->component repository. For example, you could +edit the file <filename>kernel/<replaceable>&Version;</replaceable>/src/sync/mutex.cxx</filename> +to change the way kernel mutexes work, or possibly just to add some +extra diagnostics or assertions. Once the file has been edited, +it is possible to invoke <command>make</command> at +the top level of the build tree and the target library will be rebuilt +as required. A small optimization is possible: the build tree is +largely a mirror of the component repository, so it too will contain +a subdirectory <filename>kernel/<replaceable>&Version;</replaceable></filename>; +if make is invoked in this directory +then it will only check for changes to the kernel sources, which +is a bit more efficient than checking for changes throughout the component +repository. </PARA> +<PARA>Editing a file in the component repository is fine if this +tree is used for only one <productname>eCos</productname> configuration. If the repository +is used for several different configurations, however, and especially +if it is shared by multiple users, then making what may be experimental +changes to the master sources would be a bad idea. The build system provides +an alternative. It is possible to make a copy of the file in the +build tree, in other words copy <filename>mutex.cxx</filename> from +the <filename>kernel/<replaceable>&Version;</replaceable>/src/sync</filename> directory +in the component repository to <filename>kernel/<replaceable>&Version;</replaceable>/src/sync</filename> in +the build tree, and edit the file in the build tree. When <command>make</command> is +invoked it will pick up local copies of any of the sources in preference +to the master versions in the component repository. Once you have +finished modifying the <productname>eCos</productname> sources you can install the final version +back in the component repository. If the changes were temporary +in nature and only served to aid the debugging process, then you +can discard the modified version of the sources. </PARA> +<PARA>The situation is slightly more complicated for the header +files that a package may export, such as the C library’s <filename>stdio.h</filename> header +file, which can be found in the directory <filename>language/c/libc/<replaceable>&Version;</replaceable>/include</filename>. +If such a header file is changed, either directly in the component +repository or after copying it to the build tree, then <command>make</command> must +be invoked at the top level of the build tree. In cases like this +it is not safe to rebuild just the C library because other packages +may depend on the contents of <filename>stdio.h</filename>. </PARA> +</SECT1> +<SECT1 id="modifying-the-memory-layout"> +<TITLE>Modifying the Memory Layout</TITLE> +<PARA>Each <productname>eCos</productname> platform package is supplied with linker script +fragments which describe the location of memory regions on the evaluation +board and the location of memory sections within these regions. +The correct linker script fragment is selected and included in the +<productname>eCos</productname> linker script <!-- <index></index> --><filename>target.ld</filename> when +<productname>eCos</productname> is built.</PARA> +<PARA>It is not necessary to <!-- <index></index> -->modify the default memory +layouts in order to start development with <productname>eCos</productname>. However, it will +be necessary to edit a linker script fragment when the memory map +of the evaluation board is changed. For example, if additional memory +is added, the linker must be notified that the new memory is available +for use. As a minimum, this would involve modifying the length of +the corresponding memory region. Where the available memory is non-contiguous, +it may be necessary to declare a new memory region and reassign +certain linker output sections to the new region.</PARA> +<PARA>Linker script fragments and memory layout header files should +be <!-- <index></index> -->edited within the <productname>eCos</productname> install tree. They are +located at <filename>include/pkgconf/mlt_*.*</filename>. +Where multiple start-up types are in use, it will be necessary to +edit multiple linker script fragments and header files. The information +provided in the header file and the corresponding linker script +fragment must always match. A typical linker script fragment is +shown below:</PARA> +<EXAMPLE><!-- <index></index> --> +<TITLE><productname>eCos</productname> linker script fragment</TITLE> +<PROGRAMLISTING>MEMORY +{ + rom : ORIGIN = 0x40000000, LENGTH = 0x80000 + ram : ORIGIN = 0x48000000, LENGTH = 0x200000 +} + +SECTIONS +{ + SECTIONS_BEGIN + SECTION_rom_vectors (rom, 0x40000000, LMA_EQ_VMA) + SECTION_text (rom, ALIGN (0x1), LMA_EQ_VMA) + SECTION_fini (rom, ALIGN (0x1), LMA_EQ_VMA) + SECTION_rodata (rom, ALIGN (0x1), LMA_EQ_VMA) + SECTION_rodata1 (rom, ALIGN (0x1), LMA_EQ_VMA) + SECTION_fixup (rom, ALIGN (0x1), LMA_EQ_VMA) + SECTION_gcc_except_table (rom, ALIGN (0x1), LMA_EQ_VMA) + SECTION_data (ram, 0x48000000, FOLLOWING (.gcc_except_table)) + SECTION_bss (ram, ALIGN (0x4), LMA_EQ_VMA) + SECTIONS_END +}</PROGRAMLISTING> +</EXAMPLE> +<PARA>The file consists of two blocks, the <literal>MEMORY</literal> block +contains lines describing the address (<literal>ORIGIN</literal>) +and the size (<literal>LENGTH</literal>) of each memory +region. The <literal>MEMORY</literal> block is followed +by the <literal>SECTIONS</literal> block which contains +lines describing each of the linker output sections. Each section +is represented by a macro call. The arguments of these macros are +ordered as follows: </PARA> +<ORDEREDLIST> +<LISTITEM> +<PARA>The memory region in which the section will finally + reside.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>The final address ( +<LITERAL>VMA</LITERAL> +) of the section. This is expressed using one of the following forms:</PARA> +<VARIABLELIST> +<VARLISTENTRY> +<TERM><EMPHASIS>n</EMPHASIS></TERM> +<LISTITEM> +<PARA>at the absolute address specified by the + unsigned integer <EMPHASIS>n</EMPHASIS></PARA> +</LISTITEM> +</VARLISTENTRY> +<VARLISTENTRY> +<TERM>ALIGN (<EMPHASIS>n</EMPHASIS>)</TERM> +<LISTITEM> +<PARA>following the final location of the previous section + with alignment to the next <EMPHASIS>n</EMPHASIS>-byte + boundary</PARA> +</LISTITEM> +</VARLISTENTRY> +</VARIABLELIST> +</LISTITEM> +<LISTITEM> +<PARA>The initial address (<LITERAL>LMA</LITERAL>) + of the section. This is expressed using one of the + following forms:</PARA> +<VARIABLELIST> +<VARLISTENTRY> +<TERM>LMA_EQ_VMA</TERM> +<LISTITEM> +<PARA>the <LITERAL>LMA</LITERAL> + equals the <LITERAL>VMA</LITERAL> (no relocation)</PARA> +</LISTITEM> +</VARLISTENTRY> +<VARLISTENTRY> +<TERM>AT (<EMPHASIS>n</EMPHASIS>)</TERM> +<LISTITEM> +<PARA>at the absolute address specified by the + unsigned integer <EMPHASIS>n</EMPHASIS></PARA> +</LISTITEM> +</VARLISTENTRY> +<VARLISTENTRY> +<TERM>FOLLOWING (.<EMPHASIS>name</EMPHASIS>)</TERM> +<LISTITEM> +<PARA>following the initial location of section + <EMPHASIS>name</EMPHASIS></PARA> +</LISTITEM> +</VARLISTENTRY> +</VARIABLELIST> +</LISTITEM> +</ORDEREDLIST> +<PARA>In order to maintain compatibility with linker script + fragments and header files exported by the + <productname>eCos</productname> <APPLICATION>Configuration Tool</APPLICATION>, the use + of other expressions within these files is not + recommended.</PARA> +<PARA>Note that the names of the linker output sections will vary +between target architectures. A description of these sections can +be found in the specific <productname>GCC</productname> documentation for +your architecture.</PARA> +</SECT1> +</CHAPTER> +<CHAPTER id="managing-package-repository"> +<TITLE>Managing the <!-- <index></index> -->Package Repository</TITLE> +<PARA>A source distribution of <productname>eCos</productname> consists of a number of + packages, such as the kernel, the C library, and the + µITRON subsystems. These are + individually versioned in the tree structure of the source + code, to support distribution on a per-package basis and to + support third party packages whose versioning systems might be + different. The <productname>eCos</productname> <application>Package + Administration Tool</application> is used to manage the + installation and removal of packages from a variety of sources + with potentially multiple versions.</PARA> +<PARA>The presence of the version information in the source tree + structure might be a hindrance to the use of a separate source + control system such as <EMPHASIS>CVS</EMPHASIS> or + <EMPHASIS>SourceSafe</EMPHASIS>. To work + in this way, you can rename all the version components to some + common name (such as “current”) thus unifying the + structure of source trees from distinct <productname>eCos</productname> releases.</PARA> +<PARA>The <productname>eCos</productname> build system will treat any such name as just another +version of the package(s), and support building in exactly the same +way. However, performing this rename invalidates any existing build +trees that referred to the versioned source tree, so do the rename +first, before any other work, and do a complete rebuild afterwards.</PARA> +<SECT1 id="package-installation"> +<TITLE>Package Installation</TITLE> +<PARA>Package installation and removal is performed using the + <productname>eCos</productname> <application>Package Administration Tool</application>. This + tool is a Tcl script named + <command>ecosadmin.tcl</command> which allows + the user to add new <productname>eCos</productname> packages and new versions of + existing packages to an <productname>eCos</productname> repository. Such packages must + be distributed as a single file in the <productname>eCos</productname> package + distribution format. Unwanted packages may also be removed + from the repository using this tool. A graphical version of + the tool is provided as part of the + <productname>eCos</productname> <application>Configuration Tool</application>.</PARA> +<SECT2> +<TITLE>Using the Administration Tool</TITLE> <PARA>The graphical +version of the <productname>eCos</productname> <application>Package +Administration Tool</application>, provided as part of the +<productname>eCos</productname> <application>Configuration +Tool</application>, provides functions equivalent to the command-line +version for those who prefer a Windows-based interface.</PARA> +<PARA>It may be invoked in one of two ways:</PARA> +<ITEMIZEDLIST> +<LISTITEM> +<PARA>from the <GUIMENU>start menu</GUIMENU> (by default + <GUIMENUITEM>Start->Programs-> + eCos->Package Administration + Tool</GUIMENUITEM>)</PARA> +<!-- +<para> +XXXXX What is the Windows menu structure now? XXXXX +</para> +--> + +</LISTITEM> +<LISTITEM> +<PARA>from the <productname>eCos</productname> <APPLICATION>Configuration + Tool</APPLICATION> via the + <GUIMENUITEM>Tools->Administration</GUIMENUITEM> + menu item</PARA> +</LISTITEM> +</ITEMIZEDLIST> +<PARA><GRAPHIC ENTITYREF="graphic31"></GRAPHIC></PARA> +<PARA>The main window of the tool displays the packages which are +currently installed in the form of a tree. The installed versions +of each package may be examined by expanding the tree.</PARA> +<PARA>Packages may be added to the <productname>eCos</productname> repository by clicking on +the <EMPHASIS>Add</EMPHASIS> button. The <productname>eCos</productname> package distribution +file to be added is then selected via a <EMPHASIS>File Open</EMPHASIS> dialog +box.</PARA> +<PARA>Packages may be removed by selecting a package in the tree +and then clicking on the <EMPHASIS>Remove</EMPHASIS> button. If +a package node is selected, all versions of the selected package +will be removed. If a package version node is selected, only the +selected version of the package will be removed.</PARA> +</SECT2> +<SECT2> +<TITLE>Using the command line</TITLE> +<PARA>The <command>ecosadmin.tcl</command> + script is located in the base of the <productname>eCos</productname> repository. Use + a command of the following form under versions of + UNIX:</PARA> +<SCREEN>$ tclsh ecosadmin.tcl <command></SCREEN> +<PARA>Under Windows, a command of the following form may be used +at the Cygwin command line prompt:</PARA> +<SCREEN>$ cygtclsh80 ecosadmin.tcl <command></SCREEN> +<PARA>The following commands are available:</PARA> +<VARIABLELIST> +<VARLISTENTRY> +<TERM><COMMAND>add <file></COMMAND></TERM> +<LISTITEM><!-- <index></index> --> +<PARA>Adds the packages contained with the specified package distribution +file to the <productname>eCos</productname> repository and updates the package database accordingly. +By convention, <productname>eCos</productname> package distribution files are given the <filename>.epk</filename> suffix.</PARA> +</LISTITEM> +</VARLISTENTRY> +<VARLISTENTRY> +<TERM><COMMAND>remove <package> [ --version=<version> ]</COMMAND></TERM><!-- <index></index> --> +<LISTITEM> +<PARA>Removes the specified package from the <productname>eCos</productname> + repository and updates the package database + accordingly. Where the optional version qualifier is + used, only the specified version of the package is + removed.</PARA> +</LISTITEM> +</VARLISTENTRY> +<VARLISTENTRY> +<TERM><COMMAND>list</COMMAND></TERM><!-- <index></index> --> +<LISTITEM> +<PARA>Produces a list of the packages which + are currently installed and their versions. The + available templates and hardware targets are also + listed.</PARA> +</LISTITEM> +</VARLISTENTRY> +</VARIABLELIST> +<PARA>Note that is is possible to remove critical packages + such as the common HAL package using this tool. Users + should take care to avoid such errors since core <productname>eCos</productname> + packages may only be re-installed in the context of a + complete re-installation of <productname>eCos</productname>.</PARA> +</SECT2> +</SECT1> +<SECT1 id="package-structure"> +<TITLE>Package Structure</TITLE> +<PARA>The files in an installed <productname>eCos</productname> source tree are organized in +a natural tree structure, grouping together files which work together +into <EMPHASIS>Packages</EMPHASIS>. For example, the kernel files +are all together in: </PARA> +<SIMPLELIST> +<MEMBER><FILENAME><REPLACEABLE>BASE_DIR</REPLACEABLE>/kernel/<replaceable>&Version;</replaceable>/include/</FILENAME></MEMBER> +<MEMBER> <FILENAME><REPLACEABLE>BASE_DIR</REPLACEABLE>/kernel/<replaceable>&Version;</replaceable>/src/</FILENAME></MEMBER> +<MEMBER> <FILENAME><REPLACEABLE>BASE_DIR</REPLACEABLE>/kernel/<replaceable>&Version;</replaceable>/tests/</FILENAME></MEMBER> +</SIMPLELIST> +<PARA>and µITRON compatibility layer files are in: + </PARA> +<SIMPLELIST> +<MEMBER> <FILENAME><REPLACEABLE>BASE_DIR</REPLACEABLE>/compat/uitron/<replaceable>&Version;</replaceable>/include/</FILENAME></MEMBER> +<MEMBER> <FILENAME><REPLACEABLE>BASE_DIR</REPLACEABLE>/compat/uitron/<replaceable>&Version;</replaceable>/src/</FILENAME></MEMBER> +<MEMBER> <FILENAME><REPLACEABLE>BASE_DIR</REPLACEABLE>/compat/uitron/<replaceable>&Version;</replaceable>/tests/</FILENAME></MEMBER> +</SIMPLELIST> +<PARA>The feature of these names which is of interest here is + the <replaceable>&Version;</replaceable> near the end. It may seem odd to place a version number deep in the + path, rather than having something like + <FILENAME><REPLACEABLE>BASE_DIR</REPLACEABLE>/<replaceable>&Version;</replaceable>/...everything...</FILENAME> + or leaving it up to you to choose a different + install-place when a new release of the system arrives. + </PARA> +<PARA>There is a rationale for this organization: as + indicated, the kernel and the + µITRON compatibility subsystem + are examples of software packages. For the first few + releases of <productname>eCos</productname>, all the packages will move along + in step, i.e. Release 1.3.x will feature Version + 1.3.x of every package, and so forth. But in future, + especially when third party packages become available, it is + intended that the package be the unit of software + distribution, so it will be possible to build a system from + a selection of packages with different version numbers, and + even differing versioning <EMPHASIS>schemes</EMPHASIS>. A + Tcl script <command>ecosadmin.tcl</command> is + provided in the <productname>eCos</productname> repository to manage the installation + and removal of packages in this way.</PARA> +<PARA>Many users will have their own source code control system, +version control system or equivalent, and will want to use it with +<productname>eCos</productname> sources. In that case, since a new release of <productname>eCos</productname> comes with +different pathnames for all the source files, a bit of work is necessary +to import a new release into your source repository. </PARA> +<PARA>One way of handling the import is to rename all the version +parts to some common name, for example “current”, +and continue to work. “current” is suggested because <command>ecosconfig</command> recognizes +it and places it first in any list of versions. In the future, we +may provide a tool to help with this, or an option in the install +wizard. Alternatively, in a POSIX shell environment (Linux or Cygwin +on Windows) use the following command: </PARA> +<SCREEN>find . -name <replaceable>&Version;</replaceable> -type d -printf 'mv %p %h/current\n' | sh</SCREEN> +<PARA>Having carried out such a renaming operation, your + source tree will now look like this: </PARA> +<SCREEN><REPLACEABLE>BASE_DIR</REPLACEABLE>/kernel/current/include/ +<REPLACEABLE>BASE_DIR</REPLACEABLE>/kernel/current/src/ +<REPLACEABLE>BASE_DIR</REPLACEABLE>/kernel/current/tests/ + ... +<REPLACEABLE>BASE_DIR</REPLACEABLE>/compat/uitron/current/include/ +<REPLACEABLE>BASE_DIR</REPLACEABLE>/compat/uitron/current/src/ +<REPLACEABLE>BASE_DIR</REPLACEABLE>/compat/uitron/current/tests/ + </SCREEN> +<PARA>which is a suitable format for import into your own + source code control system. When you get a subsequent + release of <productname>eCos</productname>, do the same thing and use your own source + code control system to manage the new source base, by + importing the new version from </PARA> +<SCREEN><REPLACEABLE>NEW_BASE_DIR</REPLACEABLE>/kernel/current/include/</SCREEN> +<PARA>and so on. </PARA> +<PARA>The <productname>eCos</productname> build tool will now offer only the + “current” version of each package; select this + for the packages you wish to use. </PARA> +<PARA>Making such a change has implications for any build + trees you already have in use. A configured build tree + contains information about the selected packages and their + selected versions. Changing the name of the + “versioning” folder in the source tree + invalidates this information, and in consequence it also + invalidates any local configuration options you have set up + in this build tree. So if you want to change the version + information in the source tree, do it first, before + investing any serious time in configuring and building your + system. When you create a new build tree to deal with the + new source layout, it will contain default settings for all + the configuration options, just like the old build tree did + before you configured it. You will need to redo that + configuration work in the new tree. </PARA> +<PARA>Moving source code around also invalidates debugging information +in any programs or libraries built from the old tree; these will +need to be rebuilt. </PARA> +</SECT1> +</CHAPTER> +</PART> +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:nil +sgml-shorttag:t +sgml-namecase-general:t +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:2 +sgml-indent-data:t +sgml-parent-document:("user-guide.sgml" "book" "part") +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> diff --git a/ecos/doc/sgml/user-guide/ecos-license.sgml b/ecos/doc/sgml/user-guide/ecos-license.sgml new file mode 100644 index 0000000..c7b889d --- /dev/null +++ b/ecos/doc/sgml/user-guide/ecos-license.sgml @@ -0,0 +1,380 @@ +<!-- {{{ Banner --> + +<!-- =============================================================== --> +<!-- --> +<!-- config-tool.sgml --> +<!-- --> +<!-- eCos User Guide --> +<!-- --> +<!-- =============================================================== --> +<!-- ####ECOSDOCCOPYRIGHTBEGIN#### --> +<!-- =============================================================== --> +<!-- Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002 Free Software Foundation, 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 --> +<!-- =============================================================== --> +<!-- ####ECOSDOCCOPYRIGHTEND#### --> +<!-- =============================================================== --> +<!-- #####DESCRIPTIONBEGIN#### --> +<!-- --> +<!-- ####DESCRIPTIONEND#### --> +<!-- =============================================================== --> + +<!-- }}} --> + +<APPENDIX ID="GNU-GENERAL-PUBLIC-LICENSE"> + <docinfo> + <edition>Version 2, June 1991</edition> + <copyright> + <year>1989</year> + <year>1991</year> + <holder>Free Software Foundation, Inc.</holder> + </copyright> + <address>59 Temple Place, Suite 330, Boston, MA 02111-1307 USA</address> + </docinfo> +<TITLE>GNU General Public License</TITLE> +<LITERALLAYOUT> + Copyright (C) 1989, 1991 Free Software Foundation, Inc. + 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + Preamble + + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +License is intended to guarantee your freedom to share and change free +software--to make sure the software is free for all its users. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +the GNU Library General Public License instead.) You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it +in new free programs; and that you know you can do these things. + + To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their +rights. + + We protect your rights with two steps: (1) copyright the software, and +(2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + + Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + + Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at all. + + The precise terms and conditions for copying, distribution and +modification follow. + + GNU GENERAL PUBLIC LICENSE + TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + + 0. This License applies to any program or other work which contains +a notice placed by the copyright holder saying it may be distributed +under the terms of this General Public License. The "Program", below, +refers to any such program or work, and a "work based on the Program" +means either the Program or any derivative work under copyright law: +that is to say, a work containing the Program or a portion of it, +either verbatim or with modifications and/or translated into another +language. (Hereinafter, translation is included without limitation in +the term "modification".) Each licensee is addressed as "you". + +Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running the Program is not restricted, and the output from the Program +is covered only if its contents constitute a work based on the +Program (independent of having been made by running the Program). +Whether that is true depends on what the Program does. + + 1. You may copy and distribute verbatim copies of the Program's +source code as you receive it, in any medium, provided that you +conspicuously and appropriately publish on each copy an appropriate +copyright notice and disclaimer of warranty; keep intact all the +notices that refer to this License and to the absence of any warranty; +and give any other recipients of the Program a copy of this License +along with the Program. + +You may charge a fee for the physical act of transferring a copy, and +you may at your option offer warranty protection in exchange for a fee. + + 2. You may modify your copy or copies of the Program or any portion +of it, thus forming a work based on the Program, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + + a) You must cause the modified files to carry prominent notices + stating that you changed the files and the date of any change. + + b) You must cause any work that you distribute or publish, that in + whole or in part contains or is derived from the Program or any + part thereof, to be licensed as a whole at no charge to all third + parties under the terms of this License. + + c) If the modified program normally reads commands interactively + when run, you must cause it, when started running for such + interactive use in the most ordinary way, to print or display an + announcement including an appropriate copyright notice and a + notice that there is no warranty (or else, saying that you provide + a warranty) and that users may redistribute the program under + these conditions, and telling the user how to view a copy of this + License. (Exception: if the Program itself is interactive but + does not normally print such an announcement, your work based on + the Program is not required to print an announcement.) + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Program, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Program, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Program. + +In addition, mere aggregation of another work not based on the Program +with the Program (or with a work based on the Program) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + + 3. You may copy and distribute the Program (or a work based on it, +under Section 2) in object code or executable form under the terms of +Sections 1 and 2 above provided that you also do one of the following: + + a) Accompany it with the complete corresponding machine-readable + source code, which must be distributed under the terms of Sections + 1 and 2 above on a medium customarily used for software interchange; or, + + b) Accompany it with a written offer, valid for at least three + years, to give any third party, for a charge no more than your + cost of physically performing source distribution, a complete + machine-readable copy of the corresponding source code, to be + distributed under the terms of Sections 1 and 2 above on a medium + customarily used for software interchange; or, + + c) Accompany it with the information you received as to the offer + to distribute corresponding source code. (This alternative is + allowed only for noncommercial distribution and only if you + received the program in object code or executable form with such + an offer, in accord with Subsection b above.) + +The source code for a work means the preferred form of the work for +making modifications to it. For an executable work, complete source +code means all the source code for all modules it contains, plus any +associated interface definition files, plus the scripts used to +control compilation and installation of the executable. However, as a +special exception, the source code distributed need not include +anything that is normally distributed (in either source or binary +form) with the major components (compiler, kernel, and so on) of the +operating system on which the executable runs, unless that component +itself accompanies the executable. + +If distribution of executable or object code is made by offering +access to copy from a designated place, then offering equivalent +access to copy the source code from the same place counts as +distribution of the source code, even though third parties are not +compelled to copy the source along with the object code. + + 4. You may not copy, modify, sublicense, or distribute the Program +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense or distribute the Program is +void, and will automatically terminate your rights under this License. +However, parties who have received copies, or rights, from you under +this License will not have their licenses terminated so long as such +parties remain in full compliance. + + 5. You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Program or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Program (or any work based on the +Program), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Program or works based on it. + + 6. Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the +original licensor to copy, distribute or modify the Program subject to +these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties to +this License. + + 7. If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Program at all. For example, if a patent +license would not permit royalty-free redistribution of the Program by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Program. + +If any portion of this section is held invalid or unenforceable under +any particular circumstance, the balance of the section is intended to +apply and the section as a whole is intended to apply in other +circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system, which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + + 8. If the distribution and/or use of the Program is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Program under this License +may add an explicit geographical distribution limitation excluding +those countries, so that distribution is permitted only in or among +countries not thus excluded. In such case, this License incorporates +the limitation as if written in the body of this License. + + 9. The Free Software Foundation may publish revised and/or new versions +of the General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies a version number of this License which applies to it and "any +later version", you have the option of following the terms and conditions +either of that version or of any later version published by the Free +Software Foundation. If the Program does not specify a version number of +this License, you may choose any version ever published by the Free Software +Foundation. + + 10. If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the author +to ask for permission. For software which is copyrighted by the Free +Software Foundation, write to the Free Software Foundation; we sometimes +make exceptions for this. Our decision will be guided by the two goals +of preserving the free status of all derivatives of our free software and +of promoting the sharing and reuse of software generally. + + NO WARRANTY + + 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY +FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES +PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED +OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS +TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE +PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, +REPAIR OR CORRECTION. + + 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR +REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING +OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED +TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY +YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER +PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGES. + + END OF TERMS AND CONDITIONS + + How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least +the "copyright" line and a pointer to where the full notice is found. + + <one line to give the program's name and a brief idea of what it does.> + Copyright (C) <year> <name of author> + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + + +Also add information on how to contact you by electronic and paper mail. + +If the program is interactive, make it output a short notice like this +when it starts in an interactive mode: + + Gnomovision version 69, Copyright (C) year name of author + Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type `show c' for details. + +The hypothetical commands `show w' and `show c' should show the appropriate +parts of the General Public License. Of course, the commands you use may +be called something other than `show w' and `show c'; they could even be +mouse-clicks or menu items--whatever suits your program. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a "copyright disclaimer" for the program, if +necessary. Here is a sample; alter the names: + + Yoyodyne, Inc., hereby disclaims all copyright interest in the program + `Gnomovision' (which makes passes at compilers) written by James Hacker. + + <signature of Ty Coon>, 1 April 1989 + Ty Coon, President of Vice + +This General Public License does not permit incorporating your program into +proprietary programs. If your program is a subroutine library, you may +consider it more useful to permit linking proprietary applications with the +library. If this is what you want to do, use the GNU Library General +Public License instead of this License. +</LITERALLAYOUT> +</APPENDIX> diff --git a/ecos/doc/sgml/user-guide/installation.sgml b/ecos/doc/sgml/user-guide/installation.sgml new file mode 100644 index 0000000..0151223 --- /dev/null +++ b/ecos/doc/sgml/user-guide/installation.sgml @@ -0,0 +1,247 @@ +<!-- {{{ Banner --> + +<!-- =============================================================== --> +<!-- --> +<!-- installation.sgml --> +<!-- --> +<!-- eCos User Guide --> +<!-- --> +<!-- =============================================================== --> +<!-- ####ECOSDOCCOPYRIGHTBEGIN#### --> +<!-- =============================================================== --> +<!-- Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2009 Free Software Foundation, 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 --> +<!-- =============================================================== --> +<!-- ####ECOSDOCCOPYRIGHTEND#### --> +<!-- =============================================================== --> +<!-- #####DESCRIPTIONBEGIN#### --> +<!-- --> +<!-- ####DESCRIPTIONEND#### --> +<!-- =============================================================== --> + +<!-- }}} --> + +<part ID="user-guide-installation"> +<TITLE>Installing <productname>eCos</productname></TITLE> + +<!-- {{{ System Requirements --> + +<chapter id="user-guide-installation-requirements"> +<title>System Requirements</title> + +<ITEMIZEDLIST> + +<LISTITEM> +<PARA><!-- <conditionaltext> -->Standard Intel architecture PC running + Linux (tested on recent Fedora, openSUSE and Ubuntu distributions), + Microsoft Windows NT 4 + SP6a, Windows 2000, Windows XP and Windows Vista. + Linux distributions from other vendors may also work, but + are currently untested.</PARA> +</LISTITEM> + +<LISTITEM> +<PARA>Enough <!-- <index></index> --> disk space for the installed +distribution. The <productname>eCos</productname> installation process +will detail the various components of <productname>eCos</productname> +and the compiler toolkit that can be installed, and their disk space +requirements.</PARA> +</LISTITEM> + +<LISTITEM> +<PARA>64MB of RAM and a 350MHz or faster Pentium processor.</PARA><!-- <conditionaltext> --> +</LISTITEM> + +</ITEMIZEDLIST> + +<PARA>If you are downloading the <productname>eCos</productname> +release distribution from <ULINK +URL="http://ecos.sourceware.org">ecos.sourceware.org</ULINK>, +you will also need space to store that image and to compile the +toolchain and <productname>eCos</productname> from source.</PARA> + + +</chapter> + +<!-- }}} --> +<!-- {{{ Installation on Linux --> + +<chapter id="user-guide-installation-linux"> +<title>Installation on Linux</title> + +<para> +Full instructions for the <ULINK +URL="http://ecos.sourceware.org/getstart.html">downloading and +installation of eCos</ULINK> on Linux hosts are provided on the eCos +website. +</para> + +</chapter> + +<!-- }}} --> +<!-- {{{ Installation on Windows --> + +<chapter id="user-guide-installation-windows"> +<title>Installation on Windows</title> + +<para> +Full instructions for the <ULINK +URL="http://ecos.sourceware.org/getstart.html">downloading and +installation of eCos</ULINK> on Windows hosts are provided on the +eCos website. +</para> + +</chapter> + +<!-- }}} --> +<!-- {{{ Target Setup --> + +<chapter id="user-guide-installation-target"> +<title>Target Setup</title> + +<PARA>While <productname>eCos</productname> supports a variety of +targets, communication with all the targets happens in one of four +ways. These are described in general below. Any details or variations +from these descriptions will be found in the +<productname>eCos</productname> documentation for a specific target, +in the appendix.</PARA> + +<SECT1 id="connecting-target-serial"> +<TITLE><!-- <index></index> -->Connecting Via Serial Line</TITLE> + +<PARA>Most targets will have RedBoot or GDB Stubs installed. +These normally waits for GDB to connect at 38400 baud, using 8 data +bit, no parity bit and 1 stop-bit and no hardware flow control. Check +the documentation for your target to ensure it uses this speed. If not, +adjust the following instructions accordingly.</PARA> + +<PARA>The following instructions depend on your having selected +the appropriate serial port on the host. That is, the serial port +which connects to the target's (primary) serial port. On +Linux this could be <FILENAME>/dev/ttyS0</FILENAME>, +while the same port on Windows would be named COM1. +Substitute the proper serial port name in the below.</PARA> + +<PARA>Connect to the target by issuing the following commands in +GDB console mode:</PARA> + +<PROGRAMLISTING> +(gdb) set remotebaud 38400 <!-- <conditionaltext> --> +(gdb) target remote /dev/ttyS0 +</PROGRAMLISTING> + +<PARA>In Insight, connect by opening the <EMPHASIS>File->Target +Settings</EMPHASIS> window and enter:</PARA> + +<PROGRAMLISTING> +Target: Remote/Serial +Baud Rate: 38400 +Port: /dev/ttyS0 +</PROGRAMLISTING> + +<PARA>Set other options according to preference, close the window +and select +<EMPHASIS>Run->Connect to target</EMPHASIS>. +</PARA> + +</SECT1> + +<!-- ==================================================== --> + +<SECT1 id="connecting-target-ethernet"> +<TITLE><!-- <index></index> -->Connecting Via Ethernet</TITLE> + +<PARA>Some targets allow GDB to connect via Ethernet - if so, it will +be mentioned in the document describing the target. Substitute the +target's assigned IP address or hostname for <hostname> in the +following. Depending on how RedBoot has been configured, it will +either have this address allocated statically, or will acquire it via +BOOTP. In both cases RedBoot will report the IP address it is +listening on in its startup message printed on the serial port. The +<port> is the TCP port which RedBoot is listening on, usually +9000. It is also listed in the target document.</PARA> + +<PARA>Connect to the target by issuing the following command in +GDB console mode:</PARA> + +<PROGRAMLISTING> +(gdb) target remote <hostname>:<port> +</PROGRAMLISTING> + +<PARA>In Insight, connect by opening the <EMPHASIS>File->Target +Settings</EMPHASIS> window and enter:</PARA> + +<PROGRAMLISTING> +Target: Remote/TCP +Hostname: <hostname> +Port: <port> +</PROGRAMLISTING> + +<PARA><!-- <conditionaltext> -->Set other options according to +preference, close the window and select <EMPHASIS>Run->Connect to +target</EMPHASIS>.</PARA> + +</SECT1> + +<!-- ==================================================== --> + +<SECT1 id="connecting-target-sim"> +<TITLE><!-- <index></index> -->Using A Simulator Target</TITLE> + +<PARA>GDB connects to all simulator targets using the same basic +command, although each simulator may require additional options. +These are listed in the document describing the target, and should +be used when connecting.</PARA> + +<PARA>Connect to the target by issuing the following command in +GDB console mode:</PARA> + +<PROGRAMLISTING> +(gdb) target sim [target specific options] +</PROGRAMLISTING> + +<PARA>In Insight, connect by opening the <EMPHASIS>File->Target +Settings</EMPHASIS> window and enter:</PARA> + +<PROGRAMLISTING> +Target: Simulator +Options: [target specific options] +</PROGRAMLISTING> + +<PARA>Set other options according to preference, close the window and +select <EMPHASIS>Run->Connect to target</EMPHASIS>.</PARA> + +</SECT1> + +<!-- ==================================================== --> + +<SECT1 id="connecting-target-synth"> +<TITLE>Using A Synthetic Target</TITLE> + +<PARA>Synthetic targets are special in that the built tests and +applications actually run as native applications on the host. This +means that there is no target to connect to. The test or application +can be run directly from the GDB console using:</PARA> + +<PROGRAMLISTING> +(gdb) run +</PROGRAMLISTING> + +<PARA>or from Insight by pressing the <EMPHASIS>Run</EMPHASIS> icon. +There is therefore no need to connect to the target or download the +application, so you should ignore GDB “target” and +“load” commands in any instructions found in other places +in the documentation.</PARA> +</SECT1> + +</chapter> + +<!-- }}} --> + +</part> + diff --git a/ecos/doc/sgml/user-guide/introduction.sgml b/ecos/doc/sgml/user-guide/introduction.sgml new file mode 100644 index 0000000..d2c0ca0 --- /dev/null +++ b/ecos/doc/sgml/user-guide/introduction.sgml @@ -0,0 +1,794 @@ +<!-- {{{ Banner --> + +<!-- =============================================================== --> +<!-- --> +<!-- introduction.sgml --> +<!-- --> +<!-- eCos User Guide --> +<!-- --> +<!-- =============================================================== --> +<!-- ####ECOSDOCCOPYRIGHTBEGIN#### --> +<!-- =============================================================== --> +<!-- Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2010 Free Software Foundation, 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 --> +<!-- =============================================================== --> +<!-- ####ECOSDOCCOPYRIGHTEND#### --> +<!-- =============================================================== --> +<!-- #####DESCRIPTIONBEGIN#### --> +<!-- --> +<!-- ####DESCRIPTIONEND#### --> +<!-- =============================================================== --> + +<!-- }}} --> + +<part ID="user-guide-introduction"> +<TITLE>Introduction</TITLE> + +<!-- +<chapter ID="FOREWORD-WHATS-NEW"> +<TITLE>What's New?</TITLE> + +<para> +XXXXX So what is new??? XXXXX +</para> + +</chapter> +--> + +<!-- ==================================================== --> + +<chapter ID="ecos-key-features"> +<TITLE>Key Features</TITLE> + +<itemizedlist> + +<listitem> +<para><productname>eCos</productname> is distributed under the GPL +license with an exception which permits proprietary application code +to be linked with <productname>eCos</productname> without itself being +forced to be released under the GPL. It is also royalty and buyout +free. +</para> +</listitem> + +<listitem> +<para>As an Open Source project, <productname>eCos</productname> is +under constant improvement, with an active developer community, based +around the <productname>eCos</productname> web site at <ULINK +URL="http://ecos.sourceware.org/">http://ecos.sourceware.org/</ULINK>. +</para> +</listitem> + +<listitem> +<para>Powerful GUI-based configuration system allowing both large and +fine grained configuration of <productname>eCos</productname>. This +allows the functionality of <productname>eCos</productname> to be +customized to the exact requirements of the application. +</para> +</listitem> + +<listitem> +<para>Full-featured, flexible, configurable, real time embedded +kernel. The kernel provides thread scheduling, synchronization, +timer, and communication primitives. It handles hardware resources +such as interrupts, exceptions, memory and caches. +</para> +</listitem> + +<listitem> +<para>The Hardware Abstraction Layer (HAL) hides the specific features +of each supported CPU and platform, so that the kernel and other +run-time components can be implemented in a portable fashion. +</para> +</listitem> + +<listitem> +<para>Support for µITRON and POSIX Application Programmer +Interfaces (APIs). It also includes a fully featured, thread-safe ISO +standard C library and math library. +</para> +</listitem> + +<listitem> +<para>Support for a wide variety of devices including many serial +devices, ethernet controllers and FLASH memories. There is also +support for PCMCIA, USB and PCI interconnects. +</para> +</listitem> + +<listitem> +<para>A fully featured TCP/IP stack implementing IP, IPv6, ICMP, UDP +and TCP over ethernet and serial interfaces. Support for SNMP, HTTP, +TFTP, PPP and FTP is also present. +</para> +</listitem> + +<listitem> +<para>A lightweight TCP/IP stack (lwIP) implementing IP, ICMP, UDP +and TCP over ethernet and serial interfaces. +</para> +</listitem> + +<listitem> +<para>A lightweight implementation of the C++ Standard Template +Library (uSTL). +</para> +</listitem> + +<listitem> +<para>The RedBoot ROM monitor is an application that uses the +<productname>eCos</productname> HAL for portability. It provides +serial and ethernet based booting and debug services during +development. +</para> +</listitem> + +<listitem> +<para>Many components include test programs that validate the +components behaviour. These can be used both to check that hardware is +functioning correctly, and as examples of +<productname>eCos</productname> usage. +</para> +</listitem> + +<listitem> +<para><productname>eCos</productname> documentation included this User +Guide, the Reference Manual and the Components Writer's Guide. These +are being continually updated as the system develops. +</para> +</listitem> + +</itemizedlist> + +</chapter> + +<!-- ==================================================== --> + +<chapter ID="ecos-overview"> +<TITLE><productname>eCos</productname> Overview</TITLE> + +<PARA><productname>eCos</productname> is an open source, configurable, + portable, and royalty-free embedded real-time operating + system. The following text expands on these core aspects that + define <productname>eCos</productname>.</PARA> + +<PARA><productname>eCos</productname> is provided as an open source + runtime system supported by the GNU open source development + tools. Developers have full and unfettered access to all + aspects of the runtime system. No parts of it are proprietary + or hidden, and you are at liberty to examine, add to, and + modify the code as you deem necessary. These rights are + granted to you and protected by the GNU Public License (GPL). + An exception clause has been added to the eCos license which + limits the circumstances in which the license applies to other + code when used in conjunction with eCos. This exception grants + you the right to freely develop and distribute applications + based on <productname>eCos</productname>. You are not expected + or required to make your embedded applications or any + additional components that you develop freely available so + long as they are not derived from + <productname>eCos</productname> code. We of course welcome all + contributions back to <productname>eCos</productname> such as + board ports, device drivers and other components, as this + helps the growth and development of + <productname>eCos</productname>, and is of benefit to the + entire <productname>eCos</productname> community. See <XREF + LINKEND="ecos-licensing"> for more details.</PARA> + +<PARA>One of the key technological innovations in + <productname>eCos</productname> is the configuration + system. The configuration system allows the application writer + to impose their requirements on the run-time components, both + in terms of their functionality and implementation, whereas + traditionally the operating system has constrained the + application's own implementation. Essentially, this enables + <productname>eCos</productname> developers to create their own + application-specific operating system and makes + <productname>eCos</productname> suitable for a wide range of + embedded uses. Configuration also ensures that the resource + footprint of <productname>eCos</productname> is minimized as + all unnecessary functionality and features are removed. The + configuration system also presents + <productname>eCos</productname> as a component + architecture. This provides a standardized mechanism for + component suppliers to extend the functionality of + <productname>eCos</productname> and allows applications to be + built from a wide set of optional configurable run-time + components. Components can be provided from a variety of + sources including: the standard + <productname>eCos</productname> release; commercial third + party developers or open source contributors.</PARA> + +<PARA>The royalty-free nature of <productname>eCos</productname> means that you can develop and +deploy your application using the standard <productname>eCos</productname> release without +incurring any royalty charges. In addition, there are no up-front +license charges for the <productname>eCos</productname> runtime source code and associated +tools. We provide, without charge, everything necessary for basic +embedded applications development.</PARA> + +<PARA><productname>eCos</productname> is designed to be portable to a +wide range of target architectures and target platforms including 16, +32, and 64 bit architectures, MPUs, MCUs and DSPs. The +<productname>eCos</productname> kernel, libraries and runtime +components are layered on the Hardware Abstraction Layer (HAL), and +thus will run on any target once the HAL and relevant device drivers +have been ported to the target's processor architecture and +board. Currently <productname>eCos</productname> supports a large +range of different target architectures: + </para> + +<itemizedlist> + +<listitem><para>ARM, Cortex-M, Intel StrongARM and XScale</para></listitem> + +<listitem><para>Fujitsu FR-V, FR30</para></listitem> + +<listitem><para>Hitachi SH2/3/4</para></listitem> + +<listitem><para>Hitachi H8/300H, H8S </para></listitem> + +<listitem><para>Intel x86</para></listitem> + +<listitem><para>MIPS</para></listitem> + +<listitem><para>Matsushita AM3x</para></listitem> + +<listitem><para>Freescale PowerPC</para></listitem> + +<listitem><para>Freescale 68k/Coldfire</para></listitem> + +<listitem><para>NEC V850</para></listitem> + +<listitem><para>Sun SPARC</para></listitem> + +</itemizedlist> + +<para> +including many of the popular variants of these architectures +and evaluation boards.</PARA> + +<PARA><productname>eCos</productname> has been designed to support +applications with real-time requirements, providing features such as +full preemptability, minimal interrupt latencies, and all the +necessary synchronization primitives, scheduling policies, and +interrupt handling mechanisms needed for these type of +applications. <productname>eCos</productname> also provides all the +functionality required for general embedded application support +including device drivers, memory management, exception handling, C, +math libraries, etc. In addition to runtime support, the +<productname>eCos</productname> system includes all the tools +necessary to develop embedded applications, including +<productname>eCos</productname> software configuration and build +tools, and GNU based compilers, assemblers, linkers, debuggers, and +simulators.</PARA> + +<PARA>To get the most out of <productname>eCos</productname> you +should visit the <productname>eCos</productname> open source +developers site: <ULINK +URL="http://ecos.sourceware.org/">http://ecos.sourceware.org/</ULINK>. +</para> + +<PARA>The site is dedicated to the <productname>eCos</productname> + developer community and contains a rich set of resources + including news, FAQ, online documentation, installation guide, + discussion and announcement mailing lists, and runtime and + development tools downloads. The site also supports anonymous + CVS and WEBCVS access to provide direct access to the latest + <productname>eCos</productname> source base. </PARA> + +<PARA><productname>eCos</productname> is released as open source + software because we believe that this is the most effective + software development model, and that it provides the greatest + benefit to the embedded developer community as a whole. As part + of this endeavor, we seek the input and participation of + <productname>eCos</productname> developers in its continuing + evolution. Participation can take many forms including:</PARA> +<ITEMIZEDLIST> +<LISTITEM> +<PARA>providing us with feedback on how <productname>eCos</productname> might be made more +useful to you - by taking part in the ongoing mailing list discussions +and by submitting problem reports covering bugs, documentation issues, +and missing features</PARA> +</LISTITEM> +<LISTITEM> +<PARA>contributing bug fixes and enhancement patches</PARA> +</LISTITEM> +<LISTITEM> +<PARA>contributing new code including device drivers, board +ports, libraries, and other runtime components</PARA> +</LISTITEM> +</ITEMIZEDLIST> + +<PARA>Our long term aim is to make <productname>eCos</productname> a +rich and ubiquitous standard infrastructure for the development of +deeply embedded applications. This will be achieved with the +assistance of the <productname>eCos</productname> developer community +cooperating to improve <productname>eCos</productname> for all. We +would like to take this opportunity to extend our thanks to the many +<productname>eCos</productname> developers who have already +contributed feedback, ideas, patches, and code that have augmented and +improved this release.</PARA> + + +<para> +<emphasis>The <productname>eCos</productname> Maintainers</emphasis> +</para> + +</chapter> + +<!-- ==================================================== --> + +<chapter ID="ecos-licensing"> +<TITLE><productname>eCos</productname> Licence Overview</TITLE> + +<para>As of May 2002, <productname>eCos</productname> is released +under a modified version of the well known <ulink +url="http://www.gnu.org/copyleft/gpl.html">GNU General Public License +(GPL)</ulink>, now making it an <ulink +url="http://www.gnu.org/philosophy/license-list.html">official +GPL-compatible Free Software License</ulink>. An exception clause has +been added to the <productname>eCos</productname> license which limits +the circumstances in which the license applies to other code when used +in conjunction with <productname>eCos</productname>. The exception +clause is as follows:</para> + +<programlisting width=72> + As a special exception, if other files instantiate templates or use macros + or inline functions from this file, or you compile this file and link it + with other works to produce a work based on this file, this file does not + by itself cause the resulting work to be covered by the GNU General Public + License. However the source code for this file must still be made + available in accordance with section (3) of the GNU General Public + License. + + This exception does not invalidate any other reasons why a work based on + this file might be covered by the GNU General Public License. +</programlisting> + +<para>The goal of the license is to serve the +<productname>eCos</productname> user community as a whole. It allows +all <productname>eCos</productname> users to develop products without +paying anybody anything, no matter how many developers are working on +the product or how many units will be shipped. The license also +guarantees that the <productname>eCos</productname> source code will +always be freely available. This applies not only to the core +<productname>eCos</productname> code itself but also to any changes +that anybody makes to the core. In particular, it should prevent any +company or individual contributing code to the system and then later +claiming that all <productname>eCos</productname> users are now guilty +of copyright or patent infringements and have to pay royalties. It +should also prevent any company from making some small improvements, +calling the result a completely new system, and releasing this under a +new and less generous license.</para> + +<para>The license does <emphasis>not</emphasis> require users to +release the source code of any <emphasis>applications</emphasis> that +are developed with <productname>eCos</productname>. However, if +anybody makes any changes to code covered by the +<productname>eCos</productname> license, or writes new files derived +in any way from <productname>eCos</productname> code, then we believe +that the entire user community should have the opportunity to benefit +from this. The license stipulates that these changes must be made +available in source code form to all recipients of binaries based on +the modified code, either by including the sources along with the +binaries you deliver (or with any device containing such binaries) or +with a written offer to supply the source code to the general public +for three years. It is perhaps most practical for +<productname>eCos</productname> developers to make the source code +available online and inform those who are receiving binaries +containing <productname>eCos</productname> code, and probably also the +<productname>eCos</productname> maintainers, about the location of the +code. See the <ulink url="http://www.gnu.org/copyleft/gpl.html">full +text of the GPL</ulink> for the most authoritative definition of the +obligations.</para> + +<para>Although it is not strictly necessary to contribute the modified +code back to the <productname>eCos</productname> open source project, +we are always pleased to receive code contributions and hope that +developers will also be keen to give back in return for what they +received from the <productname>eCos</productname> project completely +free of charge. The <productname>eCos</productname> maintainers are +responsible for deciding whether such contributions should be applied +to the public repository. In addition, a <ulink +url="http://ecos.sourceware.org/assign.html">copyright +assignment</ulink> is required for any significant changes to the core +<productname>eCos</productname> packages.</para> + +<para>The result is a royalty-free system with minimal obligations on +the part of application developers. This has resulted in the rapid +uptake of <productname>eCos</productname>. At the same time, +<productname>eCos</productname> is fully open source with all the +benefits that implies in terms of quality and innovation. We believe +that this is a winning combination.</para> + +<sect1 id="ecos-licensing-qna"> +<title>Questions and answers</title> + +<para>The following queries provide some clarification as to the +implications of the <productname>eCos</productname> license. They do +not consititute part of the legal meaning of the license.</para> + +<para><emphasis>Q.</emphasis> What is the effect of the +<productname>eCos</productname> license?</para> + +<para><emphasis>A.</emphasis> In the simplest terms, when you +distribute anything containing <productname>eCos</productname> code, +you must make the source code to <productname>eCos</productname> +available under the terms of the GPL.</para> + +<para><emphasis>Q.</emphasis> What if I make changes to +<productname>eCos</productname>, or write new code based on +<productname>eCos</productname> code?</para> + +<para><emphasis>A.</emphasis> Then you must make those changes +available as well.</para> + +<para><emphasis>Q.</emphasis> Do I have to distribute the source +code to my application? Isn't the GPL "viral"?</para> + +<para><emphasis>A.</emphasis> You do not have to distribute any +code under the terms of the GPL other than +<productname>eCos</productname> code or code derived from +<productname>eCos</productname>. For example, if you write a HAL port +based on copying an existing <productname>eCos</productname> HAL in +any way, you must make the source code available with the +binary. However you would not need to make available any other code, +such as the code of a wholly separate application linked with +<productname>eCos</productname>.</para> + +<para><emphasis>Q.</emphasis> I would rather stick with the +RHEPL code, but I updated my anonymous CVS checkout.</para> + +<para><emphasis>A.</emphasis> You can check out the final +version of anonymous CVS before the license change using the CVS tag +<literal>last-rhepl</literal>. See <ulink +url="http://ecos.sourceware.org/anoncvs.html">the anonymous CVS +access page</ulink> +for details.</para> + +</sect1> + +<sect1 id="ecos-licensing-previous"> +<title>Previous License</title> + +<para> + +Prior to May 2002, <productname>eCos</productname> was released under +the <ulink url="http://ecos.sourceware.org/old-license.html">Red +Hat eCos Public License (RHEPL)</ulink>. The RHEPL required any +modifications to <productname>eCos</productname> code to be made +available under preferential terms to Red Hat and was therefore +incompatible with code licensed under the GPL. The use of +<productname>eCos</productname> source code which was licensed under +the RHEPL is not affected by the switch to the modified GPL for later +revisions. +</para> + +</sect1> + +</chapter> + +<!-- ==================================================== --> + +<chapter id="notation-and-conventions"> +<title>Notation and Conventions</title> + +<para> +Since there are many supported target architectures, notation +conventions are used in this manual to avoid repeating instructions +that are very similar. +</para> + +<SECT1 ID="GDB-AND-GCC-COMMAND-NOTATION"><!-- <index></index> --><!-- <xref> --> +<TITLE>GDB and <!-- <index></index> -->GCC Command Notation</TITLE> + +<para> +Cross-development commands like <COMMAND>gcc</COMMAND> and +<COMMAND>gdb</COMMAND> will be shown with a +<replaceable>TARGET-</replaceable> prefix. You need to replace +<replaceable>TARGET-</replaceable> with the correct prefix before +using the command. Just using <command>gcc</command> or +<command>gdb</command> will use the tools for the host, which is not +(usually) what you want. +</para> + +<para> +For example use <command>arm-elf-gcc</command> and +<command>arm-elf-gdb</command> for ARM, Thumb, and StrongARM targets. +Use <command>xscale-elf-gcc</command> and +<command>xscale-elf-gdb</command> for Intel Xscale targets. +Use <command>i386-elf-gcc</command> and +<command>i386-elf-gdb</command> for IA32 targets. And so on, the exact +prefix to use is shown in the documentation for each target. +</para> + +<PARA>Note that some versions of the GCC cross compiler generate +executable files with the <FILENAME>.exe</FILENAME> suffix on Windows, +but not on Linux. The suffix <FILENAME>.exe</FILENAME> will be omitted +from executable file names, so you will see <FILENAME>hello</FILENAME> +instead of <FILENAME>hello.exe</FILENAME>.</PARA> + +</sect1> + +<SECT1 ID="DIRECTORY-AND-FILE-SYSTEM-CONVENTIONS"><!-- <index></index> --> +<TITLE>Directory and File System Conventions</TITLE> + +<PARA>The default directory for installing +<productname>eCos</productname> on Windows (usually +<FILENAME>C:/Program Files/eCos</FILENAME>) is different from that on +Linux (usually <FILENAME>/opt/ecos</FILENAME>). Since many command +line examples in the tutorials use these paths, this default (base) +directory will be cited as <replaceable>BASE_DIR</replaceable>.</PARA> + +<PARA>Windows and Linux have a similar file system syntax, but the +MS-DOS command interpreter on Windows uses the backslash character +(\) as a path separator, while Linux and POSIX shells (including +the Cygwin bash shell for windows) use the forward slash (/).</PARA> + +<PARA>This document will use the POSIX shell convention of forward +slashes throughout.</PARA> + +</SECT1> + +<!-- ==================================================== --> + +<SECT1 ID="VERSION-CONVENTIONS"> +<TITLE>Version Conventions</TITLE> + +<para> +This manual does not refer explicitly to any particular version of +<productname>eCos</productname>. However, version numbers form part of +many file path names. In all of these places the version number will +be shown like this: <replaceable>&Version;</replaceable>. +</para> + +<para> +If you have used anonymous CVS to check +<productname>eCos</productname> out of the CVS repository, the version +number will always be <literal>current</literal>, since that is the +name of the directory in the repository. When a stable release is made +this directory name is changed, in the release, to the number of the +release, for example <literal>v2_0</literal> or +<literal>v2_1</literal>. +</para> + +</SECT1> + + +</chapter> + + + +<chapter id="documentation-roadmap"> +<title>Documentation Roadmap</title> + +<para> +The <productname>eCos</productname> documentation is divided into a +three main parts: +</para> + +<VARIABLELIST> +<VARLISTENTRY> +<TERM><EMPHASIS>User Guide</EMPHASIS></TERM> +<LISTITEM> +<PARA>This document. It includes the following sections:</PARA> + + <VARIABLELIST> + <VARLISTENTRY> + <TERM>Installing <productname>eCos</productname></TERM> + <LISTITEM> + <para> + This section describes how to install the + <productname>eCos</productname> software, how to set up your + hardware and how to test that it is all working. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM>Programming Under <productname>eCos</productname></TERM> + <LISTITEM> + <para> + This section describes how to write programs that run under + <productname>eCos</productname> by running through some examples. + </para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM>The <productname>eCos</productname> <application>Configuration Tool</application></TERM> + <LISTITEM> + <para> + This section describes the <productname>eCos</productname> graphical + configuration tool and how to use it to change how + <productname>eCos</productname> behaves.</para> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM><productname>eCos</productname> Programming Concepts and Techniques</TERM> + <LISTITEM> + <PARA>An explanation of the <productname>eCos</productname> programming + cycle, and a description of some debugging facilities that + <productname>eCos</productname> offers. + </PARA> + </listitem> + </varlistentry> + + <VARLISTENTRY> + <TERM>Configuration and the Package + Repository</TERM> + <LISTITEM> + <PARA>Information on how to configure <productname>eCos</productname> + manually, including a reference on the + <command>ecosconfig</command> command, memory layouts, + and information on how to manage a package repository + using the <productname>eCos</productname> Package Administration + Tool. + </PARA> + </LISTITEM> + </VARLISTENTRY> + + + </variablelist> + +</LISTITEM> +</VARLISTENTRY> + +<VARLISTENTRY> +<TERM><EMPHASIS>Reference Guide</EMPHASIS></TERM> +<LISTITEM> + +<PARA>The Reference Guide provides detailed documentation on various +aspects of <productname>eCos</productname>. This document is being +constantly updated, so the following list just mentions the more +important sections, take a look at the guide itself for the full +story.</PARA> + + <variablelist> + + <VARLISTENTRY> + <TERM>The <productname>eCos</productname> Kernel</TERM> + <LISTITEM> + <PARA>In-depth description of <productname>eCos</productname>"s + native C kernel API Important considerations are given + for programming the <productname>eCos</productname> + kernel. The semantics for each kernel function are + described, including how they are affected by + configuration. </PARA> + </LISTITEM> + </VARLISTENTRY> + + <VARLISTENTRY> + <TERM>POSIX and µITRON APIs</TERM> + <LISTITEM> + <PARA>A description of the POSIX and µITRON APIs and how they + are supported under <productname>eCos</productname>. + </para> + </LISTITEM> + </VARLISTENTRY> + + <VARLISTENTRY> + <TERM>The <productname>eCos</productname> Hardware Abstraction Layer (HAL)</TERM> + <LISTITEM> + <PARA>A description of the structure and functionality of the + <productname>eCos</productname> HAL. This section also includes a + porting guide to help moving <productname>eCos</productname> to + different platforms. + </para> + </LISTITEM> + </VARLISTENTRY> + + <VARLISTENTRY> + <TERM>Device Drivers</TERM> + <LISTITEM> + <PARA>A description of the philosophy behind + <productname>eCos</productname> device drivers, as well as a + presentation of the C language APIs for using the current + device drivers. </PARA> + <para> + Device driver support includes serial, ethernet and FLASH devices, + and support for PCI, PCMCIA and USB interconnects. + </para> + </LISTITEM> + </VARLISTENTRY> + + <VARLISTENTRY> + <TERM>RedBoot User's Guide</TERM> + <LISTITEM> + <PARA>This describes RedBoot, which provides a complete bootstrap + environment for a range of embedded operating systems, such as + embedded Linux and <productname>eCos</productname>, and + includes facilities such as network downloading and + debugging. It also provides a simple flash file system for + boot images. + </para> + </LISTITEM> + </VARLISTENTRY> + + <VARLISTENTRY> + <TERM>TCP/IP Stack Support</TERM> + <LISTITEM> + <PARA>This describes the Common Networking for + <productname>eCos</productname> package, which provides + support for a complete TCP/IP networking stack. The design + allows for the actual stack to be modular and at the current + time two different implementations, one based on OpenBSD from + 2000 and a new version based on FreeBSD, are available. + </para> + <para>Other components related to networking, including support for + SNMP, DNS, HTTP and FTP, are also described. + </para> + </LISTITEM> + </VARLISTENTRY> + + </variablelist> + +</LISTITEM> +</VARLISTENTRY> + +<VARLISTENTRY> +<TERM><EMPHASIS>Component Writer's Guide</EMPHASIS></TERM> +<LISTITEM> +<PARA>The Component Writer's Guide is intended for developers who need +to add or modify parts of <productname>eCos</productname> itself. It +describes the following things: +</PARA> + + <VARIABLELIST> + <VARLISTENTRY> + <TERM>Overview</TERM> + <LISTITEM> + <PARA>An explanation of the configuration technology used in + <productname>eCos</productname>, why it is done this way, how it + works and the terminology used. + </para> + </LISTITEM> + </VARLISTENTRY> + + <VARLISTENTRY> + <TERM>Package Organization</TERM> + <LISTITEM> + <PARA>A description of the <productname>eCos</productname> package + repository, how it is organized and how packages themselves are + organized. + </para> + </LISTITEM> + </VARLISTENTRY> + + <VARLISTENTRY> + <TERM>The CDL Language</TERM> + <LISTITEM> + <PARA>A description of the CDL language and how it is used to + control the configuration of <productname>eCos</productname> + components. The document also contains a complete specification of + the language. + </para> + </LISTITEM> + </VARLISTENTRY> + + <VARLISTENTRY> + <TERM>The Build Process</TERM> + <LISTITEM> + <PARA>A description of what happens once a configuration has been + created and must be built into a set of executables. + </para> + </LISTITEM> + </VARLISTENTRY> + + </variablelist> + +</LISTITEM> +</VARLISTENTRY> +</variablelist> + +</chapter> + + +</part> diff --git a/ecos/doc/sgml/user-guide/jadetex.cfg b/ecos/doc/sgml/user-guide/jadetex.cfg new file mode 100644 index 0000000..f5c94ec --- /dev/null +++ b/ecos/doc/sgml/user-guide/jadetex.cfg @@ -0,0 +1 @@ +\hypersetup{pdfauthor=eCos (pdfjadetex) , colorlinks=true, linkcolor=blue, pdfstartview=FitH} diff --git a/ecos/doc/sgml/user-guide/makefile b/ecos/doc/sgml/user-guide/makefile new file mode 100644 index 0000000..17915bd --- /dev/null +++ b/ecos/doc/sgml/user-guide/makefile @@ -0,0 +1,56 @@ +#============================================================================= +# +# makefile +# +# For building the eCos RedBoot docs +# +#============================================================================= +# ####ECOSGPLCOPYRIGHTBEGIN#### +# ------------------------------------------- +# This file is part of eCos, the Embedded Configurable Operating System. +# Copyright (C) 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc. +# +# eCos is free software; you can redistribute it and/or modify it under +# the terms of the GNU General Public License as published by the Free +# Software Foundation; either version 2 or (at your option) any later +# version. +# +# eCos is distributed in the hope that it will be useful, but WITHOUT +# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +# for more details. +# +# You should have received a copy of the GNU General Public License +# along with eCos; if not, write to the Free Software Foundation, Inc., +# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. +# +# As a special exception, if other files instantiate templates or use +# macros or inline functions from this file, or you compile this file +# and link it with other works to produce a work based on this file, +# this file does not by itself cause the resulting work to be covered by +# the GNU General Public License. However the source code for this file +# must still be made available in accordance with section (3) of the GNU +# General Public License v2. +# +# This exception does not invalidate any other reasons why a work based +# on this file might be covered by the GNU General Public License. +# ------------------------------------------- +# ####ECOSGPLCOPYRIGHTEND#### +#============================================================================= +#####DESCRIPTIONBEGIN#### +# +# Author(s): bartv, jlarmour +# Date: 2001-01-11 +#####DESCRIPTIONEND#### +#============================================================================= + +TOPLEVEL := ../../../packages +MAIN_SGML := user-guide.sgml +MAIN_HTML := ecos-user-guide.html +MAIN_PDF := ecos-user-guide.pdf +OTHER_SGML := config-tool.sgml configuration.sgml ecos-license.sgml installation.sgml \ + introduction.sgml programming-concepts-techniques.sgml \ + programming.sgml real-time-characterization.sgml target-setup.sgml +PICTURES := + +include $(TOPLEVEL)/pkgconf/rules.doc diff --git a/ecos/doc/sgml/user-guide/pix/ARMStartup01.png b/ecos/doc/sgml/user-guide/pix/ARMStartup01.png Binary files differnew file mode 100644 index 0000000..3b7f13b --- /dev/null +++ b/ecos/doc/sgml/user-guide/pix/ARMStartup01.png diff --git a/ecos/doc/sgml/user-guide/pix/BuildPackages.png b/ecos/doc/sgml/user-guide/pix/BuildPackages.png Binary files differnew file mode 100644 index 0000000..859ffe4 --- /dev/null +++ b/ecos/doc/sgml/user-guide/pix/BuildPackages.png diff --git a/ecos/doc/sgml/user-guide/pix/Conflicts.png b/ecos/doc/sgml/user-guide/pix/Conflicts.png Binary files differnew file mode 100644 index 0000000..87e3e83 --- /dev/null +++ b/ecos/doc/sgml/user-guide/pix/Conflicts.png diff --git a/ecos/doc/sgml/user-guide/pix/ToolsOptions.png b/ecos/doc/sgml/user-guide/pix/ToolsOptions.png Binary files differnew file mode 100644 index 0000000..66b33c8 --- /dev/null +++ b/ecos/doc/sgml/user-guide/pix/ToolsOptions.png diff --git a/ecos/doc/sgml/user-guide/pix/addfromfolder.png b/ecos/doc/sgml/user-guide/pix/addfromfolder.png Binary files differnew file mode 100644 index 0000000..c3be0d8 --- /dev/null +++ b/ecos/doc/sgml/user-guide/pix/addfromfolder.png diff --git a/ecos/doc/sgml/user-guide/pix/addplatform.png b/ecos/doc/sgml/user-guide/pix/addplatform.png Binary files differnew file mode 100644 index 0000000..a0e1561 --- /dev/null +++ b/ecos/doc/sgml/user-guide/pix/addplatform.png diff --git a/ecos/doc/sgml/user-guide/pix/admin.png b/ecos/doc/sgml/user-guide/pix/admin.png Binary files differnew file mode 100644 index 0000000..1dbdb09 --- /dev/null +++ b/ecos/doc/sgml/user-guide/pix/admin.png diff --git a/ecos/doc/sgml/user-guide/pix/bash.png b/ecos/doc/sgml/user-guide/pix/bash.png Binary files differnew file mode 100644 index 0000000..8fee4dc --- /dev/null +++ b/ecos/doc/sgml/user-guide/pix/bash.png diff --git a/ecos/doc/sgml/user-guide/pix/build-lib01.png b/ecos/doc/sgml/user-guide/pix/build-lib01.png Binary files differnew file mode 100644 index 0000000..75f9b30 --- /dev/null +++ b/ecos/doc/sgml/user-guide/pix/build-lib01.png diff --git a/ecos/doc/sgml/user-guide/pix/build-processalt.png b/ecos/doc/sgml/user-guide/pix/build-processalt.png Binary files differnew file mode 100644 index 0000000..a7b7b4f --- /dev/null +++ b/ecos/doc/sgml/user-guide/pix/build-processalt.png diff --git a/ecos/doc/sgml/user-guide/pix/build-tests01.png b/ecos/doc/sgml/user-guide/pix/build-tests01.png Binary files differnew file mode 100644 index 0000000..d10a2f7 --- /dev/null +++ b/ecos/doc/sgml/user-guide/pix/build-tests01.png diff --git a/ecos/doc/sgml/user-guide/pix/build-tools.png b/ecos/doc/sgml/user-guide/pix/build-tools.png Binary files differnew file mode 100644 index 0000000..e5b7536 --- /dev/null +++ b/ecos/doc/sgml/user-guide/pix/build-tools.png diff --git a/ecos/doc/sgml/user-guide/pix/build-tools2.png b/ecos/doc/sgml/user-guide/pix/build-tools2.png Binary files differnew file mode 100644 index 0000000..35a0fb2 --- /dev/null +++ b/ecos/doc/sgml/user-guide/pix/build-tools2.png diff --git a/ecos/doc/sgml/user-guide/pix/buildoptions.png b/ecos/doc/sgml/user-guide/pix/buildoptions.png Binary files differnew file mode 100644 index 0000000..cdbe9a7 --- /dev/null +++ b/ecos/doc/sgml/user-guide/pix/buildoptions.png diff --git a/ecos/doc/sgml/user-guide/pix/ch-properties-dialog.png b/ecos/doc/sgml/user-guide/pix/ch-properties-dialog.png Binary files differnew file mode 100644 index 0000000..887543c --- /dev/null +++ b/ecos/doc/sgml/user-guide/pix/ch-properties-dialog.png diff --git a/ecos/doc/sgml/user-guide/pix/comprepos.png b/ecos/doc/sgml/user-guide/pix/comprepos.png Binary files differnew file mode 100644 index 0000000..5fcd460 --- /dev/null +++ b/ecos/doc/sgml/user-guide/pix/comprepos.png diff --git a/ecos/doc/sgml/user-guide/pix/config-f1.png b/ecos/doc/sgml/user-guide/pix/config-f1.png Binary files differnew file mode 100644 index 0000000..787f313 --- /dev/null +++ b/ecos/doc/sgml/user-guide/pix/config-f1.png diff --git a/ecos/doc/sgml/user-guide/pix/configwin.png b/ecos/doc/sgml/user-guide/pix/configwin.png Binary files differnew file mode 100644 index 0000000..a5e2e33 --- /dev/null +++ b/ecos/doc/sgml/user-guide/pix/configwin.png diff --git a/ecos/doc/sgml/user-guide/pix/conflictwin.png b/ecos/doc/sgml/user-guide/pix/conflictwin.png Binary files differnew file mode 100644 index 0000000..62eea1a --- /dev/null +++ b/ecos/doc/sgml/user-guide/pix/conflictwin.png diff --git a/ecos/doc/sgml/user-guide/pix/connection.png b/ecos/doc/sgml/user-guide/pix/connection.png Binary files differnew file mode 100644 index 0000000..bbecb1f --- /dev/null +++ b/ecos/doc/sgml/user-guide/pix/connection.png diff --git a/ecos/doc/sgml/user-guide/pix/find-dialog.png b/ecos/doc/sgml/user-guide/pix/find-dialog.png Binary files differnew file mode 100644 index 0000000..5994d85 --- /dev/null +++ b/ecos/doc/sgml/user-guide/pix/find-dialog.png diff --git a/ecos/doc/sgml/user-guide/pix/html-help.png b/ecos/doc/sgml/user-guide/pix/html-help.png Binary files differnew file mode 100644 index 0000000..bf752b5 --- /dev/null +++ b/ecos/doc/sgml/user-guide/pix/html-help.png diff --git a/ecos/doc/sgml/user-guide/pix/memorywin.png b/ecos/doc/sgml/user-guide/pix/memorywin.png Binary files differnew file mode 100644 index 0000000..d21a60b --- /dev/null +++ b/ecos/doc/sgml/user-guide/pix/memorywin.png diff --git a/ecos/doc/sgml/user-guide/pix/memregions.png b/ecos/doc/sgml/user-guide/pix/memregions.png Binary files differnew file mode 100644 index 0000000..c573ba5 --- /dev/null +++ b/ecos/doc/sgml/user-guide/pix/memregions.png diff --git a/ecos/doc/sgml/user-guide/pix/memreloc.png b/ecos/doc/sgml/user-guide/pix/memreloc.png Binary files differnew file mode 100644 index 0000000..7f951aa --- /dev/null +++ b/ecos/doc/sgml/user-guide/pix/memreloc.png diff --git a/ecos/doc/sgml/user-guide/pix/modifyplatform.png b/ecos/doc/sgml/user-guide/pix/modifyplatform.png Binary files differnew file mode 100644 index 0000000..f794789 --- /dev/null +++ b/ecos/doc/sgml/user-guide/pix/modifyplatform.png diff --git a/ecos/doc/sgml/user-guide/pix/open-dialog.png b/ecos/doc/sgml/user-guide/pix/open-dialog.png Binary files differnew file mode 100644 index 0000000..233e46c --- /dev/null +++ b/ecos/doc/sgml/user-guide/pix/open-dialog.png diff --git a/ecos/doc/sgml/user-guide/pix/propwin.png b/ecos/doc/sgml/user-guide/pix/propwin.png Binary files differnew file mode 100644 index 0000000..f8afa6c --- /dev/null +++ b/ecos/doc/sgml/user-guide/pix/propwin.png diff --git a/ecos/doc/sgml/user-guide/pix/regprops.png b/ecos/doc/sgml/user-guide/pix/regprops.png Binary files differnew file mode 100644 index 0000000..7459d91 --- /dev/null +++ b/ecos/doc/sgml/user-guide/pix/regprops.png diff --git a/ecos/doc/sgml/user-guide/pix/repos-relocate.png b/ecos/doc/sgml/user-guide/pix/repos-relocate.png Binary files differnew file mode 100644 index 0000000..38d80fb --- /dev/null +++ b/ecos/doc/sgml/user-guide/pix/repos-relocate.png diff --git a/ecos/doc/sgml/user-guide/pix/run-tests.png b/ecos/doc/sgml/user-guide/pix/run-tests.png Binary files differnew file mode 100644 index 0000000..0a36ab3 --- /dev/null +++ b/ecos/doc/sgml/user-guide/pix/run-tests.png diff --git a/ecos/doc/sgml/user-guide/pix/save-as-dialog.png b/ecos/doc/sgml/user-guide/pix/save-as-dialog.png Binary files differnew file mode 100644 index 0000000..29336ea --- /dev/null +++ b/ecos/doc/sgml/user-guide/pix/save-as-dialog.png diff --git a/ecos/doc/sgml/user-guide/pix/settings-conflict.png b/ecos/doc/sgml/user-guide/pix/settings-conflict.png Binary files differnew file mode 100644 index 0000000..0f4b59d --- /dev/null +++ b/ecos/doc/sgml/user-guide/pix/settings-conflict.png diff --git a/ecos/doc/sgml/user-guide/pix/settings-display.png b/ecos/doc/sgml/user-guide/pix/settings-display.png Binary files differnew file mode 100644 index 0000000..a9cb40b --- /dev/null +++ b/ecos/doc/sgml/user-guide/pix/settings-display.png diff --git a/ecos/doc/sgml/user-guide/pix/settings-runtests.png b/ecos/doc/sgml/user-guide/pix/settings-runtests.png Binary files differnew file mode 100644 index 0000000..cd5dde4 --- /dev/null +++ b/ecos/doc/sgml/user-guide/pix/settings-runtests.png diff --git a/ecos/doc/sgml/user-guide/pix/settings-viewers.png b/ecos/doc/sgml/user-guide/pix/settings-viewers.png Binary files differnew file mode 100644 index 0000000..7b7957b --- /dev/null +++ b/ecos/doc/sgml/user-guide/pix/settings-viewers.png diff --git a/ecos/doc/sgml/user-guide/pix/templates.png b/ecos/doc/sgml/user-guide/pix/templates.png Binary files differnew file mode 100644 index 0000000..7adb370 --- /dev/null +++ b/ecos/doc/sgml/user-guide/pix/templates.png diff --git a/ecos/doc/sgml/user-guide/pix/templates01.png b/ecos/doc/sgml/user-guide/pix/templates01.png Binary files differnew file mode 100644 index 0000000..a888aa3 --- /dev/null +++ b/ecos/doc/sgml/user-guide/pix/templates01.png diff --git a/ecos/doc/sgml/user-guide/pix/toolsplatforms.png b/ecos/doc/sgml/user-guide/pix/toolsplatforms.png Binary files differnew file mode 100644 index 0000000..bd2497f --- /dev/null +++ b/ecos/doc/sgml/user-guide/pix/toolsplatforms.png diff --git a/ecos/doc/sgml/user-guide/pix/twothreads2.png b/ecos/doc/sgml/user-guide/pix/twothreads2.png Binary files differnew file mode 100644 index 0000000..4559339 --- /dev/null +++ b/ecos/doc/sgml/user-guide/pix/twothreads2.png diff --git a/ecos/doc/sgml/user-guide/pix/user-tools-dialog.png b/ecos/doc/sgml/user-guide/pix/user-tools-dialog.png Binary files differnew file mode 100644 index 0000000..9738d51 --- /dev/null +++ b/ecos/doc/sgml/user-guide/pix/user-tools-dialog.png diff --git a/ecos/doc/sgml/user-guide/programming-concepts-techniques.sgml b/ecos/doc/sgml/user-guide/programming-concepts-techniques.sgml new file mode 100644 index 0000000..48d3d2c --- /dev/null +++ b/ecos/doc/sgml/user-guide/programming-concepts-techniques.sgml @@ -0,0 +1,966 @@ +<!-- {{{ Banner --> + +<!-- =============================================================== --> +<!-- --> +<!-- programming-concepts-techniques.sgml --> +<!-- --> +<!-- eCos User Guide --> +<!-- --> +<!-- =============================================================== --> +<!-- ####ECOSDOCCOPYRIGHTBEGIN#### --> +<!-- =============================================================== --> +<!-- Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002, 2010 Free Software Foundation, 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 --> +<!-- =============================================================== --> +<!-- ####ECOSDOCCOPYRIGHTEND#### --> +<!-- =============================================================== --> +<!-- #####DESCRIPTIONBEGIN#### --> +<!-- --> +<!-- ####DESCRIPTIONEND#### --> +<!-- =============================================================== --> + +<!-- }}} --> + +<PART id="ecos-programming-concepts-and-techniques"> +<TITLE><productname>eCos</productname> Programming Concepts and Techniques</TITLE> +<PARTINTRO id="programming-partintro"> +<PARA>Programming with <productname>eCos</productname> is somewhat different from programming + in more traditional environments. <productname>eCos</productname> is a configurable open + source system, and you are able to configure and build a system + specifically to meet the needs of your application. </PARA> +<PARA>Various different directory hierarchies are involved in + configuring and building the system: the <EMPHASIS>component + repository</EMPHASIS>, the <EMPHASIS>build tree</EMPHASIS>, + and the <EMPHASIS>install tree</EMPHASIS>. These directories + exist in addition to the ones used to develop + applications.</PARA> +</PARTINTRO> +<CHAPTER id="cdl-concepts"> +<TITLE>CDL Concepts</TITLE> +<SECT1 id="cdl-concepts-about"> +<TITLE>About this chapter</TITLE> +<PARA>This chapter serves as a brief introduction to the + concepts involved in <productname>eCos</productname> (Embedded Configurable Operating + System). It describes the configuration architecture and the + underlying technology to a level required for the embedded + systems developer to configure <productname>eCos</productname>. It does not describe in + detail aspects such as how to write reusable components for + <productname>eCos</productname>: this information is given in the <citetitle>Component + Writer’s Guide</citetitle>.</PARA> +<SECT2> +<TITLE>Background</TITLE> +<PARA>Software solutions for the embedded space place + particularly stringent demands on the developer, typically + represented as requirements for small memory footprint, high + performance and robustness. These demands are addressed in + <productname>eCos</productname> by providing the ability to perform compile-time + specialization: the developer can tailor the operating + system to suit the needs of the application. In order to + make this process manageable, <productname>eCos</productname> is built in the context + of a Configuration Infrastructure: a set of tools including + a <application>Configuration Tool</application> and a formal + description of the process of configuration by means of a + <EMPHASIS>Component Definition Language</EMPHASIS>.</PARA> +</SECT2> +<SECT2> +<TITLE>Configurations</TITLE> +<PARA><productname>eCos</productname> is tailored at source level (that is, before + compilation or assembly) in order to create an <productname>eCos</productname> + <EMPHASIS>configuration</EMPHASIS>. In concrete terms, an + <productname>eCos</productname> configuration takes the form of a configuration save + file (with extension .ecc) and set of files used to build + user applications (including, when built, a library file + against which the application is linked). </PARA> +</SECT2> +</SECT1> +<SECT1 id="cdl-component-repository"> +<TITLE>Component Repository</TITLE> +<PARA><productname>eCos</productname> is shipped in source in the form of a + <EMPHASIS>component repository</EMPHASIS> - a directory + hierarchy that contains the sources and other files which + are used to build a configuration. The component repository + can be added to by, for example, downloading from the + net.</PARA> +</SECT1> +<SECT1 id="cdl-component-definition-language"> +<TITLE>Component Definition Language</TITLE> +<PARA>Part of the component repository is a set of files + containing a definition of its structure. The form used for + this purpose is the <EMPHASIS>Component Definition + Language</EMPHASIS> (CDL). CDL defines the relationships + between components and other information used by tools such + as the <productname>eCos</productname><APPLICATION>Configuration Tool</APPLICATION>. + CDL is generally formulated by the writers of components: it + is not necessary to write or understand CDL in order for the + embedded systems developer to construct an <productname>eCos</productname> + configuration. </PARA> +</SECT1> +<SECT1 id="cdl-packages"> +<TITLE>Packages</TITLE> +<PARA>The building blocks of an <productname>eCos</productname> configuration are called + <EMPHASIS>packages</EMPHASIS>. Packages are the units of + software distribution. A set of core packages (such as + kernel, C library and math library) is provided by Red Hat: + additional third-party packages will be available in + future.</PARA> +<PARA>A package may exist in one of a number of <EMPHASIS>versions</EMPHASIS>. + The default version is the <EMPHASIS>current</EMPHASIS> version. + Only one version of a given package may be present in the component +repository at any given time.</PARA> +<PARA>Packages are organized in a tree hierarchy. Each package +is either at the top-level or is the child of another package.</PARA> +<PARA>The <productname>eCos</productname> <application> Package Administration Tool</application> can be used to add or remove +packages from the component repository. The <productname>eCos</productname> <APPLICATION>Configuration Tool</APPLICATION> can be used to include or exclude packages from the configuration +being built.</PARA> +</SECT1> +<SECT1 id="cdl-configuration-items"> +<TITLE>Configuration Items</TITLE> +<PARA><EMPHASIS>Configuration items</EMPHASIS> are the + individual entities that form a configuration. Each item + corresponds to the setting of a C pre-processor macro (for + example, + <literal>CYGHWR_HAL_ARM_PID_GDB_BAUD</literal>). + The code of <productname>eCos</productname> itself is written to test such pre-processor + macros so as to tailor the code. User code can do + likewise.</PARA> +<PARA>Configuration items come in the following flavors:</PARA> +<ITEMIZEDLIST> +<LISTITEM> +<PARA><EMPHASIS>None</EMPHASIS>: such entities serve only as +place holders in the hierarchy, allowing other entities to be grouped +more easily.</PARA> +</LISTITEM> +<LISTITEM> +<PARA><EMPHASIS>Boolean</EMPHASIS> entities are the most common +flavor; they correspond to units of functionality that can be either +enabled or disabled. If the entity is enabled then there will be +a #define; code will check the setting using, for example, #ifdef</PARA> +</LISTITEM> +<LISTITEM> +<PARA><EMPHASIS>Data</EMPHASIS> entities encapsulate some arbitrary +data. Other properties such as a set or range of legal values can +be used to constrain the actual values, for example to an integer +or floating point value within a certain range.</PARA> +</LISTITEM> +<LISTITEM> +<PARA><EMPHASIS>Booldata</EMPHASIS> entities combine the attributes +of <EMPHASIS>Boolean</EMPHASIS> and <EMPHASIS>Data</EMPHASIS>: they +can be enabled or disabled and, if enabled, will hold a data value.</PARA> +</LISTITEM> +</ITEMIZEDLIST> +<PARA>Like packages, configuration items exist in a tree-based hierarchy: +each configuration item has a parent which may be another configuration +item or a package. Under some conditions (such as when packages +are added or removed from a configuration), items may be “re-parented” such +that their position in the tree changes. </PARA> +<SECT2> +<TITLE>Expressions</TITLE> +<PARA>Expressions are relationships between CDL items. There are +three types of expression in CDL:</PARA> + <table id="cdl-expressions"> + <title>CDL Expressions</title> + <tgroup cols="3"> + <thead> + <row> + <entry>Expression Type</entry> + <entry>Result</entry> + <entry>Common Use (see <xref linkend="table-configuration-properties">)</entry></row> + </thead> + <tbody> + <row> + <entry>Ordinary</entry> + <entry>A single value</entry> + <entry>legal_values property</entry> + </row> + <row> + <entry>List</entry><entry>A range of + values (for example “1 to 10”)</entry> + <entry>legal_values property </entry></row> + <row> + <entry>Goal</entry><entry>True or False</entry> + <entry>requires and active_if properties</entry></row> + </tbody> + </tgroup> + </table> + </SECT2> + <SECT2> + <TITLE>Properties</TITLE> +<PARA>Each configuration item has a set of properties. The following +table describes the most commonly used:</PARA> + <table id="table-configuration-properties"> + <title>Configuration properties</title> + <tgroup cols="2"> + <thead><row> + <entry><emphasis>Property</emphasis></entry> +<entry><emphasis>Use </emphasis></entry></row> + </thead> + <tbody> + <row> + <entry>Flavor</entry> + <entry>The “type” of the item, as + described above </entry></row> + <row> + <entry>Enabled</entry><entry>Whether + the item is enabled </entry></row> + <row> + <entry>Current_value</entry> +<entry>The current value of the item </entry></row> + <row> + <entry>Default_value</entry> +<entry>An ordinary expression defining the default value of the + item</entry></row> + <row> + <entry>Legal_values</entry><entry>A + list expression defining the values the item may hold (for example, + 1 to10) </entry></row> + <row> + <entry>Active_if</entry><entry>A + goal expression denoting the requirement for this item to be active +(see below: <emphasis>Inactive Items</emphasis>) </entry></row> +<row> +<entry>Requires</entry><entry>A goal +expression denoting requirements this item places on others (see +below: <emphasis>Conflicts</emphasis>) </entry></row> +<row> +<entry>Calculated</entry><entry>Whether +the item as non-modifiable </entry></row> +<row> +<entry>Macro</entry><entry>The corresponding +C pre-processor macro </entry></row> +<row> +<entry>File</entry><entry>The C header +file in which the macro is defined </entry></row> +<row> +<entry>URL</entry><entry>The URL of +a documentation page describing the item </entry></row> +<row> +<entry>Hardware</entry><entry>Indicates +that a particular package is related to specific hardware</entry></row> + </tbody> + </tgroup> + </table> + +<PARA>A complete description of properties is contained in the <citetitle>Component +Writer’s Guide</citetitle>.</PARA> +</SECT2> +<SECT2> +<TITLE>Inactive Items</TITLE> +<PARA>Descendants of an item that is disabled are inactive: their +values may not be changed. Items may also become <EMPHASIS>inactive</EMPHASIS> if +an active_if expression is used to make the item dependent +on an expression involving other items. </PARA> +</SECT2> +</SECT1> +<SECT1 id="cdl-conflicts"> +<TITLE>Conflicts</TITLE> +<PARA>Not all settings of configuration items will lead to a + coherent configuration; for example, the use of a timeout + facility might require the existence of timer support, so if + the one is required the other cannot be removed. Coherence + is policed by means of consistency rules (in particular, the + goal expressions that appear as CDL items + <EMPHASIS>requires</EMPHASIS> and + <EMPHASIS>active_if</EMPHASIS> attributes [see + above]). A violation of consistency rules creates a + <EMPHASIS>conflict</EMPHASIS>, which must be resolved in + order to ensure a consistent configuration. Conflict + resolution can be performed manually or with the assistance + of the <productname>eCos</productname> tools. Conflicts come in the following + flavors:</PARA> +<ITEMIZEDLIST> +<LISTITEM> +<PARA>An <EMPHASIS>unresolved</EMPHASIS> conflict means that +there is a reference to an entity that is not yet in the current +configuration </PARA> +</LISTITEM> +<LISTITEM> +<PARA>An <EMPHASIS>illegal value</EMPHASIS> conflict is caused +when a configuration item is set to a value that is not permitted +(that is, a <EMPHASIS>legal_values</EMPHASIS> goal expression +is failing) </PARA> +</LISTITEM> +<LISTITEM> +<PARA>An <EMPHASIS>evaluation exception</EMPHASIS> conflict +is caused when the evaluation of an expression would fail (for example, +because of a division by zero) </PARA> +</LISTITEM> +<LISTITEM> +<PARA>An <EMPHASIS>unsatisfied goal</EMPHASIS> conflict is caused +by a failing <EMPHASIS>requires</EMPHASIS> goal expression </PARA> +</LISTITEM> +<LISTITEM> +<PARA>A <EMPHASIS>bad data</EMPHASIS> conflict arises only rarely, +and corresponds to badly constructed CDL. Such a conflict can only +be resolved by reference to the CDL writer.</PARA> +</LISTITEM> +</ITEMIZEDLIST> +</SECT1> +<SECT1 id="cdl-templates"> +<TITLE>Templates</TITLE> +<PARA>A <EMPHASIS>template</EMPHASIS> is a saved configuration + - that is, a set of packages and configuration item + settings. Templates are provided with <productname>eCos</productname> to allow you to + get started quickly by instantiating (copying) a saved + configuration corresponding to one of a number of common + scenarios; for example, a basic <productname>eCos</productname> configuration template + is supplied that contains the infrastructure, kernel, C and + math libraries, plus their support packages.</PARA> +</SECT1> +</CHAPTER> +<CHAPTER id="component-repo-and-working-dirs"> +<TITLE>The Component Repository and Working Directories</TITLE> +<PARA>Each of the file trees involved in <productname>eCos</productname> development has a + different role. </PARA> +<SECT1 id="component-repo"> +<TITLE>Component Repository</TITLE> +<PARA>The <productname>eCos</productname> <FIRSTTERM>component repository</FIRSTTERM> + contains directories for all the packages that are shipped + with <productname>eCos</productname> or provided by third parties.</PARA> +<PARA>The component repository should not be modified as part of +application development. </PARA> +<!-- +<para> +XXXXX We may want to change this picture XXXXX +</para> +--> +<FIGURE> +<TITLE>Component repository</TITLE> +<GRAPHIC ENTITYREF="graphic30"></GRAPHIC> +</FIGURE> +<SECT2> +<TITLE>Purpose</TITLE> +<PARA>The component repository is the master copy of source code +for all system and third party components. It also contains some +files needed to administer and build the system, such as <command>ecosadmin.tcl</command>.</PARA> +</SECT2> +<SECT2> +<TITLE>How is it modified?</TITLE> +<PARA>You modify it by importing new versions of packages from a +distribution or removing existing packages. These activities are +undertaken using the <productname>eCos</productname> <application>Package Administration Tool</application>.</PARA> +</SECT2> +<SECT2> +<TITLE>When is it edited manually?</TITLE> +<PARA>Files in the component repository should only be edited manually +as determined by the component maintainer.</PARA> +</SECT2> +<SECT2> +<TITLE>User Applications</TITLE> +<PARA>User application source code should <EMPHASIS>not</EMPHASIS> go +into the component repository.</PARA> +</SECT2> +<SECT2> +<TITLE>Examples of files in this hierarchy:</TITLE> +<VARIABLELIST> +<VARLISTENTRY> +<TERM><FILENAME><REPLACEABLE>BASE_DIR</REPLACEABLE>/doc/ref/ecos-ref.html</FILENAME></TERM> +<LISTITEM> +<PARA>The top level HTML file for the + <citetitle><PRODUCTNAME>eCos</PRODUCTNAME> Reference + Manual</citetitle>. </PARA> +</LISTITEM> +</VARLISTENTRY> +<VARLISTENTRY> +<TERM><FILENAME><REPLACEABLE>BASE_DIR</REPLACEABLE>/prebuilt/pid/tests/kernel/<replaceable>&Version;</replaceable>/tests/thread_gdb.exe</FILENAME></TERM> +<LISTITEM> +<PARA></PARA> +</LISTITEM> +</VARLISTENTRY> +<VARLISTENTRY> +<TERM><FILENAME><REPLACEABLE>BASE_DIR</REPLACEABLE>/prebuilt/linux/tests/kernel/<replaceable>&Version;</replaceable>/tests/thread_gdb.exe</FILENAME></TERM> +<LISTITEM> +<PARA>Pre-built tests for the supported platforms, and + the synthetic Linux target.</PARA> +</LISTITEM> +</VARLISTENTRY> +<VARLISTENTRY> +<TERM><FILENAME><REPLACEABLE>BASE_DIR</REPLACEABLE>/examples/twothreads.c</FILENAME></TERM> +<LISTITEM> +<PARA>One of the example programs.</PARA> +</LISTITEM> +</VARLISTENTRY> +<VARLISTENTRY> +<TERM><FILENAME><REPLACEABLE>BASE_DIR</REPLACEABLE>/ecosadmin.tcl</FILENAME></TERM> +<LISTITEM> +<para>The Tcl program which is used to import new versions of packages +from a distribution or remove existing packages.</para> +</LISTITEM> +</VARLISTENTRY> +<VARLISTENTRY> +<TERM><FILENAME><REPLACEABLE>BASE_DIR</REPLACEABLE>/packages/language/c/libm/<replaceable>&Version;</replaceable>/src/double/portable-api/s_tanh.c</FILENAME></TERM> +<LISTITEM> +<para>Implementation of the hyperbolic tangent function in the standard +math library.</para> +</LISTITEM> +</VARLISTENTRY> +<VARLISTENTRY> +<TERM><FILENAME><REPLACEABLE>BASE_DIR</REPLACEABLE>/pkgconf/rules.mak</FILENAME></TERM> +<LISTITEM> +<para>A file with <command>make</command> rules, used +by the <FILENAME>makefile</FILENAME>.</para> +</LISTITEM> +</VARLISTENTRY> +</VARIABLELIST> +</SECT2> +</SECT1> +<SECT1 id="build-tree"> +<TITLE>Build Tree</TITLE> +<PARA>The <FIRSTTERM>build tree</FIRSTTERM> is the directory + hierarchy in which all <EMPHASIS>generated</EMPHASIS> files + are placed. Generated files consist of the + <FILENAME>makefile</FILENAME>, the compiled object files, + and a dependency file (with a <FILENAME>.d</FILENAME> + extension) for each source file.</PARA> +<SECT2><!--<conditionaltext>--> +<TITLE>Purpose</TITLE> +<PARA>The build tree is where all intermediate object files are + placed. </PARA> +</SECT2> +<SECT2> +<TITLE>How is it modified?</TITLE> +<PARA>Recompiling can modify the object files.</PARA> +</SECT2> +<SECT2> +<TITLE>User applications</TITLE> +<PARA>User application source or binary code should + <EMPHASIS>not</EMPHASIS> go in the build tree. </PARA> +</SECT2> +<SECT2> +<TITLE>Examples of files in this hierarchy</TITLE> +<VARIABLELIST> +<VARLISTENTRY> +<TERM><FILENAME>ecos-work/language/c/libc/<replaceable>&Version;</replaceable>/src</FILENAME></TERM> +<LISTITEM> +<PARA>The directory in which object files for + the C library are built.</PARA> +</LISTITEM> +</VARLISTENTRY> +</VARIABLELIST> +</SECT2> +</SECT1> +<SECT1 id="install-tree"> +<TITLE>Install Tree</TITLE> +<PARA>The <FIRSTTERM>install tree</FIRSTTERM> is the location + for all files needed for application development. The + <filename>libtarget.a</filename> library, which contains the + custom-built <productname>eCos</productname> kernel and other components, is placed + in the install tree, along with all packages’ public + header files. If you build the tests, the test executable + programs will also be placed in the install + tree. </PARA> +<PARA>By default, the install tree is created by + <COMMAND>ecosconfig</COMMAND> in a subdirectory of the build + tree called <FILENAME>install</FILENAME>. This can be + modified with the <OPTION>--prefix</OPTION> option (see + <xref linkend="manual-configuration">). + </PARA> +<SECT2><!--<conditionaltext>--> +<TITLE>Purpose</TITLE> +<PARA>The install tree is where the custom-built + <FILENAME>libtarget.a</FILENAME> library, which contains + the <productname>eCos</productname> kernel and other components, is located. The + install tree is also the location for all the header files + that are part of a published interface for their + component. </PARA> +</SECT2> +<SECT2> +<TITLE>How is it modified?</TITLE> +<PARA>Recompiling can replace + <FILENAME>libtarget.a</FILENAME> and the test + executables. </PARA> +</SECT2> +<SECT2> +<TITLE>When is it edited manually?</TITLE> +<PARA>Where a memory layout requires modification without + use of the <productname>eCos</productname> <application>Configuration Tool</application>, the memory layout + files must be edited directly in the install tree. These + files are located at + <FILENAME>install/include/pkgconf/mlt_*.*</FILENAME>. + Note that subsequent modification of the install tree + using the Configuration Tool will result in such manual + edits being lost.</PARA> +</SECT2> +<SECT2> +<TITLE>User applications</TITLE> +<PARA>User application source or binary code should + <EMPHASIS>not</EMPHASIS> go in the install tree. </PARA> +</SECT2> +<SECT2> +<TITLE>Examples of files in this hierarchy</TITLE> +<VARIABLELIST> +<VARLISTENTRY> +<TERM><FILENAME>install/lib/libtarget.a</FILENAME></TERM> +<LISTITEM> +<PARA>The library containing the kernel and other components.</PARA> +</LISTITEM> +</VARLISTENTRY> +<VARLISTENTRY> +<TERM><FILENAME>install/include/cyg/kernel/kapi.h</FILENAME></TERM> +<LISTITEM> +<PARA>The header file for the kernel C language API.</PARA> +</LISTITEM> +</VARLISTENTRY> +<VARLISTENTRY> +<TERM><FILENAME>install/include/pkgconf/mlt_arm_pid_ram.ldi</FILENAME></TERM> +<LISTITEM> +<PARA>The linker script fragment describing the memory + layout for linking applications intended for + execution on an ARM PID development board using RAM + startup.</PARA> +</LISTITEM> +</VARLISTENTRY> +<VARLISTENTRY> +<TERM><FILENAME>install/include/stdio.h</FILENAME></TERM> +<LISTITEM> +<PARA>The C library header file for standard I/O. </PARA> +</LISTITEM> +</VARLISTENTRY> +</VARIABLELIST> +</SECT2> +</SECT1> +<SECT1 id="repository-app-build-tree"> +<TITLE>Application Build Tree</TITLE> +<PARA>This tree is not part of <productname>eCos</productname> itself: it is the + directory in which <productname>eCos</productname> end users write their own + applications.</PARA> +<PARA>Example applications and their + <FILENAME>Makefile</FILENAME> are located in the component + repository, in the directory + <FILENAME>BASE_DIR</FILENAME><FILENAME>/examples</FILENAME>. + + </PARA> +<PARA>There is no imposed format on this directory, but there + are certain compiler and linker flags that must be used to + compile an <productname>eCos</productname> application. The basic set of flags is shown + in the example <FILENAME>Makefile</FILENAME>, and additional + details can be found in <xref linkend="compiler-and-linker-options">. </PARA> +</SECT1> +</CHAPTER> +<CHAPTER id="compiler-and-linker-options"> +<TITLE>Compiler and Linker Options</TITLE> + + <PARA><productname>eCos</productname> is built using + the GNU C and C++ compilers. <productname>eCos</productname> relies on certain features of these + tools such as constructor priority ordering and selective linking + which are not part of other toolchains. + </PARA> + +<PARA>Some <application>GCC</application> options are required for <productname>eCos</productname>, +and others can be useful. This chapter gives a brief description +of the required options as well as some recommended <productname>eCos</productname>-specific options. +All other <application>GCC</application> options (described in the <application>GCC</application> manuals) +are available. </PARA> +<SECT1 id="compiling-c-app"> +<TITLE>Compiling a C Application</TITLE> +<PARA>The following command lines demonstrate the + <EMPHASIS>minimum</EMPHASIS> set of options required to + compile and link an <productname>eCos</productname> program written in C. </PARA> +<NOTE> +<PARA>Remember that when this manual shows + <COMMAND><replaceable>TARGET-</replaceable>gcc</COMMAND> + you should use the full name of the cross compiler, + e.g. <COMMAND>i386-elf-gcc</COMMAND>, + <COMMAND>arm-elf-gcc</COMMAND>, or + <COMMAND>sh-elf-gcc</COMMAND>. When compiling for the + synthetic Linux target, use the native + <command>gcc</command> which must have the features + required by <productname>eCos</productname>.</PARA> +</NOTE> +<SCREEN> +$ <replaceable>TARGET-</replaceable>gcc -c -I<EMPHASIS>INSTALL_DIR</EMPHASIS>/include file.c +$ <replaceable>TARGET-</replaceable>gcc -o program file.o -L<EMPHASIS>INSTALL_DIR</EMPHASIS>/lib -Ttarget.ld -nostdlib +</SCREEN> +<NOTE> +<PARA>Certain targets may require extra options, for example + the SPARClite architectures require the option + <OPTION>-mcpu=sparclite</OPTION>. Examine the + <FILENAME><REPLACEABLE>BASE_DIR</REPLACEABLE>/examples/Makefile</FILENAME> + or the “Global compiler flags” option + (CYGBLD_GLOBAL_CFLAGS) in your generated + <productname>eCos</productname> configuration) to see if any extra options are + required, and if so, what they are. </PARA> +<PARA>The following command lines use some other options + which are recommended because they use the + <!-- <index></index> -->selective linking feature:</PARA> +<SCREEN>$ <replaceable>TARGET-</replaceable>gcc -c -I<REPLACEABLE>INSTALL_DIR</REPLACEABLE>/include -I. -ffunction-sections -fdata-sections -g -O2 file.c +$ <replaceable>TARGET-</replaceable>gcc -o program file.o -ffunction-sections -fdata-sections -Wl,--gc-sections -g -O2 \ + -L<REPLACEABLE>INSTALL_DIR</REPLACEABLE>/lib -Ttarget.ld -nostdlib +</SCREEN> + +</NOTE> +</SECT1> +<SECT1 id="compiling-cpp-app"> +<TITLE>Compiling a C++ Application</TITLE> +<PARA>The following command lines demonstrate the + <EMPHASIS>minimum</EMPHASIS> set of options required to + compile and link an <productname>eCos</productname> program written in C++. + </PARA> +<NOTE> +<PARA>Remember that when this manual shows + <COMMAND><replaceable>TARGET-</replaceable>g++</COMMAND> + you should use the full name of the cross compiler, + e.g. <COMMAND>i386-elf-g++</COMMAND>, + <COMMAND>arm-elf-g++</COMMAND>, or + <COMMAND>sh-elf-g++</COMMAND>. When compiling for the + synthetic Linux target, use the native + <command>g++</command> which must have the features + required by <productname>eCos</productname>.</PARA> +</NOTE> +<SCREEN>$ <replaceable>TARGET-</replaceable>g++ -c -I<REPLACEABLE>INSTALL_DIR</REPLACEABLE>/include -fno-rtti -fno-exceptions file.cxx +$ <replaceable>TARGET-</replaceable>g++ -o program file.o -L<REPLACEABLE>INSTALL_DIR</REPLACEABLE>/lib -Ttarget.ld -nostdlib +</SCREEN> + +<NOTE> +<PARA>Certain targets may require extra options, + for example the SPARClite architectures require the option + <OPTION>-mcpu=sparclite</OPTION>. Examine the + <FILENAME><REPLACEABLE>BASE_DIR</REPLACEABLE>/packages/targets</FILENAME> + file or <FILENAME><REPLACEABLE>BASE_DIR</REPLACEABLE>/examples/Makefile</FILENAME> + or the “Global compiler flags” option + (CYGBLD_GLOBAL_CFLAGS) in your generated + <productname>eCos</productname> configuration) to see if any extra options are + required, and if so, what they are.</PARA> +<PARA>The following command lines use some other options + which are recommended because they use the + <FIRSTTERM>selective linking</FIRSTTERM> feature:</PARA> +<SCREEN> +$ <replaceable>TARGET-</replaceable>g++ -c -I<REPLACEABLE>INSTALL_DIR</REPLACEABLE>/include -I. -ffunction-sections -fdata-sections -fno-rtti \ + -fno-exceptions -finit-priority -g -O2 file.cxx +$ <replaceable>TARGET-</replaceable>g++ -o program file.o -W1,--gc-sections -g -O2 -L<REPLACEABLE>INSTALL_DIR</REPLACEABLE>/lib -Ttarget.ld -nostdlib</SCREEN> +</NOTE> +</SECT1> +</CHAPTER> + +<CHAPTER id="debugging-techniques"> +<TITLE>Debugging Techniques</TITLE> +<PARA><productname>eCos</productname> applications and components can be debugged in + traditional ways, with printing statements and debugger + single-stepping, but there are situations in which these + techniques cannot be used. One example of this is when a + program is getting data at a high rate from a real-time + source, and cannot be slowed down or interrupted.</PARA> +<PARA><productname>eCos</productname>’s infrastructure module provides a + <EMPHASIS>tracing</EMPHASIS> formalism, allowing the + kernel’s tracing macros to be configured in many useful + ways. <productname>eCos</productname>’s kernel provides <FIRSTTERM>instrumentation + buffers</FIRSTTERM> which also collect specific + (configurable) data about the system’s history and + performance.</PARA> +<SECT1 id="tracing"> +<TITLE>Tracing</TITLE> +<PARA>To use <productname>eCos</productname>’s tracing facilities you must first + configure your system to use <FIRSTTERM>tracing</FIRSTTERM>. + You should enable the Asserts and Tracing component + (<OPTION>CYGPKG_INFRA_DEBUG</OPTION>) and the + <OPTION>Use tracing</OPTION> component within it + (<OPTION>CYGDBG_USE_TRACING</OPTION>). These + options can be enabled with the <APPLICATION>Configuration + Tool</APPLICATION> or by editing the file + <FILENAME><REPLACEABLE>BUILD_DIR</REPLACEABLE>/pkgconf/infra.h + </FILENAME> manually.</PARA> +<PARA>You should then examine all the tracing-related options in +the <citetitle>Package: Infrastructure</citetitle> chapter of the <citetitle><PRODUCTNAME>eCos</PRODUCTNAME> Reference +Manual</citetitle>. One useful set of configuration options are: <literal>CYGDBG_INFRA_DEBUG_FUNCTION_REPORTS</literal> and <literal>CYGDBG_INFRA_DEBUG_TRACE_MESSAGE</literal>, +which are both enabled by default when tracing is enabled.</PARA> +<PARA>The following “Hello world with tracing” shows +the output from running the hello world program (from <xref linkend="ecos-hello-world">) that was +built with tracing enabled: </PARA> +<EXAMPLE> +<TITLE>Hello world with tracing</TITLE> +<SCREEN>$ mips-tx39-elf-run --board=jmr3904 hello +Hello, eCos world! +ASSERT FAIL: <2>cyg_trac.h [ 623] Cyg_TraceFunction_Report_::set_exitvoid() exitvoid used in typed function +TRACE: <1>mlqueue.cxx [ 395] Cyg_ThreadQueue_Implementation::enqueue() {{enter +TRACE: <1>mlqueue.cxx [ 395] Cyg_ThreadQueue_Implementation::enqueue() }}RETURNING UNSET! +TRACE: <1>mlqueue.cxx [ 126] Cyg_Scheduler_Implementation::add_thread() }}RETURNING UNSET! +TRACE: <1>thread.cxx [ 654] Cyg_Thread::resume() }}return void +TRACE: <1>cstartup.cxx [ 160] cyg_iso_c_start() }}return void +TRACE: <1>startup.cxx [ 142] cyg_package_start() }}return void +TRACE: <1>startup.cxx [ 150] cyg_user_start() {{enter +TRACE: <1>startup.cxx [ 150] cyg_user_start() (((void))) +TRACE: <1>startup.cxx [ 153] cyg_user_start() 'This is the system default cyg_user_start()' +TRACE: <1>startup.cxx [ 157] cyg_user_start() }}return void +TRACE: <1>sched.cxx [ 212] Cyg_Scheduler::start() {{enter +TRACE: <1>mlqueue.cxx [ 102] Cyg_Scheduler_Implementation::schedule() {{enter +TRACE: <1>mlqueue.cxx [ 437] Cyg_ThreadQueue_Implementation::highpri() {{enter +TRACE: <1>mlqueue.cxx [ 437] Cyg_ThreadQueue_Implementation::highpri() }}RETURNING UNSET! +TRACE: <1>mlqueue.cxx [ 102] Cyg_Scheduler_Implementation::schedule() }}RETURNING UNSET! +TRACE: <2>intr.cxx [ 450] Cyg_Interrupt::enable_interrupts() {{enter +TRACE: <2>intr.cxx [ 450] Cyg_Interrupt::enable_interrupts() }}RETURNING UNSET! +TRACE: <2>thread.cxx [ 69] Cyg_HardwareThread::thread_entry() {{enter +TRACE: <2>cstartup.cxx [ 127] invoke_main() {{enter +TRACE: <2>cstartup.cxx [ 127] invoke_main() ((argument is ignored)) +TRACE: <2>dummyxxmain.cxx [ 60] __main() {{enter +TRACE: <2>dummyxxmain.cxx [ 60] __main() (((void))) +TRACE: <2>dummyxxmain.cxx [ 63] __main() 'This is the system default __main()' +TRACE: <2>dummyxxmain.cxx [ 67] __main() }}return void +TRACE: <2>memcpy.c [ 112] _memcpy() {{enter +TRACE: <2>memcpy.c [ 112] _memcpy() ((dst=80002804, src=BFC14E58, n=19)) +TRACE: <2>memcpy.c [ 164] _memcpy() }}returning 80002804 +TRACE: <2>cstartup.cxx [ 137] invoke_main() 'main() has returned with code 0. Calling exit()' +TRACE: <2>exit.cxx [ 71] __libc_exit() {{enter +TRACE: <2>exit.cxx [ 71] __libc_exit() ((status=0 )) +TRACE: <2>atexit.cxx [ 84] cyg_libc_invoke_atexit_handlers() {{enter +TRACE: <2>atexit.cxx [ 84] cyg_libc_invoke_atexit_handlers() (((void))) + +Scheduler: + +Lock: 0 +Current Thread: <null> + +Threads: + +Idle Thread pri = 31 state = R id = 1 + stack base = 800021F0 ptr = 80002510 size = 00000400 + sleep reason NONE wake reason NONE + queue = 80000C54 wait info = 00000000 + +<null> pri = 0 state = R id = 2 + stack base = 80002A48 ptr = 8000A968 size = 00008000 + sleep reason NONE wake reason NONE + queue = 80000BD8 wait info = 00000000 + </SCREEN> +</EXAMPLE> +</SECT1> +<SECT1 id="kernel-instrumentation"> +<TITLE>Kernel Instrumentation</TITLE> +<PARA><FIRSTTERM>Instrument buffers</FIRSTTERM> can be used to + find out how many events of a given type happened in the + kernel during execution of a program.</PARA> +<PARA>You can monitor a class of several types of events, or + you can just look at individual events. </PARA> +<PARA>Examples of <FIRSTTERM>events</FIRSTTERM> that can be + monitored are: + </PARA> +<ITEMIZEDLIST> +<LISTITEM> +<PARA>scheduler events </PARA> +</LISTITEM> +<LISTITEM> +<PARA>thread operations</PARA> +</LISTITEM> +<LISTITEM> +<PARA>interrupts </PARA> +</LISTITEM> +<LISTITEM> +<PARA>mutex operations </PARA> +</LISTITEM> +<LISTITEM> +<PARA>binary semaphore operations </PARA> +</LISTITEM> +<LISTITEM> +<PARA>counting semaphore operations </PARA> +</LISTITEM> +<LISTITEM> +<PARA>condition variable operations </PARA> +</LISTITEM> +<LISTITEM> +<PARA>event flag operations </PARA> +</LISTITEM> +<LISTITEM> +<PARA>message box operations </PARA> +</LISTITEM> +<LISTITEM> +<PARA>clock ticks, interrupts and alarms</PARA> +</LISTITEM> +</ITEMIZEDLIST> +<PARA>Examples of fine-grained scheduler event types are: </PARA> +<ITEMIZEDLIST> +<LISTITEM> +<PARA>scheduler lock</PARA> +</LISTITEM> +<LISTITEM> +<PARA>scheduler unlock</PARA> +</LISTITEM> +<LISTITEM> +<PARA>rescheduling</PARA> +</LISTITEM> +<LISTITEM> +<PARA>time slicing </PARA> +</LISTITEM> +</ITEMIZEDLIST> +<PARA>Information about the events is stored in an + <FIRSTTERM>event record</FIRSTTERM>. The structure that + defines this record has type <type>struct + Instrument_Record</type>: +</PARA> +<PARA>The list of records is stored in an array called <TYPE>instrument_buffer</TYPE> +which you can let the kernel provide or you can provide yourself +by setting the configuration option <literal>CYGVAR_KERNEL_INSTRUMENT_EXTERNAL_BUFFER</literal>. </PARA> +<PARA>To write a program that examines the instrumentation + buffers: </PARA> +<ORDEREDLIST> +<LISTITEM> +<PARA>Enable instrumentation buffers in the <productname>eCos</productname> kernel configuration. +The component macro is <literal>CYGPKG_KERNEL_INSTRUMENT</literal>.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>To allocate the buffers yourself, enable the configuration +option <literal>CYGVAR_KERNEL_INSTRUMENT_EXTERNAL_BUFFER</literal>. </PARA> +</LISTITEM> +<LISTITEM> +<PARA>Include the header file +<FILENAME>cyg/kernel/instrmnt.h</FILENAME> +. +<PROGRAMLISTING>#include <cyg/kernel/instrmnt.h></PROGRAMLISTING></PARA> +</LISTITEM> +<LISTITEM> +<PARA>The <STRUCTNAME>Instrumentation_Record</STRUCTNAME> structure +is not published in the kernel header file. In the future there +will be a cleaner mechanism to access it, but for now you should +paste into your code in the following lines: + </para> +<PROGRAMLISTING>struct Instrument_Record +{ + CYG_WORD16 type; // record type + CYG_WORD16 thread; // current thread id + CYG_WORD timestamp; // 32 bit timestamp + CYG_WORD arg1; // first arg + CYG_WORD arg2; // second arg +};</PROGRAMLISTING> +</LISTITEM> +<LISTITEM> +<PARA>Enable the events you want to record using +<FUNCTION>cyg_instrument_enable()</FUNCTION> +, and disable them later. Look at +<filename>cyg/kernel/instrmnt.h</filename> + and the examples below to see what events can be enabled. </PARA> +</LISTITEM> +<LISTITEM> +<PARA>Place the code you want to debug between the matching +functions +<FUNCTION>cyg_instrument_enable()</FUNCTION> + and +<FUNCTION>cyg_instrument_disable()</FUNCTION> +. </PARA> +</LISTITEM> +<LISTITEM> +<PARA>Examine the buffer. For now you need to look at the data +in there (the example program below shows how to do that), and future +versions of <productname>eCos</productname> will include a host-side tool to help you understand +the data. </PARA> +</LISTITEM> +</ORDEREDLIST> +<EXAMPLE> +<TITLE>Using instrument buffers</TITLE> +<PARA>This program is also provided in the + <FILENAME>examples</FILENAME> directory. + </PARA> +<PROGRAMLISTING> +/* this is a program which uses <productname>eCos</productname> instrumentation buffers; it needs + to be linked with a kernel which was compiled with support for + instrumentation */ + +#include <stdio.h> +#include <pkgconf/kernel.h> +#include <cyg/kernel/instrmnt.h> +#include <cyg/kernel/kapi.h> + +#ifndef CYGVAR_KERNEL_INSTRUMENT_EXTERNAL_BUFFER +# error You must configure eCos with CYGVAR_KERNEL_INSTRUMENT_EXTERNAL_BUFFER +#endif + +struct Instrument_Record +{ + CYG_WORD16 type; // record type + CYG_WORD16 thread; // current thread id + CYG_WORD timestamp; // 32 bit timestamp + CYG_WORD arg1; // first arg + CYG_WORD arg2; // second arg +}; + +struct Instrument_Record instrument_buffer[20]; +cyg_uint32 instrument_buffer_size = 20; + +int main(void) +{ + int i; + + cyg_instrument_enable(CYG_INSTRUMENT_CLASS_CLOCK, 0); + cyg_instrument_enable(CYG_INSTRUMENT_CLASS_THREAD, 0); + cyg_instrument_enable(CYG_INSTRUMENT_CLASS_ALARM, 0); + + printf("Program to play with instrumentation buffer\n"); + + cyg_thread_delay(2); + + cyg_instrument_disable(CYG_INSTRUMENT_CLASS_CLOCK, 0); + cyg_instrument_disable(CYG_INSTRUMENT_CLASS_THREAD, 0); + cyg_instrument_disable(CYG_INSTRUMENT_CLASS_ALARM, 0); + + for (i = 0; i < instrument_buffer_size; ++i) { + printf("Record %02d: type 0x%04x, thread %d, ", + i, instrument_buffer[i].type, instrument_buffer[i].thread); + printf("time %5d, arg1 0x%08x, arg2 0x%08x\n", + instrument_buffer[i].timestamp, instrument_buffer[i].arg1, + instrument_buffer[i].arg2); + } + return 0; +}</PROGRAMLISTING> +</EXAMPLE> +<PARA>Here is how you could compile and run this program in the <filename>examples</filename> directory, +using (for example) the MN10300 simulator target: </PARA> +<SCREEN> +$ make XCC=mn10300-elf-gcc INSTALL_DIR=/tmp/ecos-work-mn10300/install instrument-test +mn10300-elf-gcc -c -o instrument-test.o -g -Wall -I/tmp/ecos-work-mn10300/install/include \ + -ffunction-sections -fdata-sections instrument-test.c +mn10300-elf-gcc -nostartfiles -L/tmp/ecos-work-mn10300/install/lib -W1,--gc-sections -o \ + instrument-test instrument-test.o -Ttarget.ld -nostdlib +$ mn10300-elf-run --board=stdeval1 instrument-test +</SCREEN> +<EXAMPLE> +<TITLE>Instrument buffer output</TITLE> +<PARA>Here is the output of the + <COMMAND>instrument-test</COMMAND> program. Notice that in + little over 2 seconds, and with very little activity, and + with few event types enabled, it gathered 17 records. In + larger programs it will be necessary to select very few + event types for debugging. </PARA> +<PROGRAMLISTING>Program to play with instrumentation buffer +Record 00: type 0x0207, thread 2, time 6057, arg1 0x48001cd8, arg2 0x00000002 +Record 01: type 0x0202, thread 2, time 6153, arg1 0x48001cd8, arg2 0x00000000 +Record 02: type 0x0904, thread 2, time 6358, arg1 0x48001d24, arg2 0x00000000 +Record 03: type 0x0905, thread 2, time 6424, arg1 0x00000002, arg2 0x00000000 +Record 04: type 0x0906, thread 2, time 6490, arg1 0x00000000, arg2 0x00000000 +Record 05: type 0x0901, thread 2, time 6608, arg1 0x48009d74, arg2 0x48001d24 +Record 06: type 0x0201, thread 2, time 6804, arg1 0x48001cd8, arg2 0x480013e0 +Record 07: type 0x0803, thread 1, time 94, arg1 0x00000000, arg2 0x00000000 +Record 08: type 0x0801, thread 1, time 361, arg1 0x00000000, arg2 0x00000000 +Record 09: type 0x0802, thread 1, time 548, arg1 0x00000001, arg2 0x00000000 +Record 10: type 0x0803, thread 1, time 94, arg1 0x00000000, arg2 0x00000000 +Record 11: type 0x0801, thread 1, time 361, arg1 0x00000001, arg2 0x00000000 +Record 12: type 0x0903, thread 1, time 513, arg1 0x48009d74, arg2 0x48001d24 +Record 13: type 0x0208, thread 1, time 588, arg1 0x00000000, arg2 0x00000000 +Record 14: type 0x0203, thread 1, time 697, arg1 0x48001cd8, arg2 0x480013e0 +Record 15: type 0x0802, thread 1, time 946, arg1 0x00000002, arg2 0x00000000 +Record 16: type 0x0201, thread 1, time 1083, arg1 0x480013e0, arg2 0x48001cd8 +Record 17: type 0x0000, thread 0, time 0, arg1 0x00000000, arg2 0x00000000 +Record 18: type 0x0000, thread 0, time 0, arg1 0x00000000, arg2 0x00000000 +Record 19: type 0x0000, thread 0, time 0, arg1 0x00000000, arg2 0x00000000</PROGRAMLISTING> +</EXAMPLE> +</SECT1> +</CHAPTER> +</PART> +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:nil +sgml-shorttag:t +sgml-namecase-general:t +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:2 +sgml-indent-data:t +sgml-parent-document:("user-guide.sgml" "book" "part") +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> diff --git a/ecos/doc/sgml/user-guide/programming.sgml b/ecos/doc/sgml/user-guide/programming.sgml new file mode 100644 index 0000000..9250528 --- /dev/null +++ b/ecos/doc/sgml/user-guide/programming.sgml @@ -0,0 +1,1337 @@ +<!-- {{{ Banner --> + +<!-- =============================================================== --> +<!-- --> +<!-- programming.sgml --> +<!-- --> +<!-- eCos User Guide --> +<!-- --> +<!-- =============================================================== --> +<!-- ####ECOSDOCCOPYRIGHTBEGIN#### --> +<!-- =============================================================== --> +<!-- Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002, 2003 Free Software Foundation, 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 --> +<!-- =============================================================== --> +<!-- ####ECOSDOCCOPYRIGHTEND#### --> +<!-- =============================================================== --> +<!-- #####DESCRIPTIONBEGIN#### --> +<!-- --> +<!-- ####DESCRIPTIONEND#### --> +<!-- =============================================================== --> + +<!-- }}} --> + +<part ID="user-guide-programming"> +<TITLE>Programming With <productname>eCos</productname></TITLE> + +<CHAPTER ID="PROGRAMMING-WITH-ECOS"> +<TITLE>Programming With <productname>eCos</productname></TITLE> + +<PARA>The following chapters of this manual comprise a simple tutorial +for configuring and building <productname>eCos</productname>, building and running <productname>eCos</productname> tests, +and finally building three stand-alone example programs which use +the <productname>eCos</productname> API to perform some simple tasks.</PARA> + +<PARA>You will need a properly installed <productname>eCos</productname> system, with the correct +versions of the GNU toolchain.<!-- <conditionaltext> --> On Windows +you will be using the bash command line interpreter that comes with +Cygwin, with the environment variables set as described in the +toolchain documentation.</PARA> + +<SECT1 id="development-process"> +<TITLE>The Development Process</TITLE> + +<PARA>Most development projects using <productname>eCos</productname> would contain some (or +most) of the following:</PARA> + +<SECT2> +<TITLE><productname>eCos</productname> Configuration</TITLE> + +<PARA><productname>eCos</productname> is configured to provide the desired API (the inclusion +of libc, uitron, and the disabling of certain undesired funtions, +etc.), and semantics (selecting scheduler, mutex behavior, etc.). +See <XREF LINKEND="CONFIGURING-AND-BUILDING-ECOS-FROM-SOURCE">.</PARA> + +<PARA>It would normally make sense to enable <productname>eCos</productname> assertion checking +at this time as well, to catch as many programming errors during +the development phase as possible.</PARA> + +<PARA>Note that it should not be necessary to spend much time on +<productname>eCos</productname> configuration initially. It may be important to perform fine +tuning to reduce the memory footprint and to improve performance +later when the product reaches a testable state.</PARA> +</SECT2> + +<SECT2> +<TITLE> Integrity check of the <productname>eCos</productname> configuration</TITLE> + +<PARA>While we strive to thoroughly test <productname>eCos</productname>, the vast number +of configuration permutations mean that the particular configuration +parameters used for your project may not have been tested. Therefore, +we advise running the <productname>eCos</productname> tests after the project's +<productname>eCos</productname> configuration has been determined. See <XREF LINKEND="RUNNING-AN-ECOS-TEST-CASE">.</PARA> + +<PARA>Obviously, this should be repeated if the configuration changes +later on in the development process.</PARA> +</SECT2> + +<SECT2> +<TITLE> Application Development - Target Neutral Part</TITLE> + +<PARA>While your project is probably targeting a specific architecture +and platform, possibly custom hardware, it may be possible to perform +part of the application development using simulated or synthetic +targets.</PARA> + +<PARA>There are three good reasons for doing this:</PARA> + +<ITEMIZEDLIST> + +<LISTITEM> +<PARA>It may be possible by this means to perform application +development in parallel with the design/implementation +of the target hardware, thus providing more time for developing +and testing functionality, and reducing time-to-market.</PARA> +</LISTITEM> + +<LISTITEM> +<PARA>The build-run-debug-cycle may be faster when the application +does not have to be downloaded to a target via a serial interface. +Debugging is also likely to be more responsive when you do not have to +to communicate with the remote GDB stubs in RedBoot via serial. It +also removes the need for manually or automatically resetting the +target hardware.</PARA> +</LISTITEM> + +<listitem> +<para> +New hardware can often be buggy. Comparing the behaviour of the +program on the hardware and in the simulator or synthetic target may +allow you to identify where the problems lie. +</para> +</listitem> + +</ITEMIZEDLIST> + +<PARA>This approach is possible because all targets (including +simulators and synthetic ones) provide the same basic API: that +is, kernel, libc, libm, uitron, infra, and to some extent, HAL and +IO.</PARA> + +<PARA>Synthetic targets are especially suitable as they allow you +to construct simulations of elaborate devices by interaction with +the host system, where an IO device API can hide the details from +the application. When switching to hardware later in the development +cycle, the IO driver is properly implemented. +</para> + +<para> +Simulators can also do this, but it all depends on the +design and capabilities of the simulator you use. Some, like +<ULINK URL="http://sources.redhat.com/sid">SID</ULINK> or +<ULINK URL="http://bochs.sourceforge.net/">Bochs</ULINK> provide +complete hardware emulation, while others just support enough of the +instruction set to run compiled code. +</PARA> + +<PARA>Therefore, select a simulator or synthetic target and use +it for as long as possible for application development. That is, +configure for the selected target, build <productname>eCos</productname>, build the application +and link with <productname>eCos</productname>, run and debug. Repeat the latter two steps until +you are happy with it.</PARA> + +<PARA>Obviously, at some time you will have to switch to the intended +target hardware, for example when adding target specific feature +support, for memory footprint/performance characterization, +and for final tuning of <productname>eCos</productname> and the application.</PARA> + +</SECT2> + +<SECT2> +<TITLE> Application Development - Target Specific Part</TITLE> + +<PARA>Repeat the build-run-debug-cycle while performing final tuning +and debugging of application. Remember to disable <productname>eCos</productname> assertion +checking if you are testing any performance-related aspects, it can +make a big difference.</PARA> + +<PARA>It may be useful to switch between this and the previous step +repeatedly through the development process; use the simulator/synthetic +target for actual development, and use the target hardware to continually +check memory footprint and performance. There should be little cost +in switching between the two targets when using two separate build +trees. </PARA> +</SECT2> + +</SECT1> + +</CHAPTER> + +<!-- ==================================================== --> + +<CHAPTER ID="CONFIGURING-AND-BUILDING-ECOS-FROM-SOURCE"><!-- <conditionaltext> --> +<TITLE><!-- <xref> --><!-- <index></index> -->Configuring and Building <productname>eCos</productname> from Source</TITLE> + +<PARA>This chapter documents the configuration of <productname>eCos</productname>. The process is +the same for any of the supported targets: you may select a +hardware target (if you have a board available), any one of the +simulators, or a synthetic target (if your host platform has synthetic +target support).</PARA> + +<!-- ==================================================== --> + +<SECT1 id="ecos-startup-configs"> +<TITLE><!-- <xref> --><productname>eCos</productname> Start-up Configurations</TITLE> + +<PARA>There are various ways to download an executable image to a +target board, and these involve different ways of preparing the +executable image. In the <productname>eCos</productname> Hardware Abstraction Layer (HAL package) +there are configuration options to support the different download +methods. <XREF LINKEND="user-guide-download-methods"> summarizes the +ways in which an <productname>eCos</productname> image can be prepared for different types of +download. This is not an exhaustive list, some targets define +additional start-up types of their own. Where a ROM Monitor is +mentioned, this will usually be RedBoot, although on some older, or +low resource, targets you may need to use CygMon or the GDB stubs ROM, +see the target documentation for details.</PARA> + + +<TABLE id="user-guide-download-methods"> +<TITLE>Configuration for various download methods</TITLE> +<TGROUP COLS="2"> +<THEAD> +<ROW> +<ENTRY>Download method</ENTRY> +<ENTRY>HAL configuration</ENTRY> +</ROW> +</THEAD> +<TBODY> +<ROW> +<ENTRY>Burn hardware ROM</ENTRY> +<ENTRY> ROM or ROMRAM start-up</ENTRY> +</ROW> +<ROW> +<ENTRY>Download to ROM emulator</ENTRY> +<ENTRY> ROM or ROMRAM start-up</ENTRY> +</ROW> +<ROW> +<ENTRY>Download to board with ROM Monitor</ENTRY> +<ENTRY> RAM start-up</ENTRY> +</ROW> +<ROW> +<ENTRY>Download to simulator without ROM Monitor</ENTRY> +<ENTRY> ROM start-up</ENTRY> +</ROW> +<ROW> +<ENTRY>Download to simulator with ROM Monitor</ENTRY> +<ENTRY> RAM start-up</ENTRY> +</ROW> +<ROW> +<ENTRY>Download to simulator ignoring devices</ENTRY> +<ENTRY> SIM configuration</ENTRY> +</ROW> +<ROW> +<ENTRY>Run synthetic target</ENTRY> +<ENTRY> RAM start-up</ENTRY> +</ROW> +</TBODY> +</TGROUP> +</TABLE> + +<CAUTION> + +<PARA>You cannot run an application configured for RAM start-up +on the simulator directly: it will fail during start-up. You can +only download it to the simulator if +you are already running RedBoot in the simulator, +as described in the toolchain documentation +or you load through the +<EMPHASIS>SID </EMPHASIS> +GDB debugging component. This is not the same as the simulated +stub, since it does not require a target program to be running to +get GDB to talk to it. It can be done before letting the simulator +run +or you use the ELF loader component to get a program into memory.</PARA> + +</CAUTION><!-- <label> --><!-- <conditionaltext> --><!-- NOTE</label> --> + +<NOTE> +<PARA>Configuring <productname>eCos</productname>' HAL package for simulation should +rarely be needed for real development; binaries built with such +a kernel will not run on target boards at all,<!-- <conditionaltext> --> +and the MN10300 and +TX39 simulators can run binaries built for stdeval1 and jmr3904 +target boards. +The main use for a ``simulation'' configuration +is if you are trying to work around problems with the device drivers +or with the simulator. Also note that when using a TX39 system configured +for simulator start-up you should then invoke the simulator with +the <OPTION>--board=jmr3904pal</OPTION> +option instead of +<OPTION>--board=jmr3904</OPTION><!-- <conditionaltext> --></PARA> +</NOTE> + +<NOTE> +<PARA>If your chosen architecture does not have simulator support, +then the combinations above that refer to the simulator do not apply. +Similarly, if your chosen platform does not have RedBoot +ROM support, the combinations listed above that use +RedBoot do not apply.</PARA> +</NOTE> + +<PARA>The debugging environment for most developers will be either +a hardware board or the simulator, in which case they will be able +to select a single HAL configuration.</PARA> + +</SECT1> + +<!-- ==================================================== --> + +<SECT1 id="using-configtool-windows-linux"> +<TITLE><!-- <index></index> --> +Configuration Tool on Windows and Linux Quick Start</TITLE> + +<PARA><!-- <conditionaltext> --> + +This section described the GUI based configuration tool. This +tool is probably more suited to users who prefer GUI's. The next +section describes a CLI based tool which Unix users may +prefer. </PARA> + +<PARA>Note that the use of the <application>Configuration Tool</application> +is described in detail in <XREF +LINKEND="THE-ECOS-CONFIGURATION-TOOL">.</PARA> + +<PARA>The <application>Configuration Tool</application> (see <XREF LINKEND="PROGRAMMING-FIGURE-CONFIGURATION-TOOL">) +has five main elements: the <EMPHASIS>configuration window</EMPHASIS>, +the <emphasis>conflicts window</emphasis>, +the <EMPHASIS>properties window</EMPHASIS>, the <!-- <xref> --><EMPHASIS>short +description window</EMPHASIS>, +and the <EMPHASIS>output window</EMPHASIS>.</PARA> + +<FIGURE ID="PROGRAMMING-FIGURE-CONFIGURATION-TOOL"> +<TITLE>Configuration Tool</TITLE><!-- <xref> --> +<GRAPHIC ENTITYREF="programming-graphic1"></GRAPHIC> +</FIGURE> + +<PARA>Start by opening the templates window via <GUIMENUITEM>Build->Templates</GUIMENUITEM>. +Select the desired target (see <XREF LINKEND="FIGURE-TEMPLATE-SELECTION">).</PARA> + +<FIGURE ID="FIGURE-TEMPLATE-SELECTION"> +<TITLE>Template selection</TITLE><!-- <xref> --> +<GRAPHIC ENTITYREF="programming-graphic2"></GRAPHIC> +</FIGURE> + +<PARA>Make sure that the configuration is correct for the target +in terms of endianness, CPU model, Startup type, etc. (see <XREF LINKEND="CONFIGURING-FOR-THE-TARGET">).</PARA> + +<FIGURE ID="CONFIGURING-FOR-THE-TARGET"> +<TITLE><!-- <conditionaltext> --><!-- <xref> -->Configuring +for the target</TITLE> +<GRAPHIC ENTITYREF="programming-graphic3"></GRAPHIC> +</FIGURE> + +<PARA>Next, select the <EMPHASIS>Build->Library</EMPHASIS> menu +item to start building <productname>eCos</productname> (see <XREF +LINKEND="FIGURE-SELECTING-THE-BUILD-LIBRARY-MENU-ITEM">). The +application will configure the sources, prepare a build tree, and +build the <FILENAME>libtarget.a</FILENAME> library, which contains the +<productname>eCos</productname> kernel and other packages.</PARA> + +<FIGURE ID="FIGURE-SELECTING-THE-BUILD-LIBRARY-MENU-ITEM"><!-- <xref> --> +<TITLE>Selecting the Build Library menu item</TITLE> +<GRAPHIC ENTITYREF="programming-graphic4"></GRAPHIC> +</FIGURE> + + +<PARA>The <EMPHASIS>Save As</EMPHASIS> dialog box will appear, asking +you to specify a directory in which to place your save file. You +can use the default, but it is a good idea to make a subdirectory, +called <filename>ecos-work</filename> for example. </PARA> + +<FIGURE> +<TITLE>Save file dialog</TITLE> +<GRAPHIC ENTITYREF="programming-graphic5"></GRAPHIC> +</FIGURE> + +<PARA>The first time you build an <productname>eCos</productname> library for a specific +architecture, the <application>Configuration Tool</application> may prompt +you for the location of the appropriate build tools (including +<command>make</command> and +<command><replaceable>TARGET-</replaceable>gcc</command>) using a +<EMPHASIS>Build Tools</EMPHASIS> dialog box (as shown in <XREF +LINKEND="FIGURE-BUILD-TOOLS-DIALOG">). You can select a location from +the drop down list, browse to the directory using the +<EMPHASIS>Browse</EMPHASIS> button, or type in the location of the +build tools manually.</PARA> + +<FIGURE ID="FIGURE-BUILD-TOOLS-DIALOG"><!-- <xref> --> +<TITLE>Build tools dialog</TITLE> +<GRAPHIC ENTITYREF="programming-graphic6"></GRAPHIC> +</FIGURE> + +<PARA>The <application>Configuration Tool</application> may also prompt you +for the location of the user tools (such as <command>cat</command> and +<command>ls</command>) using a <emphasis>User Tools</emphasis> dialog +box (as shown in <XREF LINKEND="FIGURE-USER-TOOLS-DIALOG">). As with +the <EMPHASIS>Build Tools</EMPHASIS> dialog, you can select a location +from the drop down list, browse to the directory using the +<EMPHASIS>Browse</EMPHASIS> button, or type in the location of the +user tools manually. Note that on Linux, this will often be +unnecessary as the tools will already be on your PATH.</PARA> + +<FIGURE ID="FIGURE-USER-TOOLS-DIALOG"><!-- <xref> --> +<TITLE>User tools dialog</TITLE> +<GRAPHIC ENTITYREF="programming-graphic7"></GRAPHIC> +</FIGURE> + +<PARA>When the tool locations have been entered, the <application>Configuration +Tool</application> will configure the sources, prepare a build tree, +and build the <filename>libtarget.a</filename> library, which contains +the <productname>eCos</productname> kernel and other packages.</PARA> + +<PARA>The output from the configuration process and the building +of <filename>libtarget.a</filename> will be shown in the output +window.</PARA> + +<PARA>Once the build process has finished you will have a kernel +with other packages in <FILENAME>libtarget.a</FILENAME>. You should +now build the <productname>eCos</productname> tests for your particular configuration. </PARA> + +<PARA>You can do this by selecting <EMPHASIS>Build</EMPHASIS> -> <EMPHASIS>Tests</EMPHASIS>. +Notice that you could have selected <EMPHASIS>Tests</EMPHASIS> instead +of <EMPHASIS>Library</EMPHASIS> in the earlier step and it would +have built <EMPHASIS>both</EMPHASIS> the library and the tests, +but this would increase the build time substantially, and if you +do not need to build the tests it is unnecessary.</PARA> + +<FIGURE> +<TITLE>Selecting the Build Tests menu item</TITLE> +<GRAPHIC ENTITYREF="programming-graphic8"></GRAPHIC> +</FIGURE> + +<PARA><XREF LINKEND="RUNNING-AN-ECOS-TEST-CASE"> will guide you through running one + of the test cases you just built on the selected target, + using GDB. </PARA> +</SECT1> + +<!-- ==================================================== --> + +<SECT1 ID="USING-ECOSCONFIG-ON-LINUX"> +<TITLE><!-- <index></index> --> +Ecosconfig on Windows and Linux Quick Start</TITLE> + +<PARA>As an alternative to using the graphical +<application>Configuration Tool</application>, it is possible to +configure and build a kernel by editing a configuration file manually +and using the <command>ecosconfig</command> command. Users with a Unix +background may find this tool more suitable than the GUI tool +described in the previous section.</PARA> + +<para> +Manual configuration and the <command>ecosconfig</command> command are +described in detail in <XREF LINKEND="manual-configuration">. +</para> + +<para> +To use the <command>ecosconfig</command> command you need to start a +shell. In Windows you need to start a +<productname>CygWin</productname> <command>bash</command> shell, not a +DOS command line. +</para> + +<!-- +<para> +XXXXX Need to know whether there will be a packaged shell entry in the +start menu, and where XXXXX +</para> +--> + +<PARA>The following instructions assume that the +<literal>PATH</literal> and <literal>ECOS_REPOSITORY</literal> +environment variables have been setup correctly as described in <XREF +LINKEND="user-guide-installation-linux">. They also assume Linux +usage but equally well apply to Windows running Cygwin.</PARA> + +<PARA>Before invoking <command>ecosconfig</command> you need to +choose a directory in which to work. For the purposes of this tutorial, +the default path will be <FILENAME><replaceable>BASE_DIR</replaceable>/ecos-work</FILENAME>. +Create this directory and change to it by typing: </PARA> + +<PROGRAMLISTING> +$ mkdir <replaceable>BASE_DIR</replaceable>/ecos-work +$ cd <replaceable>BASE_DIR</replaceable>/ecos-work +</PROGRAMLISTING> + +<PARA>To see what options can be used with <command>ecosconfig</command>, +type: </PARA> + +<PROGRAMLISTING>$ ecosconfig --help</PROGRAMLISTING> + +<PARA>The available packages, targets and templates may be listed +as follows:</PARA> + +<PROGRAMLISTING> +$ ecosconfig list +</PROGRAMLISTING> + +<PARA>Here is sample output from <command>ecosconfig</command> showing +the usage message.</PARA> + +<EXAMPLE> +<TITLE>Getting <!-- <index></index> --> help from ecosconfig</TITLE> + +<PROGRAMLISTING> +$ ecosconfig --help +Usage: ecosconfig [ qualifier ... ] [ command ] + commands are: + list : list repository contents + new TARGET [ TEMPLATE [ VERSION ] ] : create a configuration + target TARGET : change the target hardware + template TEMPLATE [ VERSION ] : change the template + add PACKAGE [ PACKAGE ... ] : add package(s) + remove PACKAGE [ PACKAGE ... ] : remove package(s) + version VERSION PACKAGE [ PACKAGE ... ] : change version of package(s) + export FILE : export minimal config info + import FILE : import additional config info + check : check the configuration + resolve : resolve conflicts + tree : create a build tree + qualifiers are: + --config=FILE : the configuration file + --prefix=DIRECTORY : the install prefix + --srcdir=DIRECTORY : the source repository + --no-resolve : disable conflict +resolution + --version : show version and copyright +$ +</PROGRAMLISTING> +</EXAMPLE> + +<EXAMPLE> + +<TITLE>ecosconfig output — <!-- <index></index> --> +list of available packages, targets and templates</TITLE> + +<PROGRAMLISTING> +$ ecosconfig list +Package CYGPKG_CYGMON (CygMon support via eCos): +aliases: cygmon +versions: &Version; +Package CYGPKG_DEVICES_WALLCLOCK_DALLAS_DS1742 (Wallclock driver for Dallas 1742): +aliases: devices_wallclock_ds1742 device_wallclock_ds1742 +versions: &Version; +Package CYGPKG_DEVICES_WALLCLOCK_SH3 (Wallclock driver for SH3 RTC module): +aliases: devices_wallclock_sh3 device_wallclock_sh3 +versions: &Version; +Package CYGPKG_DEVICES_WATCHDOG_ARM_AEB (Watchdog driver for ARM/AEB board): +aliases: devices_watchdog_aeb device_watchdog_aeb +versions: &Version; +Package CYGPKG_DEVICES_WATCHDOG_ARM_EBSA285 (Watchdog driver for ARM/EBSA285 board): +aliases: devices_watchdog_ebsa285 device_watchdog_ebsa285 +versions: &Version; +… +</PROGRAMLISTING> +</EXAMPLE> + + +<SECT2> +<TITLE>Selecting a <!-- <index></index> --> Target</TITLE> + +<PARA>To configure for a listed target, type: </PARA> + +<PROGRAMLISTING> +$ ecosconfig new <target> +</PROGRAMLISTING> + +<PARA>For example, to configure for the ARM PID development board, +type: </PARA> + +<PROGRAMLISTING> +$ ecosconfig new pid +</PROGRAMLISTING> + +<PARA>You can then edit the generated file, +<FILENAME>ecos.ecc</FILENAME>, setting the options as required for the +target (endianess, CPU model, Startup type, etc.). For detailed +information about how to edit the <filename>ecos.ecc</filename> file, +see the <citetitle>CDL Writer's Guide</citetitle> and <XREF +LINKEND="editing-an-ecos-savefile">. +</PARA> + +<PARA>Create a build tree for the configured target by typing:</PARA> + +<PROGRAMLISTING> +$ ecosconfig tree +</PROGRAMLISTING> + +<para> +If there are any problem with the configuration, +<command>ecosconfig</command> will tell you. The most likely cause of +this is mistakes when editing the <filename>ecos.ecc</filename> file. +You can check whether the configuration you have made is correct, +without building the tree with the following command: +</para> + +<PROGRAMLISTING> +$ ecosconfig check +</PROGRAMLISTING> + +<para> +If this reports any conflicts you can get +<command>ecosconfig</command> to try and resolve them itself by typing: +</para> + +<PROGRAMLISTING> +$ ecosconfig resolve +</PROGRAMLISTING> + +<para> +See <XREF LINKEND="conflicts-and-constraints"> for more details. +</para> + +<PARA>You can now run the command <command>make</command> or <command>make +tests</command>, after which you will be at the same point you +would be after running the <application>Configuration Tool</application> +— you can start developing your own applications, +following the steps in <XREF LINKEND="BUILDING-AND-RUNNING-SAMPLE-APPLIATIONS">. </PARA> + +<PARA>The procedure shown above allows you to do very coarse-grained +configuration of the <productname>eCos</productname> kernel: you can select which packages +to include in your kernel, and give target and start-up options. +But you cannot select components within a package, or set the very +fine-grained options. </PARA> + +<PARA>To select fine-grained configuration options you will need to +edit the configuration file <filename>ecos.ecc</filename> in the +current directory and regenerate the build tree.</PARA> + +<CAUTION> +<PARA>You should follow the manual configuration process described +above very carefully, and you should read the comments in each file +to see when one option depends on other options or packages being +enabled or disabled. If you do not, you might end up with an inconsistently +configured kernel which could fail to build or might execute +incorrectly.</PARA> +</CAUTION> + +</SECT2> +</SECT1> + +</CHAPTER> + +<!-- ==================================================== --> + +<CHAPTER ID="RUNNING-AN-ECOS-TEST-CASE"> +<TITLE>Running an <productname>eCos</productname> Test Case</TITLE> + +<PARA>In <XREF LINKEND="using-configtool-windows-linux"> or <XREF +LINKEND="using-ecosconfig-on-linux"> you created the <productname>eCos</productname> test cases +as part of the build process. Now it is time to try and run one. +</para> + +<!-- ==================================================== --> + +<SECT1 id="using-configtool-testcase"> +<TITLE>Using the <application>Configuration Tool</application></TITLE> + +<PARA>Test executables that have been linked using the +<emphasis>Build->Tests</emphasis> operation against the current +configuration can be executed by selecting <EMPHASIS>Tools->Run +Tests</EMPHASIS>.</PARA> + +<PARA>When a test run is invoked, a property sheet is displayed, see +<xref linkend="programming-run-tests">. Press the <emphasis>Uncheck +All</emphasis> button and then find and check just one test, +<filename>bin_sem0</filename> for example. +</para> + +<FIGURE id="programming-run-tests"> +<TITLE>Run tests</TITLE> +<GRAPHIC ENTITYREF="graphic27"></GRAPHIC> +</FIGURE> + +<para> +Now press the <emphasis>Properties</emphasis> button to set up +communications with the target. This will bring up a properties dialog +shown in <xref linkend="programming-run-properties">. If you have +connected the target board via a serial cable, check the +<emphasis>Serial</emphasis> radio button, and select the serial port +and baud rate for the board. If the target is connected via the +network select the <emphasis>TCP/IP</emphasis> button and enter the IP +address that the board has been given, and the port number (usually +9000). +</para> + +<FIGURE id="programming-run-properties"> +<TITLE>Properties dialog box</TITLE> +<GRAPHIC ENTITYREF="graphic25"></GRAPHIC> +</FIGURE> + +<para> +Click OK on this dialog and go back to the <emphasis>Run +Tests</emphasis> dialog. Press the <emphasis>Run</emphasis> button and +the selected test will be downloaded and run. The +<emphasis>Output</emphasis> tab will show you how this is +progressing. If it seems to stop for a long time, check that the +target board is correctly connected, and that <productname>eCos</productname> has been correctly +configured -- especially the start-up type. +</para> + +<para> +When the program runs you should see a couple of line similar to this appear: +</para> + +<PROGRAMLISTING> +PASS:<Binary Semaphore 0 OK> +EXIT:<done> +</PROGRAMLISTING> + +<para> +This indicates that the test has run successfully. +</para> + +<PARA>See <xref linkend="config-tool-test-execution"> for +further details.</PARA> + +</SECT1> + +<!-- ==================================================== --> + +<SECT1 id="using-commandline-testcase"> +<TITLE>Using the command line</TITLE> + +<PARA>Start a command shell (such as a Cygwin shell window in Windows) +with the environment variables set as described in the toolchain +documentation. Change to the directory in which you set up your build +tree, and invoke <!-- <index></index> --> GDB on the test +program.</PARA> + +<PARA>To run the <!-- <index></index> -->bin_sem0 test (which will +test the kernel for the correct creation and destruction of binary +semaphores) type: </PARA> + +<PROGRAMLISTING> +$ <replaceable>TARGET-</replaceable>gdb -nw install/tests/kernel/<replaceable>&Version;</replaceable>/tests/bin_sem0 +</PROGRAMLISTING> + +<PARA>You should see output similar to the following in the command +window:</PARA> + +<PROGRAMLISTING> +GNU gdb THIS-GDB-VERSION +Copyright 2001 Free Software Foundation, Inc. +GDB is free software, covered by the GNU General Public License, and you are +welcome to change it and/or distribute copies of it under certain conditions. +Type "show copying" to see the conditions. +There is absolutely no warranty for GDB. Type "show warranty" for details. +This GDB was configured as "--host=THIS-HOST --target=THIS-TARGET". +(gdb) +</PROGRAMLISTING> + +<PARA>If you are trying to run a synthetic target test on <!-- +<index></index> -->Linux, skip the following connection and download +steps. Otherwise, connect to the target by typing: </PARA> + +<PROGRAMLISTING> +(gdb) set remotebaud 38400 +(gdb) target remote /dev/ttyS0 +</PROGRAMLISTING> +<PARA>on Linux or</PARA> +<PROGRAMLISTING> +(gdb) set remotebaud 38400 +(gdb) target remote com1 +</PROGRAMLISTING> +<PARA>on Windows or</PARA> +<PROGRAMLISTING> +(gdb) target sim +</PROGRAMLISTING> +<para>to use a simulator in either host O/S.</para> + +<para> +Check the documentation for the target board for the actual baud rate +to use when connecting to real targets. +</para> + +<PARA> +You will see output similar to the following: </PARA> + +<programlisting width=72> +Remote debugging using /dev/ttyS1 +0x0000d50c in ?? () + at <replaceable>BASE_DIR</replaceable>/kernel/<replaceable>&Version;</replaceable>/src/common/kapi.cxx:345 + +Current language: auto; currently c++ +(gdb) +</programlisting> + +<para> +Or if you are using the simulator: +</para> + +<PROGRAMLISTING> +Connected to the simulator. +(gdb) +</PROGRAMLISTING> + +<PARA>Now download the program to the target with</PARA> + +<PROGRAMLISTING> +(gdb) load +</PROGRAMLISTING> + +<PARA>You should see output similar to the following on your screen: </PARA> + +<PROGRAMLISTING> +Loading section .text, size 0x4b04 lma 0x108000 +Loading section .rodata, size 0x738 lma 0x10cb08 +Loading section .data, size 0x1c0 lma 0x10d240 +Start address 0x108000, load size 21500 +Transfer rate: 24571 bits/sec, 311 bytes/write. +(gdb) +</PROGRAMLISTING> + +<PARA>You are now ready to run your program. If you type: </PARA> + +<PROGRAMLISTING> +(gdb) continue +</PROGRAMLISTING> + +<PARA>you will see output similar to the following: </PARA> + +<PROGRAMLISTING> +Continuing. +PASS:<Binary Semaphore 0 OK> +EXIT:<done> +</PROGRAMLISTING> + +<NOTE> +<PARA> If you are using a simulator or the synthetic target rather + than real hardware, you must use the GDB command + “run” rather than “continue” to + start your program.</PARA> +</NOTE> + +<PARA>You can terminate your GDB session with +<EMPHASIS>Control+C</EMPHASIS>, otherwise it will sit in the +“idle” thread and use up CPU time. This is not a problem +with real targets, but may have undesirable effects in simulated or +synthetic targets. Type <command>quit</command> and you are +done. </PARA> + +</SECT1> + +<!-- ==================================================== --> + +<SECT1 id="testing-filters"> +<TITLE>Testing Filters</TITLE> + +<PARA>While most test cases today run solely in the target environment, +some packages may require external testing infrastructure and/or +feedback from the external environment to do complete testing.</PARA> + +<PARA>The serial package is an example of this. The network package +also contains some tests that require programs to be run on a +host. See the network <citetitle>Tests and Demonstrations</citetitle> +section in the network documentation in the <citetitle><productname>eCos</productname> Reference +Guide</citetitle>. Here we will concentrate on the serial tests since +these are applicable to more targets. +</para> + +<PARA>Since the serial line is also used for communication with +GDB, a filter is inserted in the communication pathway between +GDB and the serial device which is connected to the hardware target. +The filter forwards all communication between the two, but also +listens for special commands embedded in the data stream from the +target.</PARA> + +<PARA>When such a command is seen, the filter stops forwarding data +to GDB from the target and enters a special mode. In this mode +the test case running on the target is able to control the filter, +commanding it to run various tests. While these tests run, GDB is +isolated from the target.</PARA> + +<PARA>As the test completes (or if the filter detects a target crash) +the communication path between GDB and the hardware target is re-established, +allowing GDB to resume control.</PARA> + +<PARA>In theory, it is possible to extend the filter to provide +a generic framework for other target-external testing components, +thus decoupling the testing infrastructure from the (possibly limited) +communication means provided by the target (serial, JTAG, Ethernet, +etc). </PARA> + +<PARA>Another advantage is that the host tools do not need to +know about the various testing environments required by the <productname>eCos</productname> +packages, since all contact with the target continues to happen +via GDB.</PARA> + +</sect1> + +</CHAPTER> + + +<!-- ==================================================== --> + +<CHAPTER ID="BUILDING-AND-RUNNING-SAMPLE-APPLIATIONS"><!-- <conditionaltext> --> +<TITLE><!-- <xref> -->Building and <!-- <index></index> -->Running Sample Applications</TITLE> + +<PARA>The example programs in this tutorial are included, along +with a <filename>Makefile</filename>, in the <filename>examples</filename> directory +of the <productname>eCos</productname> distribution. The first program you will run is a <EMPHASIS>hello +world</EMPHASIS>-style application, then you will run a more complex +application that demonstrates the creation of threads and the use +of cyg_thread_delay(), and finally you will run +one that uses clocks and alarm handlers.</PARA> + +<PARA>The <filename>Makefile</filename> depends on an externally +defined variable to find the <productname>eCos</productname> library and header files. This +variable is <literal>INSTALL_DIR</literal> and must be set to the +pathname of the install directory created in <xref +linkend="using-configtool-windows-linux">. +</PARA> + +<para> +<literal>INSTALL_DIR</literal> may be either be set in the shell +environment or may be supplied on the command line. To set it in the +shell do the following in a <command>bash</command> shell: +</para> + +<programlisting width=72> +$ export INSTALL_DIR=BASE_DIR/ecos-work/arm_install +</programlisting> + +<para> +You can then run <command>make</command> without any extra parameters +to build the examples. +</para> + +<para> +Alternatively, if you can do the following: +</para> + +<programlisting width=72> +$ make INSTALL_DIR=BASE_DIR/ecos-work/arm_install +</programlisting> + +<!-- ==================================================== --> + +<SECT1 id="ecos-hello-world"> +<TITLE><productname>eCos</productname> Hello World</TITLE> + +<PARA>The following code is found in the file <FILENAME><!-- <index></index> -->hello.c</FILENAME> +in the <FILENAME>examples</FILENAME> directory: </PARA> + +<SECT2> +<TITLE><productname>eCos</productname><!-- <index></index> --> hello world program listing</TITLE> + +<PROGRAMLISTING> +/* this is a simple hello world program */ +#include <stdio.h> +int main(void) +{ + printf("Hello, eCos world!\n"); + return 0; +} +</PROGRAMLISTING> + +<PARA>To compile this or any other program that is not part of the +<productname>eCos</productname> distribution, you can follow the procedures described below. Type +this explicit compilation command (assuming your current working +directory is also where you built the <productname>eCos</productname> kernel):</PARA> + +<PROGRAMLISTING> +$ <replaceable>TARGET-</replaceable>gcc -g -I<replaceable>BASE_DIR</replaceable>/ecos-work/install/include hello.c -L<replaceable>BASE_DIR</replaceable>/ecos-work/install/lib -Ttarget.ld -nostdlib +</PROGRAMLISTING> + +<PARA>The compilation command above contains some standard GCC +options (for example, <OPTION>-g</OPTION> enables debugging), as well +as some mention of paths +(<OPTION>-I<replaceable>BASE_DIR</replaceable>/ecos-work/install/include</OPTION> allows files +like <FILENAME>cyg/kernel/kapi.h</FILENAME> to be found, and +<OPTION>-L<replaceable>BASE_DIR</replaceable>/ecos-work/install/lib</OPTION> allows the linker to +find <OPTION>-Ttarget.ld</OPTION>). </PARA> + +<PARA>The executable program will be called <FILENAME>a.out</FILENAME>. </PARA> + +<NOTE> +<PARA>Some target systems require special options to be passed to +gcc to compile correctly for that system. Please examine the Makefile +in the examples directory to see if this applies to your target.</PARA> +</NOTE> + +<PARA>You can now run the resulting program using GDB in exactly the +same the way you ran the test case before. The procedure will be the +same, but this time run +<command><replaceable>TARGET-</replaceable>gdb</command> specifying +<option>-nw a.out</option> on the command line:</PARA> + +<PROGRAMLISTING> +$ <replaceable>TARGET-</replaceable>gdb -nw a.out +</PROGRAMLISTING> + +<PARA>For targets other than the synthetic linux target, you should +now run the usual GDB commands described earlier. Once this is done, +typing the command "continue" at the (gdb) prompt ("run" for +simulators) will allow the program to execute and print the string +"Hello, eCos world!" on your screen.</PARA> + +<PARA>On the synthetic linux target, you may use the "run" command +immediately - you do not need to connect to the target, nor use the +"load" command.<!-- <conditionaltext> --></PARA> + +</SECT2> +</SECT1> + +<!-- ==================================================== --> + +<SECT1 id="sample-twothreads"> +<TITLE>A Sample Program with Two Threads</TITLE> + +<PARA>Below is a program that uses some of <productname>eCos</productname>' system calls. It +creates two threads, each of which goes into an infinite loop in which +it sleeps for a while (using cyg_thread_delay()). This code is found +in the file <filename><!-- <index></index> -->twothreads.c</filename> +in the examples directory.</PARA> + +<SECT2> +<TITLE><productname>eCos</productname> <!-- <index></index> -->two-threaded program listing</TITLE> + +<PROGRAMLISTING> +#include <cyg/kernel/kapi.h> +#include <stdio.h> +#include <math.h> +#include <stdlib.h> + +/* now declare (and allocate space for) some kernel objects, + like the two threads we will use */ +cyg_thread thread_s[2]; /* space for two thread objects */ + +char stack[2][4096]; /* space for two 4K stacks */ + +/* now the handles for the threads */ +cyg_handle_t simple_threadA, simple_threadB; + +/* and now variables for the procedure which is the thread */ +cyg_thread_entry_t simple_program; + +/* and now a mutex to protect calls to the C library */ +cyg_mutex_t cliblock; + +/* we install our own startup routine which sets up threads */ +void cyg_user_start(void) +{ + printf("Entering twothreads' cyg_user_start() function\n"); + + cyg_mutex_init(&cliblock); + + cyg_thread_create(4, simple_program, (cyg_addrword_t) 0, + "Thread A", (void *) stack[0], 4096, + &simple_threadA, &thread_s[0]); + cyg_thread_create(4, simple_program, (cyg_addrword_t) 1, + "Thread B", (void *) stack[1], 4096, + &simple_threadB, &thread_s[1]); + + cyg_thread_resume(simple_threadA); + cyg_thread_resume(simple_threadB); +} + +/* this is a simple program which runs in a thread */ +void simple_program(cyg_addrword_t data) +{ + int message = (int) data; + int delay; + + printf("Beginning execution; thread data is %d\n", message); + + cyg_thread_delay(200); + + for (;;) { + delay = 200 + (rand() % 50); + + /* note: printf() must be protected by a + call to cyg_mutex_lock() */ + cyg_mutex_lock(&cliblock); { + printf("Thread %d: and now a delay of %d clock ticks\n", + message, delay); + } + cyg_mutex_unlock(&cliblock); + cyg_thread_delay(delay); + } +} +</PROGRAMLISTING> + +<PARA> +When you run the program (by typing <command>continue</command> at +the (<EMPHASIS>gdb</EMPHASIS>) prompt) the output should look like +this:</PARA> + +<PROGRAMLISTING> +Starting program: <replaceable>BASE_DIR</replaceable>/examples/twothreads.exe +Entering twothreads' cyg_user_start() +function +Beginning execution; thread data is 0 +Beginning execution; thread data is 1 +Thread 0: and now a delay of 240 clock ticks +Thread 1: and now a delay of 225 clock ticks +Thread 1: and now a delay of 234 clock ticks +Thread 0: and now a delay of 231 clock ticks +Thread 1: and now a delay of 224 clock ticks +Thread 0: and now a delay of 249 clock ticks +Thread 1: and now a delay of 202 clock ticks +Thread 0: and now a delay of 235 clock ticks +</PROGRAMLISTING> + +<NOTE> +<PARA>When running in a simulator the <!-- <index></index> --> +delays might be quite long. On a hardware board (where the clock +speed is 100 ticks/second) the delays should average to +about 2.25 seconds. In simulation, the delay will depend on the +speed of the host processor and will almost always be much slower than +the actual board. You might want to reduce the delay parameter when running +in simulation. +</PARA> +</NOTE> + +<PARA> +<XREF LINKEND="FIGURE-TWOTHREADS-WITH-SIMPLE-PRINTS"> shows how this +multitasking program executes. Note that apart from the thread +creation system calls, this program also creates and uses a +<EMPHASIS><!-- <index></index> -->mutex</EMPHASIS> for synchronization +between the <function>printf()</function> calls in the two +threads. This is because the C library standard I/O (by default) is +configured not to be thread-safe, which means that if more than one +thread is using standard I/O they might corrupt each other. This is +fixed by a mutual exclusion (or <EMPHASIS>mutex</EMPHASIS>) lockout +mechanism: the threads do not call <function>printf()</function> until +<function>cyg_mutex_lock()</function> has returned, which only happens +when the other thread calls +<function>cyg_mutex_unlock()</function>.</PARA> + +<PARA>You could avoid using the mutex by configuring the C library to +be thread-safe (by selecting the component +<LITERAL>CYGSEM_LIBC_STDIO_THREAD_SAFE_STREAMS</LITERAL>).</PARA> + +<FIGURE +ID="FIGURE-TWOTHREADS-WITH-SIMPLE-PRINTS"><!-- <xref> --> <TITLE>Two +threads with simple print statements after random delays</TITLE> +<GRAPHIC ENTITYREF="programming-graphic9"></GRAPHIC> +</FIGURE> + +</SECT2> + +</SECT1> + +</CHAPTER> + +<!-- ==================================================== --> + +<CHAPTER ID="CLOCKS-AND-ALARM-HANDLERS"> +<TITLE>More Features — <!-- <index></index> -->Clocks and Alarm +Handlers</TITLE> + +<PARA>If a program wanted to execute a task at a given time, or +periodically, it could do it in an inefficient way by sitting in a +loop and checking the real-time clock to see if the proper amount of +time has elapsed. But operating systems usually provide system calls +which allow the program to be informed at the desired time.</PARA> + +<PARA><productname>eCos</productname> provides a rich timekeeping formalism, involving +<EMPHASIS>counters</EMPHASIS>, <EMPHASIS>clocks</EMPHASIS>, +<EMPHASIS>alarms</EMPHASIS>, and <EMPHASIS>timers</EMPHASIS>. The +precise definition, relationship, and motivation of these features is +beyond the scope of this tutorial, but these examples illustrate how +to set up basic periodic tasks.</PARA> + +<PARA><!-- <index></index> -->Alarms are events that happen at +a given time, either once or periodically. A thread associates an +alarm handling function with the alarm, so that the function will +be invoked every time the alarm “goes off”.</PARA> + +<!-- ==================================================== --> + +<SECT1 id="sample-alarms"> +<TITLE>A Sample Program with Alarms</TITLE> + +<PARA><!-- <index></index> --><FILENAME>simple-alarm.c</FILENAME> (in +the examples directory) is a short program that creates a thread that +creates an alarm. The alarm is handled by the function +<FUNCTION>test_alarm_func()</FUNCTION>, which sets a global +variable. When the main thread of execution sees that the variable has +changed, it prints a message.</PARA> + +<EXAMPLE> +<TITLE>A sample <!-- <index></index> -->program that creates an alarm</TITLE> + +<PROGRAMLISTING> +/* this is a very simple program meant to demonstrate + a basic use of time, alarms and alarm-handling functions in eCos */ + +#include <cyg/kernel/kapi.h> + +#include <stdio.h> + +#define NTHREADS 1 +#define STACKSIZE 4096 + +static cyg_handle_t thread[NTHREADS]; + +static cyg_thread thread_obj[NTHREADS]; +static char stack[NTHREADS][STACKSIZE]; + +static void alarm_prog( cyg_addrword_t data ); + +/* we install our own startup routine which sets up + threads and starts the scheduler */ +void cyg_user_start(void) +{ + cyg_thread_create(4, alarm_prog, (cyg_addrword_t) 0, + "alarm_thread", (void *) stack[0], + STACKSIZE, &thread[0], &thread_obj[0]); + cyg_thread_resume(thread[0]); +} + +/* we need to declare the alarm handling function (which is + defined below), so that we can pass it to cyg_alarm_initialize() */ +cyg_alarm_t test_alarm_func; + +/* alarm_prog() is a thread which sets up an alarm which is then + handled by test_alarm_func() */ +static void alarm_prog(cyg_addrword_t data) +{ + cyg_handle_t test_counterH, system_clockH, test_alarmH; + cyg_tick_count_t ticks; + cyg_alarm test_alarm; + unsigned how_many_alarms = 0, prev_alarms = 0, tmp_how_many; + + system_clockH = cyg_real_time_clock(); + cyg_clock_to_counter(system_clockH, &test_counterH); + cyg_alarm_create(test_counterH, test_alarm_func, + (cyg_addrword_t) &how_many_alarms, + &test_alarmH, &test_alarm); + cyg_alarm_initialize(test_alarmH, cyg_current_time()+200, 200); + + /* get in a loop in which we read the current time and + print it out, just to have something scrolling by */ + for (;;) { + ticks = cyg_current_time(); + printf("Time is %llu\n", ticks); + /* note that we must lock access to how_many_alarms, since the + alarm handler might change it. this involves using the + annoying temporary variable tmp_how_many so that I can keep the + critical region short */ + cyg_scheduler_lock(); + tmp_how_many = how_many_alarms; + cyg_scheduler_unlock(); + if (prev_alarms != tmp_how_many) { + printf(" --- alarm calls so far: %u\n", tmp_how_many); + prev_alarms = tmp_how_many; + } + cyg_thread_delay(30); + } +} + +/* test_alarm_func() is invoked as an alarm handler, so + it should be quick and simple. in this case it increments + the data that is passed to it. */ +void test_alarm_func(cyg_handle_t alarmH, cyg_addrword_t data) +{ + ++*((unsigned *) data); +} +</PROGRAMLISTING> +</EXAMPLE> + +<PARA>When you run this program (by typing <COMMAND>continue</COMMAND> at +the (<EMPHASIS>gdb</EMPHASIS>) prompt) the output should look like +this:</PARA> +<SCREEN> +Starting program: <replaceable>BASE_DIR</replaceable>/examples/simple-alarm.exe +Time is 0 +Time is 30 +Time is 60 +Time is 90 +Time is 120 +Time is 150 +Time is 180 +Time is 210 + --- alarm calls so far: 1 +Time is 240 +Time is 270 +Time is 300 +Time is 330 +Time is 360 +Time is 390 +Time is 420 + --- alarm calls so far: 2 +Time is 450 +Time is 480 +</SCREEN> + +<NOTE> +<PARA>When running in a simulator the <!-- <index></index> --> delays +might be quite long. On a hardware board (where the clock speed is 100 +ticks/second) the delays should average to about 0.3 seconds (and 2 +seconds between alarms). In simulation, the delay will depend on the +speed of the host processor and will almost always be much slower than +the actual board. You might want to reduce the delay parameter when +running in simulation.</PARA> +</NOTE> + +<PARA>Here are a few things you might notice about this program:</PARA> + +<ITEMIZEDLIST> +<LISTITEM> +<PARA>It used the <function>cyg_real_time_clock()</function> function; +this always returns a handle to the default system real-time <!-- +<index></index> --> clock. </PARA> +</LISTITEM> + +<LISTITEM> +<PARA><!-- <index></index> -->Clocks are based on <!-- <index></index> +--> counters, so the function <function>cyg_alarm_create()</function> +uses a counter handle. The program used the function +<function>cyg_clock_to_counter()</function> to strip the clock handle +to the underlying counter handle. </PARA> +</LISTITEM> + +<LISTITEM> +<PARA>Once the alarm is created it is <!-- <index></index> --> +initialized with <function>cyg_alarm_initialize()</function>, which +sets the time at which the alarm should go off, as well as the period +for repeating alarms. It is set to go off at the current time and +then to repeat every 200 ticks. </PARA> +</LISTITEM> + +<LISTITEM> +<PARA>The alarm handler function +<function>test_alarm_func()</function> conforms to the guidelines for +writing alarm handlers and other <!-- <index></index> --><!-- +<index></index> --> delayed service routines: it does not invoke any +functions which might lock the scheduler. This is discussed in detail +in the <CITETITLE><productname>eCos</productname> Reference Manual</CITETITLE>, in the chapter +<citetitle>The <productname>eCos</productname> Kernel</citetitle>.</PARA> +</LISTITEM> + +<LISTITEM> +<PARA>There is a <EMPHASIS>critical region</EMPHASIS> in this program: +the variable <LITERAL>how_many_alarms</LITERAL> is accessed in the +main thread of control and is also modified in the alarm handler. To +prevent a possible (though unlikely) race condition on this variable, +access to <LITERAL>how_many_alarms</LITERAL> in the principal thread +is protected by calls to <FUNCTION>cyg_scheduler_lock()</FUNCTION> and +<FUNCTION>cyg_scheduler_unlock()</FUNCTION>. When the scheduler is +locked, the alarm handler will not be invoked, so the problem is +averted. </PARA> +</LISTITEM> +</ITEMIZEDLIST> +</SECT1> +</CHAPTER> + +</part> + diff --git a/ecos/doc/sgml/user-guide/real-time-characterization.sgml b/ecos/doc/sgml/user-guide/real-time-characterization.sgml new file mode 100644 index 0000000..f87b110 --- /dev/null +++ b/ecos/doc/sgml/user-guide/real-time-characterization.sgml @@ -0,0 +1,3314 @@ +<!-- {{{ Banner --> + +<!-- =============================================================== --> +<!-- --> +<!-- config-tool.sgml --> +<!-- --> +<!-- eCos User Guide --> +<!-- --> +<!-- =============================================================== --> +<!-- ####ECOSDOCCOPYRIGHTBEGIN#### --> +<!-- =============================================================== --> +<!-- Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002 Free Software Foundation, 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 --> +<!-- =============================================================== --> +<!-- ####ECOSDOCCOPYRIGHTEND#### --> +<!-- =============================================================== --> +<!-- #####DESCRIPTIONBEGIN#### --> +<!-- --> +<!-- ####DESCRIPTIONEND#### --> +<!-- =============================================================== --> + +<!-- }}} --> + +<APPENDIX ID="REAL-TIME-CHARACTERIZATION"> +<TITLE>Real-time characterization</TITLE> + +<PARA>For a discussion of real-time performance measurement for eCos, see the +kernel documentation in the eCos Reference Manual. +</PARA> + +<caution> +<para> +As with the target setup descriptions in the previous appendix, this +information will eventually be merged into per-target documents. +</para> +</caution> + +<PARA> Sample numbers: + </PARA> + +<!-- ==================================================== --> + +<SECT1 id="rt-arm-aeb1"> +<TITLE>Board: ARM AEB-1 Revision B Evaluation Board</TITLE> +<LITERALLAYOUT CLASS="MONOSPACED"> + +Board: ARM AEB-1 Revision B Evaluation Board + +CPU : Sharp LH77790A 24MHz + + + +Startup, main stack : stack used 404 size 2400 +Startup : Interrupt stack used 128 size 2048 +Startup : Idlethread stack used 80 size 2048 + +eCos Kernel Timings +Notes: all times are in microseconds (.000001) unless otherwise stated + +Reading the hardware clock takes 13 'ticks' overhead +... this value will be factored out of all other measurements +Clock interrupt took 193.49 microseconds (290 raw clock ticks) + +Testing parameters: + Clock samples: 32 + Threads: 7 + Thread switches: 128 + Mutexes: 32 + Mailboxes: 32 + Semaphores: 32 + Scheduler operations: 128 + Counters: 32 + Alarms: 32 + + + Confidence + Ave Min Max Var Ave Min Function + ====== ====== ====== ====== ========== ======== + 110.19 104.67 116.00 3.26 42% 28% Create thread + 34.00 34.00 34.00 0.00 100% 100% Yield thread [all suspended] + 24.67 24.67 24.67 0.00 100% 100% Suspend [suspended] thread + 25.05 24.67 25.33 0.33 57% 42% Resume thread + 37.14 36.67 37.33 0.27 71% 28% Set priority + 3.81 3.33 4.00 0.27 71% 28% Get priority + 80.00 80.00 80.00 0.00 100% 100% Kill [suspended] thread + 33.90 33.33 34.00 0.16 85% 14% Yield [no other] thread + 45.90 44.00 46.67 0.54 57% 14% Resume [suspended low prio] thread + 24.57 24.00 24.67 0.16 85% 14% Resume [runnable low prio] thread + 42.29 36.67 43.33 1.61 85% 14% Suspend [runnable] thread + 33.90 33.33 34.00 0.16 85% 14% Yield [only low prio] thread + 24.67 24.67 24.67 0.00 100% 100% Suspend [runnable->not runnable] + 80.00 80.00 80.00 0.00 100% 100% Kill [runnable] thread + 43.33 43.33 43.33 0.00 100% 100% Destroy [dead] thread + 106.29 101.33 107.33 1.41 85% 14% Destroy [runnable] thread + 144.95 141.33 166.00 6.01 85% 85% Resume [high priority] thread + 78.31 76.67 254.67 2.75 99% 99% Thread switch + + 4.00 4.00 4.00 0.00 100% 100% Scheduler lock + 16.37 16.00 16.67 0.33 56% 43% Scheduler unlock [0 threads] + 16.37 16.00 16.67 0.33 56% 43% Scheduler unlock [1 suspended] + 16.37 16.00 16.67 0.33 56% 43% Scheduler unlock [many suspended] + 16.37 16.00 16.67 0.33 56% 43% Scheduler unlock [many low prio] + + 10.67 10.67 10.67 0.00 100% 100% Init mutex + 28.67 28.67 28.67 0.00 100% 100% Lock [unlocked] mutex + 30.44 30.00 31.33 0.33 59% 37% Unlock [locked] mutex + 25.42 25.33 26.00 0.15 87% 87% Trylock [unlocked] mutex + 22.50 22.00 22.67 0.25 75% 25% Trylock [locked] mutex + 5.75 5.33 6.00 0.31 62% 37% Destroy mutex + 185.33 185.33 185.33 0.00 100% 100% Unlock/Lock mutex + + 20.17 20.00 20.67 0.25 75% 75% Create mbox + 2.92 2.67 3.33 0.31 62% 62% Peek [empty] mbox + 32.42 32.00 32.67 0.31 62% 37% Put [first] mbox + 3.00 2.67 3.33 0.33 100% 50% Peek [1 msg] mbox + 32.50 32.00 32.67 0.25 75% 25% Put [second] mbox + 2.92 2.67 3.33 0.31 62% 62% Peek [2 msgs] mbox + 32.83 32.67 33.33 0.25 75% 75% Get [first] mbox + 32.67 32.67 32.67 0.00 100% 100% Get [second] mbox + 31.33 31.33 31.33 0.00 100% 100% Tryput [first] mbox + 27.58 27.33 28.00 0.31 62% 62% Peek item [non-empty] mbox + 32.83 32.67 33.33 0.25 75% 75% Tryget [non-empty] mbox + 26.50 26.00 26.67 0.25 75% 25% Peek item [empty] mbox + 28.00 28.00 28.00 0.00 100% 100% Tryget [empty] mbox + 3.25 2.67 3.33 0.15 87% 12% Waiting to get mbox + 3.25 2.67 3.33 0.15 87% 12% Waiting to put mbox + 30.83 30.67 31.33 0.25 75% 75% Delete mbox + 101.08 100.67 101.33 0.31 62% 37% Put/Get mbox + + 11.17 10.67 11.33 0.25 75% 25% Init semaphore + 24.17 24.00 24.67 0.25 75% 75% Post [0] semaphore + 27.08 26.67 27.33 0.31 62% 37% Wait [1] semaphore + 22.75 22.67 23.33 0.15 87% 87% Trywait [0] semaphore + 22.21 22.00 22.67 0.29 68% 68% Trywait [1] semaphore + 7.33 7.33 7.33 0.00 100% 100% Peek semaphore + 5.92 5.33 6.00 0.15 87% 12% Destroy semaphore + 110.04 110.00 110.67 0.08 93% 93% Post/Wait semaphore + + 9.54 9.33 10.00 0.29 68% 68% Create counter + 3.92 3.33 4.00 0.15 87% 12% Get counter value + 4.00 4.00 4.00 0.00 100% 100% Set counter value + 30.92 30.67 31.33 0.31 62% 62% Tick counter + 5.75 5.33 6.00 0.31 62% 37% Delete counter + + 13.83 13.33 14.00 0.25 75% 25% Create alarm + 46.67 46.67 46.67 0.00 100% 100% Initialize alarm + 3.67 3.33 4.00 0.33 100% 50% Disable alarm + 45.67 45.33 46.00 0.33 100% 50% Enable alarm + 8.33 8.00 8.67 0.33 100% 50% Delete alarm + 36.33 36.00 36.67 0.33 100% 50% Tick counter [1 alarm] + 214.67 214.67 214.67 0.00 100% 100% Tick counter [many alarms] + 62.67 62.67 62.67 0.00 100% 100% Tick & fire counter [1 alarm] + 1087.04 1075.33 1278.67 21.91 93% 93% Tick & fire counters [>1 together] + 246.35 240.67 412.00 10.35 96% 96% Tick & fire counters [>1 separately] + 168.01 167.33 237.33 1.08 99% 99% Alarm latency [0 threads] + 187.36 168.00 234.67 3.60 86% 1% Alarm latency [2 threads] + 187.37 167.33 235.33 3.59 85% 1% Alarm latency [many threads] + 303.12 280.00 508.67 3.21 98% 0% Alarm -> thread resume latency + + 36.65 36.00 38.67 0.00 Clock/interrupt latency + + 65.79 52.00 152.67 0.00 Clock DSR latency + + 316 316 316 (main stack: 752) Thread stack used (1120 total) +All done, main stack : stack used 752 size 2400 +All done : Interrupt stack used 280 size 2048 +All done : Idlethread stack used 268 size 2048 + +Timing complete - 30390 ms total + +PASS:<Basic timing OK> +EXIT:<done> + + </LITERALLAYOUT> +</SECT1> + +<!-- ==================================================== --> + +<SECT1 id="rt-at91-eb40"> +<TITLE>Board: Atmel AT91/EB40</TITLE> +<LITERALLAYOUT CLASS="MONOSPACED"> +Board: Atmel AT91/EB40 +CPU : AT91R40807 (ARM7TDMI core), 32MHz +512KB RAM, 64K Flash + +Startup, main stack : stack used 420 size 2400 +Startup : Interrupt stack used 144 size 4096 +Startup : Idlethread stack used 84 size 2048 + +eCos Kernel Timings +Notes: all times are in microseconds (.000001) unless otherwise stated + +Reading the hardware clock takes 3 'ticks' overhead +... this value will be factored out of all other measurements +Clock interrupt took 127.53 microseconds (130 raw clock ticks) + +Testing parameters: + Clock samples: 32 + Threads: 25 + Thread switches: 128 + Mutexes: 32 + Mailboxes: 32 + Semaphores: 32 + Scheduler operations: 128 + Counters: 32 + Alarms: 32 + + + Confidence + Ave Min Max Var Ave Min Function + ====== ====== ====== ====== ========== ======== + 86.48 71.29 101.56 7.99 48% 28% Create thread + 20.70 20.51 21.48 0.31 80% 80% Yield thread [all suspended] + 17.15 16.60 17.58 0.48 56% 44% Suspend [suspended] thread + 17.07 16.60 17.58 0.49 52% 52% Resume thread + 25.51 25.39 26.37 0.21 88% 88% Set priority + 3.16 2.93 3.91 0.36 76% 76% Get priority + 52.34 51.76 52.73 0.47 60% 40% Kill [suspended] thread + 20.70 20.51 21.48 0.31 80% 80% Yield [no other] thread + 28.98 28.32 30.27 0.48 60% 36% Resume [suspended low prio] thread + 17.11 16.60 17.58 0.49 52% 48% Resume [runnable low prio] thread + 27.85 26.37 28.32 0.52 96% 4% Suspend [runnable] thread + 20.70 20.51 21.48 0.31 80% 80% Yield [only low prio] thread + 17.23 16.60 17.58 0.45 64% 36% Suspend [runnable->not runnable] + 52.34 51.76 52.73 0.47 60% 40% Kill [runnable] thread + 33.01 32.23 33.20 0.31 80% 20% Destroy [dead] thread + 72.03 70.31 72.27 0.38 80% 4% Destroy [runnable] thread + 96.99 95.70 112.30 1.22 64% 96% Resume [high priority] thread + 51.48 49.80 164.06 1.76 99% 99% Thread switch + + 2.78 1.95 2.93 0.26 84% 15% Scheduler lock + 11.81 11.72 12.70 0.17 90% 90% Scheduler unlock [0 threads] + 11.81 11.72 12.70 0.17 90% 90% Scheduler unlock [1 suspended] + 11.81 11.72 12.70 0.17 90% 90% Scheduler unlock [many suspended] + 11.81 11.72 12.70 0.17 90% 90% Scheduler unlock [many low prio] + + 5.49 4.88 5.86 0.46 62% 37% Init mutex + 20.20 19.53 20.51 0.42 68% 31% Lock [unlocked] mutex + 24.44 24.41 25.39 0.06 96% 96% Unlock [locked] mutex + 18.25 17.58 18.55 0.42 68% 31% Trylock [unlocked] mutex + 16.11 15.63 16.60 0.49 100% 50% Trylock [locked] mutex + 6.10 5.86 6.84 0.37 75% 75% Destroy mutex + 124.21 124.02 125.00 0.30 81% 81% Unlock/Lock mutex + + 9.28 8.79 9.77 0.49 100% 50% Create mbox + 2.93 2.93 2.93 0.00 100% 100% Peek [empty] mbox + 22.58 22.46 23.44 0.21 87% 87% Put [first] mbox + 2.44 1.95 2.93 0.49 100% 50% Peek [1 msg] mbox + 22.58 22.46 23.44 0.21 87% 87% Put [second] mbox + 2.44 1.95 2.93 0.49 100% 50% Peek [2 msgs] mbox + 22.71 22.46 23.44 0.37 75% 75% Get [first] mbox + 22.71 22.46 23.44 0.37 75% 75% Get [second] mbox + 21.18 20.51 21.48 0.42 68% 31% Tryput [first] mbox + 18.98 18.55 19.53 0.48 56% 56% Peek item [non-empty] mbox + 22.46 22.46 22.46 0.00 100% 100% Tryget [non-empty] mbox + 18.31 17.58 18.55 0.37 75% 25% Peek item [empty] mbox + 19.53 19.53 19.53 0.00 100% 100% Tryget [empty] mbox + 2.69 1.95 2.93 0.37 75% 25% Waiting to get mbox + 2.93 2.93 2.93 0.00 100% 100% Waiting to put mbox + 23.86 23.44 24.41 0.48 56% 56% Delete mbox + 67.60 67.38 68.36 0.33 78% 78% Put/Get mbox + + 5.37 4.88 5.86 0.49 100% 50% Init semaphore + 16.97 16.60 17.58 0.46 62% 62% Post [0] semaphore + 18.98 18.55 19.53 0.48 56% 56% Wait [1] semaphore + 15.81 15.63 16.60 0.30 81% 81% Trywait [0] semaphore + 15.29 14.65 15.63 0.44 65% 34% Trywait [1] semaphore + 5.62 4.88 5.86 0.37 75% 25% Peek semaphore + 6.35 5.86 6.84 0.49 100% 50% Destroy semaphore + 72.36 72.27 73.24 0.17 90% 90% Post/Wait semaphore + + 7.08 6.84 7.81 0.37 75% 75% Create counter + 3.17 2.93 3.91 0.37 75% 75% Get counter value + 3.05 2.93 3.91 0.21 87% 87% Set counter value + 24.11 23.44 24.41 0.42 68% 31% Tick counter + 5.49 4.88 5.86 0.46 62% 37% Delete counter + + 10.92 10.74 11.72 0.30 81% 81% Create alarm + 31.46 31.25 32.23 0.33 78% 78% Initialize alarm + 3.05 2.93 3.91 0.21 87% 87% Disable alarm + 31.49 31.25 32.23 0.37 75% 75% Enable alarm + 7.02 6.84 7.81 0.30 81% 81% Delete alarm + 31.16 30.27 31.25 0.17 90% 9% Tick counter [1 alarm] + 309.26 304.69 425.78 7.28 96% 96% Tick counter [many alarms] + 44.83 43.95 44.92 0.17 90% 9% Tick & fire counter [1 alarm] + 781.68 774.41 893.55 13.62 93% 93% Tick & fire counters [>1 together] + 324.16 320.31 433.59 6.84 96% 96% Tick & fire counters [>1 separately] + 114.26 113.28 167.97 0.84 57% 42% Alarm latency [0 threads] + 126.91 113.28 159.18 8.20 50% 31% Alarm latency [2 threads] + 127.11 113.28 158.20 8.09 51% 28% Alarm latency [many threads] + 196.49 189.45 331.05 2.10 98% 0% Alarm -> thread resume latency + + 23.50 23.44 25.39 0.00 Clock/interrupt latency + + 40.31 33.20 514.65 0.00 Clock DSR latency + + 300 271 312 (main stack: 832) Thread stack used (1120 total) +All done, main stack : stack used 832 size 2400 +All done : Interrupt stack used 288 size 4096 +All done : Idlethread stack used 272 size 2048 + +Timing complete - 30350 ms total + +PASS:<Basic timing OK> +EXIT:<done> + </LITERALLAYOUT> +</SECT1> + +<!-- ==================================================== --> + +<SECT1 id="rt-arm-ebsa285"> +<TITLE>Board: Intel StrongARM EBSA-285 Evaluation Board</TITLE> +<LITERALLAYOUT CLASS="MONOSPACED">Board: Intel StrongARM EBSA-285 Evaluation Board + +CPU : Intel StrongARM SA-110 228MHz + + +Startup, main stack : stack used 404 size 2400 +Startup : Interrupt stack used 136 size 4096 +Startup : Idlethread stack used 80 size 2048 + +eCos Kernel Timings +Notes: all times are in microseconds (.000001) unless otherwise stated + +Reading the hardware clock takes 1 'ticks' overhead +... this value will be factored out of all other measurements +Clock interrupt took 4.61 microseconds (16 raw clock ticks) + +Testing parameters: + Clock samples: 32 + Threads: 64 + Thread switches: 128 + Mutexes: 32 + Mailboxes: 32 + Semaphores: 32 + Scheduler operations: 128 + Counters: 32 + Alarms: 32 + + + Confidence + Ave Min Max Var Ave Min Function + ====== ====== ====== ====== ========== ======== + 4.97 3.26 7.34 0.60 50% 4% Create thread + 0.73 0.54 2.17 0.14 60% 37% Yield thread [all suspended] + 0.98 0.82 2.99 0.23 81% 68% Suspend [suspended] thread + 0.54 0.27 1.63 0.03 92% 6% Resume thread + 0.83 0.54 1.90 0.10 73% 14% Set priority + 0.21 0.00 0.54 0.21 25% 48% Get priority + 2.25 1.90 10.05 0.37 96% 67% Kill [suspended] thread + 0.70 0.54 1.09 0.14 53% 45% Yield [no other] thread + 0.96 0.82 1.36 0.14 50% 48% Resume [suspended low prio] thread + 0.53 0.27 0.82 0.03 92% 6% Resume [runnable low prio] thread + 0.90 0.82 1.63 0.13 70% 70% Suspend [runnable] thread + 0.70 0.54 0.82 0.13 57% 42% Yield [only low prio] thread + 0.55 0.54 0.82 0.01 98% 98% Suspend [runnable->not runnable] + 1.64 1.63 2.17 0.02 98% 98% Kill [runnable] thread + 0.97 0.82 4.62 0.20 98% 64% Destroy [dead] thread + 2.17 1.90 2.17 0.01 98% 1% Destroy [runnable] thread + 6.06 5.16 10.60 0.53 59% 31% Resume [high priority] thread + 1.69 1.63 5.98 0.11 90% 90% Thread switch + + 0.14 0.00 1.36 0.14 99% 50% Scheduler lock + 0.37 0.27 0.54 0.13 62% 62% Scheduler unlock [0 threads] + 0.38 0.27 0.54 0.13 60% 60% Scheduler unlock [1 suspended] + 0.37 0.27 0.54 0.13 63% 63% Scheduler unlock [many suspended] + 0.37 0.27 0.54 0.13 63% 63% Scheduler unlock [many low prio] + + 0.34 0.00 1.90 0.15 78% 6% Init mutex + 0.88 0.54 4.62 0.37 93% 71% Lock [unlocked] mutex + 0.79 0.54 4.35 0.26 93% 53% Unlock [locked] mutex + 0.59 0.27 2.17 0.10 93% 3% Trylock [unlocked] mutex + 0.50 0.27 0.82 0.09 78% 18% Trylock [locked] mutex + 0.18 0.00 0.54 0.13 59% 37% Destroy mutex + 3.85 3.80 5.16 0.08 96% 96% Unlock/Lock mutex + + 0.64 0.27 3.53 0.24 81% 15% Create mbox + 0.61 0.27 2.17 0.21 68% 18% Peek [empty] mbox + 0.87 0.54 5.16 0.31 59% 87% Put [first] mbox + 0.08 0.00 0.54 0.12 71% 71% Peek [1 msg] mbox + 0.71 0.54 1.09 0.14 56% 40% Put [second] mbox + 0.08 0.00 0.27 0.12 68% 68% Peek [2 msgs] mbox + 0.89 0.54 4.89 0.31 62% 81% Get [first] mbox + 0.76 0.54 1.09 0.17 43% 37% Get [second] mbox + 0.76 0.54 3.26 0.21 96% 50% Tryput [first] mbox + 0.65 0.54 2.45 0.17 81% 81% Peek item [non-empty] mbox + 0.76 0.54 2.72 0.19 53% 43% Tryget [non-empty] mbox + 0.58 0.54 0.82 0.06 87% 87% Peek item [empty] mbox + 0.61 0.54 0.82 0.10 75% 75% Tryget [empty] mbox + 0.10 0.00 0.54 0.13 65% 65% Waiting to get mbox + 0.10 0.00 0.54 0.13 65% 65% Waiting to put mbox + 0.77 0.54 3.26 0.20 53% 43% Delete mbox + 2.10 1.90 6.25 0.30 93% 93% Put/Get mbox + + 0.34 0.27 1.09 0.11 81% 81% Init semaphore + 0.60 0.27 1.09 0.12 68% 6% Post [0] semaphore + 0.59 0.54 0.82 0.08 81% 81% Wait [1] semaphore + 0.59 0.54 2.17 0.10 96% 96% Trywait [0] semaphore + 0.48 0.27 0.82 0.11 71% 25% Trywait [1] semaphore + 0.24 0.00 0.82 0.09 78% 18% Peek semaphore + 0.19 0.00 0.54 0.13 62% 34% Destroy semaphore + 2.28 2.17 4.08 0.18 93% 90% Post/Wait semaphore + + 0.43 0.00 2.72 0.23 90% 6% Create counter + 0.40 0.00 1.63 0.25 68% 28% Get counter value + 0.13 0.00 0.82 0.15 96% 59% Set counter value + 0.71 0.54 1.63 0.16 50% 46% Tick counter + 0.16 0.00 0.54 0.14 53% 43% Delete counter + + 0.47 0.27 1.36 0.15 59% 37% Create alarm + 1.58 1.09 7.07 0.44 71% 68% Initialize alarm + 0.12 0.00 1.09 0.16 96% 65% Disable alarm + 1.01 0.82 2.45 0.17 53% 43% Enable alarm + 0.21 0.00 0.27 0.09 78% 21% Delete alarm + 0.78 0.54 1.90 0.12 71% 25% Tick counter [1 alarm] + 3.90 3.80 4.35 0.13 68% 68% Tick counter [many alarms] + 1.25 1.09 1.63 0.14 53% 43% Tick & fire counter [1 alarm] + 19.88 19.84 20.11 0.07 84% 84% Tick & fire counters [>1 together] + 4.37 4.35 4.62 0.05 90% 90% Tick & fire counters [>1 separately] + 3.83 3.80 7.61 0.06 99% 99% Alarm latency [0 threads] + 4.46 3.80 7.88 0.27 71% 24% Alarm latency [2 threads] + 16.06 13.59 26.36 1.05 54% 10% Alarm latency [many threads] + 6.67 6.52 22.83 0.29 98% 98% Alarm -> thread resume latency + + 1.89 0.82 9.78 0.00 Clock/interrupt latency + + 2.17 1.09 7.34 0.00 Clock DSR latency + + 11 0 316 (main stack: 744) Thread stack used (1120 total) +All done, main stack : stack used 744 size 2400 +All done : Interrupt stack used 288 size 4096 +All done : Idlethread stack used 268 size 2048 + +Timing complete - 30210 ms total + +PASS:<Basic timing OK> +EXIT:<done> + </LITERALLAYOUT> +</SECT1> + +<!-- ==================================================== --> + +<SECT1 id="rt-arm-ep7211"> +<TITLE>Board: Cirrus Logic EDB7111-2 Development Board</TITLE> +<SECT2> +<TITLE>CPU : Cirrus Logic EP7211 73MHz</TITLE> +<LITERALLAYOUT CLASS="MONOSPACED">Board: Cirrus Logic EDB7111-2 Development Board + +CPU : Cirrus Logic EP7211 73MHz + + + +Startup, main stack : stack used 404 size 2400 +Startup : Interrupt stack used 136 size 4096 +Startup : Idlethread stack used 88 size 2048 + +eCos Kernel Timings +Notes: all times are in microseconds (.000001) unless otherwise stated + +Reading the hardware clock takes 0 'ticks' overhead +... this value will be factored out of all other measurements +Clock interrupt took 356.69 microseconds (182 raw clock ticks) + +Testing parameters: + Clock samples: 32 + Threads: 64 + Thread switches: 128 + Mutexes: 32 + Mailboxes: 32 + Semaphores: 32 + Scheduler operations: 128 + Counters: 32 + Alarms: 32 + + + Confidence + Ave Min Max Var Ave Min Function + ====== ====== ====== ====== ========== ======== + 22.71 17.58 37.11 3.07 46% 34% Create thread + 4.36 3.91 5.86 0.70 76% 76% Yield thread [all suspended] + 4.24 3.91 7.81 0.56 84% 84% Suspend [suspended] thread + 4.09 1.95 7.81 0.45 85% 3% Resume thread + 5.31 3.91 11.72 0.92 65% 32% Set priority + 2.11 1.95 3.91 0.28 92% 92% Get priority + 11.54 9.77 25.39 0.99 62% 28% Kill [suspended] thread + 4.46 3.91 9.77 0.82 75% 75% Yield [no other] thread + 7.57 5.86 13.67 0.69 75% 20% Resume [suspended low prio] thread + 3.94 1.95 5.86 0.18 92% 3% Resume [runnable low prio] thread + 7.02 5.86 13.67 1.05 53% 45% Suspend [runnable] thread + 4.42 3.91 9.77 0.79 76% 76% Yield [only low prio] thread + 4.24 1.95 5.86 0.61 79% 1% Suspend [runnable->not runnable] + 11.29 9.77 27.34 1.14 57% 37% Kill [runnable] thread + 6.29 3.91 11.72 0.84 71% 4% Destroy [dead] thread + 13.52 11.72 31.25 0.90 70% 25% Destroy [runnable] thread + 24.50 21.48 42.97 1.69 79% 12% Resume [high priority] thread + 8.79 7.81 19.53 1.05 99% 53% Thread switch + + 1.66 0.00 3.91 0.52 83% 15% Scheduler lock + 2.59 1.95 3.91 0.86 67% 67% Scheduler unlock [0 threads] + 2.62 1.95 3.91 0.88 65% 65% Scheduler unlock [1 suspended] + 2.61 1.95 3.91 0.87 66% 66% Scheduler unlock [many suspended] + 2.58 1.95 3.91 0.85 67% 67% Scheduler unlock [many low prio] + + 2.69 1.95 5.86 0.96 65% 65% Init mutex + 4.88 3.91 9.77 1.10 96% 56% Lock [unlocked] mutex + 4.64 3.91 11.72 1.05 71% 71% Unlock [locked] mutex + 3.97 1.95 7.81 0.47 81% 9% Trylock [unlocked] mutex + 3.48 1.95 3.91 0.67 78% 21% Trylock [locked] mutex + 1.77 0.00 3.91 0.44 84% 12% Destroy mutex + 31.92 29.30 42.97 1.65 71% 18% Unlock/Lock mutex + + 4.09 3.91 9.77 0.35 96% 96% Create mbox + 1.83 0.00 3.91 0.34 87% 9% Peek [empty] mbox + 5.31 3.91 9.77 0.96 62% 34% Put [first] mbox + 1.59 0.00 1.95 0.60 81% 18% Peek [1 msg] mbox + 5.19 3.91 9.77 1.04 56% 40% Put [second] mbox + 1.65 0.00 3.91 0.62 78% 18% Peek [2 msgs] mbox + 5.43 3.91 9.77 0.86 68% 28% Get [first] mbox + 5.31 3.91 7.81 0.96 59% 34% Get [second] mbox + 4.76 3.91 9.77 1.07 62% 62% Tryput [first] mbox + 4.82 1.95 9.77 1.15 93% 3% Peek item [non-empty] mbox + 5.55 3.91 11.72 0.82 71% 25% Tryget [non-empty] mbox + 3.97 1.95 7.81 0.59 75% 12% Peek item [empty] mbox + 4.33 3.91 7.81 0.69 81% 81% Tryget [empty] mbox + 1.59 0.00 3.91 0.79 68% 25% Waiting to get mbox + 1.71 0.00 3.91 0.53 81% 15% Waiting to put mbox + 5.25 3.91 9.77 1.01 59% 37% Delete mbox + 17.82 15.63 29.30 1.14 65% 18% Put/Get mbox + + 2.69 1.95 5.86 0.96 65% 65% Init semaphore + 3.78 1.95 7.81 0.46 84% 12% Post [0] semaphore + 4.27 3.91 7.81 0.62 84% 84% Wait [1] semaphore + 3.72 1.95 7.81 0.66 75% 18% Trywait [0] semaphore + 3.29 1.95 5.86 0.92 62% 34% Trywait [1] semaphore + 2.32 1.95 3.91 0.59 81% 81% Peek semaphore + 1.89 0.00 3.91 0.24 90% 6% Destroy semaphore + 15.75 13.67 29.30 1.07 68% 21% Post/Wait semaphore + + 2.69 1.95 5.86 0.96 65% 65% Create counter + 1.83 0.00 1.95 0.23 93% 6% Get counter value + 1.53 0.00 3.91 0.76 71% 25% Set counter value + 4.82 3.91 5.86 0.97 53% 53% Tick counter + 1.89 0.00 1.95 0.12 96% 3% Delete counter + + 3.78 1.95 7.81 0.46 84% 12% Create alarm + 7.99 5.86 15.63 0.70 81% 9% Initialize alarm + 1.71 0.00 1.95 0.43 87% 12% Disable alarm + 7.14 5.86 11.72 1.04 56% 40% Enable alarm + 2.50 1.95 3.91 0.79 71% 71% Delete alarm + 4.94 3.91 7.81 1.04 96% 50% Tick counter [1 alarm] + 19.47 17.58 23.44 0.36 87% 9% Tick counter [many alarms] + 7.63 5.86 11.72 0.55 81% 15% Tick & fire counter [1 alarm] + 99.06 97.66 105.47 1.05 59% 37% Tick & fire counters [>1 together] + 22.15 21.48 27.34 0.96 71% 71% Tick & fire counters [>1 separately] + 359.16 357.42 378.91 0.87 71% 25% Alarm latency [0 threads] + 364.03 357.42 402.34 3.03 58% 15% Alarm latency [2 threads] + 408.25 402.34 416.02 2.89 53% 24% Alarm latency [many threads] + 381.16 376.95 492.19 2.48 95% 46% Alarm -> thread resume latency + + 9.79 5.86 19.53 0.00 Clock/interrupt latency + + 12.13 5.86 31.25 0.00 Clock DSR latency + + 12 0 316 (main stack: 752) Thread stack used (1120 total) +All done, main stack : stack used 752 size 2400 +All done : Interrupt stack used 288 size 4096 +All done : Idlethread stack used 276 size 2048 + +Timing complete - 30450 ms total + +PASS:<Basic timing OK> +EXIT:<done> + + </LITERALLAYOUT> +</SECT2> +<SECT2> +<TITLE>CPU : Cirrus Logic EP7212 73MHz</TITLE> +<LITERALLAYOUT CLASS="MONOSPACED">Board: Cirrus Logic EDB7111-2 Development Board + +CPU : Cirrus Logic EP7212 73MHz + + + +Startup, main stack : stack used 404 size 2400 +Startup : Interrupt stack used 136 size 4096 +Startup : Idlethread stack used 88 size 2048 + +eCos Kernel Timings +Notes: all times are in microseconds (.000001) unless otherwise stated + +Reading the hardware clock takes 0 'ticks' overhead +... this value will be factored out of all other measurements +Clock interrupt took 356.32 microseconds (182 raw clock ticks) + +Testing parameters: + Clock samples: 32 + Threads: 64 + Thread switches: 128 + Mutexes: 32 + Mailboxes: 32 + Semaphores: 32 + Scheduler operations: 128 + Counters: 32 + Alarms: 32 + + + Confidence + Ave Min Max Var Ave Min Function + ====== ====== ====== ====== ========== ======== + 22.43 15.63 33.20 3.02 68% 18% Create thread + 4.48 3.91 5.86 0.81 70% 70% Yield thread [all suspended] + 4.42 3.91 7.81 0.78 75% 75% Suspend [suspended] thread + 4.12 1.95 5.86 0.49 82% 3% Resume thread + 5.62 3.91 11.72 0.64 78% 18% Set priority + 2.17 1.95 3.91 0.38 89% 89% Get priority + 11.54 9.77 27.34 0.88 70% 25% Kill [suspended] thread + 4.64 3.91 9.77 0.96 65% 65% Yield [no other] thread + 7.51 5.86 15.63 0.72 76% 21% Resume [suspended low prio] thread + 3.88 1.95 9.77 0.42 82% 10% Resume [runnable low prio] thread + 7.14 5.86 13.67 1.00 59% 39% Suspend [runnable] thread + 4.52 3.91 7.81 0.86 70% 70% Yield [only low prio] thread + 4.15 1.95 7.81 0.49 85% 1% Suspend [runnable->not runnable] + 11.26 9.77 27.34 1.17 56% 39% Kill [runnable] thread + 6.22 3.91 13.67 0.88 70% 7% Destroy [dead] thread + 13.64 11.72 33.20 1.02 64% 26% Destroy [runnable] thread + 24.17 21.48 41.02 1.49 82% 12% Resume [high priority] thread + 8.80 7.81 21.48 1.08 98% 54% Thread switch + + 1.60 0.00 1.95 0.58 82% 17% Scheduler lock + 2.61 1.95 3.91 0.87 66% 66% Scheduler unlock [0 threads] + 2.59 1.95 3.91 0.86 67% 67% Scheduler unlock [1 suspended] + 2.61 1.95 3.91 0.87 66% 66% Scheduler unlock [many suspended] + 2.59 1.95 3.91 0.86 67% 67% Scheduler unlock [many low prio] + + 2.62 1.95 3.91 0.88 65% 65% Init mutex + 4.82 3.91 9.77 1.09 96% 59% Lock [unlocked] mutex + 4.39 3.91 9.77 0.79 81% 81% Unlock [locked] mutex + 3.84 1.95 7.81 0.36 87% 9% Trylock [unlocked] mutex + 3.54 1.95 5.86 0.69 75% 21% Trylock [locked] mutex + 1.83 0.00 3.91 0.34 87% 9% Destroy mutex + 34.61 31.25 46.88 1.68 78% 9% Unlock/Lock mutex + + 3.97 1.95 7.81 0.24 93% 3% Create mbox + 1.83 0.00 3.91 0.34 87% 9% Peek [empty] mbox + 4.76 3.91 9.77 1.07 62% 62% Put [first] mbox + 1.71 0.00 3.91 0.64 75% 18% Peek [1 msg] mbox + 5.00 3.91 9.77 1.10 96% 50% Put [second] mbox + 1.65 0.00 1.95 0.52 84% 15% Peek [2 msgs] mbox + 5.31 3.91 11.72 1.05 59% 37% Get [first] mbox + 5.13 3.91 7.81 0.99 56% 40% Get [second] mbox + 4.76 3.91 11.72 1.12 96% 65% Tryput [first] mbox + 4.46 3.91 7.81 0.82 75% 75% Peek item [non-empty] mbox + 5.55 3.91 9.77 0.82 68% 25% Tryget [non-empty] mbox + 4.03 1.95 7.81 0.58 78% 9% Peek item [empty] mbox + 4.27 3.91 5.86 0.59 81% 81% Tryget [empty] mbox + 1.77 0.00 3.91 0.44 84% 12% Waiting to get mbox + 1.59 0.00 1.95 0.60 81% 18% Waiting to put mbox + 5.37 3.91 9.77 0.91 65% 31% Delete mbox + 16.66 13.67 27.34 1.42 90% 3% Put/Get mbox + + 2.62 1.95 5.86 0.92 68% 68% Init semaphore + 3.84 1.95 7.81 0.47 81% 12% Post [0] semaphore + 4.21 3.91 7.81 0.53 87% 87% Wait [1] semaphore + 3.48 1.95 5.86 0.76 71% 25% Trywait [0] semaphore + 3.60 1.95 5.86 0.62 78% 18% Trywait [1] semaphore + 2.26 1.95 5.86 0.53 87% 87% Peek semaphore + 1.89 0.00 1.95 0.12 96% 3% Destroy semaphore + 16.05 13.67 29.30 1.40 59% 18% Post/Wait semaphore + + 2.38 1.95 3.91 0.67 78% 78% Create counter + 2.01 0.00 3.91 0.35 84% 6% Get counter value + 1.89 0.00 3.91 0.24 90% 6% Set counter value + 4.58 3.91 5.86 0.88 65% 65% Tick counter + 1.71 0.00 1.95 0.43 87% 12% Delete counter + + 3.84 1.95 7.81 0.36 87% 9% Create alarm + 7.99 5.86 15.63 0.47 93% 3% Initialize alarm + 2.01 0.00 3.91 0.35 84% 6% Disable alarm + 6.53 5.86 13.67 1.01 75% 75% Enable alarm + 2.32 1.95 3.91 0.59 81% 81% Delete alarm + 4.76 3.91 7.81 1.01 59% 59% Tick counter [1 alarm] + 19.53 17.58 23.44 0.24 90% 6% Tick counter [many alarms] + 7.57 5.86 13.67 0.75 75% 21% Tick & fire counter [1 alarm] + 98.57 97.66 105.47 1.14 96% 62% Tick & fire counters [>1 together] + 22.15 21.48 27.34 0.96 71% 71% Tick & fire counters [>1 separately] + 359.18 357.42 384.77 1.10 65% 31% Alarm latency [0 threads] + 362.63 357.42 396.48 2.55 43% 27% Alarm latency [2 threads] + 408.22 402.34 416.02 2.73 55% 21% Alarm latency [many threads] + 378.63 375.00 494.14 2.56 93% 71% Alarm -> thread resume latency + + 9.78 5.86 19.53 0.00 Clock/interrupt latency + + 12.21 5.86 31.25 0.00 Clock DSR latency + + 12 0 316 (main stack: 752) Thread stack used (1120 total) +All done, main stack : stack used 752 size 2400 +All done : Interrupt stack used 288 size 4096 +All done : Idlethread stack used 276 size 2048 + +Timing complete - 30550 ms total + +PASS:<Basic timing OK> +EXIT:<done> + + </LITERALLAYOUT> +</SECT2> +</SECT1> + +<!-- ==================================================== --> + +<SECT1 id="rt-arm-pid"> +<TITLE>Board: ARM PID Evaluation Board</TITLE> +<SECT2> +<TITLE>CPU : ARM 7TDMI 20 MHz</TITLE> +<LITERALLAYOUT CLASS="MONOSPACED">Board: ARM PID Evaluation Board + +CPU : ARM 7TDMI 20 MHz + + + +Startup, main stack : stack used 404 size 2400 +Startup : Interrupt stack used 136 size 4096 +Startup : Idlethread stack used 84 size 2048 + +eCos Kernel Timings +Notes: all times are in microseconds (.000001) unless otherwise stated + +Reading the hardware clock takes 6 'ticks' overhead +... this value will be factored out of all other measurements +Clock interrupt took 120.74 microseconds (150 raw clock ticks) + +Testing parameters: + Clock samples: 32 + Threads: 50 + Thread switches: 128 + Mutexes: 32 + Mailboxes: 32 + Semaphores: 32 + Scheduler operations: 128 + Counters: 32 + Alarms: 32 + + + Confidence + Ave Min Max Var Ave Min Function + ====== ====== ====== ====== ========== ======== + 99.01 68.00 129.60 15.62 50% 26% Create thread + 21.60 21.60 21.60 0.00 100% 100% Yield thread [all suspended] + 15.65 15.20 16.00 0.39 56% 44% Suspend [suspended] thread + 15.79 15.20 16.00 0.31 74% 26% Resume thread + 23.65 23.20 24.00 0.39 56% 44% Set priority + 2.26 1.60 2.40 0.24 82% 18% Get priority + 51.39 51.20 52.00 0.29 76% 76% Kill [suspended] thread + 21.60 21.60 21.60 0.00 100% 100% Yield [no other] thread + 29.47 28.00 29.60 0.22 86% 2% Resume [suspended low prio] thread + 15.60 15.20 16.00 0.40 100% 50% Resume [runnable low prio] thread + 27.73 24.00 28.00 0.40 74% 2% Suspend [runnable] thread + 21.60 21.60 21.60 0.00 100% 100% Yield [only low prio] thread + 15.65 15.20 16.00 0.39 56% 44% Suspend [runnable->not runnable] + 51.39 51.20 52.00 0.29 76% 76% Kill [runnable] thread + 27.66 27.20 28.80 0.41 54% 44% Destroy [dead] thread + 68.93 64.80 69.60 0.35 72% 2% Destroy [runnable] thread + 91.26 90.40 107.20 0.64 66% 32% Resume [high priority] thread + 49.14 48.80 49.60 0.39 57% 57% Thread switch + + 2.20 1.60 2.40 0.30 75% 25% Scheduler lock + 10.20 9.60 10.40 0.30 75% 25% Scheduler unlock [0 threads] + 10.20 9.60 10.40 0.30 75% 25% Scheduler unlock [1 suspended] + 10.20 9.60 10.40 0.30 75% 25% Scheduler unlock [many suspended] + 10.20 9.60 10.40 0.30 75% 25% Scheduler unlock [many low prio] + + 6.85 6.40 7.20 0.39 56% 43% Init mutex + 18.40 18.40 18.40 0.00 100% 100% Lock [unlocked] mutex + 19.57 19.20 20.00 0.40 53% 53% Unlock [locked] mutex + 16.55 16.00 16.80 0.34 68% 31% Trylock [unlocked] mutex + 14.55 14.40 15.20 0.24 81% 81% Trylock [locked] mutex + 3.55 3.20 4.00 0.39 56% 56% Destroy mutex + 119.85 119.20 120.00 0.24 81% 18% Unlock/Lock mutex + + 12.85 12.80 13.60 0.09 93% 93% Create mbox + 1.65 1.60 2.40 0.09 93% 93% Peek [empty] mbox + 20.70 20.00 20.80 0.17 87% 12% Put [first] mbox + 1.65 1.60 2.40 0.09 93% 93% Peek [1 msg] mbox + 20.70 20.00 20.80 0.17 87% 12% Put [second] mbox + 1.65 1.60 2.40 0.09 93% 93% Peek [2 msgs] mbox + 20.85 20.80 21.60 0.09 93% 93% Get [first] mbox + 20.85 20.80 21.60 0.09 93% 93% Get [second] mbox + 19.90 19.20 20.00 0.17 87% 12% Tryput [first] mbox + 17.60 17.60 17.60 0.00 100% 100% Peek item [non-empty] mbox + 20.90 20.80 21.60 0.17 87% 87% Tryget [non-empty] mbox + 16.80 16.80 16.80 0.00 100% 100% Peek item [empty] mbox + 17.65 17.60 18.40 0.09 93% 93% Tryget [empty] mbox + 1.85 1.60 2.40 0.34 68% 68% Waiting to get mbox + 1.85 1.60 2.40 0.34 68% 68% Waiting to put mbox + 19.40 19.20 20.00 0.30 75% 75% Delete mbox + 65.05 64.80 65.60 0.34 68% 68% Put/Get mbox + + 7.05 6.40 7.20 0.24 81% 18% Init semaphore + 15.55 15.20 16.00 0.39 56% 56% Post [0] semaphore + 17.35 16.80 17.60 0.34 68% 31% Wait [1] semaphore + 14.60 14.40 15.20 0.30 75% 75% Trywait [0] semaphore + 14.20 13.60 14.40 0.30 75% 25% Trywait [1] semaphore + 4.55 4.00 4.80 0.34 68% 31% Peek semaphore + 3.75 3.20 4.00 0.34 68% 31% Destroy semaphore + 70.85 70.40 71.20 0.39 56% 43% Post/Wait semaphore + + 6.05 5.60 6.40 0.39 56% 43% Create counter + 2.25 1.60 2.40 0.24 81% 18% Get counter value + 2.25 1.60 2.40 0.24 81% 18% Set counter value + 19.70 19.20 20.00 0.37 62% 37% Tick counter + 3.45 3.20 4.00 0.34 68% 68% Delete counter + + 9.05 8.80 9.60 0.34 68% 68% Create alarm + 29.60 29.60 29.60 0.00 100% 100% Initialize alarm + 2.15 1.60 2.40 0.34 68% 31% Disable alarm + 29.35 28.80 29.60 0.34 68% 31% Enable alarm + 5.10 4.80 5.60 0.37 62% 62% Delete alarm + 23.20 23.20 23.20 0.00 100% 100% Tick counter [1 alarm] + 138.00 137.60 138.40 0.40 100% 50% Tick counter [many alarms] + 40.40 40.00 40.80 0.40 100% 50% Tick & fire counter [1 alarm] + 704.25 697.60 804.00 12.47 93% 93% Tick & fire counters [>1 together] + 155.20 155.20 155.20 0.00 100% 100% Tick & fire counters [>1 separately] + 105.20 104.80 151.20 0.76 99% 94% Alarm latency [0 threads] + 117.57 104.80 149.60 7.13 57% 25% Alarm latency [2 threads] + 117.49 104.80 148.80 7.10 58% 26% Alarm latency [many threads] + 192.59 177.60 316.00 1.93 98% 0% Alarm -> thread resume latency + + 22.10 21.60 24.00 0.00 Clock/interrupt latency + + 38.69 32.80 61.60 0.00 Clock DSR latency + + 297 276 316 (main stack: 752) Thread stack used (1120 total) +All done, main stack : stack used 752 size 2400 +All done : Interrupt stack used 288 size 4096 +All done : Idlethread stack used 272 size 2048 + +Timing complete - 30350 ms total + +PASS:<Basic timing OK> +EXIT:<done> + + </LITERALLAYOUT> +</SECT2> +<SECT2> +<TITLE>CPU : ARM 920T 20 MHz</TITLE> +<LITERALLAYOUT CLASS="MONOSPACED"> + +Board: ARM PID Evaluation Board + +CPU : ARM 920T 20 MHz + + +Startup, main stack : stack used 404 size 2400 +Startup : Interrupt stack used 136 size 4096 +Startup : Idlethread stack used 84 size 2048 + +eCos Kernel Timings +Notes: all times are in microseconds (.000001) unless otherwise stated + +Reading the hardware clock takes 15 'ticks' overhead +... this value will be factored out of all other measurements +Clock interrupt took 291.41 microseconds (364 raw clock ticks) + +Testing parameters: + Clock samples: 32 + Threads: 50 + Thread switches: 128 + Mutexes: 32 + Mailboxes: 32 + Semaphores: 32 + Scheduler operations: 128 + Counters: 32 + Alarms: 32 + + + Confidence + Ave Min Max Var Ave Min Function + ====== ====== ====== ====== ========== ======== + 257.78 168.00 568.00 48.70 56% 28% Create thread + 50.21 49.60 50.40 0.29 76% 24% Yield thread [all suspended] + 36.26 36.00 36.80 0.35 68% 68% Suspend [suspended] thread + 37.20 36.80 37.60 0.40 100% 50% Resume thread + 56.24 56.00 56.80 0.34 70% 70% Set priority + 5.20 4.80 5.60 0.40 100% 50% Get priority + 122.75 122.40 123.20 0.39 56% 56% Kill [suspended] thread + 50.19 49.60 50.40 0.31 74% 26% Yield [no other] thread + 69.49 66.40 69.60 0.21 92% 2% Resume [suspended low prio] thread + 37.01 36.80 37.60 0.31 74% 74% Resume [runnable low prio] thread + 64.75 55.20 65.60 0.38 80% 2% Suspend [runnable] thread + 50.19 49.60 50.40 0.31 74% 26% Yield [only low prio] thread + 36.24 36.00 36.80 0.34 70% 70% Suspend [runnable->not runnable] + 122.75 122.40 123.20 0.39 56% 56% Kill [runnable] thread + 67.76 67.20 68.00 0.34 70% 30% Destroy [dead] thread + 167.07 158.40 168.00 0.35 92% 2% Destroy [runnable] thread + 213.49 212.00 249.60 1.46 84% 90% Resume [high priority] thread + 122.81 120.00 389.60 4.17 99% 99% Thread switch + + 4.70 4.00 4.80 0.17 87% 12% Scheduler lock + 23.70 23.20 24.00 0.37 62% 37% Scheduler unlock [0 threads] + 23.60 23.20 24.00 0.40 100% 50% Scheduler unlock [1 suspended] + 23.70 23.20 24.00 0.37 62% 37% Scheduler unlock [many suspended] + 23.60 23.20 24.00 0.40 100% 50% Scheduler unlock [many low prio] + + 15.65 15.20 16.00 0.39 56% 43% Init mutex + 42.40 42.40 42.40 0.00 100% 100% Lock [unlocked] mutex + 45.37 44.80 46.40 0.36 65% 31% Unlock [locked] mutex + 39.20 39.20 39.20 0.00 100% 100% Trylock [unlocked] mutex + 34.45 34.40 35.20 0.09 93% 93% Trylock [locked] mutex + 8.00 8.00 8.00 0.00 100% 100% Destroy mutex + 284.42 284.00 284.80 0.40 53% 46% Unlock/Lock mutex + + 29.40 28.80 29.60 0.30 75% 25% Create mbox + 3.35 3.20 4.00 0.24 81% 81% Peek [empty] mbox + 49.35 48.80 49.60 0.34 68% 31% Put [first] mbox + 3.35 3.20 4.00 0.24 81% 81% Peek [1 msg] mbox + 49.35 48.80 49.60 0.34 68% 31% Put [second] mbox + 3.35 3.20 4.00 0.24 81% 81% Peek [2 msgs] mbox + 49.15 48.80 49.60 0.39 56% 56% Get [first] mbox + 49.15 48.80 49.60 0.39 56% 56% Get [second] mbox + 47.80 47.20 48.00 0.30 75% 25% Tryput [first] mbox + 41.40 40.80 41.60 0.30 75% 25% Peek item [non-empty] mbox + 49.40 48.80 49.60 0.30 75% 25% Tryget [non-empty] mbox + 40.15 40.00 40.80 0.24 81% 81% Peek item [empty] mbox + 40.95 40.80 41.60 0.24 81% 81% Tryget [empty] mbox + 4.05 4.00 4.80 0.09 93% 93% Waiting to get mbox + 4.05 4.00 4.80 0.09 93% 93% Waiting to put mbox + 45.60 45.60 45.60 0.00 100% 100% Delete mbox + 153.27 152.80 153.60 0.39 59% 40% Put/Get mbox + + 16.80 16.80 16.80 0.00 100% 100% Init semaphore + 36.60 36.00 36.80 0.30 75% 25% Post [0] semaphore + 39.60 39.20 40.00 0.40 100% 50% Wait [1] semaphore + 34.80 34.40 35.20 0.40 100% 50% Trywait [0] semaphore + 33.35 32.80 33.60 0.34 68% 31% Trywait [1] semaphore + 10.30 9.60 10.40 0.17 87% 12% Peek semaphore + 8.80 8.80 8.80 0.00 100% 100% Destroy semaphore + 166.92 166.40 167.20 0.36 65% 34% Post/Wait semaphore + + 13.60 13.60 13.60 0.00 100% 100% Create counter + 4.85 4.80 5.60 0.09 93% 93% Get counter value + 4.80 4.80 4.80 0.00 100% 100% Set counter value + 45.25 44.80 45.60 0.39 56% 43% Tick counter + 7.75 7.20 8.00 0.34 68% 31% Delete counter + + 20.80 20.80 20.80 0.00 100% 100% Create alarm + 69.30 68.80 69.60 0.37 62% 37% Initialize alarm + 4.80 4.80 4.80 0.00 100% 100% Disable alarm + 67.35 67.20 68.00 0.24 81% 81% Enable alarm + 11.80 11.20 12.00 0.30 75% 25% Delete alarm + 54.80 54.40 55.20 0.40 100% 50% Tick counter [1 alarm] + 372.35 363.20 652.80 17.53 96% 96% Tick counter [many alarms] + 95.50 95.20 96.00 0.37 62% 62% Tick & fire counter [1 alarm] + 1757.92 1707.20 1996.80 81.43 81% 81% Tick & fire counters [>1 together] + 404.37 404.00 404.80 0.40 53% 53% Tick & fire counters [>1 separately] + 256.57 254.40 395.20 2.17 98% 97% Alarm latency [0 threads] + 296.60 255.20 359.20 23.53 53% 31% Alarm latency [2 threads] + 307.49 265.60 357.60 27.52 53% 53% Alarm latency [many threads] + 467.04 432.00 788.80 5.03 97% 1% Alarm -> thread resume latency + + 55.63 54.40 60.80 0.00 Clock/interrupt latency + + 101.23 80.80 1433.60 0.00 Clock DSR latency + + 316 316 316 (main stack: 752) Thread stack used (1120 total) +All done, main stack : stack used 752 size 2400 +All done : Interrupt stack used 288 size 4096 +All done : Idlethread stack used 272 size 2048 + +Timing complete - 30780 ms total + +PASS:<Basic timing OK> +EXIT:<done> + </LITERALLAYOUT> +</SECT2> +</SECT1> + +<!-- ==================================================== --> + +<SECT1 id="rt-arm-iq80310"> +<TITLE>Board: Intel IQ80310 XScale Development Kit</TITLE> +<LITERALLAYOUT CLASS="MONOSPACED">Board: Intel IQ80310 XScale Development Kit + +CPU: Intel XScale 600MHz + + +Startup, main stack : stack used 388 size 2400 +Startup : Interrupt stack used 148 size 4096 +Startup : Idlethread stack used 76 size 1120 + +eCos Kernel Timings +Notes: all times are in microseconds (.000001) unless otherwise stated + +Reading the hardware clock takes 73 'ticks' overhead +... this value will be factored out of all other measurements +Clock interrupt took 12.11 microseconds (399 raw clock ticks) + +Testing parameters: + Clock samples: 32 + Threads: 64 + Thread switches: 128 + Mutexes: 32 + Mailboxes: 32 + Semaphores: 32 + Scheduler operations: 128 + Counters: 32 + Alarms: 32 + + + Confidence + Ave Min Max Var Ave Min Function + ====== ====== ====== ====== ========== ======== + 6.53 5.48 8.55 0.50 53% 23% Create thread + 0.37 0.03 3.24 0.18 87% 1% Yield thread [all suspended] + 0.24 0.00 2.06 0.12 87% 1% Suspend [suspended] thread + 0.25 0.00 0.73 0.06 71% 1% Resume thread + 0.36 0.09 0.82 0.10 89% 1% Set priority + 0.03 0.00 0.42 0.05 90% 90% Get priority + 1.07 0.52 6.39 0.18 92% 1% Kill [suspended] thread + 0.33 0.06 0.91 0.08 78% 3% Yield [no other] thread + 0.55 0.03 1.06 0.09 85% 1% Resume [suspended low prio] thread + 0.28 0.00 1.79 0.11 84% 4% Resume [runnable low prio] thread + 0.43 0.00 1.00 0.12 76% 1% Suspend [runnable] thread + 0.31 0.00 1.24 0.09 82% 4% Yield [only low prio] thread + 0.21 0.00 0.42 0.04 73% 1% Suspend [runnable->not runnable] + 1.00 0.88 1.45 0.04 78% 4% Kill [runnable] thread + 0.59 0.42 3.97 0.13 81% 87% Destroy [dead] thread + 1.43 1.27 1.94 0.07 78% 7% Destroy [runnable] thread + 3.12 2.58 5.09 0.33 56% 34% Resume [high priority] thread + 0.87 0.36 1.39 0.07 86% 0% Thread switch + + 0.15 0.00 1.39 0.21 81% 81% Scheduler lock + 0.16 0.00 0.64 0.08 85% 7% Scheduler unlock [0 threads] + 0.16 0.00 0.64 0.08 75% 8% Scheduler unlock [1 suspended] + 0.16 0.00 0.70 0.08 78% 6% Scheduler unlock [many suspended] + 0.16 0.00 0.64 0.07 81% 4% Scheduler unlock [many low prio] + + 0.45 0.00 1.39 0.34 56% 46% Init mutex + 0.43 0.18 3.27 0.23 87% 87% Lock [unlocked] mutex + 0.48 0.09 3.88 0.26 84% 71% Unlock [locked] mutex + 0.35 0.21 2.24 0.21 87% 84% Trylock [unlocked] mutex + 0.26 0.00 0.67 0.13 78% 9% Trylock [locked] mutex + 0.21 0.00 1.27 0.24 78% 75% Destroy mutex + 2.58 2.09 3.09 0.13 75% 9% Unlock/Lock mutex + + 0.99 0.21 2.48 0.41 65% 28% Create mbox + 0.04 0.00 0.39 0.07 90% 87% Peek [empty] mbox + 0.47 0.27 3.48 0.29 90% 78% Put [first] mbox + 0.02 0.00 0.39 0.03 90% 90% Peek [1 msg] mbox + 0.29 0.15 0.58 0.04 68% 3% Put [second] mbox + 0.02 0.00 0.45 0.04 93% 93% Peek [2 msgs] mbox + 0.48 0.21 3.67 0.26 84% 87% Get [first] mbox + 0.35 0.09 0.82 0.11 75% 3% Get [second] mbox + 0.50 0.21 3.18 0.33 90% 68% Tryput [first] mbox + 0.39 0.15 1.39 0.19 78% 68% Peek item [non-empty] mbox + 0.43 0.18 3.33 0.23 87% 90% Tryget [non-empty] mbox + 0.28 0.03 0.79 0.06 68% 3% Peek item [empty] mbox + 0.28 0.21 0.58 0.05 71% 65% Tryget [empty] mbox + 0.01 0.00 0.36 0.02 96% 90% Waiting to get mbox + 0.05 0.00 0.45 0.09 87% 84% Waiting to put mbox + 0.42 0.09 2.88 0.20 84% 12% Delete mbox + 1.39 1.27 2.39 0.14 87% 87% Put/Get mbox + + 0.35 0.00 1.36 0.45 75% 68% Init semaphore + 0.19 0.00 0.45 0.04 81% 3% Post [0] semaphore + 0.25 0.21 0.88 0.06 84% 81% Wait [1] semaphore + 0.32 0.06 1.79 0.21 78% 68% Trywait [0] semaphore + 0.20 0.00 0.52 0.06 62% 3% Trywait [1] semaphore + 0.07 0.00 0.45 0.10 84% 81% Peek semaphore + 0.06 0.00 0.52 0.06 71% 78% Destroy semaphore + 1.45 1.42 1.79 0.04 87% 87% Post/Wait semaphore + + 0.70 0.00 2.88 0.47 43% 34% Create counter + 0.05 0.00 0.42 0.09 87% 84% Get counter value + 0.02 0.00 0.45 0.04 93% 93% Set counter value + 0.38 0.12 0.58 0.06 59% 3% Tick counter + 0.03 0.00 0.48 0.05 93% 78% Delete counter + + 1.10 0.39 4.30 0.47 62% 53% Create alarm + 0.58 0.03 3.12 0.18 87% 3% Initialize alarm + 0.04 0.00 0.42 0.07 90% 90% Disable alarm + 0.54 0.36 1.36 0.12 84% 43% Enable alarm + 0.03 0.00 0.70 0.06 84% 84% Delete alarm + 0.50 0.24 0.97 0.08 84% 6% Tick counter [1 alarm] + 5.30 5.12 5.97 0.14 84% 75% Tick counter [many alarms] + 0.82 0.64 1.36 0.11 78% 43% Tick & fire counter [1 alarm] + 14.13 13.85 14.55 0.09 78% 3% Tick & fire counters [>1 together] + 5.56 5.45 6.00 0.09 78% 71% Tick & fire counters [>1 separately] + 9.69 9.45 12.52 0.22 64% 71% Alarm latency [0 threads] + 9.98 9.48 12.76 0.23 69% 14% Alarm latency [2 threads] + 10.38 9.48 24.67 0.59 74% 45% Alarm latency [many threads] + 11.72 11.30 21.33 0.32 81% 58% Alarm -> thread resume latency + + 1.87 1.82 10.42 0.00 Clock/interrupt latency + + 3.02 2.58 7.67 0.00 Clock DSR latency + + 9 0 260 (main stack: 776) Thread stack used (1120 total) +All done, main stack : stack used 776 size 2400 +All done : Interrupt stack used 268 size 4096 +All done : Idlethread stack used 244 size 1120 + +Timing complete - 30300 ms total + +PASS:<Basic timing OK> +EXIT:<done> + + </LITERALLAYOUT> +</SECT1> + +<!-- ==================================================== --> + +<SECT1 id="rt-tx39-jmr3904"> +<TITLE>Board: Toshiba JMR3904 Evaluation Board</TITLE> +<LITERALLAYOUT CLASS="MONOSPACED"> + +Board: Toshiba JMR3904 Evaluation Board + +CPU : TMPR3904F 50MHz + + +eCOS Kernel Timings +Note: all times are in microseconds (.000001) unless otherwise stated + +Reading the hardware clock takes 0 'ticks' overhead +... this value will be factored out of all other measurements +Clock interrupt took 29.68 microseconds (45 raw clock ticks) + +Testing parameters: + Clock samples: 32 + Threads: 24 + Thread switches: 128 + Mutexes: 32 + Mailboxes: 32 + Semaphores: 32 + Scheduler operations: 128 + Counters: 32 + Alarms: 32 + + + Confidence + Ave Min Max Var Ave Min Function + ====== ====== ====== ====== ========== ======== + 13.62 11.72 27.99 1.51 79% 54% Create thread + 2.77 2.60 3.91 0.26 79% 79% Yield thread [all suspended] + 3.31 2.60 6.51 0.27 83% 12% Suspend [suspended] thread + 2.58 1.95 7.81 0.47 58% 37% Resume thread + 4.94 4.56 11.07 0.60 95% 79% Set priority + 0.71 0.65 1.95 0.10 95% 95% Get priority + 14.97 14.32 25.39 0.87 95% 95% Kill [suspended] thread + 2.25 1.95 9.11 0.57 95% 95% Yield [no other] thread + 7.27 6.51 12.37 0.42 79% 16% Resume [suspended low prio] thread + 2.28 1.95 7.16 0.51 95% 79% Resume [runnable low prio] thread + 4.31 3.26 12.37 0.75 87% 79% Suspend [runnable] thread + 2.17 1.95 7.16 0.42 95% 95% Yield [only low prio] thread + 2.39 1.95 6.51 0.51 95% 58% Suspend [runnable->not runnable] + 13.43 12.37 22.79 0.80 91% 91% Kill [runnable] thread + 22.30 20.83 37.76 1.76 91% 91% Resume [high priority] thread + 4.62 4.56 11.07 0.13 98% 98% Thread switch + + 1.51 1.30 2.60 0.29 68% 68% Scheduler lock + 2.36 1.95 3.26 0.31 61% 37% Scheduler unlock [0 threads] + 2.39 1.95 5.21 0.32 62% 36% Scheduler unlock [1 suspended] + 2.38 1.95 4.56 0.32 61% 37% Scheduler unlock [many suspended] + 2.38 1.95 5.21 0.32 61% 37% Scheduler unlock [many low prio] + + 0.90 0.65 3.26 0.35 71% 71% Init mutex + 2.48 1.95 8.46 0.50 50% 46% Lock [unlocked] mutex + 2.83 2.60 9.11 0.42 93% 93% Unlock [locked] mutex + 2.30 1.95 6.51 0.45 96% 65% Trylock [unlocked] mutex + 1.99 1.30 5.86 0.24 84% 12% Trylock [locked] mutex + 0.04 0.00 1.30 0.08 96% 96% Destroy mutex + 42.40 42.32 44.92 0.16 96% 96% Unlock/Lock mutex + + 1.44 1.30 5.86 0.28 96% 96% Create mbox + 0.51 0.00 1.30 0.25 71% 25% Peek [empty] mbox + 2.93 2.60 9.11 0.51 96% 78% Put [first] mbox + 0.51 0.00 1.30 0.25 71% 25% Peek [1 msg] mbox + 4.19 3.91 5.21 0.34 59% 59% Put [second] mbox + 0.45 0.00 0.65 0.28 68% 31% Peek [2 msgs] mbox + 3.28 2.60 10.42 0.45 65% 31% Get [first] mbox + 3.34 2.60 9.77 0.40 78% 18% Get [second] mbox + 2.69 1.95 9.11 0.40 78% 18% Tryput [first] mbox + 2.75 1.95 7.81 0.32 93% 3% Peek item [non-empty] mbox + 3.15 2.60 9.11 0.48 53% 43% Tryget [non-empty] mbox + 2.22 1.95 6.51 0.41 96% 78% Peek item [empty] mbox + 2.40 1.95 5.86 0.42 50% 46% Tryget [empty] mbox + 0.47 0.00 0.65 0.26 71% 28% Waiting to get mbox + 0.59 0.00 1.30 0.15 84% 12% Waiting to put mbox + 4.01 3.26 10.42 0.40 81% 15% Delete mbox + 26.18 26.04 30.60 0.28 96% 96% Put/Get mbox + + 0.92 0.65 3.91 0.38 71% 71% Init semaphore + 2.24 1.95 6.51 0.43 96% 75% Post [0] semaphore + 2.32 1.95 7.16 0.48 96% 65% Wait [1] semaphore + 2.03 1.30 5.86 0.24 90% 6% Trywait [0] semaphore + 1.91 1.30 4.56 0.23 78% 18% Trywait [1] semaphore + 0.77 0.00 1.95 0.30 65% 9% Peek semaphore + 0.61 0.00 1.95 0.15 84% 12% Destroy semaphore + 22.62 22.14 30.60 0.61 96% 62% Post/Wait semaphore + + 0.92 0.65 3.91 0.38 71% 71% Create counter + 0.69 0.65 1.95 0.08 96% 96% Get counter value + 0.41 0.00 1.30 0.33 56% 40% Set counter value + 3.21 2.60 5.86 0.27 71% 21% Tick counter + 0.65 0.00 3.26 0.16 84% 12% Delete counter + + 1.57 1.30 4.56 0.38 71% 71% Create alarm + 4.52 3.91 13.02 0.57 50% 46% Initialize alarm + 0.61 0.00 1.95 0.15 84% 12% Disable alarm + 4.43 3.91 9.11 0.43 56% 40% Enable alarm + 0.87 0.65 2.60 0.32 71% 71% Delete alarm + 2.93 2.60 6.51 0.43 96% 65% Tick counter [1 alarm] + 14.83 14.32 22.79 0.60 96% 59% Tick counter [many alarms] + 4.88 4.56 11.07 0.51 96% 78% Tick & fire counter [1 alarm] + 83.25 82.03 102.86 1.23 96% 93% Tick & fire counters [>1 together] + 17.58 16.93 27.34 0.61 50% 46% Tick & fire counters [>1 separately] + 26.18 24.74 40.36 0.30 97% 0% Alarm latency [0 threads] + 33.88 29.30 56.64 1.70 85% 6% Alarm latency [2 threads] + 36.37 29.30 61.20 3.25 53% 24% Alarm latency [many threads] + + 7.85 6.51 14.97 0.00 Clock/interrupt latency + +Timing complete - 23540 ms total + +PASS:<Basic timing OK> +EXIT:<done> + + </LITERALLAYOUT> +</SECT1> + +<!-- ==================================================== --> + +<SECT1 id="rt-tx49-ref4955"> +<TITLE>Board: Toshiba REF 4955</TITLE> +<LITERALLAYOUT CLASS="MONOSPACED"> + +Board: Toshiba REF 4955 + +CPU : Toshiba TX4955 66MHz + +Startup, main stack : stack used 960 size 2936 +Startup : Interrupt stack used 168 size 4096 +Startup : Idlethread stack used 372 size 2048 + +eCos Kernel Timings +Notes: all times are in microseconds (.000001) unless otherwise stated + +Reading the hardware clock takes 3 `ticks' overhead +... this value will be factored out of all other measurements +Clock interrupt took 4.00 microseconds (264 raw clock ticks) + +Testing parameters: + Clock samples: 32 + Threads: 64 + Thread switches: 128 + Mutexes: 32 + Mailboxes: 32 + Semaphores: 32 + Scheduler operations: 128 + Counters: 32 + Alarms: 32 + + + Confidence + Ave Min Max Var Ave Min Function + ====== ====== ====== ====== ========== ======== + 11.21 9.58 14.11 0.95 48% 34% Create thread + 0.66 0.65 1.29 0.02 98% 98% Yield thread [all suspended] + 0.63 0.53 3.06 0.17 82% 82% Suspend [suspended] thread + 0.54 0.53 1.06 0.02 98% 98% Resume thread + 0.78 0.74 1.39 0.05 93% 93% Set priority + 0.05 0.05 0.36 0.01 98% 98% Get priority + 2.06 1.89 6.65 0.25 95% 79% Kill [suspended] thread + 0.65 0.65 0.68 0.00 98% 98% Yield [no other] thread + 1.15 1.02 3.03 0.20 81% 81% Resume [suspended low prio] thread + 0.54 0.52 1.18 0.03 96% 96% Resume [runnable low prio] thread + 0.94 0.88 1.27 0.01 95% 1% Suspend [runnable] thread + 0.65 0.65 0.68 0.00 98% 98% Yield [only low prio] thread + 0.54 0.53 0.86 0.01 98% 96% Suspend [runnable->not runnable] + 1.97 1.89 2.98 0.12 84% 84% Kill [runnable] thread + 1.03 0.92 4.94 0.17 89% 89% Destroy [dead] thread + 2.55 2.33 4.38 0.24 89% 70% Destroy [runnable] thread + 5.62 4.11 13.23 0.99 65% 40% Resume [high priority] thread + 1.84 1.83 2.79 0.02 98% 98% Thread switch + + 0.12 0.02 0.65 0.15 74% 74% Scheduler lock + 0.35 0.35 0.35 0.00 100% 100% Scheduler unlock [0 threads] + 0.35 0.35 0.35 0.00 100% 100% Scheduler unlock [1 suspended] + 0.43 0.35 1.17 0.13 78% 78% Scheduler unlock [many suspended] + 0.45 0.35 1.17 0.15 75% 75% Scheduler unlock [many low prio] + + 0.46 0.15 3.38 0.30 62% 50% Init mutex + 0.73 0.64 3.27 0.16 96% 96% Lock [unlocked] mutex + 0.77 0.65 4.50 0.23 96% 96% Unlock [locked] mutex + 0.58 0.55 1.42 0.05 96% 96% Trylock [unlocked] mutex + 0.51 0.50 0.83 0.02 96% 96% Trylock [locked] mutex + 0.12 0.11 0.41 0.02 96% 96% Destroy mutex + 4.72 4.70 5.58 0.05 96% 96% Unlock/Lock mutex + + 1.01 0.67 3.48 0.40 71% 71% Create mbox + 0.02 0.00 0.53 0.03 96% 96% Peek [empty] mbox + 0.89 0.68 4.20 0.29 96% 71% Put [first] mbox + 0.02 0.00 0.33 0.02 96% 96% Peek [1 msg] mbox + 0.69 0.68 0.76 0.01 50% 46% Put [second] mbox + 0.02 0.00 0.30 0.02 96% 96% Peek [2 msgs] mbox + 0.81 0.71 3.83 0.19 96% 96% Get [first] mbox + 0.72 0.71 1.02 0.02 96% 96% Get [second] mbox + 0.81 0.65 2.74 0.22 96% 71% Tryput [first] mbox + 0.67 0.62 2.27 0.10 96% 96% Peek item [non-empty] mbox + 0.77 0.71 2.41 0.10 96% 96% Tryget [non-empty] mbox + 0.59 0.58 0.88 0.02 96% 96% Peek item [empty] mbox + 0.62 0.62 0.67 0.00 96% 96% Tryget [empty] mbox + 0.03 0.02 0.32 0.02 96% 96% Waiting to get mbox + 0.02 0.02 0.06 0.01 50% 46% Waiting to put mbox + 0.75 0.65 3.59 0.18 96% 96% Delete mbox + 2.80 2.77 3.59 0.05 96% 96% Put/Get mbox + + 0.37 0.18 0.88 0.28 71% 71% Init semaphore + 0.48 0.47 0.80 0.02 96% 96% Post [0] semaphore + 0.60 0.59 0.67 0.01 50% 46% Wait [1] semaphore + 0.53 0.50 1.41 0.06 96% 96% Trywait [0] semaphore + 0.51 0.50 0.71 0.01 96% 50% Trywait [1] semaphore + 0.09 0.09 0.15 0.00 96% 96% Peek semaphore + 0.12 0.11 0.41 0.02 96% 96% Destroy semaphore + 3.05 3.05 3.05 0.00 100% 100% Post/Wait semaphore + + 0.57 0.17 2.76 0.24 59% 25% Create counter + 0.06 0.05 0.58 0.03 96% 96% Get counter value + 0.06 0.03 0.64 0.04 96% 96% Set counter value + 0.73 0.71 1.02 0.02 96% 96% Tick counter + 0.12 0.11 0.15 0.01 50% 46% Delete counter + + 0.89 0.64 3.15 0.34 84% 71% Create alarm + 1.00 0.95 2.41 0.09 96% 96% Initialize alarm + 0.09 0.06 0.68 0.04 96% 96% Disable alarm + 1.05 1.00 2.48 0.09 96% 96% Enable alarm + 0.18 0.17 0.50 0.02 96% 96% Delete alarm + 0.90 0.89 1.11 0.01 96% 96% Tick counter [1 alarm] + 5.60 5.59 5.88 0.02 96% 96% Tick counter [many alarms] + 1.53 1.52 2.11 0.04 96% 96% Tick & fire counter [1 alarm] + 25.48 25.47 25.76 0.02 96% 96% Tick & fire counters [>1 together] + 6.22 6.21 6.44 0.01 96% 96% Tick & fire counters [>1 separately] + 2.59 2.56 6.17 0.07 98% 98% Alarm latency [0 threads] + 4.06 3.95 6.24 0.08 78% 57% Alarm latency [2 threads] + 5.03 2.56 9.03 0.89 59% 10% Alarm latency [many threads] + 5.68 5.59 15.45 0.15 99% 99% Alarm -> thread resume latency + + 2.52 1.41 8.12 0.00 Clock/interrupt latency + + 2.05 1.17 6.00 0.00 Clock DSR latency + + 34 0 1072 (main stack: 1320) Thread stack used (1912 total) +All done, main stack : stack used 1320 size 2936 +All done : Interrupt stack used 136 size 4096 +All done : Idlethread stack used 996 size 2048 + +Timing complete - 30360 ms total + +PASS:<Basic timing OK> +EXIT:<done> + + </LITERALLAYOUT> +</SECT1> + +<!-- ==================================================== --> + +<SECT1 id="rt-mn10300-stdeval1"> +<TITLE>Board: Matsushita STDEVAL1 Board</TITLE> +<LITERALLAYOUT CLASS="MONOSPACED"> + +Board: Matsushita STDEVAL1 Board + +CPU : MN103002A 60MHz + +eCOS Kernel Timings +Note: all times are in microseconds (.000001) unless otherwise stated + +Reading the hardware clock takes 18 'ticks' overhead +... this value will be factored out of all other measurements +Clock interrupt took 13.73 microseconds (205 raw clock ticks) + +Testing parameters: + Clock samples: 32 + Threads: 24 + Thread switches: 128 + Mutexes: 32 + Mailboxes: 32 + Semaphores: 32 + Scheduler operations: 128 + Counters: 32 + Alarms: 32 + + + Confidence + Ave Min Max Var Ave Min Function + ====== ====== ====== ====== ========== ======== + 14.36 11.53 23.53 1.81 54% 33% Create thread + 2.64 2.53 5.07 0.20 95% 95% Yield thread [all suspended] + 2.25 1.93 4.80 0.31 45% 83% Suspend [suspended] thread + 2.19 2.00 4.93 0.28 91% 91% Resume thread + 3.42 3.00 8.40 0.47 95% 87% Set priority + 0.31 0.13 1.20 0.19 79% 58% Get priority + 8.26 7.40 18.80 0.93 95% 87% Kill [suspended] thread + 2.58 2.47 5.13 0.21 95% 95% Yield [no other] thread + 5.07 4.53 8.67 0.44 62% 50% Resume [suspended low prio] thread + 2.27 2.07 4.53 0.23 87% 87% Resume [runnable low prio] thread + 4.76 4.07 9.40 0.65 66% 75% Suspend [runnable] thread + 2.63 2.53 4.73 0.18 95% 95% Yield [only low prio] thread + 2.09 1.87 4.27 0.27 91% 79% Suspend [runnable->not runnable] + 10.79 10.00 18.20 0.81 95% 79% Kill [runnable] thread + 20.30 18.40 28.80 1.42 79% 54% Resume [high priority] thread + 5.53 5.47 12.13 0.11 98% 97% Thread switch + + 0.28 0.27 2.20 0.03 97% 97% Scheduler lock + 1.14 1.13 2.00 0.01 99% 99% Scheduler unlock [0 threads] + 1.14 1.13 2.40 0.02 99% 99% Scheduler unlock [1 suspended] + 1.16 1.13 3.33 0.06 95% 95% Scheduler unlock [many suspended] + 1.23 1.20 3.13 0.05 95% 95% Scheduler unlock [many low prio] + + 1.29 1.00 4.20 0.25 65% 50% Init mutex + 2.65 2.47 5.27 0.23 93% 87% Lock [unlocked] mutex + 3.26 3.07 6.80 0.28 93% 87% Unlock [locked] mutex + 2.48 2.33 5.07 0.21 90% 87% Trylock [unlocked] mutex + 2.20 2.07 4.67 0.21 93% 87% Trylock [locked] mutex + 0.23 0.20 1.00 0.05 96% 93% Destroy mutex + 25.11 24.73 27.53 0.21 65% 31% Unlock/Lock mutex + + 2.49 2.00 5.73 0.32 81% 37% Create mbox + 0.11 0.00 1.60 0.15 84% 81% Peek [empty] mbox + 3.01 2.60 9.47 0.52 96% 78% Put [first] mbox + 0.10 0.00 1.67 0.15 87% 81% Peek [1 msg] mbox + 3.09 2.60 8.33 0.50 93% 75% Put [second] mbox + 0.06 0.00 1.13 0.08 96% 87% Peek [2 msgs] mbox + 3.10 2.80 7.93 0.40 93% 84% Get [first] mbox + 3.13 2.80 7.53 0.43 90% 78% Get [second] mbox + 2.99 2.60 8.53 0.52 93% 75% Tryput [first] mbox + 2.65 2.33 6.80 0.42 90% 78% Peek item [non-empty] mbox + 3.05 2.73 7.60 0.42 93% 78% Tryget [non-empty] mbox + 3.16 2.93 6.27 0.31 84% 84% Peek item [empty] mbox + 2.48 2.27 5.73 0.30 84% 84% Tryget [empty] mbox + 0.23 0.13 2.07 0.14 96% 87% Waiting to get mbox + 0.22 0.13 1.93 0.13 96% 75% Waiting to put mbox + 3.08 2.80 7.93 0.42 84% 84% Delete mbox + 16.01 15.53 19.00 0.52 78% 59% Put/Get mbox + + 0.85 0.67 3.27 0.19 96% 50% Init semaphore + 2.00 1.93 3.87 0.12 96% 90% Post [0] semaphore + 2.05 2.00 3.47 0.09 96% 96% Wait [1] semaphore + 1.85 1.80 3.47 0.10 96% 96% Trywait [0] semaphore + 1.82 1.80 2.53 0.04 96% 96% Trywait [1] semaphore + 0.36 0.33 1.33 0.06 96% 96% Peek semaphore + 0.38 0.33 1.87 0.09 96% 96% Destroy semaphore + 12.38 12.20 16.27 0.30 93% 87% Post/Wait semaphore + + 1.18 0.73 4.07 0.24 78% 18% Create counter + 0.20 0.13 1.40 0.11 87% 87% Get counter value + 0.24 0.20 1.40 0.08 93% 93% Set counter value + 3.17 3.13 4.20 0.07 93% 93% Tick counter + 0.44 0.40 1.73 0.08 96% 96% Delete counter + + 2.24 1.67 5.13 0.47 68% 65% Create alarm + 3.86 3.40 9.67 0.51 90% 78% Initialize alarm + 0.15 0.07 1.60 0.12 96% 68% Disable alarm + 3.76 3.47 7.67 0.35 93% 75% Enable alarm + 0.57 0.47 2.73 0.16 96% 84% Delete alarm + 3.64 3.60 4.73 0.07 96% 96% Tick counter [1 alarm] + 21.72 21.67 23.27 0.10 96% 96% Tick counter [many alarms] + 6.13 6.07 8.07 0.12 96% 96% Tick & fire counter [1 alarm] + 101.40 99.53 132.73 2.75 93% 93% Tick & fire counters [>1 together] + 24.21 24.13 26.40 0.14 96% 96% Tick & fire counters [>1 separately] + 11.74 11.60 22.67 0.26 98% 98% Alarm latency [0 threads] + 14.58 11.73 24.93 1.59 54% 28% Alarm latency [2 threads] + 18.18 15.20 41.07 1.96 60% 43% Alarm latency [many threads] + + 3.06 2.13 10.33 0.00 Clock/interrupt latency + +Timing complete - 23480 ms total + +PASS:<Basic timing OK> +EXIT:<done> + + </LITERALLAYOUT> +</SECT1> + +<!-- ==================================================== --> + +<SECT1 id="rt-sparclite-sleb"> +<TITLE>Board: Fujitsu SPARClite Evaluation Board</TITLE> +<LITERALLAYOUT CLASS="MONOSPACED"> + +Board: Fujitsu SPARClite Evaluation Board + +CPU : Fujitsu SPARClite MB8683X 100MHz + + +eCOS Kernel Timings +Note: all times are in microseconds (.000001) unless otherwise stated + +Reading the hardware clock takes 0 'ticks' overhead +... this value will be factored out of all other measurements +Clock interrupt took 17.19 microseconds (17 raw clock ticks) + +Testing parameters: + Clock samples: 32 + Threads: 24 + Thread switches: 128 + Mutexes: 32 + Mailboxes: 32 + Semaphores: 32 + Scheduler operations: 128 + Counters: 32 + Alarms: 32 + + + Confidence + Ave Min Max Var Ave Min Function + ====== ====== ====== ====== ========== ======== + 48.59 47.00 63.01 1.41 66% 70% Create thread + 2.13 2.00 5.00 0.24 95% 95% Yield thread [all suspended] + 2.92 2.00 10.00 0.69 58% 37% Suspend [suspended] thread + 2.13 1.00 10.00 0.66 75% 20% Resume thread + 2.79 2.00 11.00 0.86 95% 54% Set priority + 1.00 0.00 5.00 0.33 79% 16% Get priority + 7.17 5.00 34.00 2.24 95% 95% Kill [suspended] thread + 2.42 2.00 12.00 0.80 95% 95% Yield [no other] thread + 3.46 2.00 14.00 1.10 75% 83% Resume [suspended low prio] thread + 2.00 1.00 9.00 0.58 66% 29% Resume [runnable low prio] thread + 4.21 3.00 20.00 1.38 95% 91% Suspend [runnable] thread + 2.33 2.00 10.00 0.64 95% 95% Yield [only low prio] thread + 2.00 1.00 9.00 0.67 58% 33% Suspend [runnable->not runnable] + 5.79 4.00 30.00 2.07 95% 95% Kill [runnable] thread + 39.34 37.00 75.01 3.36 91% 91% Resume [high priority] thread + 15.20 15.00 31.00 0.40 97% 97% Thread switch + + 1.04 1.00 4.00 0.08 97% 97% Scheduler lock + 1.42 1.00 5.00 0.51 60% 60% Scheduler unlock [0 threads] + 1.41 1.00 5.00 0.50 61% 61% Scheduler unlock [1 suspended] + 1.41 1.00 5.00 0.50 60% 60% Scheduler unlock [many suspended] + 1.40 1.00 5.00 0.50 62% 62% Scheduler unlock [many low prio] + + 1.19 1.00 6.00 0.35 93% 93% Init mutex + 2.34 2.00 12.00 0.64 93% 93% Lock [unlocked] mutex + 3.41 3.00 13.00 0.71 96% 87% Unlock [locked] mutex + 2.16 1.00 10.00 0.49 87% 9% Trylock [unlocked] mutex + 1.78 1.00 7.00 0.59 59% 37% Trylock [locked] mutex + 0.72 0.00 2.00 0.45 65% 31% Destroy mutex + 25.25 24.00 41.00 0.98 71% 25% Unlock/Lock mutex + + 1.44 1.00 9.00 0.68 96% 78% Create mbox + 0.94 0.00 3.00 0.23 84% 12% Peek [empty] mbox + 3.06 2.00 13.00 0.62 71% 25% Put [first] mbox + 0.69 0.00 3.00 0.52 59% 37% Peek [1 msg] mbox + 2.44 2.00 10.00 0.68 96% 78% Put [second] mbox + 0.78 0.00 3.00 0.44 68% 28% Peek [2 msgs] mbox + 3.78 3.00 14.00 0.83 96% 53% Get [first] mbox + 2.97 2.00 9.00 0.61 56% 31% Get [second] mbox + 2.53 2.00 12.00 0.80 96% 75% Tryput [first] mbox + 2.72 2.00 12.00 0.81 96% 56% Peek item [non-empty] mbox + 2.63 2.00 13.00 0.94 90% 75% Tryget [non-empty] mbox + 1.97 1.00 6.00 0.42 68% 21% Peek item [empty] mbox + 2.09 1.00 9.00 0.49 78% 15% Tryget [empty] mbox + 0.84 0.00 4.00 0.42 71% 25% Waiting to get mbox + 0.81 0.00 4.00 0.46 68% 28% Waiting to put mbox + 2.38 2.00 11.00 0.66 96% 87% Delete mbox + 23.41 22.00 47.00 1.47 96% 96% Put/Get mbox + + 1.03 0.00 6.00 0.31 84% 12% Init semaphore + 2.66 2.00 8.00 0.66 96% 50% Post [0] semaphore + 1.97 1.00 10.00 0.55 68% 28% Wait [1] semaphore + 1.78 1.00 8.00 0.63 56% 40% Trywait [0] semaphore + 1.84 1.00 8.00 0.58 62% 34% Trywait [1] semaphore + 1.00 0.00 5.00 0.25 84% 12% Peek semaphore + 0.81 0.00 4.00 0.46 68% 28% Destroy semaphore + 19.03 18.00 41.00 1.37 96% 96% Post/Wait semaphore + + 1.38 1.00 6.00 0.56 75% 75% Create counter + 1.09 1.00 3.00 0.18 93% 93% Get counter value + 1.00 0.00 5.00 0.31 78% 15% Set counter value + 3.09 2.00 6.00 0.35 78% 9% Tick counter + 0.91 0.00 5.00 0.40 75% 21% Delete counter + + 2.53 2.00 9.00 0.70 96% 65% Create alarm + 6.03 5.00 22.00 1.00 50% 46% Initialize alarm + 0.78 0.00 4.00 0.49 65% 31% Disable alarm + 2.91 2.00 13.00 0.91 87% 50% Enable alarm + 0.97 0.00 5.00 0.30 81% 15% Delete alarm + 2.69 2.00 9.00 0.69 96% 50% Tick counter [1 alarm] + 12.00 11.00 23.00 0.69 62% 34% Tick counter [many alarms] + 4.16 3.00 13.00 0.55 84% 12% Tick & fire counter [1 alarm] + 72.69 72.01 87.01 1.03 96% 96% Tick & fire counters [>1 together] + 13.66 13.00 23.00 0.82 96% 62% Tick & fire counters [>1 separately] + 13.26 13.00 42.00 0.51 98% 98% Alarm latency [0 threads] + 16.75 11.00 53.01 2.78 64% 16% Alarm latency [2 threads] + 24.06 18.00 58.01 3.55 67% 25% Alarm latency [many threads] + + 3.61 2.00 13.00 0.00 Clock/interrupt latency + +Timing complete - 23590 ms total + +PASS:<Basic timing OK> +EXIT:<done> + + </LITERALLAYOUT> +</SECT1> + +<!-- ==================================================== --> + +<SECT1 id="rt-ppc-cogent"> +<TITLE>Board: Cogent CMA MPC860 (PowerPC) Evaluation </TITLE> +<LITERALLAYOUT CLASS="MONOSPACED">Board: Cogent CMA MPC860 (PowerPC) Evaluation +CPU : MPC860, revision A3 33MHz + + +eCOS Kernel Timings +Note: all times are in microseconds (.000001) unless otherwise stated + +Reading the hardware clock takes 0 'ticks' overhead +... this value will be factored out of all other measurements +Clock interrupt took 14.46 microseconds (30 raw clock ticks) + +Testing parameters: + Clock samples: 32 + Threads: 24 + Thread switches: 128 + Mutexes: 32 + Mailboxes: 32 + Semaphores: 32 + Scheduler operations: 128 + Counters: 32 + Alarms: 32 + + + + + + Confidence + Ave Min Max Var Ave Min Function + ====== ====== ====== ====== ========== ======== + 26.78 23.52 41.76 1.97 66% 37% Create thread + 4.00 3.84 4.80 0.23 70% 70% Yield thread [all suspended] + 3.78 3.36 7.68 0.38 50% 45% Suspend [suspended] thread + 3.56 3.36 7.68 0.37 95% 91% Resume thread + 5.28 4.32 12.96 0.76 83% 66% Set priority + 0.84 0.48 3.84 0.39 91% 54% Get priority + 11.76 10.08 32.16 1.70 95% 95% Kill [suspended] thread + 4.14 3.84 8.64 0.45 95% 75% Yield [no other] thread + 7.14 5.76 17.76 1.07 79% 70% Resume [suspended low prio] thread + 3.60 3.36 8.16 0.42 95% 87% Resume [runnable low prio] thread + 6.10 5.28 14.88 0.80 62% 70% Suspend [runnable] thread + 4.00 3.84 5.76 0.25 79% 79% Yield [only low prio] thread + 3.66 3.36 8.64 0.47 95% 79% Suspend [runnable->not runnable] + 11.66 10.08 30.24 1.58 79% 91% Kill [runnable] thread + 31.12 27.84 53.28 2.35 87% 50% Resume [high priority] thread + 7.52 7.20 15.84 0.30 50% 48% Thread switch + + 1.00 0.48 2.88 0.21 63% 14% Scheduler lock + 2.57 2.40 3.84 0.23 65% 65% Scheduler unlock [0 threads] + 2.58 2.40 4.32 0.23 64% 64% Scheduler unlock [1 suspended] + 2.59 2.40 4.32 0.24 62% 62% Scheduler unlock [many suspended] + 2.59 2.40 4.32 0.24 61% 61% Scheduler unlock [many low prio] + + 1.69 1.44 5.76 0.37 96% 71% Init mutex + 4.15 3.84 10.56 0.47 96% 75% Lock [unlocked] mutex + 5.82 5.28 10.56 0.38 62% 28% Unlock [locked] mutex + 3.70 3.36 8.64 0.41 96% 59% Trylock [unlocked] mutex + 3.42 2.88 6.72 0.26 75% 15% Trylock [locked] mutex + 0.36 0.00 1.92 0.25 62% 34% Destroy mutex + 43.41 42.72 45.12 0.34 81% 3% Unlock/Lock mutex + + 3.27 2.88 8.16 0.39 96% 50% Create mbox + 0.57 0.00 2.40 0.34 50% 21% Peek [empty] mbox + 6.16 5.76 11.04 0.48 87% 87% Put [first] mbox + 0.48 0.00 1.92 0.27 50% 28% Peek [1 msg] mbox + 5.92 5.28 10.56 0.35 90% 6% Put [second] mbox + 0.60 0.00 2.40 0.30 62% 12% Peek [2 msgs] mbox + 4.69 4.32 12.00 0.54 93% 93% Get [first] mbox + 4.68 4.32 11.52 0.52 93% 93% Get [second] mbox + 5.86 5.28 11.04 0.47 62% 31% Tryput [first] mbox + 4.00 3.36 9.12 0.38 87% 9% Peek item [non-empty] mbox + 4.59 3.84 12.48 0.61 71% 75% Tryget [non-empty] mbox + 3.75 3.36 7.68 0.34 53% 43% Peek item [empty] mbox + 3.93 3.36 9.60 0.45 65% 31% Tryget [empty] mbox + 0.63 0.00 2.40 0.28 68% 6% Waiting to get mbox + 0.54 0.00 1.92 0.19 75% 9% Waiting to put mbox + 4.84 4.32 12.00 0.47 56% 40% Delete mbox + 24.18 23.52 29.76 0.66 81% 75% Put/Get mbox + + 1.72 0.96 3.84 0.33 90% 6% Init semaphore + 3.15 2.88 6.24 0.34 96% 62% Post [0] semaphore + 3.85 3.36 8.64 0.30 68% 28% Wait [1] semaphore + 3.24 2.88 6.24 0.34 46% 46% Trywait [0] semaphore + 3.22 2.88 6.24 0.32 50% 46% Trywait [1] semaphore + 0.96 0.48 2.88 0.12 84% 12% Peek semaphore + 0.99 0.96 1.92 0.06 96% 96% Destroy semaphore + 24.71 24.00 28.80 0.40 87% 6% Post/Wait semaphore + + 2.31 1.44 6.24 0.77 46% 56% Create counter + 0.45 0.00 0.96 0.08 87% 9% Get counter value + 0.42 0.00 0.96 0.16 75% 18% Set counter value + 4.14 3.84 4.80 0.26 50% 43% Tick counter + 0.91 0.48 2.40 0.19 71% 21% Delete counter + + 5.23 4.32 7.68 0.61 65% 53% Create alarm + 5.58 4.80 12.96 0.72 68% 84% Initialize alarm + 0.75 0.48 1.92 0.30 90% 56% Disable alarm + 8.02 7.20 14.40 0.53 84% 68% Enable alarm + 1.32 0.96 3.84 0.29 56% 40% Delete alarm + 4.63 4.32 6.24 0.28 53% 43% Tick counter [1 alarm] + 23.67 23.52 25.44 0.23 78% 78% Tick counter [many alarms] + 7.24 6.72 10.56 0.21 84% 12% Tick & fire counter [1 alarm] + 106.83 106.56 110.40 0.35 96% 65% Tick & fire counters [>1 together] + 26.18 25.44 29.76 0.46 81% 9% Tick & fire counters [>1 separately] + 10.79 10.08 29.28 0.66 53% 55% Alarm latency [0 threads] + 17.20 13.92 35.52 1.48 67% 21% Alarm latency [2 threads] + 29.69 22.56 47.04 3.58 57% 17% Alarm latency [many threads] + + 7.66 3.84 19.20 0.00 Clock/interrupt latency + +Timing complete - 23530 ms total + +PASS:<Basic timing OK> +EXIT:<done> + + </LITERALLAYOUT> +</SECT1> + +<!-- ==================================================== --> + +<SECT1 id="rt-vr4300-vrc4373"> +<TITLE>Board: NEC VR4373</TITLE> +<LITERALLAYOUT CLASS="MONOSPACED"> + +Board: NEC VR4373 + +CPU : NEC VR4300 133MHz + + +Startup, main stack : stack used 1304 size 3576 +Startup : Interrupt stack used 980 size 4096 +Startup : Idlethread stack used 494 size 2552 + +eCos Kernel Timings +Notes: all times are in microseconds (.000001) unless otherwise stated + +Reading the hardware clock takes 3 `ticks' overhead +... this value will be factored out of all other measurements +Clock interrupt took 6.49 microseconds (431 raw clock ticks) + +Testing parameters: + Clock samples: 32 + Threads: 16 + Thread switches: 128 + Mutexes: 32 + Mailboxes: 32 + Semaphores: 32 + Scheduler operations: 128 + Counters: 32 + Alarms: 32 + + + Confidence + Ave Min Max Var Ave Min Function + ====== ====== ====== ====== ========== ======== + 17.21 16.18 22.14 0.88 75% 68% Create thread + 0.84 0.78 1.29 0.10 81% 81% Yield thread [all suspended] + 0.90 0.62 3.20 0.35 87% 87% Suspend [suspended] thread + 0.74 0.65 1.16 0.12 81% 68% Resume thread + 1.11 0.90 1.70 0.25 75% 68% Set priority + 0.11 0.05 0.35 0.09 75% 75% Get priority + 2.93 2.24 8.27 0.78 93% 75% Kill [suspended] thread + 0.88 0.78 1.92 0.16 93% 81% Yield [no other] thread + 1.82 1.20 4.71 0.62 87% 62% Resume [suspended low prio] thread + 0.70 0.63 0.86 0.09 68% 68% Resume [runnable low prio] thread + 1.21 1.07 1.61 0.13 81% 68% Suspend [runnable] thread + 0.86 0.78 1.58 0.13 81% 81% Yield [only low prio] thread + 0.69 0.62 0.84 0.09 68% 68% Suspend [runnable->not runnable] + 2.64 2.24 4.35 0.43 81% 62% Kill [runnable] thread + 1.50 1.07 5.82 0.56 93% 87% Destroy [dead] thread + 3.66 2.75 7.74 0.82 50% 56% Destroy [runnable] thread + 13.65 8.33 27.88 3.70 50% 43% Resume [high priority] thread + 2.04 1.89 3.32 0.15 46% 49% Thread switch + + 0.19 0.05 0.83 0.13 48% 44% Scheduler lock + 0.50 0.41 1.59 0.13 89% 73% Scheduler unlock [0 threads] + 0.52 0.41 1.29 0.14 89% 64% Scheduler unlock [1 suspended] + 0.56 0.41 1.49 0.15 42% 47% Scheduler unlock [many suspended] + 0.56 0.41 1.41 0.15 43% 47% Scheduler unlock [many low prio] + + 0.57 0.20 2.33 0.27 65% 50% Init mutex + 0.89 0.75 3.35 0.20 96% 75% Lock [unlocked] mutex + 0.90 0.74 4.38 0.25 96% 93% Unlock [locked] mutex + 0.77 0.65 2.63 0.17 96% 75% Trylock [unlocked] mutex + 0.66 0.59 1.16 0.10 75% 75% Trylock [locked] mutex + 0.07 0.00 0.45 0.09 75% 75% Destroy mutex + 7.95 7.71 9.49 0.19 50% 46% Unlock/Lock mutex + + 1.04 0.81 3.44 0.27 93% 68% Create mbox + 0.10 0.02 0.57 0.11 71% 68% Peek [empty] mbox + 1.15 0.83 4.71 0.31 53% 71% Put [first] mbox + 0.10 0.02 0.57 0.12 68% 68% Peek [1 msg] mbox + 1.01 0.83 3.83 0.22 93% 75% Put [second] mbox + 0.09 0.02 0.57 0.10 71% 71% Peek [2 msgs] mbox + 1.03 0.81 5.02 0.27 96% 87% Get [first] mbox + 0.93 0.81 1.61 0.14 84% 62% Get [second] mbox + 1.07 0.77 4.18 0.23 68% 50% Tryput [first] mbox + 0.89 0.72 3.49 0.21 93% 71% Peek item [non-empty] mbox + 1.04 0.83 4.09 0.26 90% 81% Tryget [non-empty] mbox + 0.79 0.68 1.97 0.15 87% 68% Peek item [empty] mbox + 0.84 0.72 2.36 0.17 93% 68% Tryget [empty] mbox + 0.13 0.02 0.59 0.13 87% 62% Waiting to get mbox + 0.13 0.02 0.90 0.13 90% 62% Waiting to put mbox + 0.93 0.77 3.23 0.21 90% 71% Delete mbox + 4.74 4.51 8.80 0.32 93% 78% Put/Get mbox + + 0.50 0.21 1.95 0.29 90% 50% Init semaphore + 0.86 0.57 2.87 0.29 93% 56% Post [0] semaphore + 1.01 0.74 3.62 0.28 93% 56% Wait [1] semaphore + 0.87 0.60 3.17 0.28 90% 59% Trywait [0] semaphore + 0.74 0.62 1.70 0.14 93% 56% Trywait [1] semaphore + 0.36 0.11 1.11 0.26 65% 56% Peek semaphore + 0.25 0.12 1.19 0.14 93% 56% Destroy semaphore + 7.85 7.52 8.93 0.21 62% 43% Post/Wait semaphore + + 0.90 0.44 3.08 0.29 65% 28% Create counter + 0.07 0.05 0.89 0.05 96% 96% Get counter value + 0.06 0.05 0.33 0.02 96% 96% Set counter value + 0.88 0.86 1.62 0.05 96% 96% Tick counter + 0.13 0.12 0.41 0.02 96% 96% Delete counter + + 1.37 0.81 2.95 0.27 62% 25% Create alarm + 1.35 1.17 6.03 0.31 96% 93% Initialize alarm + 0.11 0.08 0.65 0.05 90% 90% Disable alarm + 1.23 1.14 3.05 0.15 93% 87% Enable alarm + 0.21 0.18 0.47 0.04 90% 90% Delete alarm + 1.03 0.99 2.11 0.07 96% 96% Tick counter [1 alarm] + 4.96 4.96 4.96 0.00 100% 100% Tick counter [many alarms] + 1.70 1.67 2.51 0.05 96% 96% Tick & fire counter [1 alarm] + 26.39 26.38 26.71 0.02 96% 96% Tick & fire counters [>1 together] + 5.65 5.64 5.91 0.02 96% 96% Tick & fire counters [>1 separately] + 2.55 2.38 9.86 0.19 96% 54% Alarm latency [0 threads] + 5.37 3.80 9.73 0.95 50% 34% Alarm latency [2 threads] + 8.79 5.83 16.12 1.29 57% 14% Alarm latency [many threads] + + 5.85 2.26 16.24 0.00 Clock/interrupt latency + + 1540 1536 1544 (main stack: 1664) Thread stack used (2552 total) +All done, main stack : stack used 1664 size 3576 +All done : Interrupt stack used 312 size 4096 +All done : Idlethread stack used 1440 size 2552 + +Timing complete - 23810 ms total + +PASS:<Basic timing OK> +EXIT:<done> + </LITERALLAYOUT> +</SECT1> + +<!-- ==================================================== --> + +<SECT1 id="rt-arm-assabet"> +<TITLE>Board: Intel SA1110 (Assabet)</TITLE> +<LITERALLAYOUT CLASS="MONOSPACED">Board: Intel SA1110 (Assabet) + +CPU : StrongARM 221.2 MHz + + + +Microseconds for one run through Dhrystone: 3.3 +Dhrystones per Second: 306748.5 +VAX MIPS rating = 174.586 + +Startup, main stack : stack used 420 size 2400 +Startup : Interrupt stack used 136 size 4096 +Startup : Idlethread stack used 84 size 2048 + +eCos Kernel Timings +Notes: all times are in microseconds (.000001) unless otherwise stated + +Reading the hardware clock takes 0 `ticks' overhead +... this value will be factored out of all other measurements +Clock interrupt took 3.20 microseconds (11 raw clock ticks) + +Testing parameters: + Clock samples: 32 + Threads: 64 + Thread switches: 128 + Mutexes: 32 + Mailboxes: 32 + Semaphores: 32 + Scheduler operations: 128 + Counters: 32 + Alarms: 32 + + + Confidence + Ave Min Max Var Ave Min Function + ====== ====== ====== ====== ========== ======== + 5.98 4.88 14.38 0.70 57% 35% Create thread + 0.86 0.81 1.90 0.08 87% 87% Yield thread [all suspended] + 1.05 0.81 3.53 0.19 46% 39% Suspend [suspended] thread + 1.07 0.81 3.80 0.18 48% 35% Resume thread + 1.36 1.09 5.97 0.22 45% 39% Set priority + 0.73 0.54 1.90 0.19 85% 50% Get priority + 2.93 2.44 13.56 0.39 79% 70% Kill [suspended] thread + 0.89 0.81 4.34 0.14 89% 89% Yield [no other] thread + 1.63 1.36 4.61 0.17 57% 29% Resume [suspended low prio] thread + 1.03 0.81 3.53 0.19 46% 42% Resume [runnable low prio] thread + 1.74 1.36 6.51 0.22 87% 6% Suspend [runnable] thread + 0.93 0.81 4.61 0.18 98% 78% Yield [only low prio] thread + 1.06 0.81 3.26 0.19 42% 39% Suspend [runnable->not runnable] + 2.56 1.90 13.02 0.41 87% 34% Kill [runnable] thread + 2.02 1.63 7.05 0.22 92% 3% Destroy [dead] thread + 3.09 2.44 15.19 0.51 78% 46% Destroy [runnable] thread + 6.77 5.43 13.02 0.59 75% 17% Resume [high priority] thread + 1.81 1.63 7.87 0.18 49% 49% Thread switch + + 0.25 0.00 1.36 0.05 89% 10% Scheduler lock + 0.51 0.27 1.36 0.06 85% 13% Scheduler unlock [0 threads] + 0.51 0.27 1.09 0.06 85% 13% Scheduler unlock [1 suspended] + 0.51 0.27 1.09 0.07 85% 14% Scheduler unlock [many suspended] + 0.51 0.27 1.09 0.06 85% 13% Scheduler unlock [many low prio] + + 0.52 0.27 2.17 0.15 62% 31% Init mutex + 0.97 0.54 4.34 0.28 84% 65% Lock [unlocked] mutex + 1.05 0.81 5.15 0.28 96% 96% Unlock [locked] mutex + 0.86 0.54 3.26 0.24 65% 31% Trylock [unlocked] mutex + 0.79 0.54 3.53 0.23 43% 46% Trylock [locked] mutex + 0.33 0.27 1.63 0.11 90% 90% Destroy mutex + 4.16 3.80 8.95 0.30 75% 96% Unlock/Lock mutex + + 0.70 0.54 2.98 0.21 96% 65% Create mbox + 0.59 0.27 1.63 0.14 75% 9% Peek [empty] mbox + 1.33 1.09 5.70 0.31 96% 93% Put [first] mbox + 0.61 0.27 1.63 0.13 81% 3% Peek [1 msg] mbox + 1.35 1.09 5.43 0.31 96% 87% Put [second] mbox + 0.58 0.27 1.36 0.11 78% 6% Peek [2 msgs] mbox + 1.38 1.09 4.88 0.25 59% 37% Get [first] mbox + 1.40 1.09 5.15 0.26 62% 34% Get [second] mbox + 1.27 0.81 4.88 0.28 90% 65% Tryput [first] mbox + 1.34 0.81 4.61 0.22 59% 6% Peek item [non-empty] mbox + 1.47 1.09 5.15 0.27 84% 12% Tryget [non-empty] mbox + 1.12 0.81 4.34 0.23 59% 31% Peek item [empty] mbox + 1.14 0.81 4.07 0.24 71% 25% Tryget [empty] mbox + 0.59 0.27 1.36 0.12 78% 6% Waiting to get mbox + 0.59 0.27 1.36 0.12 78% 6% Waiting to put mbox + 1.28 0.81 5.43 0.32 87% 78% Delete mbox + 2.64 2.17 10.31 0.48 96% 96% Put/Get mbox + + 0.47 0.27 2.17 0.19 46% 46% Init semaphore + 0.77 0.54 3.80 0.26 90% 56% Post [0] semaphore + 0.90 0.54 4.07 0.26 75% 21% Wait [1] semaphore + 0.85 0.54 3.26 0.21 56% 28% Trywait [0] semaphore + 0.69 0.54 2.17 0.18 96% 62% Trywait [1] semaphore + 0.44 0.27 2.17 0.19 96% 56% Peek semaphore + 0.38 0.27 1.90 0.17 96% 75% Destroy semaphore + 2.74 2.44 9.49 0.42 96% 96% Post/Wait semaphore + + 0.43 0.27 1.90 0.18 96% 56% Create counter + 0.49 0.00 2.17 0.18 56% 3% Get counter value + 0.33 0.00 1.63 0.13 78% 6% Set counter value + 1.03 0.81 2.44 0.22 84% 50% Tick counter + 0.42 0.27 1.90 0.20 90% 65% Delete counter + + 0.70 0.54 2.44 0.20 93% 62% Create alarm + 1.65 1.36 6.78 0.40 96% 81% Initialize alarm + 0.75 0.54 1.63 0.18 43% 43% Disable alarm + 1.75 1.36 7.05 0.38 65% 81% Enable alarm + 0.81 0.54 2.44 0.15 62% 28% Delete alarm + 1.01 0.81 2.17 0.16 56% 40% Tick counter [1 alarm] + 4.19 4.07 5.43 0.16 96% 68% Tick counter [many alarms] + 1.48 1.36 3.80 0.20 96% 78% Tick & fire counter [1 alarm] + 20.23 20.07 22.52 0.21 96% 65% Tick & fire counters [>1 together] + 4.70 4.61 6.78 0.16 87% 87% Tick & fire counters [>1 separately] + 2.81 2.71 14.38 0.20 98% 98% Alarm latency [0 threads] + 3.19 2.71 13.56 0.38 73% 59% Alarm latency [2 threads] + 9.71 7.87 18.17 1.25 59% 53% Alarm latency [many threads] + 5.77 5.43 45.57 0.68 97% 97% Alarm -> thread resume latency + + 2.38 0.81 9.49 0.00 Clock/interrupt latency + + 2.02 1.09 7.32 0.00 Clock DSR latency + + 11 0 316 (main stack: 764) Thread stack used (1120 total) +All done, main stack : stack used 764 size 2400 +All done : Interrupt stack used 287 size 4096 +All done : Idlethread stack used 272 size 2048 + +Timing complete - 30220 ms total + </LITERALLAYOUT> +</SECT1> + +<!-- ==================================================== --> + +<SECT1 id="rt-arm-brutus"> +<TITLE>Board: Intel SA1100 (Brutus)</TITLE> +<LITERALLAYOUT CLASS="MONOSPACED">Board: Intel SA1100 (Brutus) + +CPU : StrongARM 221.2 MHz + +Microseconds for one run through Dhrystone: 3.3 +Dhrystones per Second: 306748.5 +VAX MIPS rating = 174.586 + +Startup, main stack : stack used 404 size 2400 +Startup : Interrupt stack used 136 size 4096 +Startup : Idlethread stack used 87 size 2048 + +eCos Kernel Timings +Notes: all times are in microseconds (.000001) unless otherwise stated + +Reading the hardware clock takes 0 `ticks' overhead +... this value will be factored out of all other measurements +Clock interrupt took 3.09 microseconds (11 raw clock ticks) + +Testing parameters: + Clock samples: 32 + Threads: 64 + Thread switches: 128 + Mutexes: 32 + Mailboxes: 32 + Semaphores: 32 + Scheduler operations: 128 + Counters: 32 + Alarms: 32 + + + Confidence + Ave Min Max Var Ave Min Function + ====== ====== ====== ====== ========== ======== + 6.63 5.43 18.99 0.77 70% 37% Create thread + 0.83 0.81 2.17 0.04 98% 98% Yield thread [all suspended] + 1.27 0.81 5.15 0.30 68% 73% Suspend [suspended] thread + 1.25 0.81 5.15 0.25 82% 1% Resume thread + 1.52 1.09 7.87 0.30 78% 75% Set priority + 0.97 0.54 2.71 0.28 64% 51% Get priority + 3.45 2.71 19.53 0.66 84% 76% Kill [suspended] thread + 0.90 0.81 6.24 0.17 98% 98% Yield [no other] thread + 1.86 1.36 6.24 0.33 68% 50% Resume [suspended low prio] thread + 1.25 0.81 5.15 0.25 82% 1% Resume [runnable low prio] thread + 2.01 1.63 10.04 0.32 70% 84% Suspend [runnable] thread + 0.90 0.81 6.24 0.17 98% 98% Yield [only low prio] thread + 1.25 0.81 5.15 0.24 84% 1% Suspend [runnable->not runnable] + 2.92 1.90 18.72 0.57 85% 43% Kill [runnable] thread + 2.45 1.90 10.31 0.33 95% 54% Destroy [dead] thread + 3.95 2.71 23.60 0.89 68% 54% Destroy [runnable] thread + 8.55 6.24 19.53 1.15 60% 23% Resume [high priority] thread + 1.85 1.63 11.94 0.21 49% 49% Thread switch + + 0.25 0.00 1.63 0.05 89% 10% Scheduler lock + 0.52 0.27 1.90 0.07 85% 13% Scheduler unlock [0 threads] + 0.51 0.27 1.36 0.06 85% 13% Scheduler unlock [1 suspended] + 0.51 0.27 1.36 0.06 85% 13% Scheduler unlock [many suspended] + 0.51 0.27 1.63 0.06 85% 13% Scheduler unlock [many low prio] + + 0.58 0.27 3.53 0.20 71% 21% Init mutex + 1.07 0.54 5.70 0.35 87% 59% Lock [unlocked] mutex + 1.14 0.81 6.51 0.40 96% 81% Unlock [locked] mutex + 0.96 0.54 5.15 0.34 68% 65% Trylock [unlocked] mutex + 0.94 0.54 4.88 0.34 65% 65% Trylock [locked] mutex + 0.33 0.27 2.17 0.11 96% 96% Destroy mutex + 4.21 3.80 10.85 0.41 71% 96% Unlock/Lock mutex + 0.76 0.54 4.07 0.25 96% 56% Create mbox + 0.75 0.54 1.90 0.20 84% 50% Peek [empty] mbox + 1.56 1.09 6.78 0.39 68% 59% Put [first] mbox + 0.75 0.54 1.90 0.20 84% 50% Peek [1 msg] mbox + 1.55 1.09 6.78 0.40 68% 62% Put [second] mbox + 0.77 0.54 1.63 0.17 46% 37% Peek [2 msgs] mbox + 1.67 1.09 6.24 0.31 87% 34% Get [first] mbox + 1.63 1.09 6.24 0.31 75% 34% Get [second] mbox + 1.50 1.09 6.51 0.40 56% 62% Tryput [first] mbox + 1.58 1.09 5.43 0.37 68% 53% Peek item [non-empty] mbox + 1.79 1.09 7.05 0.43 71% 25% Tryget [non-empty] mbox + 1.29 1.09 5.15 0.32 87% 87% Peek item [empty] mbox + 1.33 1.09 5.97 0.37 96% 84% Tryget [empty] mbox + 0.73 0.54 1.90 0.21 84% 56% Waiting to get mbox + 0.76 0.54 1.90 0.19 40% 43% Waiting to put mbox + 1.47 1.09 6.78 0.39 59% 84% Delete mbox + 2.70 2.17 12.75 0.63 96% 96% Put/Get mbox + + 0.47 0.27 2.71 0.20 96% 50% Init semaphore + 0.89 0.54 4.88 0.33 56% 75% Post [0] semaphore + 0.96 0.54 5.15 0.33 71% 75% Wait [1] semaphore + 0.86 0.54 4.88 0.32 96% 81% Trywait [0] semaphore + 0.69 0.54 3.26 0.22 96% 75% Trywait [1] semaphore + 0.49 0.27 3.26 0.28 84% 84% Peek semaphore + 0.39 0.27 2.44 0.19 96% 78% Destroy semaphore + 2.83 2.44 11.66 0.55 96% 96% Post/Wait semaphore + + 0.52 0.27 3.26 0.20 56% 40% Create counter + 0.59 0.00 2.71 0.34 81% 46% Get counter value + 0.36 0.00 2.44 0.21 81% 9% Set counter value + 1.13 0.81 2.98 0.26 59% 37% Tick counter + 0.39 0.27 1.90 0.19 90% 78% Delete counter + + 0.86 0.54 4.07 0.24 65% 31% Create alarm + 1.86 1.36 9.77 0.54 96% 90% Initialize alarm + 0.77 0.54 2.71 0.23 84% 50% Disable alarm + 1.86 1.36 9.22 0.51 96% 75% Enable alarm + 0.89 0.54 3.26 0.25 65% 21% Delete alarm + 0.99 0.81 3.26 0.21 96% 59% Tick counter [1 alarm] + 4.22 4.07 6.78 0.22 96% 71% Tick counter [many alarms] + 1.51 1.36 4.61 0.24 96% 78% Tick & fire counter [1 alarm] + 20.29 20.07 23.33 0.23 96% 53% Tick & fire counters [>1 together] + 4.71 4.61 7.87 0.20 96% 96% Tick & fire counters [>1 separately] + 2.88 2.71 23.87 0.33 99% 99% Alarm latency [0 threads] + 3.24 2.71 17.36 0.40 79% 58% Alarm latency [2 threads] + 15.71 12.48 27.40 1.47 53% 17% Alarm latency [many threads] + 5.95 5.43 64.56 1.02 97% 97% Alarm -> thread resume latency + + 3.25 0.81 14.11 0.00 Clock/interrupt latency + + 2.68 1.09 12.75 0.00 Clock DSR latency + + 29 0 316 (main stack: 764) Thread stack used (1120 total) +All done, main stack : stack used 764 size 2400 +All done : Interrupt stack used 288 size 4096 +All done : Idlethread stack used 260 size 2048 + + +Timing complete - 30280 ms total + + </LITERALLAYOUT> +</SECT1> + +<!-- ==================================================== --> + +<SECT1 id="rt-ppc-mbx860"> +<TITLE>Board: Motorola MBX</TITLE> +<LITERALLAYOUT CLASS="MONOSPACED"> + +Board: Motorola MBX + +CPU : Motorola MPC860 66MHZ + + +Startup, main stack : stack used 643 size 5664 +Startup : Interrupt stack used 427 size 4096 +Startup : Idlethread stack used 236 size 2048 + +eCos Kernel Timings +Notes: all times are in microseconds (.000001) unless otherwise stated + +Reading the hardware clock takes 0 `ticks' overhead +... this value will be factored out of all other measurements +Clock interrupt took 25.36 microseconds (79 raw clock ticks) + +Testing parameters: + Clock samples: 32 + Threads: 16 + Thread switches: 128 + Mutexes: 32 + Mailboxes: 32 + Semaphores: 32 + Scheduler operations: 128 + Counters: 32 + Alarms: 32 + + + Confidence + Ave Min Max Var Ave Min Function + ====== ====== ====== ====== ========== ======== + 27.58 25.60 44.16 2.07 93% 93% Create thread + 5.94 5.76 7.04 0.22 93% 62% Yield thread [all suspended] + 6.06 5.44 10.56 0.57 75% 75% Suspend [suspended] thread + 5.42 4.80 9.60 0.53 87% 81% Resume thread + 7.10 6.40 14.08 0.90 93% 87% Set priority + 0.86 0.64 1.92 0.22 93% 50% Get priority + 16.74 15.04 36.48 2.47 93% 93% Kill [suspended] thread + 6.14 5.76 10.56 0.55 93% 93% Yield [no other] thread + 9.74 8.96 18.56 1.10 93% 93% Resume [suspended low prio] thread + 5.28 4.80 9.28 0.54 93% 81% Resume [runnable low prio] thread + 9.40 8.32 18.56 1.14 93% 93% Suspend [runnable] thread + 6.04 5.76 8.96 0.38 93% 93% Yield [only low prio] thread + 5.68 5.12 9.60 0.52 68% 75% Suspend [runnable->not runnable] + 16.10 14.40 35.20 2.39 93% 93% Kill [runnable] thread + 8.54 7.68 16.00 0.94 93% 87% Destroy [dead] thread + 20.20 18.56 40.64 2.55 93% 93% Destroy [runnable] thread + 39.02 36.48 57.28 3.28 87% 87% Resume [high priority] thread + 13.13 12.80 22.08 0.15 78% 20% Thread switch + + 0.59 0.32 1.60 0.09 82% 16% Scheduler lock + 3.67 3.52 5.12 0.17 99% 54% Scheduler unlock [0 threads] + 3.67 3.52 4.80 0.17 99% 53% Scheduler unlock [1 suspended] + 3.67 3.52 4.80 0.17 54% 54% Scheduler unlock [many suspended] + 3.69 3.52 5.12 0.17 99% 50% Scheduler unlock [many low prio] + + 2.41 2.24 5.44 0.25 96% 75% Init mutex + 6.83 6.40 11.84 0.34 75% 90% Lock [unlocked] mutex + 6.74 6.40 13.12 0.40 96% 96% Unlock [locked] mutex + 5.53 5.12 9.60 0.25 84% 12% Trylock [unlocked] mutex + 4.84 4.48 7.36 0.17 78% 15% Trylock [locked] mutex + 0.34 0.00 0.96 0.06 90% 3% Destroy mutex + 56.10 55.68 59.52 0.21 93% 3% Unlock/Lock mutex + + 4.72 4.48 10.24 0.37 96% 96% Create mbox + 0.75 0.64 1.92 0.16 75% 75% Peek [empty] mbox + 6.79 6.40 12.80 0.41 96% 90% Put [first] mbox + 0.46 0.32 1.60 0.19 93% 68% Peek [1 msg] mbox + 6.68 6.40 12.16 0.37 96% 96% Put [second] mbox + 0.50 0.32 1.60 0.20 93% 56% Peek [2 msgs] mbox + 7.13 6.40 14.08 0.49 90% 46% Get [first] mbox + 6.97 6.40 13.44 0.47 84% 78% Get [second] mbox + 6.24 5.76 11.52 0.38 78% 81% Tryput [first] mbox + 5.98 5.44 11.20 0.39 78% 62% Peek item [non-empty] mbox + 6.52 6.08 13.12 0.49 93% 81% Tryget [non-empty] mbox + 5.50 5.12 10.24 0.30 68% 28% Peek item [empty] mbox + 5.76 5.44 10.88 0.32 96% 96% Tryget [empty] mbox + 0.50 0.32 1.60 0.19 96% 53% Waiting to get mbox + 0.50 0.32 1.60 0.19 96% 53% Waiting to put mbox + 7.45 7.04 15.04 0.49 96% 93% Delete mbox + 37.47 36.80 48.64 0.70 96% 96% Put/Get mbox + + 2.49 2.24 6.08 0.28 96% 56% Init semaphore + 5.09 4.80 8.64 0.27 46% 46% Post [0] semaphore + 6.25 5.76 10.88 0.32 93% 3% Wait [1] semaphore + 4.84 4.48 8.32 0.23 68% 25% Trywait [0] semaphore + 4.98 4.80 8.00 0.26 96% 71% Trywait [1] semaphore + 1.66 1.28 3.84 0.20 68% 15% Peek semaphore + 1.24 0.96 3.20 0.17 65% 31% Destroy semaphore + 40.74 40.32 49.28 0.53 96% 96% Post/Wait semaphore + + 2.65 2.24 6.08 0.23 84% 9% Create counter + 0.85 0.64 2.24 0.22 90% 53% Get counter value + 0.68 0.64 1.92 0.08 96% 96% Set counter value + 7.13 6.72 8.64 0.24 78% 18% Tick counter + 1.30 0.96 3.20 0.12 84% 12% Delete counter + + 3.69 3.52 7.68 0.29 96% 84% Create alarm + 8.98 8.32 17.60 0.61 68% 62% Initialize alarm + 0.96 0.64 2.88 0.14 71% 21% Disable alarm + 8.76 8.32 17.60 0.59 96% 87% Enable alarm + 1.99 1.60 5.12 0.21 81% 12% Delete alarm + 7.44 7.36 9.92 0.15 96% 96% Tick counter [1 alarm] + 21.68 21.44 24.64 0.25 96% 53% Tick counter [many alarms] + 10.95 10.56 15.04 0.26 78% 18% Tick & fire counter [1 alarm] + 132.79 132.48 136.32 0.23 59% 37% Tick & fire counters [>1 together] + 25.18 24.96 28.80 0.29 96% 65% Tick & fire counters [>1 separately] + 23.06 22.72 47.36 0.40 98% 98% Alarm latency [0 threads] + 31.53 27.20 56.00 0.63 96% 0% Alarm latency [2 threads] + 36.86 30.40 58.88 4.15 50% 28% Alarm latency [many threads] + + 11.41 8.96 16.32 0.00 Clock/interrupt latency + + 609 603 651 (main stack: 1059) Thread stack used (1704 total) +All done, main stack : stack used 1059 size 5664 +All done : Interrupt stack used 251 size 4096 +All done : Idlethread stack used 587 size 2048 + +Timing complete - 23690 ms total + +PASS:<Basic timing OK> +EXIT:<done> + + </LITERALLAYOUT> +</SECT1> + +<!-- ==================================================== --> + +<SECT1 id="rt-sh-edk7708"> +<TITLE>Board: Hitachi EDK7708</TITLE> +<LITERALLAYOUT CLASS="MONOSPACED"> + + +Board: Hitachi EDK7708 + +CPU: Hitachi SH3/7708 60MHz + + + +Startup, main stack : stack used 444 size 4112 +Startup : Interrupt stack used 76 size 4096 +Startup : Idlethread stack used 96 size 2048 + +eCos Kernel Timings +Notes: all times are in microseconds (.000001) unless otherwise stated + +Reading the hardware clock takes 2 `ticks' overhead +... this value will be factored out of all other measurements +Clock interrupt took 14.75 microseconds (55 raw clock ticks) + +Testing parameters: + Clock samples: 32 + Threads: 16 + Thread switches: 128 + Mutexes: 32 + Mailboxes: 32 + Semaphores: 32 + Scheduler operations: 128 + Counters: 32 + Alarms: 32 + + + Confidence + Ave Min Max Var Ave Min Function + ====== ====== ====== ====== ========== ======== + 15.43 13.60 24.00 1.29 62% 50% Create thread + 3.33 3.20 4.27 0.18 93% 68% Yield thread [all suspended] + 2.90 2.40 5.33 0.36 81% 62% Suspend [suspended] thread + 2.93 2.67 4.80 0.27 93% 87% Resume thread + 4.30 3.73 10.13 0.73 93% 93% Set priority + 0.65 0.27 2.13 0.28 68% 62% Get priority + 9.72 8.53 21.33 1.45 93% 93% Kill [suspended] thread + 3.33 3.20 4.53 0.20 93% 75% Yield [no other] thread + 5.30 4.80 10.13 0.65 93% 87% Resume [suspended low prio] thread + 2.80 2.40 4.53 0.27 81% 75% Resume [runnable low prio] thread + 4.82 4.00 8.27 0.49 68% 25% Suspend [runnable] thread + 3.32 3.20 4.00 0.16 93% 68% Yield [only low prio] thread + 2.82 2.40 4.27 0.25 81% 12% Suspend [runnable->not runnable] + 9.45 8.53 19.47 1.25 93% 93% Kill [runnable] thread + 5.30 4.53 11.20 0.74 87% 93% Destroy [dead] thread + 11.83 10.67 25.07 1.65 93% 93% Destroy [runnable] thread + 19.53 17.33 31.20 1.88 75% 75% Resume [high priority] thread + 6.70 6.67 11.47 0.07 99% 99% Thread switch + + 0.33 0.27 0.80 0.10 75% 75% Scheduler lock + 1.74 1.60 2.67 0.14 99% 50% Scheduler unlock [0 threads] + 1.72 1.60 3.20 0.14 99% 57% Scheduler unlock [1 suspended] + 1.81 1.60 3.20 0.10 75% 23% Scheduler unlock [many suspended] + 1.86 1.60 3.20 0.02 94% 4% Scheduler unlock [many low prio] + + 1.22 1.07 3.20 0.20 96% 65% Init mutex + 3.21 2.93 5.87 0.17 68% 28% Lock [unlocked] mutex + 3.36 2.93 7.47 0.30 84% 75% Unlock [locked] mutex + 2.83 2.67 5.33 0.22 96% 65% Trylock [unlocked] mutex + 2.53 2.40 2.93 0.14 96% 53% Trylock [locked] mutex + 0.28 0.27 0.80 0.03 96% 96% Destroy mutex + 20.09 19.73 23.20 0.23 84% 12% Unlock/Lock mutex + + 2.38 2.13 4.53 0.17 59% 34% Create mbox + 0.45 0.27 1.33 0.15 56% 40% Peek [empty] mbox + 3.70 3.20 7.20 0.29 84% 59% Put [first] mbox + 0.45 0.27 0.80 0.13 62% 34% Peek [1 msg] mbox + 3.67 3.20 5.60 0.23 81% 6% Put [second] mbox + 0.42 0.27 0.53 0.13 59% 40% Peek [2 msgs] mbox + 3.98 3.47 7.47 0.24 59% 9% Get [first] mbox + 3.97 3.47 4.80 0.24 59% 12% Get [second] mbox + 3.51 3.20 6.67 0.28 56% 78% Tryput [first] mbox + 3.29 2.93 5.60 0.29 59% 65% Peek item [non-empty] mbox + 4.06 3.47 7.20 0.26 68% 3% Tryget [non-empty] mbox + 3.03 2.67 5.33 0.19 93% 3% Peek item [empty] mbox + 3.36 3.20 4.80 0.18 96% 56% Tryget [empty] mbox + 0.57 0.27 1.33 0.09 84% 3% Waiting to get mbox + 0.52 0.27 1.07 0.11 62% 21% Waiting to put mbox + 3.88 3.47 7.47 0.30 78% 65% Delete mbox + 12.04 11.73 17.33 0.33 96% 96% Put/Get mbox + + 1.17 1.07 2.40 0.16 71% 71% Init semaphore + 2.67 2.40 4.27 0.15 62% 25% Post [0] semaphore + 3.00 2.67 4.53 0.17 65% 12% Wait [1] semaphore + 2.54 2.40 4.80 0.20 96% 71% Trywait [0] semaphore + 2.42 2.40 2.93 0.03 96% 96% Trywait [1] semaphore + 0.79 0.53 2.13 0.15 59% 28% Peek semaphore + 0.77 0.53 1.87 0.12 71% 25% Destroy semaphore + 12.64 12.27 17.07 0.28 84% 96% Post/Wait semaphore + + 1.27 1.07 2.93 0.17 53% 43% Create counter + 0.54 0.27 1.33 0.13 59% 21% Get counter value + 0.47 0.27 1.60 0.17 46% 43% Set counter value + 3.47 3.20 4.80 0.16 53% 28% Tick counter + 0.80 0.53 2.13 0.13 62% 25% Delete counter + + 1.86 1.60 4.00 0.21 43% 40% Create alarm + 5.12 4.80 9.07 0.36 93% 75% Initialize alarm + 0.44 0.27 1.33 0.19 87% 53% Disable alarm + 4.77 4.27 9.60 0.35 87% 62% Enable alarm + 1.02 0.80 2.67 0.18 53% 40% Delete alarm + 3.56 3.47 5.33 0.15 84% 84% Tick counter [1 alarm] + 15.04 14.93 16.27 0.16 71% 71% Tick counter [many alarms] + 5.75 5.60 8.00 0.21 96% 68% Tick & fire counter [1 alarm] + 79.60 79.47 81.07 0.17 96% 65% Tick & fire counters [>1 together] + 17.04 16.80 18.93 0.15 65% 31% Tick & fire counters [>1 separately] + 12.44 12.27 29.60 0.31 96% 96% Alarm latency [0 threads] + 14.06 12.27 27.20 0.53 82% 4% Alarm latency [2 threads] + 19.62 17.07 38.40 1.44 57% 34% Alarm latency [many threads] + + 2.79 2.40 6.13 0.00 Clock/interrupt latency + + 376 376 376 (main stack: 764) Thread stack used (992 total) +All done, main stack : stack used 764 size 4112 +All done : Interrupt stack used 176 size 4096 +All done : Idlethread stack used 352 size 2048 + +Timing complete - 23860 ms total + +PASS:<Basic timing OK> +EXIT:<done> + + </LITERALLAYOUT> +</SECT1> + +<!-- ==================================================== --> + +<SECT1 id="rt-sh-cq7708"> +<TITLE>Board: CQ CqREEK SH3 Evaluation Board (cq7708)</TITLE> +<LITERALLAYOUT CLASS="MONOSPACED"> + +Board: CQ CqREEK SH3 Evaluation Board (cq7708) + +CPU: Hitachi SH3/7708 60MHz + +Startup, main stack : stack used 448 size 4112 +Startup : Interrupt stack used 80 size 4096 +Startup : Idlethread stack used 96 size 2048 + +eCos Kernel Timings +Notes: all times are in microseconds (.000001) unless otherwise stated + +Reading the hardware clock takes 2 `ticks' overhead +... this value will be factored out of all other measurements +Clock interrupt took 19.17 microseconds (71 raw clock ticks) + +Testing parameters: + Clock samples: 32 + Threads: 64 + Thread switches: 128 + Mutexes: 32 + Mailboxes: 32 + Semaphores: 32 + Scheduler operations: 128 + Counters: 32 + Alarms: 32 + + + Confidence + Ave Min Max Var Ave Min Function + ====== ====== ====== ====== ========== ======== + 20.62 14.40 26.93 3.23 48% 26% Create thread + 3.16 2.93 4.27 0.09 78% 20% Yield thread [all suspended] + 2.91 2.40 5.87 0.17 57% 1% Suspend [suspended] thread + 2.73 2.40 6.40 0.19 64% 15% Resume thread + 4.05 3.73 11.47 0.27 62% 90% Set priority + 0.82 0.27 2.67 0.17 56% 3% Get priority + 9.07 8.53 24.27 0.51 78% 71% Kill [suspended] thread + 3.19 2.93 7.20 0.14 70% 28% Yield [no other] thread + 5.45 4.53 17.87 0.49 78% 17% Resume [suspended low prio] thread + 2.67 2.40 5.07 0.15 56% 28% Resume [runnable low prio] thread + 4.95 4.27 11.47 0.28 82% 14% Suspend [runnable] thread + 3.15 2.93 4.53 0.11 73% 25% Yield [only low prio] thread + 2.82 2.40 5.60 0.21 84% 10% Suspend [runnable->not runnable] + 8.92 8.00 24.27 0.51 84% 14% Kill [runnable] thread + 5.10 4.53 12.00 0.27 59% 39% Destroy [dead] thread + 11.81 10.93 37.33 0.81 87% 95% Destroy [runnable] thread + 22.15 20.80 54.67 1.27 92% 92% Resume [high priority] thread + 6.85 6.67 13.60 0.19 99% 50% Thread switch + + 0.27 0.27 1.07 0.01 99% 99% Scheduler lock + 1.74 1.60 2.67 0.14 99% 50% Scheduler unlock [0 threads] + 1.74 1.60 2.93 0.14 99% 50% Scheduler unlock [1 suspended] + 1.81 1.60 4.27 0.11 72% 26% Scheduler unlock [many suspended] + 1.75 1.60 4.00 0.15 50% 49% Scheduler unlock [many low prio] + + 1.22 1.07 4.27 0.23 96% 78% Init mutex + 3.18 2.93 7.20 0.27 96% 53% Lock [unlocked] mutex + 3.40 3.20 8.00 0.31 96% 96% Unlock [locked] mutex + 2.77 2.40 5.87 0.22 87% 9% Trylock [unlocked] mutex + 2.35 2.13 3.47 0.14 65% 31% Trylock [locked] mutex + 0.78 0.53 2.67 0.14 68% 28% Destroy mutex + 22.80 22.40 28.80 0.51 96% 71% Unlock/Lock mutex + + 2.61 2.40 6.13 0.26 96% 62% Create mbox + 0.52 0.27 1.60 0.19 40% 37% Peek [empty] mbox + 3.54 3.20 7.73 0.35 93% 78% Put [first] mbox + 0.50 0.27 1.60 0.17 46% 37% Peek [1 msg] mbox + 3.62 3.20 6.93 0.34 59% 65% Put [second] mbox + 0.52 0.27 2.13 0.23 31% 43% Peek [2 msgs] mbox + 3.93 3.47 10.13 0.43 65% 65% Get [first] mbox + 3.92 3.47 7.47 0.40 56% 56% Get [second] mbox + 3.37 2.93 6.93 0.36 59% 68% Tryput [first] mbox + 3.30 2.67 6.93 0.38 84% 40% Peek item [non-empty] mbox + 3.93 3.47 9.33 0.44 65% 71% Tryget [non-empty] mbox + 2.94 2.67 6.13 0.25 43% 43% Peek item [empty] mbox + 3.23 2.93 6.67 0.27 56% 84% Tryget [empty] mbox + 0.58 0.27 2.67 0.20 62% 21% Waiting to get mbox + 0.55 0.27 1.87 0.14 62% 21% Waiting to put mbox + 3.82 3.47 9.87 0.39 96% 93% Delete mbox + 13.35 12.80 21.33 0.50 87% 78% Put/Get mbox + + 1.22 1.07 2.93 0.19 96% 59% Init semaphore + 2.42 2.13 4.27 0.12 81% 15% Post [0] semaphore + 2.96 2.67 5.07 0.16 68% 21% Wait [1] semaphore + 2.37 2.13 4.53 0.17 62% 34% Trywait [0] semaphore + 2.29 2.13 3.47 0.17 96% 53% Trywait [1] semaphore + 0.66 0.53 2.13 0.17 96% 68% Peek semaphore + 0.81 0.53 2.93 0.13 75% 21% Destroy semaphore + 14.47 14.13 21.33 0.43 96% 96% Post/Wait semaphore + + 1.44 1.07 3.47 0.29 56% 71% Create counter + 0.62 0.27 1.07 0.14 62% 3% Get counter value + 0.56 0.27 1.60 0.17 50% 25% Set counter value + 3.39 3.20 4.27 0.16 53% 40% Tick counter + 0.83 0.53 1.87 0.14 68% 15% Delete counter + + 2.02 1.87 4.00 0.21 93% 68% Create alarm + 5.06 4.27 11.73 0.46 78% 18% Initialize alarm + 0.73 0.27 2.40 0.22 84% 3% Disable alarm + 4.82 4.27 11.47 0.48 81% 65% Enable alarm + 1.19 0.80 3.47 0.22 87% 9% Delete alarm + 3.63 3.47 5.60 0.20 96% 59% Tick counter [1 alarm] + 15.01 14.93 16.53 0.13 87% 87% Tick counter [many alarms] + 5.50 5.33 8.00 0.22 96% 65% Tick & fire counter [1 alarm] + 74.27 74.13 76.80 0.21 96% 78% Tick & fire counters [>1 together] + 16.90 16.53 19.47 0.23 81% 15% Tick & fire counters [>1 separately] + 16.70 16.53 36.27 0.33 98% 98% Alarm latency [0 threads] + 17.85 16.53 34.40 0.47 73% 0% Alarm latency [2 threads] + 63.26 58.40 80.00 2.64 52% 32% Alarm latency [many threads] + 30.37 29.33 124.80 1.68 98% 97% Alarm -> thread resume latency + + 7.37 5.07 17.87 0.00 Clock/interrupt latency + + 9.00 4.53 26.93 0.00 Clock DSR latency + + 106 0 376 (main stack: 764) Thread stack used (992 total) +All done, main stack : stack used 764 size 4112 +All done : Interrupt stack used 176 size 4096 +All done : Idlethread stack used 352 size 2048 + +Timing complete - 30310 ms total + +PASS:<Basic timing OK> +EXIT:<done> + + </LITERALLAYOUT> +</SECT1> + +<!-- ==================================================== --> + +<SECT1 id="rt-sh-hs7729pci"> +<TITLE>Board: Hitachi HS7729PCI HS7729 SH3</TITLE> +<LITERALLAYOUT CLASS="MONOSPACED"> + +Board: Hitachi HS7729PCI HS7729 SH3 + +CPU: Hitachi SH3/7729 132MHz + + +Startup, main stack : stack used 464 size 4112 +Startup : Interrupt stack used 92 size 4096 +Startup : Idlethread stack used 94 size 2048 + +eCos Kernel Timings +Notes: all times are in microseconds (.000001) unless otherwise stated + +Reading the hardware clock takes 3 'ticks' overhead +... this value will be factored out of all other measurements +Clock interrupt took 18.10 microseconds (149 raw clock ticks) + +Testing parameters: + Clock samples: 32 + Threads: 64 + Thread switches: 128 + Mutexes: 32 + Mailboxes: 32 + Semaphores: 32 + Scheduler operations: 128 + Counters: 32 + Alarms: 32 + + + Confidence + Ave Min Max Var Ave Min Function + ====== ====== ====== ====== ========== ======== + 18.33 15.52 28.24 1.47 53% 28% Create thread + 3.08 2.91 6.79 0.13 78% 89% Yield thread [all suspended] + 3.23 3.03 6.18 0.16 59% 70% Suspend [suspended] thread + 2.70 2.55 6.18 0.15 54% 82% Resume thread + 4.12 4.00 7.52 0.16 96% 81% Set priority + 0.61 0.48 1.33 0.07 57% 28% Get priority + 9.14 8.61 18.91 0.42 85% 57% Kill [suspended] thread + 3.04 2.91 4.48 0.07 68% 20% Yield [no other] thread + 5.12 4.73 7.88 0.29 60% 53% Resume [suspended low prio] thread + 2.54 2.42 3.03 0.09 39% 40% Resume [runnable low prio] thread + 5.00 4.36 9.45 0.21 75% 1% Suspend [runnable] thread + 3.04 2.91 4.61 0.07 65% 21% Yield [only low prio] thread + 2.91 2.79 3.27 0.08 43% 31% Suspend [runnable->not runnable] + 8.82 8.12 15.39 0.36 68% 29% Kill [runnable] thread + 5.07 4.48 12.73 0.37 76% 50% Destroy [dead] thread + 11.17 10.55 22.91 0.52 78% 67% Destroy [runnable] thread + 22.43 21.45 32.73 0.61 81% 50% Resume [high priority] thread + 7.99 7.88 13.58 0.14 98% 86% Thread switch + + 0.37 0.36 1.33 0.02 97% 97% Scheduler lock + 1.74 1.70 2.06 0.06 70% 70% Scheduler unlock [0 threads] + 1.75 1.70 2.06 0.07 92% 64% Scheduler unlock [1 suspended] + 1.71 1.70 2.42 0.03 89% 89% Scheduler unlock [many suspended] + 1.76 1.70 3.64 0.08 96% 64% Scheduler unlock [many low prio] + + 4.23 3.88 10.67 0.41 96% 93% Unlock [locked] mutex + 3.12 2.91 6.91 0.29 96% 87% Trylock [unlocked] mutex + 2.54 2.42 2.91 0.11 18% 46% Trylock [locked] mutex + 0.88 0.73 3.15 0.14 65% 96% Destroy mutex + 22.33 22.06 25.94 0.23 81% 62% Unlock/Lock mutex + + 1.92 1.82 4.73 0.19 96% 93% Create mbox + 0.61 0.48 1.70 0.15 84% 75% Peek [empty] mbox + 4.00 3.64 9.45 0.36 96% 87% Put [first] mbox + 0.30 0.24 0.73 0.09 84% 75% Peek [1 msg] mbox + 3.82 3.64 6.67 0.22 90% 84% Put [second] mbox + 0.32 0.24 1.33 0.12 81% 81% Peek [2 msgs] mbox + 4.19 3.76 9.21 0.34 84% 50% Get [first] mbox + 3.91 3.76 5.21 0.16 84% 75% Get [second] mbox + 3.51 3.27 8.12 0.34 93% 87% Tryput [first] mbox + 3.25 2.91 7.15 0.30 62% 56% Peek item [non-empty] mbox + 3.86 3.52 8.73 0.37 93% 84% Tryget [non-empty] mbox + 2.87 2.79 3.76 0.12 84% 71% Peek item [empty] mbox + 3.15 3.03 4.24 0.10 46% 40% Tryget [empty] mbox + 0.34 0.24 1.33 0.10 43% 46% Waiting to get mbox + 0.36 0.24 1.45 0.09 53% 37% Waiting to put mbox + 4.49 4.24 10.91 0.41 96% 96% Delete mbox + 12.67 12.36 19.52 0.43 96% 96% Put/Get mbox + + 0.87 0.85 1.45 0.05 93% 93% Init semaphore + 2.74 2.55 4.48 0.18 50% 50% Post [0] semaphore + 3.39 3.15 4.24 0.14 78% 50% Wait [1] semaphore + 2.62 2.42 5.33 0.21 96% 65% Trywait [0] semaphore + 2.76 2.67 3.27 0.08 46% 43% Trywait [1] semaphore + 1.09 0.85 2.91 0.19 68% 56% Peek semaphore + 0.97 0.73 3.39 0.17 90% 65% Destroy semaphore + 13.09 12.85 16.12 0.19 84% 65% Post/Wait semaphore + + 1.57 1.45 3.88 0.15 96% 93% Create counter + 0.91 0.73 2.18 0.16 46% 68% Get counter value + 0.55 0.48 0.97 0.09 90% 62% Set counter value + 4.19 4.00 5.82 0.13 84% 75% Tick counter + 0.87 0.73 3.15 0.16 93% 93% Delete counter + + 2.50 2.30 5.21 0.18 81% 90% Create alarm + 6.16 5.70 12.97 0.47 96% 71% Initialize alarm + 0.50 0.36 1.70 0.11 62% 34% Disable alarm + 5.16 4.85 8.73 0.29 78% 78% Enable alarm + 1.18 1.09 2.30 0.12 84% 65% Delete alarm + 5.22 5.09 7.39 0.14 96% 93% Tick counter [1 alarm] + 52.37 52.12 52.73 0.20 37% 56% Tick counter [many alarms] + 6.73 6.55 8.24 0.13 78% 68% Tick & fire counter [1 alarm] + 108.65 108.61 109.21 0.07 87% 87% Tick & fire counters [>1 together] + 54.25 54.06 54.79 0.11 65% 18% Tick & fire counters [>1 separately] + 17.36 17.09 29.82 0.23 82% 57% Alarm latency [0 threads] + 19.75 17.09 28.00 1.65 46% 40% Alarm latency [2 threads] + 39.02 34.06 50.67 2.00 53% 15% Alarm latency [many threads] + 29.31 28.36 105.09 1.27 98% 97% Alarm -> thread resume latency + + 5.08 3.88 11.15 0.00 Clock/interrupt latency + + 7.32 5.09 16.73 0.00 Clock DSR latency + + 6 0 380 (main stack: 820) Thread stack used (992 total) +All done, main stack : stack used 820 size 4112 +All done : Interrupt stack used 196 size 4096 +All done : Idlethread stack used 360 size 2048 + +Timing complete - 29960 ms total +PASS:<Basic timing OK> +EXIT:<done> </LITERALLAYOUT> +</SECT1> + +<!-- ==================================================== --> + +<SECT1 id="rt-sh-se7751"> +<TITLE>Board: Hitachi Solution Engine 7751 SH4 (se7751)</TITLE> +<LITERALLAYOUT CLASS="MONOSPACED">Board: Hitachi Solution Engine 7751 SH4 (se7751) + +CPU: Hitachi SH4/7751 162MHz + + +Startup, main stack : stack used 464 size 4112 +Startup : Interrupt stack used 92 size 4096 +Startup : Idlethread stack used 94 size 2048 + + +eCos Kernel Timings +Notes: all times are in microseconds (.000001) unless otherwise stated + + +Reading the hardware clock takes 1 `ticks' overhead +... this value will be factored out of all other measurements +Clock interrupt took 14.27 microseconds (96 raw clock ticks) + + +Testing parameters: + Clock samples: 32 + Threads: 64 + Thread switches: 128 + Mutexes: 32 + Mailboxes: 32 + Semaphores: 32 + Scheduler operations: 128 + Counters: 32 + Alarms: 32 + + Confidence + Ave Min Max Var Ave Min Function + ====== ====== ====== ====== ========== ======== + 8.06 5.63 12.15 1.37 46% 29% Create thread + 1.15 1.04 5.19 0.15 98% 98% Yield thread [all suspended] + 1.13 0.89 5.04 0.27 89% 62% Suspend [suspended] thread + 1.11 0.89 5.19 0.26 89% 71% Resume thread + 1.45 1.19 3.56 0.23 53% 53% Set priority + 0.21 0.15 1.19 0.10 90% 79% Get priority + 4.15 3.56 13.04 0.53 68% 64% Kill [suspended] thread + 1.12 1.04 3.70 0.12 98% 70% Yield [no other] thread + 1.75 1.33 8.00 0.38 59% 65% Resume [suspended low prio] thread + 1.10 0.89 4.59 0.25 87% 73% Resume [runnable low prio] thread + 1.59 1.33 5.93 0.33 81% 79% Suspend [runnable] thread + 1.13 1.04 4.30 0.13 98% 71% Yield [only low prio] thread + 1.09 0.89 3.56 0.21 89% 70% Suspend [runnable->not runnable] + 4.96 4.30 11.70 0.44 68% 39% Kill [runnable] thread + 1.95 1.48 8.00 0.34 75% 57% Destroy [dead] thread + 4.41 3.85 10.37 0.47 53% 57% Destroy [runnable] thread + 13.15 11.41 23.85 1.11 73% 39% Resume [high priority] thread + 3.10 2.96 6.22 0.11 41% 39% Thread switch + + 0.13 0.00 1.33 0.06 74% 21% Scheduler lock + 0.76 0.74 1.78 0.03 96% 96% Scheduler unlock [0 threads] + 0.76 0.74 1.78 0.03 96% 96% Scheduler unlock [1 suspended] + 0.77 0.74 2.67 0.05 95% 95% Scheduler unlock [many suspended] + 0.76 0.74 2.37 0.04 95% 95% Scheduler unlock [many low prio] + + 0.52 0.15 2.67 0.26 65% 34% Init mutex + 1.23 1.04 5.63 0.32 93% 93% Lock [unlocked] mutex + 1.45 1.19 5.33 0.31 90% 87% Unlock [locked] mutex + 1.13 0.89 4.15 0.28 90% 84% Trylock [unlocked] mutex + 1.00 0.89 2.96 0.17 87% 87% Trylock [locked] mutex + 0.37 0.30 1.78 0.13 90% 84% Destroy mutex + 9.09 8.59 12.59 0.43 71% 71% Unlock/Lock mutex + 0.93 0.59 4.30 0.40 84% 71% Create mbox + 0.26 0.00 1.19 0.17 71% 59% Peek [empty] mbox + 3.03 2.52 6.37 0.47 50% 59% Put [first] mbox + 0.23 0.00 0.74 0.14 68% 15% Peek [1 msg] mbox + 2.93 2.52 4.74 0.46 71% 59% Put [second] mbox + 0.22 0.00 0.59 0.13 68% 15% Peek [2 msgs] mbox + 2.07 1.63 5.93 0.37 84% 59% Get [first] mbox + 2.06 1.63 4.74 0.34 78% 59% Get [second] mbox + 1.48 1.04 5.48 0.37 62% 53% Tryput [first] mbox + 1.31 1.04 4.89 0.32 96% 75% Peek item [non-empty] mbox + 1.47 1.04 5.78 0.38 84% 65% Tryget [non-empty] mbox + 1.15 0.89 3.11 0.18 71% 56% Peek item [empty] mbox + 1.20 1.04 3.85 0.21 93% 84% Tryget [empty] mbox + 0.21 0.00 0.74 0.14 68% 18% Waiting to get mbox + 0.19 0.00 0.44 0.10 43% 15% Waiting to put mbox + 2.19 1.93 5.78 0.27 93% 71% Delete mbox + 10.23 9.93 11.56 0.15 53% 37% Put/Get mbox + + 0.37 0.15 1.33 0.26 71% 71% Init semaphore + 0.98 0.89 2.52 0.13 96% 68% Post [0] semaphore + 1.08 0.89 3.26 0.15 68% 93% Wait [1] semaphore + 0.98 0.89 3.41 0.16 93% 93% Trywait [0] semaphore + 0.73 0.59 1.63 0.07 71% 25% Trywait [1] semaphore + 0.33 0.30 1.33 0.07 93% 93% Peek semaphore + 0.34 0.30 1.78 0.09 96% 96% Destroy semaphore + 9.36 8.74 10.37 0.33 56% 31% Post/Wait semaphore + + 0.54 0.15 3.26 0.23 59% 37% Create counter + 0.13 0.00 0.59 0.07 68% 25% Get counter value + 0.14 0.00 0.59 0.07 68% 25% Set counter value + 3.74 3.56 5.33 0.17 53% 75% Tick counter + 0.32 0.15 2.07 0.12 71% 21% Delete counter + + 1.59 1.19 3.11 0.29 71% 43% Create alarm + 1.89 1.48 6.37 0.44 87% 78% Initialize alarm + 0.20 0.15 0.74 0.09 87% 84% Disable alarm + 1.62 1.33 5.63 0.41 87% 84% Enable alarm + 0.40 0.30 1.33 0.13 87% 62% Delete alarm + + 4.03 3.70 5.78 0.27 68% 56% Tick counter [1 alarm] + 14.18 13.93 15.70 0.27 81% 75% Tick counter [many alarms] + 4.81 4.59 5.93 0.13 81% 15% Tick & fire counter [1 alarm] + 30.77 30.52 33.63 0.20 75% 65% Tick & fire counters [>1 together] + 15.10 14.52 17.04 0.23 71% 3% Tick & fire counters [>1 separately] + 8.78 8.59 18.22 0.20 97% 89% Alarm latency [0 threads] + 11.29 9.33 17.48 1.02 56% 22% Alarm latency [2 threads] + 18.70 15.70 26.37 1.45 54% 22% Alarm latency [many threads] + 19.40 18.81 57.48 0.65 97% 97% Alarm -> thread resume latency + + 4.18 2.81 8.89 0.00 Clock/interrupt latency + + 3.98 2.52 11.56 0.00 Clock DSR latency + + 6 0 380 (main stack: 728) Thread stack used (992 total) +All done, main stack : stack used 728 size 4112 +All done : Interrupt stack used 196 size 4096 +All done : Idlethread stack used 360 size 2048 + +Timing complete - 29790 ms total + +PASS:<Basic timing OK> +EXIT:<done> </LITERALLAYOUT> +</SECT1> +<SECT1 id="rt-i386-pc"> +<TITLE>Board: PC</TITLE> +<LITERALLAYOUT CLASS="MONOSPACED">Board: PC + +CPU: 433MHz Celeron + +Startup, main stack : stack used 124 size 2912 +Startup : Interrupt stack used 280 size 4108 +Startup : Idlethread stack used 62 size 2048 + +eCos Kernel Timings +Notes: all times are in microseconds (.000001) unless otherwise stated + +Reading the hardware clock takes 8 'ticks' overhead +... this value will be factored out of all other measurements +Clock interrupt took 6.75 microseconds (8 raw clock ticks) + +Testing parameters: + Clock samples: 32 + Threads: 64 + Thread switches: 128 + Mutexes: 32 + Mailboxes: 32 + Semaphores: 32 + Scheduler operations: 128 + Counters: 32 + Alarms: 32 + + + Confidence + Ave Min Max Var Ave Min Function + ====== ====== ====== ====== ========== ======== + 3.93 1.68 8.38 0.93 68% 3% Create thread + 0.71 0.00 3.35 0.84 59% 59% Yield thread [all suspended] + 0.65 0.00 5.03 0.84 64% 64% Suspend [suspended] thread + 0.63 0.00 1.68 0.79 62% 62% Resume thread + 0.76 0.00 1.68 0.83 54% 54% Set priority + 0.39 0.00 1.68 0.60 76% 76% Get priority + 1.34 0.00 6.70 0.67 73% 25% Kill [suspended] thread + 0.68 0.00 1.68 0.81 59% 59% Yield [no other] thread + 0.92 0.00 1.68 0.83 54% 45% Resume [suspended low prio] thread + 0.63 0.00 1.68 0.79 62% 62% Resume [runnable low prio] thread + 0.84 0.00 1.68 0.84 100% 50% Suspend [runnable] thread + 0.73 0.00 1.68 0.82 56% 56% Yield [only low prio] thread + 0.58 0.00 1.68 0.76 65% 65% Suspend [runnable->not runnable] + 1.26 0.00 3.35 0.67 71% 26% Kill [runnable] thread + 0.86 0.00 3.35 0.86 98% 50% Destroy [dead] thread + 1.44 0.00 1.68 0.40 85% 14% Destroy [runnable] thread + 4.45 3.35 6.70 0.89 53% 40% Resume [high priority] thread + 1.62 0.00 1.68 0.10 96% 3% Thread switch + + 0.41 0.00 1.68 0.61 75% 75% Scheduler lock + 0.48 0.00 1.68 0.69 71% 71% Scheduler unlock [0 threads] + 0.59 0.00 1.68 0.76 64% 64% Scheduler unlock [1 suspended] + 0.45 0.00 1.68 0.65 73% 73% Scheduler unlock [many suspended] + 0.45 0.00 1.68 0.65 73% 73% Scheduler unlock [many low prio] + + 0.52 0.00 1.68 0.72 68% 68% Init mutex + 0.79 0.00 5.03 0.93 96% 59% Lock [unlocked] mutex + 0.84 0.00 5.03 0.94 96% 56% Unlock [locked] mutex + 0.63 0.00 1.68 0.79 62% 62% Trylock [unlocked] mutex + 0.52 0.00 1.68 0.72 68% 68% Trylock [locked] mutex + 0.58 0.00 1.68 0.76 65% 65% Destroy mutex + 3.40 3.35 5.03 0.10 96% 96% Unlock/Lock mutex + + 0.99 0.00 1.68 0.81 59% 40% Create mbox + 0.47 0.00 1.68 0.68 71% 71% Peek [empty] mbox + 0.79 0.00 5.03 0.93 96% 59% Put [first] mbox + 0.42 0.00 1.68 0.63 75% 75% Peek [1 msg] mbox + 0.79 0.00 1.68 0.83 53% 53% Put [second] mbox + 0.37 0.00 1.68 0.57 78% 78% Peek [2 msgs] mbox + 0.73 0.00 3.35 0.87 59% 59% Get [first] mbox + 0.73 0.00 1.68 0.82 56% 56% Get [second] mbox + 0.79 0.00 3.35 0.88 56% 56% Tryput [first] mbox + 0.68 0.00 3.35 0.85 62% 62% Peek item [non-empty] mbox + 0.73 0.00 3.35 0.87 59% 59% Tryget [non-empty] mbox + 0.63 0.00 1.68 0.79 62% 62% Peek item [empty] mbox + 0.68 0.00 1.68 0.81 59% 59% Tryget [empty] mbox + 0.26 0.00 1.68 0.44 84% 84% Waiting to get mbox + 0.63 0.00 1.68 0.79 62% 62% Waiting to put mbox + 0.73 0.00 3.35 0.87 59% 59% Delete mbox + 3.25 1.68 3.35 0.20 93% 6% Put/Get mbox + + 0.63 0.00 1.68 0.79 62% 62% Init semaphore + 0.63 0.00 1.68 0.79 62% 62% Post [0] semaphore + 0.63 0.00 1.68 0.79 62% 62% Wait [1] semaphore + 0.52 0.00 1.68 0.72 68% 68% Trywait [0] semaphore + 0.52 0.00 1.68 0.72 68% 68% Trywait [1] semaphore + 0.52 0.00 1.68 0.72 68% 68% Peek semaphore + 0.21 0.00 1.68 0.37 87% 87% Destroy semaphore + 3.30 1.68 3.35 0.10 96% 3% Post/Wait semaphore + + 0.79 0.00 3.35 0.88 56% 56% Create counter + 0.42 0.00 1.68 0.63 75% 75% Get counter value + 0.37 0.00 1.68 0.57 78% 78% Set counter value + 0.73 0.00 1.68 0.82 56% 56% Tick counter + 0.63 0.00 1.68 0.79 62% 62% Delete counter + + 0.89 0.00 3.35 0.89 96% 50% Create alarm + 0.84 0.00 1.68 0.84 100% 50% Initialize alarm + 0.52 0.00 1.68 0.72 68% 68% Disable alarm + 0.89 0.00 3.35 0.89 96% 50% Enable alarm + 0.58 0.00 1.68 0.76 65% 65% Delete alarm + 0.63 0.00 1.68 0.79 62% 62% Tick counter [1 alarm] + 5.03 3.35 6.70 0.10 93% 3% Tick counter [many alarms] + 0.94 0.00 1.68 0.82 56% 43% Tick & fire counter [1 alarm] + 11.16 10.06 11.73 0.76 65% 34% Tick & fire counters [>1 together] + 5.19 5.03 6.70 0.28 90% 90% Tick & fire counters [>1 separately] + 0.01 0.00 1.68 0.03 99% 99% Alarm latency [0 threads] + 0.13 0.00 1.68 0.24 92% 92% Alarm latency [2 threads] + 0.94 0.00 3.35 0.85 53% 45% Alarm latency [many threads] + 1.75 1.68 6.70 0.15 96% 96% Alarm -> thread resume latency + + 41 0 368 (main stack: 1036) Thread stack used (1712 total) +All done, main stack : stack used 1036 size 2912 +All done : Interrupt stack used 368 size 4108 +All done : Idlethread stack used 288 size 2048 + +Timing complete - 28520 ms total + +PASS:<Basic timing OK> +EXIT:<done> + +</LITERALLAYOUT> +</SECT1> +<SECT1 id="rt-v850-cebsa1"> +<TITLE>Board: NEC V850 Cosmo Evaluation Board</TITLE> +<LITERALLAYOUT CLASS="MONOSPACED">Board: NEC V850 Cosmo Evaluation Board + +CPU: NEC CEB-V850/SA1 17MHz + +Startup, main stack : stack used 552 size 2936 +Startup : Interrupt stack used 120 size 4096 +Startup : Idlethread stack used 206 size 2048 + +eCos Kernel Timings +Notes: all times are in microseconds (.000001) unless otherwise stated + +Reading the hardware clock takes 27 `ticks' overhead +... this value will be factored out of all other measurements +Clock interrupt took 280.04 microseconds (1190 raw clock ticks) + +Testing parameters: + Clock samples: 32 + Threads: 7 + Thread switches: 128 + Mutexes: 32 + Mailboxes: 32 + Semaphores: 32 + Scheduler operations: 128 + Counters: 32 + Alarms: 32 + + + Confidence + Ave Min Max Var Ave Min Function + ====== ====== ====== ====== ========== ======== + 288.71 280.24 297.18 4.84 42% 28% Create thread + 70.76 70.59 70.82 0.10 71% 28% Yield thread [all suspended] + 59.06 59.06 59.06 0.00 100% 100% Suspend [suspended] thread + 60.00 60.00 60.00 0.00 100% 100% Resume thread + 77.38 77.18 77.41 0.06 85% 14% Set priority + 3.13 3.06 3.29 0.10 71% 71% Get priority + 187.46 187.29 187.53 0.10 71% 28% Kill [suspended] thread + 70.76 70.59 70.82 0.10 71% 28% Yield [no other] thread + 104.40 103.29 104.71 0.32 85% 14% Resume [suspended low prio] thread + 59.06 59.06 59.06 0.00 100% 100% Resume [runnable low prio] thread + 97.11 91.06 98.12 1.73 85% 14% Suspend [runnable] thread + 70.76 70.59 70.82 0.10 71% 28% Yield [only low prio] thread + 59.06 59.06 59.06 0.00 100% 100% Suspend [runnable->not runnable] + 187.46 187.29 187.53 0.10 71% 28% Kill [runnable] thread + 95.63 95.29 97.18 0.44 85% 85% Destroy [dead] thread + 241.28 236.94 242.12 1.24 85% 14% Destroy [runnable] thread + 378.55 370.35 427.06 13.86 85% 85% Resume [high priority] thread + 198.77 183.76 452.94 18.77 96% 96% Thread switch + + 2.59 2.59 2.59 0.00 100% 100% Scheduler lock + 41.29 41.18 41.41 0.12 100% 50% Scheduler unlock [0 threads] + 40.82 40.71 40.94 0.12 100% 50% Scheduler unlock [1 suspended] + 41.29 41.18 41.41 0.12 100% 50% Scheduler unlock [many suspended] + 41.29 41.18 41.41 0.12 100% 50% Scheduler unlock [many low prio] + + 17.94 17.88 18.12 0.09 75% 75% Init mutex + 68.71 68.71 68.71 0.00 100% 100% Lock [unlocked] mutex + 72.10 72.00 73.41 0.15 96% 71% Unlock [locked] mutex + 57.88 57.88 57.88 0.00 100% 100% Trylock [unlocked] mutex + 52.24 52.24 52.24 0.00 100% 100% Trylock [locked] mutex + 12.41 12.24 12.47 0.09 75% 25% Destroy mutex + 427.06 427.06 427.06 0.00 100% 100% Unlock/Lock mutex + + + 34.94 34.82 35.06 0.12 100% 50% Create mbox + 0.76 0.71 0.94 0.09 75% 75% Peek [empty] mbox + 75.29 75.29 75.29 0.00 100% 100% Put [first] mbox + 1.24 1.18 1.41 0.09 75% 75% Peek [1 msg] mbox + 75.76 75.76 75.76 0.00 100% 100% Put [second] mbox + 0.76 0.71 0.94 0.09 75% 75% Peek [2 msgs] mbox + 80.12 80.00 80.24 0.12 100% 50% Get [first] mbox + 79.65 79.53 79.76 0.12 100% 50% Get [second] mbox + 70.12 70.12 70.12 0.00 100% 100% Tryput [first] mbox + 65.76 65.65 65.88 0.12 100% 50% Peek item [non-empty] mbox + 78.00 77.88 78.12 0.12 100% 50% Tryget [non-empty] mbox + 63.12 63.06 63.29 0.09 75% 75% Peek item [empty] mbox + 67.82 67.76 68.00 0.09 75% 75% Tryget [empty] mbox + 1.94 1.88 2.12 0.09 75% 75% Waiting to get mbox + 1.47 1.41 1.65 0.09 75% 75% Waiting to put mbox + 75.59 75.53 75.76 0.09 75% 75% Delete mbox + 252.76 252.71 252.94 0.09 75% 75% Put/Get mbox + + 20.24 20.24 20.24 0.00 100% 100% Init semaphore + 54.35 54.35 54.35 0.00 100% 100% Post [0] semaphore + 66.59 66.59 66.59 0.00 100% 100% Wait [1] semaphore + 52.24 52.24 52.24 0.00 100% 100% Trywait [0] semaphore + 53.41 53.41 53.41 0.00 100% 100% Trywait [1] semaphore + 10.65 10.59 10.82 0.09 75% 75% Peek semaphore + 12.65 12.47 12.71 0.09 75% 25% Destroy semaphore + 276.94 276.94 276.94 0.00 100% 100% Post/Wait semaphore + + 14.94 14.82 15.06 0.12 100% 50% Create counter + 2.18 2.12 2.35 0.09 75% 75% Get counter value + 3.06 3.06 3.06 0.00 100% 100% Set counter value + 78.12 78.12 78.12 0.00 100% 100% Tick counter + 13.82 13.65 13.88 0.09 75% 25% Delete counter + + 26.94 26.82 27.06 0.12 100% 50% Create alarm + 104.18 104.00 104.24 0.09 75% 25% Initialize alarm + 7.65 7.53 7.76 0.12 100% 50% Disable alarm + 104.94 104.94 104.94 0.00 100% 100% Enable alarm + 19.47 19.29 19.53 0.09 75% 25% Delete alarm + 88.53 88.47 88.71 0.09 75% 75% Tick counter [1 alarm] + 418.61 411.29 645.41 14.17 96% 96% Tick counter [many alarms] + 139.59 139.53 139.76 0.09 75% 75% Tick & fire counter [1 alarm] + 2150.21 2096.71 2367.53 83.59 78% 78% Tick & fire counters [>1 together] + 478.15 462.35 733.41 29.61 93% 93% Tick & fire counters [>1 separately] + 219.89 218.59 369.88 2.34 99% 99% Alarm latency [0 threads] + 292.11 218.59 371.53 37.85 50% 25% Alarm latency [2 threads] + 292.96 218.59 370.59 38.12 49% 25% Alarm latency [many threads] + 540.90 495.76 1677.41 17.76 98% 0% Alarm -> thread resume latency + + 79.01 78.59 104.71 0.00 Clock/interrupt latency + + 123.41 85.88 1982.82 0.00 Clock DSR latency + + 522 516 536 (main stack: 1124) Thread stack used (1912 total) +All done, main stack : stack used 1124 size 2936 +All done : Interrupt stack used 288 size 4096 +All done : Idlethread stack used 488 size 2048 + +Timing complete - 32540 ms total + +</LITERALLAYOUT> +</SECT1> +<SECT1 id="rt-v850-cebsb1"> +<TITLE>Board: NEC V850 Cosmo Evaluation Board</TITLE> +<LITERALLAYOUT CLASS="MONOSPACED">Board: NEC V850 Cosmo Evaluation Board + +CPU: NEC CEB-V850/SB1 16MHz (in internal Flash) + + +Startup, main stack : stack used 572 size 2936 +Startup : Interrupt stack used 132 size 4096 +Startup : Idlethread stack used 210 size 2048 + +eCos Kernel Timings +Notes: all times are in microseconds (.000001) unless otherwise stated + +Reading the hardware clock takes 8 'ticks' overhead +... this value will be factored out of all other measurements +Clock interrupt took 118.15 microseconds (472 raw clock ticks) + +Testing parameters: + Clock samples: 32 + Threads: 7 + Thread switches: 128 + Mutexes: 32 + Mailboxes: 32 + Semaphores: 32 + Scheduler operations: 128 + Counters: 32 + Alarms: 32 + + + Confidence + Ave Min Max Var Ave Min Function + ====== ====== ====== ====== ========== ======== + 113.68 111.00 116.50 1.63 42% 28% Create thread + 30.00 30.00 30.00 0.00 100% 100% Yield thread [all suspended] + 29.57 29.50 29.75 0.10 71% 71% Suspend [suspended] thread + 27.43 27.25 27.50 0.10 71% 28% Resume thread + 34.11 34.00 34.25 0.12 57% 57% Set priority + 1.57 1.50 1.75 0.10 71% 71% Get priority + 72.96 72.75 73.00 0.06 85% 14% Kill [suspended] thread + 30.00 30.00 30.00 0.00 100% 100% Yield [no other] thread + 42.75 42.75 42.75 0.00 100% 100% Resume [suspended low prio] thread + 27.00 27.00 27.00 0.00 100% 100% Resume [runnable low prio] thread + 43.64 41.25 44.25 0.68 85% 14% Suspend [runnable] thread + 30.00 30.00 30.00 0.00 100% 100% Yield [only low prio] thread + 29.57 29.50 29.75 0.10 71% 71% Suspend [runnable->not runnable] + 72.93 72.75 73.00 0.10 71% 28% Kill [runnable] thread + 44.89 44.75 45.75 0.24 85% 85% Destroy [dead] thread + 103.00 101.50 103.25 0.43 85% 14% Destroy [runnable] thread + 175.21 171.50 197.50 6.37 85% 85% Resume [high priority] thread + 84.11 79.50 197.25 1.77 98% 0% Thread switch + + 1.00 1.00 1.00 0.00 100% 100% Scheduler lock + 20.06 20.00 20.25 0.09 75% 75% Scheduler unlock [0 threads] + 20.00 20.00 20.00 0.00 100% 100% Scheduler unlock [1 suspended] + 20.06 20.00 20.25 0.09 75% 75% Scheduler unlock [many suspended] + 20.06 20.00 20.25 0.09 75% 75% Scheduler unlock [many low prio] + + 4.00 4.00 4.00 0.00 100% 100% Init mutex + 33.00 33.00 33.00 0.00 100% 100% Lock [unlocked] mutex + 36.77 36.75 37.25 0.03 96% 96% Unlock [locked] mutex + 28.13 28.00 28.25 0.13 100% 50% Trylock [unlocked] mutex + 25.13 25.00 25.25 0.13 100% 50% Trylock [locked] mutex + 4.88 4.75 5.00 0.13 100% 50% Destroy mutex + 187.00 187.00 187.00 0.00 100% 100% Unlock/Lock mutex + + 10.00 10.00 10.00 0.00 100% 100% Create mbox + 0.69 0.50 0.75 0.09 75% 25% Peek [empty] mbox + 34.75 34.75 34.75 0.00 100% 100% Put [first] mbox + 0.69 0.50 0.75 0.09 75% 25% Peek [1 msg] mbox + 35.00 35.00 35.00 0.00 100% 100% Put [second] mbox + 0.69 0.50 0.75 0.09 75% 25% Peek [2 msgs] mbox + 36.00 36.00 36.00 0.00 100% 100% Get [first] mbox + 36.00 36.00 36.00 0.00 100% 100% Get [second] mbox + 31.00 31.00 31.00 0.00 100% 100% Tryput [first] mbox + 29.50 29.50 29.50 0.00 100% 100% Peek item [non-empty] mbox + 35.25 35.25 35.25 0.00 100% 100% Tryget [non-empty] mbox + 27.69 27.50 27.75 0.09 75% 25% Peek item [empty] mbox + 31.06 31.00 31.25 0.09 75% 75% Tryget [empty] mbox + 0.94 0.75 1.00 0.09 75% 25% Waiting to get mbox + 0.94 0.75 1.00 0.09 75% 25% Waiting to put mbox + 37.81 37.75 38.00 0.09 75% 75% Delete mbox + 112.00 112.00 112.00 0.00 100% 100% Put/Get mbox + + 3.19 3.00 3.25 0.09 75% 25% Init semaphore + 25.38 25.25 25.50 0.13 100% 50% Post [0] semaphore + 32.63 32.50 32.75 0.13 100% 50% Wait [1] semaphore + 24.25 24.25 24.25 0.00 100% 100% Trywait [0] semaphore + 25.00 25.00 25.00 0.00 100% 100% Trywait [1] semaphore + 4.00 4.00 4.00 0.00 100% 100% Peek semaphore + 4.88 4.75 5.00 0.13 100% 50% Destroy semaphore + 124.50 124.50 124.50 0.00 100% 100% Post/Wait semaphore + + 6.50 6.50 6.50 0.00 100% 100% Create counter + 1.25 1.25 1.25 0.00 100% 100% Get counter value + 1.44 1.25 1.50 0.09 75% 25% Set counter value + 36.25 36.25 36.25 0.00 100% 100% Tick counter + 5.25 5.25 5.25 0.00 100% 100% Delete counter + + 12.25 12.25 12.25 0.00 100% 100% Create alarm + 49.13 49.00 49.25 0.13 100% 50% Initialize alarm + 2.81 2.75 3.00 0.09 75% 75% Disable alarm + 48.50 48.50 48.50 0.00 100% 100% Enable alarm + 8.25 8.25 8.25 0.00 100% 100% Delete alarm + 46.50 46.50 46.50 0.00 100% 100% Tick counter [1 alarm] + 485.42 482.25 580.00 5.91 96% 96% Tick counter [many alarms] + 64.00 64.00 64.00 0.00 100% 100% Tick & fire counter [1 alarm] + 1109.76 1100.50 1198.00 16.53 90% 90% Tick & fire counters [>1 together] + 505.85 502.00 621.00 7.20 96% 96% Tick & fire counters [>1 separately] + 96.26 95.75 161.25 1.02 99% 99% Alarm latency [0 threads] + 159.20 95.75 160.75 2.52 97% 0% Alarm latency [2 threads] + 159.73 110.50 161.75 1.53 97% 0% Alarm latency [many threads] + 218.45 211.25 445.75 3.55 97% 1% Alarm -> thread resume latency + + 28.24 25.25 43.25 0.00 Clock/interrupt latency + + 60.15 40.50 221.50 0.00 Clock DSR latency + + 472 424 572 (main stack: 1052) Thread stack used (1912 total) +All done, main stack : stack used 1052 size 2936 +All done : Interrupt stack used 280 size 4096 +All done : Idlethread stack used 516 size 2048 + +Timing complete - 30590 ms total + +PASS:<Basic timing OK> +EXIT:<done> + +</LITERALLAYOUT> +</SECT1> + +<!-- ==================================================== --> + +<SECT1 id="rt-s3c4510-aim711"> +<TITLE>Board: ARM Industrial Module AIM711 (S3C4510)</TITLE> +<LITERALLAYOUT CLASS="MONOSPACED"> +Board: ARM Industrial Module AIM711 (S3C4510) +CPU : S3C4510B (ARM7TDMI core), 50MHz +8MB RAM, 2MB Flash + +Startup, main stack : stack used 82 size 2400 +Startup : Interrupt stack used 134 size 4096 +Startup : Idlethread stack used 91 size 2048 + +eCos Kernel Timings +Notes: all times are in microseconds (.000001) unless otherwise stated + +Reading the hardware clock takes 33 'ticks' overhead +... this value will be factored out of all other measurements +Clock interrupt took 17.68 microseconds (884 raw clock ticks) + +Testing parameters: + Clock samples: 32 + Threads: 64 + Thread switches: 128 + Mutexes: 32 + Mailboxes: 32 + Semaphores: 32 + Scheduler operations: 128 + Counters: 32 + Flags: 32 + Alarms: 32 + + + Confidence + Ave Min Max Var Ave Min Function + ====== ====== ====== ====== ========== ======== + 22.99 15.24 36.98 4.01 50% 26% Create thread + 2.96 2.88 8.30 0.17 98% 98% Yield thread [all suspended] + 3.57 3.36 8.76 0.26 93% 71% Suspend [suspended] thread + 3.64 3.00 8.74 0.33 65% 20% Resume thread + 5.44 4.78 15.10 0.42 75% 26% Set priority + 0.77 0.20 1.98 0.25 59% 17% Get priority + 14.46 12.40 33.02 1.03 85% 9% Kill [suspended] thread + 2.95 2.88 7.44 0.14 98% 98% Yield [no other] thread + 6.73 5.40 15.60 0.44 78% 6% Resume [suspended low prio] thread + 3.59 2.98 7.18 0.28 56% 21% Resume [runnable low prio] thread + 5.77 4.78 13.46 0.44 71% 18% Suspend [runnable] thread + 2.97 2.88 8.86 0.18 98% 98% Yield [only low prio] thread + 3.40 2.86 6.26 0.26 59% 17% Suspend [runnable->not runnable] + 14.15 12.08 30.54 1.09 78% 23% Kill [runnable] thread + 11.00 9.74 23.38 0.75 70% 31% Destroy [dead] thread + 20.35 17.72 43.00 1.26 73% 14% Destroy [runnable] thread + 23.77 21.02 45.38 1.59 68% 35% Resume [high priority] thread + 8.40 8.30 15.38 0.18 89% 89% Thread switch + + 0.10 0.08 1.52 0.03 92% 92% Scheduler lock + 2.01 1.98 3.80 0.06 92% 92% Scheduler unlock [0 threads] + 2.01 1.98 3.80 0.06 92% 92% Scheduler unlock [1 suspended] + 2.01 1.98 4.08 0.06 92% 92% Scheduler unlock [many suspended] + 2.01 1.98 3.68 0.05 92% 92% Scheduler unlock [many low prio] + + 0.67 0.54 3.90 0.21 96% 96% Init mutex + 4.55 4.14 12.40 0.53 96% 87% Lock [unlocked] mutex + 4.84 4.12 12.78 0.56 65% 56% Unlock [locked] mutex + 3.72 3.18 8.86 0.41 68% 56% Trylock [unlocked] mutex + 3.22 2.76 5.38 0.26 65% 28% Trylock [locked] mutex + 0.49 0.34 3.26 0.26 93% 84% Destroy mutex + 33.13 32.42 43.64 0.66 90% 81% Unlock/Lock mutex + + 1.21 1.06 5.12 0.25 96% 96% Create mbox + 0.63 0.46 2.66 0.22 96% 71% Peek [empty] mbox + 4.57 3.64 11.12 0.50 75% 18% Put [first] mbox + 0.52 0.10 2.74 0.23 62% 18% Peek [1 msg] mbox + 5.39 4.46 12.00 0.56 75% 43% Put [second] mbox + 0.51 0.10 2.38 0.22 62% 18% Peek [2 msgs] mbox + 5.06 4.00 13.86 0.60 81% 18% Get [first] mbox + 5.01 4.36 9.20 0.38 68% 25% Get [second] mbox + 5.56 4.70 11.22 0.55 75% 37% Tryput [first] mbox + 4.25 3.14 10.64 0.49 75% 9% Peek item [non-empty] mbox + 5.10 3.82 14.02 0.78 78% 40% Tryget [non-empty] mbox + 3.86 3.12 9.72 0.47 81% 21% Peek item [empty] mbox + 4.13 3.28 11.20 0.54 87% 59% Tryget [empty] mbox + 0.60 0.14 2.34 0.22 68% 9% Waiting to get mbox + 0.61 0.14 2.90 0.27 78% 15% Waiting to put mbox + 4.51 3.66 11.20 0.53 84% 50% Delete mbox + 26.55 26.00 31.46 0.37 78% 40% Put/Get mbox + + 0.53 0.44 2.68 0.15 96% 90% Init semaphore + 3.08 2.76 5.02 0.29 43% 46% Post [0] semaphore + 3.64 3.20 7.72 0.40 53% 50% Wait [1] semaphore + 3.08 2.66 7.40 0.39 50% 50% Trywait [0] semaphore + 2.72 2.62 5.88 0.20 96% 96% Trywait [1] semaphore + 0.85 0.52 3.30 0.32 50% 50% Peek semaphore + 0.80 0.34 3.74 0.39 46% 37% Destroy semaphore + 21.87 21.54 25.64 0.28 68% 65% Post/Wait semaphore + + 1.18 1.04 4.92 0.24 96% 96% Create counter + 0.69 0.52 2.84 0.24 93% 71% Get counter value + 0.26 0.14 1.76 0.18 78% 78% Set counter value + 3.73 3.24 5.62 0.14 78% 12% Tick counter + 0.79 0.36 3.58 0.19 78% 15% Delete counter + + 0.53 0.44 3.06 0.17 96% 90% Init flag + 3.49 3.02 9.28 0.45 53% 50% Destroy flag + 2.93 2.52 7.42 0.39 50% 46% Mask bits in flag + 3.58 3.12 9.38 0.46 50% 50% Set bits in flag [no waiters] + 7.48 7.22 12.90 0.35 96% 96% Wait for flag [AND] + 4.92 4.66 11.22 0.39 96% 96% Wait for flag [OR] + 4.58 4.30 11.66 0.44 96% 96% Wait for flag [AND/CLR] + 4.39 4.12 11.02 0.43 96% 96% Wait for flag [OR/CLR] + 0.06 0.00 1.40 0.11 87% 87% Peek on flag + + 1.82 1.58 8.02 0.40 96% 96% Create alarm + 7.27 6.54 17.86 0.77 93% 87% Initialize alarm + 3.30 2.58 7.28 0.60 56% 71% Disable alarm + 7.60 5.82 14.72 0.84 81% 12% Enable alarm + 3.86 3.06 9.20 0.67 53% 65% Delete alarm + 4.03 3.90 7.18 0.23 96% 90% Tick counter [1 alarm] + 25.12 24.98 28.82 0.24 96% 93% Tick counter [many alarms] + 7.92 7.64 14.00 0.40 96% 96% Tick & fire counter [1 alarm] + 155.10 154.42 161.04 0.37 90% 6% Tick & fire counters [>1 together] + 29.27 29.02 35.48 0.42 96% 93% Tick & fire counters [>1 separately] + 17.87 17.32 49.30 0.56 98% 97% Alarm latency [0 threads] + 24.39 22.02 63.60 1.43 57% 19% Alarm latency [2 threads] + 55.33 52.72 62.44 1.11 67% 20% Alarm latency [many threads] + 37.98 36.54 170.56 2.17 97% 97% Alarm -> thread resume latency + + 29 0 259 (main stack: 805) Thread stack used (1120 total) +All done, main stack : stack used 805 size 2400 +All done : Interrupt stack used 163 size 4096 +All done : Idlethread stack used 239 size 2048 + +Timing complete - 28880 ms total + +PASS:<Basic timing OK> +EXIT:<done> +</LITERALLAYOUT> +</SECT1> +</APPENDIX> diff --git a/ecos/doc/sgml/user-guide/target-setup.sgml b/ecos/doc/sgml/user-guide/target-setup.sgml new file mode 100644 index 0000000..a143356 --- /dev/null +++ b/ecos/doc/sgml/user-guide/target-setup.sgml @@ -0,0 +1,3182 @@ +<!-- {{{ Banner --> + +<!-- =============================================================== --> +<!-- --> +<!-- config-tool.sgml --> +<!-- --> +<!-- eCos User Guide --> +<!-- --> +<!-- =============================================================== --> +<!-- ####ECOSDOCCOPYRIGHTBEGIN#### --> +<!-- =============================================================== --> +<!-- Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002, 2011 Free Software Foundation, 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 --> +<!-- =============================================================== --> +<!-- ####ECOSDOCCOPYRIGHTEND#### --> +<!-- =============================================================== --> +<!-- #####DESCRIPTIONBEGIN#### --> +<!-- --> +<!-- ####DESCRIPTIONEND#### --> +<!-- =============================================================== --> + +<!-- }}} --> + + +<appendix id="appendix-target-setup"> +<title>Target Setup</title> + +<para> +The following sections detail the setup of many of the targets +supported by eCos. +</para> + +<caution> +<para> +This information is presented here only temporarily. It is intended +that there will be separate documents detailing this information for +each target in future releases. Consequently not much effort has been +put into bringing the following documentation up to date -- much of it +is obsolete, bogus or just plain wrong. +</para> +</caution> + +<!-- +<para> +XXXXX Exactly which of these are really supported in 2.0. Can we +delete some of them. I'm reluctant to waste much time fixing up text +that is going to be largely rewritten anyway. +XXXXX +</para> +--> + +<!-- ==================================================== --> + +<SECT1 id="setup-mn10300-stdeval1"> +<TITLE>MN10300 stdeval1 Hardware Setup</TITLE> +<PARA>The eCos Developer’s Kit package comes with a pair +of EPROMs which provide GDB support for the Matsushita MN10300 (AM31) +series evaluation board using CygMon, the Cygnus ROM monitor. Images +of these EPROMs are also provided at <filename>BASE_DIR/loaders/mn10300-stdeval1/cygmon.bin</filename>. +The LSB EPROM (LROM) is installed to socket IC8 on the board and +the MSB EPROM (UROM) is installed to socket IC9. Attention should +be paid to the correct orientation of these EPROMs during installation.</PARA> +<PARA>The CygMon stubs allows communication with GDB by way of the +serial port at connector CN2. The communication parameters are fixed +at 38400 baud, 8 data bits, no parity bit, and 1 stop bit (8-N-1). +No flow control is employed. Connection to the host computer should +be made using a standard RS232C serial cable (not a null modem cable). +A gender changer may also be required.</PARA> +</SECT1> + +<!-- ==================================================== --> + +<SECT1 id="setup-mn10300-sim"> +<TITLE>MN10300 Architectural Simulator Setup</TITLE> +<PARA>The MN10300 simulator is an architectural simulator for the +Matsushita MN10300 that implements all features of the microprocessor + necessary to run eCos. The current implementation provides accurate +simulation of the instruction set, interrupt controller, timers, +and serial I/O.</PARA> +<PARA>In this release, you can run the same eCos binaries in the +simulator that can run on target hardware, if built for ROM start-up, +with the exception of those that use the watchdog timer.</PARA> +<PARA>However, note that AM33 devices required to run eCos are not +simulated; therefore you cannot run eCos binaries built for the +AM33 under the simulator. For the AM33, the simulator is effectively +an instruction-set only simulator.</PARA> +<PARA>To simplify connection to the simulator, you are advised to +create a GDB macro by putting the following code in your personal +GDB start-up file (gdb.ini on Windows and .gdbinit on UNIX).</PARA> +<PROGRAMLISTING>define msim + target sim --board=stdeval1 --memory-region 0x34004000,0x8 + + rbreak cyg_test_exit + rbreak cyg_assert_fail +end</PROGRAMLISTING> +<PARA>You can then connect to the simulator by invoking the command <PROGRAMLISTING>msim</PROGRAMLISTING> on +the command line:</PARA> +<PROGRAMLISTING>(gdb) msim</PROGRAMLISTING> +<PARA>You can achieve the same effect by typing out the macro’s +content on the command line if necessary.</PARA> +</SECT1> + +<!-- ==================================================== --> + +<SECT1 id="setup-am33-stb"> +<TITLE>AM33 STB Hardware Setup</TITLE> +<PARA>The Matsushita AM33 STB System Reference Board may be used +in two modes: via a JTAG debugger, or by means of a GDB stub ROM.</PARA> +<SECT2> +<TITLE>Use with GDB Stub ROM</TITLE> +<PARA>The eCos Developer’s Kit package comes with a ROM +image which provides GDB support for +the Matsushita(R) AM33 STB System Reference Board. To install the +GDB stub ROM requires the use of the JTAG debugger and the Flash ROM +programming code available from Matsushita. An image of this ROM +is also provided at <filename>loaders/am33-stb/gdbload.bin</filename> under +the root of your eCos installation.</PARA> +<PARA>Ensure that there is a Flash ROM card in MAIN MEMORY SLOT <0>. +Follow the directions for programming a Flash ROM supplied with +the programming software.</PARA> +<PARA>The final programming of the ROM will need to be done with +a command similar to the following:</PARA> +<PROGRAMLISTING>fdown "gdbload.bin",0x80000000,16,1</PROGRAMLISTING> +<PARA>Once the ROM has been programmed, close down the JTAG debugger, +turn the STB off, and disconnect the JTAG cable. Ensure that the +hardware switches are in the following configuration:</PARA> +<PROGRAMLISTING>U U D D D U D D + +D = lower part of rocker switch pushed in +U = upper part of rocker switch pushed in</PROGRAMLISTING> +<PARA>This is also the configuration required by the Flash programming +code, so it should not be necessary to change these.</PARA> +<PARA>Restart the STB and the stub ROM will now be able to communicate +with <PRODUCTNAME>GDB</PRODUCTNAME>. eCos programs should be built +with RAM startup.</PARA> +<PARA>Programs can then be downloaded via a standard RS232 null +modem serial cable connected to the SERIAL1 connector on the STB +front panel (the AM33"s serial port 0). This line is programmed +to run at 38400 baud, 8 data bits, no parity and 1 stop bit (8-N-1) +with no flow control. A gender changer may also be required. Diagnostic +output will be output to GDB using the same connection.</PARA> +<PARA>This procedure also applies for programming ROM startup eCos +programs into ROM, given a binary format image of the program from<PROGRAMLISTING> mn10300-elf-objcopy.</PROGRAMLISTING></PARA> +</SECT2> +<SECT2> +<TITLE>Use with the JTAG debugger</TITLE> +<PARA>To use eCos from the JTAG debugger, executables must be built +with ROM startup and then downloaded via the JTAG debugger. For +this to work there must be an SDRAM memory card in SUB MEMORY SLOT <0> and +the hardware switches on the front panel set to the following: </PARA> +<PROGRAMLISTING>D U D D D U D D + +D = lower part of rocker switch pushed in +U = upper part of rocker switch pushed in</PROGRAMLISTING> +<PARA>Connect the JTAG unit and run the debugger as described in +the documentation that comes with it.</PARA> +<PARA>eCos executables should be renamed to have a “.out” extension +and may then be loaded using the debugger"s “l” or “lp” commands.</PARA> +<PARA>Diagnostic output generated by the program will be sent out +of the AM33"s serial port 0 which is connected to the SERIAL1 +connector on the STB front panel. This line is programmed to run +at 38400 baud, 8 data bits, no parity, and one stop bit (8-N-1) +with no flow control. Connection to the host computer should be +using a standard RS232 null modem serial cable. A gender changer +may also be required.</PARA> +</SECT2> +<SECT2> +<TITLE>Building the GDB stub ROM image</TITLE> +<PARA>eCos comes with a pre-built GDB stub ROM image for the AM33-STB +platform. This can be found at <filename>loaders/am33-stb/gdbload.bin</filename> relative +to the eCos installation directory.</PARA> +<PARA>If necessary, the ROM image can be re-built as follows:</PARA> +<ORDEREDLIST> +<LISTITEM> +<PARA> On Windows hosts, open a Bash session using +<EMPHASIS>Start->Programs->Red Hat eCos->eCos +Development Environment</EMPHASIS></PARA> +</LISTITEM> +<LISTITEM> +<PARA>Create a build directory and cd into it</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Run (all as one line): + +<PROGRAMLISTING>cygtclsh80 BASE_DIR/packages/pkgconf.tcl \ + --target=mn10300_am33 --platform stb --startup rom \ + --disable-kernel --disable-uitron --disable-libc --disable-libm \ + --disable-io --disable-io_serial --disable-wallclock +--disable-watchdog</PROGRAMLISTING> + </PARA> +<PARA>where BASE_DIR is the path to the eCos installation +directory.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Edit the configuration file +<filename>pkgconf/hal.h</filename> + in the build directory tree by ensuring the following configuration +options are set as follows: + +<PROGRAMLISTING>#define CYGDBG_HAL_DEBUG_GDB_INCLUDE_STUBS +#define CYGDBG_HAL_DEBUG_GDB_BREAK_SUPPORT +#undef CYGDBG_HAL_DEBUG_GDB_CTRLC_SUPPORT +#define CYGDBG_HAL_DEBUG_GDB_THREAD_SUPPORT +#define CYG_HAL_ROM_MONITOR</PROGRAMLISTING> + </PARA> +</LISTITEM> +<LISTITEM> +<PARA>Run: make</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Run: make -C hal/common/current/current/src/stubrom</PARA> +</LISTITEM> +<LISTITEM> +<PARA>The file +<filename>hal/common/current/src/stubrom</filename> + will be an ELF format executable of the ROM image. Use mn10300-elf-objcopy to +convert this to the appropriate format for loading into the Matsushita +FLASH ROM programmer, mode “binary” in this case: + +<PROGRAMLISTING>$ mn10300-elf-objcopy -O binary hal/common/current/src/stubrom/ \ + stubrom stubrom.img</PROGRAMLISTING></PARA> +</LISTITEM> +</ORDEREDLIST> +</SECT2> +</SECT1> + +<!-- ==================================================== --> + +<SECT1 id="setup-tx39-jmr3904"> +<TITLE>TX39 Hardware Setup</TITLE> +<PARA>The eCos Developer’s Kit package comes with a pair +of ROMs that provide GDB support for +the Toshiba JMR-TX3904 RISC processor reference board by way of CygMon. </PARA> +<PARA>Images of these ROMs are also provided at <filename>BASE_DIR/loaders/tx39-jmr3904/cygmon50.bin</filename> and <filename>BASE_DIR/loaders/tx39-jmr3904/cygmon66.bin</filename> for +50 MHz and 66 MHz boards respectively. The ROMs are installed to +sockets IC6 and IC7 on the memory daughterboard according to their +labels. Attention should be paid to the correct orientation of these +ROMs during installation.</PARA> +<PARA>The GDB stub allows communication with GDB using the serial +port (channel C) at connector PJ1. The communication parameters +are fixed at 38400 baud, 8 data bits, no parity bit, and 1 stop +bit (8-N-1). No handshaking is employed. Connection to the host +computer should be made using an RS232C null modem cable.</PARA> +<PARA>CygMon and eCos currently provide support for a 16Mbyte 60ns +72pin DRAM SIMM fitted to the PJ21 connector. Different size DRAMs +may require changes in the value stored in the DCCR0 register. This +value may be found near line 211 in <filename>hal/mips/arch/<replaceable>&Version;</replaceable>/src/vectors.S</filename> +in eCos, and near line 99 in + <filename>libstub/mips/tx39jmr/tx39jmr-power.S</filename> in +CygMon. eCos does not currently use the DRAM for any purpose itself, +so it is entirely available for application use.</PARA> +</SECT1> + +<!-- ==================================================== --> + +<SECT1 id="setup-tx39-sim"> +<TITLE>TX39 Architectural Simulator Setup</TITLE> +<PARA>The TX39 simulator is an architectural simulator which implements +all the features of the Toshiba TX39 needed to run eCos. The current +implementation provides accurate simulation of the instruction set, + interrupt controller, and timers, as well as having generic support +for diagnostic output, serial I/O, and exceptions.</PARA> +<PARA>In this release, you can run the same eCos binaries in the +simulator that can run on target hardware, if it is built for ROM +start-up.</PARA> +<PARA>To simplify connection to the simulator, you are advised to +create a GDB macro by putting the following code in your personal +GDB start-up file (gdb.ini on Windows and .gdbinit on UNIX).</PARA> +<PROGRAMLISTING>define tsim + target sim --board=jmr3904pal --memory-region 0xffff8000,0x900 \ + --memory-region 0xffffe000,0x4 \ + --memory-region 0xb2100000,0x4 + rbreak cyg_test_exit + rbreak cyg_assert_fail +end</PROGRAMLISTING> +<PARA>You can then connect to the simulator by invoking the command <command>tsim</command> on +the command line:</PARA> +<PROGRAMLISTING>(gdb) tsim</PROGRAMLISTING> +<PARA>You can achieve the same effect by typing out the macro’s +content on the command line if necessary.</PARA> +</SECT1> + +<!-- ==================================================== --> + +<SECT1 id="setup-tx49-ref4955"> +<TITLE>TX49 Hardware Setup</TITLE> +<PARA>The eCos installation CD contains a copy of the eCos GDB stubs +in SREC format which must be programmed into the board’s +FLASH memory.</PARA> +<SECT2> +<TITLE>Preparing the GDB stubs</TITLE> +<PARA>These stub preparation steps are not strictly necessary as +the eCos distribution ships with pre-compiled stubs in the directory <filename>loaders/tx49-ref4955</filename> relative +to the installation root.</PARA> +<SECT3> +<TITLE>Building the GDB stub image with the eCos Configuration Tool</TITLE> +<ORDEREDLIST> +<LISTITEM> +<PARA> Start with a new document - selecting the +<EMPHASIS>File->New</EMPHASIS> + menu item if necessary to do this.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Choose the +<EMPHASIS>Build->Templates</EMPHASIS> + menu item, and then select the TX49 REF4955 hardware.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>While still displaying the +<EMPHASIS>Build->Templates</EMPHASIS> + dialog box, select the stubs package template to build a GDB stub. +Click +<EMPHASIS>OK</EMPHASIS>.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Build eCos stubs using +<EMPHASIS>Build->Library</EMPHASIS>.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>When the build completes, the image files can be found +in the bin/ subdirectory of the install tree. GDB stub +images have the prefix gdb_module.</PARA> +</LISTITEM> +</ORDEREDLIST> +</SECT3> +<SECT3> +<TITLE> Building the GDB stub image with ecosconfig</TITLE> +<ORDEREDLIST> +<LISTITEM> +<PARA> Make an empty directory to contain the build tree, + and cd into it.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>To build a GDB stub ROM image, enter the command:</PARA> +<PROGRAMLISTING>$ ecosconfig new ref4955 stubs </PROGRAMLISTING> +</LISTITEM> +<LISTITEM> +<PARA>Enter the commands:</PARA> +<PROGRAMLISTING>$ ecosconfig tree +$ make</PROGRAMLISTING> +</LISTITEM> +<LISTITEM> +<PARA>When the build completes, the image files can be found +in the bin/ subdirectory of the install tree. GDB stub +images have the prefix gdb_module.</PARA> +</LISTITEM> +</ORDEREDLIST> +</SECT3> +</SECT2> +<SECT2> +<TITLE> Installing GDB stubs into FLASH</TITLE> +<PARA>Boot into the board’s firmware in little-endian mode:</PARA> +<PARA>Set the switches like this: </PARA> +<PARA>SW1: 10000000 (first lever up, the rest down) +SW2: 10000010</PARA> +<PARA>Connect serial cable on the lower connector, configure terminal +emulator for 38400, 8-N-1.</PARA> +<PARA>When booting the board, you should get this prompt:</PARA> +<PROGRAMLISTING>HCP5 rev 0.9B . +HCP5?</PROGRAMLISTING> +<PARA>Select o (option), a (FLASH) and b (boot write). You should +see this:</PARA> +<PROGRAMLISTING>Boot ROM Write +ROM address-ffffffffbd000000, Boot Bus-[32bit] +ID2 0 4 ffffffffa002ad40 +zzz SS-40000 IV-1 CS-20000 CC-2 +Flash ROM-[28F640J5], [16bit chip] * 2 * 1 +Block size-00040000 count-64 +ROM adr ffffffffbd000000-ffffffffbe000000 mask-00fc0000 +Send Srecord file sa=00000000 size=ffffffffffffffff +ra=fffffffffe000000 + </PROGRAMLISTING> +<PARA>Now send the stub SREC data down to the board using the terminal + emulator’s ‘send ASCII’ (or similar) +functionality. </PARA> +<PARA>Red Hat has experienced some sensitivity to how fast the data +is written to the board. Under Windows you should configure Minicom +to use a line delay of 100 milliseconds. Under Linux, use the slow_cat.tcl + script:</PARA> +<PROGRAMLISTING>% cd BASE_DIR/packages/hal/mips/ref4955/<replaceable>&Version;</replaceable>/misc +% slow_cat.tcl < [path]/gdb_module.srec > /dev/ttyS0</PROGRAMLISTING> +<PARA>Power off the board, and change it to boot the GDB stubs in +big-endian mode by setting the switches like this:</PARA> +<PARA>SW1: 00000000 (all levers down) +SW2: 10001010</PARA> +<PARA>The GDB stubs allow communication with GDB using the serial +port at connector PJ7A (lower connector). The communication parameters +are fixed at 38400 baud, 8 data bits, no parity bit and 1 stop +bit (8-N-1). No flow control is employed. Connection to the host +computer should be made using a straight through serial cable.</PARA> +</SECT2> +</SECT1> + +<!-- ==================================================== --> + +<SECT1 id="setup-vr4300-vrc4373"> +<TITLE>VR4300 Hardware Setup</TITLE> +<PARA>The eCos Developer’s Kit package comes with an EPROM +which provides GDB support for the NEC +VRC4373 evaluation board. An image of this EPROM is also provided +at <filename>loaders/vr4300-vrc4373/gdbload.bin</filename> under +the root of your eCos installation.</PARA> +<PARA>The EPROM is installed to socket U12 on the board. Attention +should be paid to the correct orientation of the EPROM during installation. +Only replace the board"s existing ROM using a proper PLCC +extraction tool, as the socket would otherwise risk getting damaged. </PARA> +<PARA>The GDB stub in the EPROM allows communication with GDB using +the serial port at connector J1. The communication parameters are +fixed at 38400 baud, 8 data bits, no parity bit and 1 stop bit (8-N-1). +No flow control is employed. Connection to the host computer should +be made using a straight-through serial cable. </PARA> +</SECT1> +<SECT1 id="setup-vr4300-vrc4375"> +<TITLE>VRC4375 Hardware Setup</TITLE> +<PARA>For information about setting up the VRC4375 to run with RedBoot, +consult the RedBoot User"s Guide. If using serial debugging, +the serial line runs at 38400 baud 8-N-1 and should be connected +to the debug host using the cable supplied with the board.</PARA> +</SECT1> +<SECT1 id="setup-mips-atlasmalta"> +<TITLE>Atlas/Malta Hardware Setup</TITLE> +<PARA>For information about setting up the Atlas and Malta boards to +run with RedBoot, consult the RedBoot User"s Guide.</PARA> +</SECT1> +<SECT1 id="setup-ppc-cogent"> +<TITLE>PowerPC Cogent Hardware Setup</TITLE> +<PARA>The eCos Developer’s Kit package comes with an EPROM +which provides GDB support for the Cogent +evaluation board. An image of this EPROM is also provided at + <filename>loaders/powerpc-cogent/gdbload.bin</filename> under +the root of your eCos installation. The same EPROM and image can +be used on all three supported daughterboards: CMA287-23 (MPC823), +CMA287-50 (MPC850), and CMA286-60 (MPC860).</PARA> +<PARA>The EPROM is installed to socket U4 on the board. Attention +should be paid to the correct orientation of the EPROM during installation. </PARA> +<PARA>If you are going to burn a new EPROM using the binary image, +be careful to get the byte order correct. It needs to be big-endian. +If the EPROM burner software has a hex-editor, check that the first +few bytes of the image look like: </PARA> +<PROGRAMLISTING>00000000: 3c60 fff0 6063 2000 7c68 03a6 4e80 0020 <`..`c.|h..N.. </PROGRAMLISTING> +<PARA>If the byte order is wrong you will see 603c instead of 3c60 +etc. Use the EPROM burner software to make a byte-swap before you +burn to image to the EPROM. </PARA> +<PARA>If the GDB stub EPROM you burn does not work, try reversing +the byte-order, even if you think you have it the right way around. +At least one DOS-based EPROM burner program is known to have the +byte-order upside down.</PARA> +<PARA>The GDB stub in the EPROM allows communication with GDB using +the serial port at connector P12 (CMA101) or P3 (CMA102). The communication parameters +are fixed at 38400 baud, 8 data bits, no parity bit and 1 stop bit +(8-N-1). No flow control is employed. Connection to the host computer +should be made using a dedicated serial cable as specified in the +Cogent CMA manual.</PARA> +<SECT2> +<TITLE>Installing the Stubs into ROM</TITLE> +<SECT3> +<TITLE>Preparing the Binaries</TITLE> +<PARA>These two binary preparation steps are not strictly necessary +as the eCos distribution ships with pre-compiled binaries in the +directory <filename>loaders/powerpc-cogent</filename> relative to the installation +root.</PARA> +<SECT4> +<TITLE>Building the ROM images with the eCos Configuration Tool</TITLE> +<ORDEREDLIST> +<LISTITEM> +<PARA>Start with a new document - selecting the +<EMPHASIS>File->New</EMPHASIS> + menu item if necessary to do this.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Choose the +<EMPHASIS>Build->Templates</EMPHASIS> + menu item, and then select the PowerPC CMA28x hardware.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>While still displaying the +<EMPHASIS>Build->Templates</EMPHASIS> + dialog box, select the “stubs” package template +to build a GDB stub. Click +<EMPHASIS>OK</EMPHASIS>.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Build eCos using +<EMPHASIS>Build->Library</EMPHASIS>.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>When the build completes, the image files can be found +in the bin/ subdirectory of the install tree. GDB stub +ROM images have the prefix “gdb_module”.</PARA> +</LISTITEM> +</ORDEREDLIST> +</SECT4> +<SECT4> +<TITLE>Building the ROM images with ecosconfig</TITLE> +<ORDEREDLIST> +<LISTITEM> +<PARA>Make an empty directory to contain the build tree, +and cd into it.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>To build a GDB stub ROM image, enter the command: + +<PROGRAMLISTING>$ ecosconfig new cma28x stubs </PROGRAMLISTING></PARA> +</LISTITEM> +<LISTITEM> +<PARA>Enter the commands: + +<PROGRAMLISTING>$ ecosconfig tree +$ make</PROGRAMLISTING> + </PARA> +</LISTITEM> +<LISTITEM> +<PARA>When the build completes, the image files can be found +in the bin/ subdirectory of the install tree. GDB stub +ROM images have the prefix “gdb_module”.</PARA> +</LISTITEM> +</ORDEREDLIST> +</SECT4> +</SECT3> +<SECT3> +<TITLE> Installing the Stubs into ROM or FLASH</TITLE> +<ORDEREDLIST> +<LISTITEM> +<PARA>Program the binary image file gdb_module.bin +into ROM or FLASH referring to the instructions of your ROM programmer.</PARA> +</LISTITEM> +<LISTITEM> +<PARA> Plug the ROM/FLASH into socket U4 as described +at the beginning of this <EMPHASIS>Hardware Setup</EMPHASIS> section.</PARA> +</LISTITEM> +</ORDEREDLIST> +</SECT3> +</SECT2> +</SECT1> +<SECT1 id="setup-ppc-mbx860"> +<TITLE>PowerPC MBX860 Hardware Setup</TITLE> +<PARA>The eCos Developer’s Kit package comes with an EPROM +which provides GDB support for the Motorola +PowerPC MBX860 evaluation board. An image of this EPROM is also +provided at <filename>loaders/powerpc-mbx/gdbload.bin</filename> under +the root of your eCos installation.</PARA> +<PARA>The EPROM is installed to socket XU1 on the board. Attention +should be paid to the correct orientation of the EPROM during installation. +Only replace the board"s existing ROM using a proper PLCC +extraction tool, as the socket would otherwise risk getting damaged.</PARA> +<PARA>The GDB stub in the EPROM allows communication with GDB using +the serial port at connector SMC1/COM1. The communication +parameters are fixed at 38400 baud, 8 data bits, no parity bit and +1 stop bit (8-N-1). No flow control is employed. Connection to the +host computer should be made using a suitable serial cable.</PARA> +<PARA>In order to make the board execute the EPROM that you just +installed (rather than the on-board FLASH memory), it may be necessary +move some links on the board. Specifically, ensure that link J4 +is in position 1-2. If in doubt, refer to the MBX documentation +from Motorola, ensuring that Boot Port Size=8 Bits/ROM +for BOOT (CS#7), in their terminology.</PARA> +<SECT2> +<TITLE>Installing the Stubs into FLASH</TITLE> +<SECT3> +<TITLE>Preparing the Binaries</TITLE> +<PARA>These two binary preparation steps are not strictly necessary +as the eCos distribution ships with pre-compiled binaries in the +directory <filename>loaders/powerpc-mbx</filename> relative to the installation +root.</PARA> +<SECT4> +<TITLE>Building the ROM images with the eCos Configuration Tool</TITLE> +<ORDEREDLIST> +<LISTITEM> +<PARA>Start with a new document - selecting the +<EMPHASIS>File->New</EMPHASIS> + menu item if necessary to do this.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Choose the +<EMPHASIS>Build->Templates</EMPHASIS> + menu item, and then select the PowerPC Motorola MBX860/821 +hardware.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>While still displaying the +<EMPHASIS>Build->Templates</EMPHASIS> + dialog box, select the “stubs” package template +to build a GDB stub. Click +<EMPHASIS>OK</EMPHASIS>.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Build eCos using +<EMPHASIS>Build->Library</EMPHASIS>. </PARA> +</LISTITEM> +<LISTITEM> +<PARA>When the build completes, the image files can be found +in the bin/ subdirectory of the install tree. GDB stub +ROM images have the prefix “gdb_module”.</PARA> +</LISTITEM> +</ORDEREDLIST> +</SECT4> +<SECT4> +<TITLE>Building the ROM images with ecosconfig</TITLE> +<ORDEREDLIST> +<LISTITEM> +<PARA>Make an empty directory to contain the build tree, +and cd into it.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>To build a GDB stub ROM image, enter the command: + +<PROGRAMLISTING>$ ecosconfig new mbx stubs </PROGRAMLISTING></PARA> +</LISTITEM> +<LISTITEM> +<PARA>Enter the commands: + +<PROGRAMLISTING>$ ecosconfig tree +$ make </PROGRAMLISTING></PARA> +</LISTITEM> +<LISTITEM> +<PARA>When the build completes, the image files can be found +in the bin/ subdirectory of the install tree. GDB stub +ROM images have the prefix “gdb_module”.</PARA> +</LISTITEM> +</ORDEREDLIST> +</SECT4> +</SECT3> +<SECT3> +<TITLE> Installing the Stubs into ROM</TITLE> +<ORDEREDLIST> +<LISTITEM> +<PARA> Program the binary image file gdb_module.bin +into ROM or FLASH referring to the instructions of your ROM programmer.</PARA> +</LISTITEM> +<LISTITEM> +<PARA> Plug the ROM/FLASH into socket XU1 as described +near the beginning of this <EMPHASIS>Hardware Setup</EMPHASIS> section.</PARA> +</LISTITEM> +</ORDEREDLIST> +</SECT3> +<SECT3> +<TITLE>Installing the Stubs into FLASH</TITLE> +<PARA>This assumes you have EPPC-Bug in the on-board FLASH. This +can be determined by setting up the board according to the below +instructions and powering up the board. The EPPC-Bug prompt should +appear on the SMC1 connector at 9600 baud, 8N1.</PARA> +<ORDEREDLIST> +<LISTITEM> +<PARA>Set jumper 3 to 2-3 [allow XU2 FLASH to +be programmed]</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Set jumper 4 to 2-3 [boot EPPC-Bug]</PARA> +</LISTITEM> +</ORDEREDLIST> +<SECT4> +<TITLE> Program FLASH</TITLE> +<ORDEREDLIST> +<LISTITEM> +<PARA> Prepare EPPC-Bug for download:</PARA> +<PROGRAMLISTING>EPPC-Bug>lo 0</PROGRAMLISTING> +<PARA>At this point the monitor is ready for input. It will not return +the prompt until the file has been downloaded.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Use the terminal emulator’s ASCII download feature +(or a simple clipboard copy/paste operation) to download +the gdb_module.srec data. + +Note that on Linux, Minicom’s ASCII download feature seems +to be broken. A workaround is to load the file into Emacs (or another +editor) and copy the full contents to the clipboard. Then press +the mouse paste-button (usually the middle one) over the Minicom +window.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Program the FLASH with the downloaded data: + +<PROGRAMLISTING>EPPC-Bug>pflash 40000 60000 fc000000</PROGRAMLISTING></PARA> +</LISTITEM> +<LISTITEM> +<PARA>Switch off the power, and change jumper 4 to 1-2. Turn +on the power again. The board should now boot using the newly programmed +stubs.</PARA> +</LISTITEM> +</ORDEREDLIST> +</SECT4> +</SECT3> +</SECT2> +</SECT1> +<SECT1 id="setup-ppc-sim"> +<TITLE>PowerPC Architectural Simulator Setup</TITLE> +<PARA>The PowerPC simulator is an architectural simulator which +implements all the features of the PowerPC needed to run eCos. The +current implementation provides accurate simulation of the instruction +set and timers, as well as having generic support for diagnostic +output and exceptions.</PARA> +<PARA>The simulator also allows devices to be simulated, but no +device simulation support has been defined for the serial device +drivers in this release.</PARA> +<PARA>To simplify connection to the simulator, you are advised to +create a GDB macro by putting the following code in your personal +GDB start-up file (gdb.ini on Windows and .gdbinit on UNIX).</PARA> +<PROGRAMLISTING>define psim + target sim -o ’/iobus/pal@0xf0001000/reg 0xf0001000 32’ + rbreak cyg_test_exit + rbreak cyg_assert_fail +end</PROGRAMLISTING> +<PARA>You can then connect to the simulator by invoking the command <command>psim</command> on +the command line:</PARA> +<PROGRAMLISTING>(gdb) psim</PROGRAMLISTING> +<PARA>You can achieve the same effect by typing out the macro’s +content on the command line if necessary.</PARA> +<NOTE> +<PARA>The PowerPC simulator cannot execute binaries built for any +of the supported hardware targets. You must generate a configuration +using the PowerPC simulator platform: +<PROGRAMLISTING>$ ecosconfig new psim</PROGRAMLISTING> + or some such.</PARA> +</NOTE> +</SECT1> +<SECT1 id="setup-sparclite-sleb"> +<TITLE>SPARClite Hardware Setup</TITLE> +<PARA>The eCos Developer’s Kit package comes with a ROM +which provides GDB support for the Fujitsu SPARClite Evaluation +Board by way of CygMon<PRODUCTNAME>. </PRODUCTNAME></PARA> +<PARA>An image of this ROM is also provided at + <filename>BASE_DIR/loaders/sparclite-sleb/cygmon.bin.</filename> The +ROM is installed in socket IC9 on the evaluation board. Attention +should be paid to the correct orientation of the ROM during installation.</PARA> +<PARA>The GDB stub allows communication with GDB using a TCP channel +via the ethernet port at connector J5.</PARA> +<SECT2> +<TITLE><!-- <index></index> --><!-- <xref> -->Ethernet Setup</TITLE> +<PARA>The ethernet setup is described in the board’s manual, +but here is a recapitulation.</PARA> +<PARA>Set the board’s ethernet address using SW1 on the +motherboard:</PARA> +<PROGRAMLISTING> SW1-4 SW1-3 SW1-2 SW1-1 Ethernet Address + ----- ----- ----- ----- ---------------- + OFF OFF OFF OFF No ethernet, use serial + OFF OFF OFF ON 00:00:0E:31:00:01 + OFF OFF ON OFF 00:00:0E:31:00:02 + OFF OFF ON ON 00:00:0E:31:00:03 + OFF ON OFF OFF 00:00:0E:31:00:04 + OFF ON OFF ON 00:00:0E:31:00:05 + OFF ON ON OFF 00:00:0E:31:00:06 + OFF ON ON ON 00:00:0E:31:00:07 + ON OFF OFF OFF 00:00:0E:31:00:08 + ON OFF OFF ON 00:00:0E:31:00:09 + ON OFF ON OFF 00:00:0E:31:00:0A + ON OFF ON ON 00:00:0E:31:00:0B + ON ON OFF OFF 00:00:0E:31:00:0C + ON ON OFF ON 00:00:0E:31:00:0D + ON ON ON OFF 00:00:0E:31:00:0E + ON ON ON ON 00:00:0E:31:00:0F</PROGRAMLISTING> +<SECT3><!-- <index></index> --> +<TITLE>BOOTP/DHCP service on Linux</TITLE> +<PARA>Configure the BOOTP or DHCP server on the network to recognize +the evaluation board’s ethernet address so it can assign +the board an IP address. Below is a sample DHCP server configuration +from a Linux system (<filename>/etc/dhcpd.conf</filename>). +It shows a setup for three evaluation boards.</PARA> +<PROGRAMLISTING># +# DHCP server configuration. +# +allow bootp; + +subnet 192.168.1.0 netmask 255.255.255.0 { + host mb831evb { + hardware ethernet 00:00:0e:31:00:01; + fixed-address mb831evb; + } + host mb832evb { + hardware ethernet 00:00:0e:31:00:02; + fixed-address mb832evb; + } + host mb833evb { + hardware ethernet 00:00:0e:31:00:03; + fixed-address mb833evb; + } +} </PROGRAMLISTING> +</SECT3> +<SECT3><!-- <index></index> --> +<TITLE>BOOTP/DHCP boot process</TITLE> +<PARA>Even when configured to use a TCP channel, CygMon will still +print a boot message to the serial channel. If the BOOTP process +was successful and an IP address was found, a message “BOOTP +found xxx.xxx.xxx.xxx” will be printed where xxx.xxx.xxx.xxx +is the IP address assigned by the BOOTP or DHCP server. If the BOOTP +process fails, a message indicating failure will be printed and +the serial port will be used as the debug channel.</PARA> +<PARA>Once the board finds an IP address it will respond to ICMP +echo request packets (ping). This gives a simple means to test the +health of the board.</PARA> +<PARA>As described in “Ethernet Setup” on page 72, +it should now be possible to connect to the SPARClite board from +within GDB by using the command:</PARA> +<PROGRAMLISTING>(gdb) target remote <host>:1000</PROGRAMLISTING> +</SECT3> +</SECT2> +<SECT2> +<TITLE>Serial Setup</TITLE> +<PARA>The CygMon stubs also allow communication with GDB by way +of the serial port at connector CON1. The communication parameters +are fixed at 19200 baud, 8 data bits, no parity bit and 1 stop bit +(8-N-1). No flow control is employed. Connection to the host computer +should be made using a null modem cable. A gender changer may also +be required.</PARA> +</SECT2> +</SECT1> +<SECT1 id="setup-sparclite-sim"> +<TITLE>SPARClite Architectural Simulator Setup</TITLE> +<PARA>The ESA SPARClite simulator is an architectural simulator +which implements all the features of the SPARClite needed to run +eCos. The current implementation provides accurate simulation of +the instruction set, interrupt controller, and timers, as well as +having generic support for diagnostic output and exceptions.</PARA> +<PARA>Note that the ESA SPARClite simulator is unsupported, but +is included in the release as a convenience.</PARA> +<PARA>To simplify connection to the simulator, you are advised to +create a GDB macro by putting the following code in your personal +GDB start-up file (gdb.ini on Windows and .gdbinit on UNIX).</PARA> +<PROGRAMLISTING>define ssim + target sim -nfp -sparclite -dumbio + rbreak cyg_test_exit + rbreak cyg_assert_fail +end</PROGRAMLISTING> +<PARA>You can then connect to the simulator by invoking the command <command>ssim</command> on +the command line:</PARA> +<PROGRAMLISTING>(gdb) ssim</PROGRAMLISTING> +<PARA>You can achieve the same effect by typing out the macro’s +content on the command line if necessary.</PARA> +</SECT1> +<SECT1 ID="setup-arm-pid"> +<TITLE><!-- <index></index> --><!-- <xref> -->ARM PID Hardware Setup</TITLE> +<PARA>eCos comes with two ROM images that provide GDB support for +the ARM PID board. The first ROM image provides a port of the CygMon +ROM monitor, which includes a command-line interface and a GDB remote +stub. The second ROM image provides a remote GDB stub only, which +is a minimal environment for downloading and debugging eCos programs +solely using GDB.</PARA> +<PARA>eCos, CygMon and the GDB stubs all support the PID fitted +with both ARM7T and ARM9 daughterboards. CygMon and the stubs can +be programmed into either the programmable ROM (U12) or the FLASH +(U13). Pre-built forms of both ROM images are provided in the directory +loaders/arm-pid under the root of your eCos installation, +along with a tool that will program the stubs into the FLASH memory on +the board. CygMon images are prefixed with the name 'cygmon' and +GDB stub ROM images are given the prefix 'gdb_module'. +Images may be provided in a number of formats including ELF (.img +extension), binary (.bin extension) and SREC (.srec extension). +Note that some unreliability has been experienced in downloading +files using Angel 1.00. Angel 1.02 appears to be more robust in +this application.</PARA> +<SECT2> +<TITLE>Installing the Stubs into FLASH</TITLE> +<SECT3> +<TITLE>Preparing the Binaries</TITLE> +<PARA>These two binary preparation steps are not strictly necessary +as the eCos distribution ships with pre-compiled binaries in the +directory loaders/arm-pid relative to the installation +root.</PARA> +</SECT3> +<SECT3> +<TITLE>Building the ROM images with the eCos Configuration Tool</TITLE> +<ORDEREDLIST> +<LISTITEM> +<PARA>Start with a new document - selecting the +<EMPHASIS>File</EMPHASIS>-><EMPHASIS>New</EMPHASIS> + menu item if necessary to do this.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Choose the +<EMPHASIS>Build</EMPHASIS> +-> +<EMPHASIS>Templates</EMPHASIS> + menu item, and then select the ARM PID hardware.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>While still displaying the +<EMPHASIS>Build</EMPHASIS> +-> +<EMPHASIS>Templates</EMPHASIS> + dialog box, select either the "stubs" package template to build +a GDB stub image, or the "cygmon" template to build the CygMon ROM +Monitor. Click +<EMPHASIS>OK</EMPHASIS>.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Build eCos using +<EMPHASIS>Build</EMPHASIS> +-> +<EMPHASIS>Library</EMPHASIS></PARA> +</LISTITEM> +<LISTITEM> +<PARA>When the build completes, the image files can be found +in the bin/ subdirectory of the install tree. GDB stub +ROM images have the prefix "gdb_module". CygMon images +have the prefix "cygmon".</PARA> +</LISTITEM> +</ORDEREDLIST> +</SECT3> +<SECT3> +<TITLE>Building the ROM images with ecosconfig</TITLE> +<!-- <PARA>(See <XREF LINKEND="USING-ECOSCONFIG-ON-UNIX">)</PARA> --> +<ORDEREDLIST> +<LISTITEM> +<PARA> Make an empty directory to contain the build tree, +and cd into it.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>To build a GDB stub ROM image, enter the command:</PARA> +<PROGRAMLISTING>$ ecosconfig new pid stubs</PROGRAMLISTING> +<PARA>or to build a CygMon ROM monitor image, enter the command:</PARA> +<PROGRAMLISTING>$ ecosconfig new pid cygmon</PROGRAMLISTING> +</LISTITEM> +<LISTITEM> +<PARA>Enter the commands:</PARA> +<PROGRAMLISTING>$ ecosconfig tree +$ make</PROGRAMLISTING> +</LISTITEM> +<LISTITEM> +<PARA>When the build completes, the image files can be found +in the bin/ subdirectory of the install tree. GDB stub +ROM images have the prefix "gdb_module". CygMon images +have the prefix "cygmon".</PARA> +</LISTITEM> +</ORDEREDLIST> +</SECT3> +<SECT3> +<TITLE>Building the FLASH Tool with the eCos Configuration Tool</TITLE> +<ORDEREDLIST> +<LISTITEM> +<PARA>Start with a new document - selecting the +<EMPHASIS>File</EMPHASIS>-><EMPHASIS>New</EMPHASIS> + menu item if necessary to do this.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Choose the +<EMPHASIS>Build</EMPHASIS>-><EMPHASIS>Templates</EMPHASIS> + menu item, and then select the ARM PID hardware.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Enable the "Build flash programming tool" option in the +ARM PID HAL (CYGBLD_BUILD_FLASH_TOOL) +and resolve any resulting configuration conflicts.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Build eCos using +<EMPHASIS>Build</EMPHASIS> +-> +<EMPHASIS>Library</EMPHASIS></PARA> +</LISTITEM> +<LISTITEM> +<PARA>When the build completes, the FLASH tool image file can +be found in the bin/ subdirectory of the install tree, +with the prefix "prog_flash"</PARA> +</LISTITEM> +</ORDEREDLIST> +</SECT3> +<SECT3> +<TITLE>Building the FLASH Tool with ecosconfig</TITLE> +<!-- <PARA>(See <XREF LINKEND="USING-ECOSCONFIG-ON-UNIX">)</PARA> --> +<ORDEREDLIST> +<LISTITEM> +<PARA> Make an empty directory to contain the build tree, +and cd into it + </PARA> +</LISTITEM> +<LISTITEM> +<PARA>Enter the command:</PARA> +<PROGRAMLISTING>$ ecosconfig new pid</PROGRAMLISTING> +</LISTITEM> +<LISTITEM> +<PARA>Edit the file ecos.ecc and enable the option CYGBLD_BUILD_FLASH_TOOL +by uncommenting its user_value property and setting it +to 1.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Enter the commands:</PARA> +<PROGRAMLISTING>$ ecosconfig resolve</PROGRAMLISTING> +<PARA>[there will be some output]</PARA> +<PROGRAMLISTING>$ ecosconfig tree +$ make</PROGRAMLISTING> +</LISTITEM> +<LISTITEM> +<PARA>When the build completes, the FLASH tool image file can +be found in the bin/ subdirectory of the install tree, +with the prefix "prog_flash"</PARA> +</LISTITEM> +</ORDEREDLIST> +</SECT3> +<SECT3> +<TITLE>Prepare the Board for FLASH Programming</TITLE> +<PARA>Each time a new image is to be programmed in the FLASH, the +jumpers on the board must be set to allow Angel to run:</PARA> +<ORDEREDLIST> +<LISTITEM> +<PARA> Set jumper 7-8 on LK6 [using the Angel code +in the 16 bit EPROM]</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Set jumper 5-6 on LK6 [select 8bit ROM mode]</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Set jumper LK18 [ROM remap - this is +also required for eCos]</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Set S1 to 0-0-1-1 [20MHz operation]</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Open jumper LK4 [enable little-endian operation] + +Attach a serial cable from Serial A on the PID board to connector +1 on the development system. This is the cable through which the +binaries will be downloaded. Attach a serial cable from Serial B +on the PID board to connector 2 on the development system (or any +system that will work as a terminal). Through this cable, the FLASH +tool will write its instructions (at 38400 baud).</PARA> +</LISTITEM> +</ORDEREDLIST> +</SECT3> +<SECT3> +<TITLE>Program the FLASH</TITLE> +<ORDEREDLIST> +<LISTITEM> +<PARA>Download the FLASH ROM image onto the PID board. For +example. for the GDB stubs image: + +<PROGRAMLISTING>bash$ arm-elf-gdb -nw gdb_module.img +GNU gdb 4.18-DEVTOOLSVERSION +Copyright 1998 Free Software Foundation, Inc. +GDB is free software, covered by the GNU General Public License, +and you are welcome to change it and/or distribute copies +of it under certain conditions. Type "show copying" to see the conditions. +There is absolutely no warranty for GDB. Type "show warranty" for details. +This GDB was configured as "--host=i586-pc-cygwin32 --target=arm-elf". +(no debugging symbols found)... +(gdb) target rdi s=com1 +Angel Debug Monitor for PID (Built with Serial(x1), Parallel, DCC) 1.00 +(Advanced RISC Machines SDT 2.10) +Angel Debug Monitor rebuilt on Jan 20 1997 at 02:33:43 +Connected to ARM RDI target. +(gdb) load +Loading section .rom_vectors, size 0x44 lma 0x60000 +Loading section .text, size 0x1f3c lma 0x60044 +Loading section .rodata, size 0x2c lma 0x61f80 +Loading section .data, size 0x124 lma 0x61fac +Start address 0x60044 , load size 8400 +Transfer rate: 5169 bits/sec. +(gdb) q +The program is running. Exit anyway? (y or n) y </PROGRAMLISTING> + +<NOTE> +<PARA> On a UNIX or Linux system, the serial port must be + /dev/ttyS0 instead of COM1. + You need to make sure that the /dev/ttyS0 files +have the right permissions: +<SCREEN>$ su + Password: + # chmod o+rw /dev/ttyS0* + # exit + </SCREEN> +If you are programming the GDB stub image, it will now be located +at 0x60000..0x64000. If you are programming the Cygmon ROM Monitor, +it will be located at 0x60000..0x80000.</PARA> +</NOTE></PARA> +</LISTITEM> +<LISTITEM> +<PARA>Now download the FLASH programmer tool</PARA> +<PROGRAMLISTING>bash$ arm-elf-gdb prog_flash.img +GNU gdb 4.18-DEVTOOLSVERSION +Copyright 1998 Free Software Foundation, Inc. +GDB is free software, covered by the GNU General Public License, +and you are welcome to change it and/or distribute +copies of it under certain conditions. Type "show copying" to see +the conditions. There is absolutely no warranty for GDB. Type "show +warranty" for details. +This GDB was configured as "--host=i586-pc-cygwin32 --target=arm-elf". +(gdb) target rdi s=com1 +Angel Debug Monitor for PID (Built with Serial(x1), Parallel, DCC) 1.00 +(Advanced RISC Machines SDT 2.10) +Angel Debug Monitor rebuilt on Jan 20 1997 at 02:33:43 +Connected to ARM RDI target. +(gdb) load +Loading section .rom_vectors, size 0x44 lma 0x40000 +Loading section .text, size 0x44a4 lma 0x40044 +Loading section .rodata, size 0x318 lma 0x444e8 +Loading section .data, size 0x1c8 lma 0x44800 +Start address 0x40044 , load size 18888 +Transfer rate: 5596 bits/sec. +(gdb) c</PROGRAMLISTING> +</LISTITEM> +<LISTITEM> +<PARA>The FLASH tool will output some text on the board serial +port B at 38400 baud:</PARA> +<PROGRAMLISTING>ARM +eCos + +FLASH here! +manuf: 8, device: 40 +Error: Wrong Manufaturer: 08 +... Please change FLASH jumper</PROGRAMLISTING> +</LISTITEM> +<LISTITEM> +<PARA>This text is repeated until you remove the jumper 7-8 +on LK6. Then the output will be:</PARA> +<PROGRAMLISTING>manuf: 1F, device: A4 +AT29C040A recognised +About to program FLASH using data at 60000..64000 +*** Press RESET now to abort!</PROGRAMLISTING> +</LISTITEM> +<LISTITEM> +<PARA> You have about 10 seconds to abort the operation by pressing +reset. After this timeout, the FLASH programming happens:</PARA> +<SCREEN>...Programming FLASH +All done!</SCREEN> +</LISTITEM> +<LISTITEM> +<PARA>Quit/kill the GDB process, which will hang.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Next time you reset the board, the stub will be in control, +communicating on Serial A at 38400 baud.</PARA> +</LISTITEM> +</ORDEREDLIST> +<NOTE> +<PARA>If you do not have two serial ports available on your host +computer, you may still verify the FLASH programming completed successfully +by quitting/killing the GDB process after running "c" in +step 2 above. Then switch the serial cable on the PID from Serial +A to Serial B and run a terminal emulator on the host computer. +In a few seconds you should see the the repeated text described +in step 2 above and you may continue the remaining steps as normal.</PARA> +</NOTE> +</SECT3> +<SECT3> +<TITLE>Programming the FLASH for big-endian mode</TITLE> +<PARA>The process is almost identical to the previous instructions +which apply to a PID board running in little-endian mode only.</PARA> +<PARA>The only adjustments to make are that if programming a <EMPHASIS>GDB</EMPHASIS> stub +ROM image (or CygMon ROM monitor image), you must enable the option "Use +Big-endian mode" in the <EMPHASIS>eCos Configuration Tool</EMPHASIS> (CYGHWR_HAL_ARM_BIGENDIAN +if using ecosconfig and editing ecos.ecc).</PARA> +<PARA>When programming the FLASH there are two options:</PARA> +<ORDEREDLIST> +<LISTITEM> +<PARA>Program FLASH using the little-endian FLASH tool. After +powering off, replace the ROM controller with the special big-endian +version which can be acquired from ARM. (This has not been tested +by Red Hat).</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Use a special big-endian version of the FLASH tool which +byte-swaps all the words as they are written to the FLASH.</PARA> +</LISTITEM> +</ORDEREDLIST> +<PARA>Build this tool by enabling the "Build flash programming tool +for BE images on LE boards" option (CYGBLD_BUILD_FLASH_TOOL_BE), +resulting in a utility with the prefix "prog_flash_BE_image_LE_system" +which should be used instead of "prog_flash".</PARA> +<PARA>Note that there is a limitation to this method: no sub-word +data can be read from the ROM. To work around this, the .rodata +section is folded into the .data section and thus copied to RAM +before the system starts.</PARA> +<PARA>Given that Thumb instructions are 16 bit, it is not possible +to run ROM-startup Thumb binaries on the PID board using this method.</PARA> +<PARA>When the image has been programmed, power off the board, and +set jumper LK4 to enable big-endian operation.</PARA> +</SECT3> +</SECT2> +<SECT2> +<TITLE>Installing the Stubs into ROM</TITLE> +<ORDEREDLIST> +<LISTITEM> +<PARA>Program the binary image file gdb_module.bin +into ROM referring to the instructions of your ROM programmer.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Plug the ROM into socket U12 and install jumper LK6 pins +7-8 to enable the ROM.</PARA> +</LISTITEM> +</ORDEREDLIST> +</SECT2> +</SECT1> +<SECT1 id="setup-arm-aeb1"> +<TITLE><!-- <index></index> -->ARM AEB-1 Hardware Setup</TITLE> +<SECT2> +<TITLE>Overview</TITLE> +<PARA>The ARM AEB-1 comes with tools in ROM. These include a simple +FLASH management tool and the Angel® monitor. eCos for +the ARM AEB-1 comes with GDB stubs suitable for programming into +the onboard FLASH. GDB is the preferred debug environment for GDB, +and while Angel provides a subset of the features in the eCos GDB +stub, Angel is unsupported.</PARA> +<PARA>Both eCos and the stubs support both Revision B and Revision +C of the AEB-1 board. Stub ROM images for both types of board can +be found in the loaders/arm-aeb directory under the root +of your eCos installation. You can select which board you are using +by selecting either the aeb or aebC platform by selecting the appropriate +platform HAL in the <EMPHASIS>eCos Configuration Tool</EMPHASIS>.</PARA> +<PARA>The GDB stub can be downloaded to the board for programming +in the FLASH using the board's on-board ROM monitor:</PARA> +<ORDEREDLIST> +<LISTITEM> +<PARA>talk to the AEB-1 board with a terminal emulator (or +a real terminal!)</PARA> +</LISTITEM> +<LISTITEM> +<PARA>use the board's rom menu to download a UU-encoded +version of the GDB stubs which will act as a ROM monitor</PARA> +</LISTITEM> +<LISTITEM> +<PARA>tell the board to use this new monitor, and then hook +GDB up to it for real debugging</PARA> +</LISTITEM> +</ORDEREDLIST> +</SECT2> +<SECT2> +<TITLE>Talking to the Board</TITLE> +<PARA>Connect a terminal or computer's serial port to the +ARM AEB-1. On a PC with a 9-pin serial port, you can use the cable +shipped by ARM with no modification. </PARA> +<PARA>Set the terminal or terminal emulator to 9600N1 (9600 baud, +no parity, 1 stop bit). </PARA> +<PARA>Reset the board by pressing the little reset button on the +top. You will see the following text: </PARA> +<PROGRAMLISTING> ARM Evaluation Board Boot Monitor 0.01 (19 APR 1998) + Press ENTER within 2 seconds to stop autoboot</PROGRAMLISTING> +<PARA>Press ENTER quickly, and you will get the boot prompt: </PARA> +<PROGRAMLISTING> Boot:</PROGRAMLISTING> +</SECT2> +<SECT2> +<TITLE>Downloading the Stubs via the Rom Menu</TITLE> +<PARA>Using the AEB-1 rom menu to download the GDB stubs from the +provided ".UU" file.</PARA> +<NOTE> +<PARA>This is an annotated 'terminal' session +with the AEB-1 monitor:</PARA> +</NOTE> +<PROGRAMLISTING>+Boot: help +Module is BootStrap 1.00 (14 Aug 1998)</PROGRAMLISTING> +<PROGRAMLISTING>Help is available on:</PROGRAMLISTING> +<PROGRAMLISTING>Help Modules ROMModules UnPlug PlugIn +Kill SetEnv UnSetEnv PrintEnv DownLoad +Go GoS Boot PC FlashWrite +FlashLoad FlashErase</PROGRAMLISTING> +<PROGRAMLISTING>Boot: download c000 +Ready to download. Use 'transmit' option on terminal +emulator to download file.</PROGRAMLISTING> +<PROGRAMLISTING>... at this point, download the ASCII file "loaders/arm-aeb/ + gdb_module.img.UU". The details of this operation differ + depending on which terminal emulator is used. It may be + necessary to enter "^D" (control+D) when the download completes + to get the monitor to return to command mode. </PROGRAMLISTING> +<PROGRAMLISTING>Loaded file gdb_module.img.bin at address +0000c000, size = 19392 </PROGRAMLISTING> +</SECT2> +<SECT2> +<TITLE>Activating the GDB Stubs</TITLE> +<PARA>Commit the GDB stubs module to FLASH: </PARA> +<PROGRAMLISTING> Boot: flashwrite 4018000 C000 8000 + </PROGRAMLISTING> +<PARA>Verify that the eCos/"GDB stubs" module is now added +in the list of modules in the board: </PARA> +<PROGRAMLISTING> Boot: rommodules + </PROGRAMLISTING> +<PARA>You should see output similar to the following: </PARA> +<PROGRAMLISTING> Header Base Limit + 04000004 04000000 040034a8 BootStrap 1.00 (14 Aug 1998) + 04003a74 04003800 04003bc0 Production Test 1.00 (13 Aug 1998) + 0400e4f4 04004000 0400e60f Angel 1.02 (12 MAY 1998) + 0401c810 04018000 0401cbc0 eCos 1.3 (27 Jan 2000) +GDB stubs + </PROGRAMLISTING> +<PARA>Now make the eCos/"GDB stubs" module be the default +monitor: </PARA> +<PROGRAMLISTING> Boot: plugin eCos + </PROGRAMLISTING> +<NOTE> +<PARA>Since the GDB stubs are always linked at the same address +(0x4018000), the operation of writing to the FLASH and selecting +the stubs as default monitor is an idempotent operation. You can +download a new set of stubs following the same procedure - you do +not have to unregister or delete anything.</PARA> +</NOTE> +</SECT2> +<SECT2> +<TITLE>Building the GDB Stub FLASH ROM Images</TITLE> +<PARA>Pre-built GDB stubs images are provided in the directory loaders/arm-aeb +relative to the root of your eCos installation, but here are instructions +on how to rebuild them if you should ever need to.</PARA> +</SECT2> +<SECT2> +<TITLE>Building the GDB Stubs with the eCos Configuration Tool</TITLE> +<ORDEREDLIST> +<LISTITEM> +<PARA>Start with a new document - selecting the +<EMPHASIS>File</EMPHASIS> +-> +<EMPHASIS>New</EMPHASIS> + menu item if necessary to do this.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Choose the +<EMPHASIS>Build</EMPHASIS> +-> +<EMPHASIS>Templates</EMPHASIS> + menu item, and then select the ARM AEB-1 hardware.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>While still displaying the +<EMPHASIS>Build->Templates</EMPHASIS> + dialog box, select the "stubs" package template to build a GDB +stub image. Click +<EMPHASIS>OK</EMPHASIS>.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>If applicable, set the "AEB board revision" option to +"C" from "B" depending on the board revision being used.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Build eCos using +<EMPHASIS>Build</EMPHASIS> +-> +<EMPHASIS>Library.</EMPHASIS></PARA> +</LISTITEM> +<LISTITEM> +<PARA>When the build completes, the image files can be found +in the bin/ subdirectory of the install tree. The GDB stub +ROM images have the prefix "gdb_module".</PARA> +</LISTITEM> +</ORDEREDLIST> +</SECT2> +<SECT2> +<TITLE>Building the GDB Stub ROMs with ecosconfig</TITLE> +<!-- <PARA>(See <XREF LINKEND="USING-ECOSCONFIG-ON-UNIX">)</PARA> --> +<ORDEREDLIST> +<LISTITEM> +<PARA>Make an empty directory to contain the build tree, +and cd into it.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>To build a GDB stub ROM image, enter the command:</PARA> +<PROGRAMLISTING>$ ecosconfig new aeb stubs</PROGRAMLISTING> +</LISTITEM> +<LISTITEM> +<PARA>If applicable, edit ecos.ecc and set the AEB board revision. (CYGHWR_HAL_ARM_AEB_REVISION) +from the default "B" to "C" by uncommenting the user_value +property and setting it to "C".</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Enter the commands + +<PROGRAMLISTING>$ ecosconfig tree +$ make</PROGRAMLISTING></PARA> +</LISTITEM> +<LISTITEM> +<PARA>When the build completes, the image files can be found +in the bin/ subdirectory of the install tree. The GDB stub +ROM images have the prefix "gdb_module".</PARA> +</LISTITEM> +</ORDEREDLIST> +</SECT2> +</SECT1> +<SECT1 id="setup-arm-cma230"> +<TITLE><!-- <index></index> -->ARM Cogent CMA230 Hardware Setup</TITLE> +<PARA>The eCos Developer's Kit package comes with an EPROM +which provides GDB support for the Cogent evaluation board. An image +of this EPROM is also provided at loaders/arm-cma230/gdbload.bin +under the root of your eCos installation. </PARA> +<PARA>The EPROM is installed to socket U3 on the board. Attention +should be paid to the correct orientation of the EPROM during installation.</PARA> +<PARA>If you are going to burn a new EPROM using the binary image, +be careful to get the byte order correct. It needs to be little-endian, +which is usually the default in PC based programmer software.</PARA> +<PARA>If the GDB stub EPROM you burn does not work, try reversing +the byte-order, even if you think you have it the right way around. +At least one DOS-based EPROM burner program is known to have the +byte-order upside down.</PARA> +<PARA>The GDB stub in the EPROM allows communication with GDB using +the serial port at connector P12 (CMA101) or P3 (CMA102). The communication parameters +are fixed at 38400 baud, 8 data bits, no parity bit and 1 stop bit +(8-N-1). No flow control is employed. Connection to the host computer +should be made using a dedicated serial cable as specified in the +Cogent CMA manual.</PARA> +<SECT2> +<TITLE>Building the GDB Stub FLASH ROM images</TITLE> +<PARA>Pre-built GDB stubs images are provided in the directory loaders/arm-cma230 relative +to the root of your eCos installation, but here are instructions +on how to rebuild them if you should ever need to.</PARA> +<PARA>CygMon images are prefixed with the name 'cygmon' and +GDB stub ROM images</PARA> +<PARA>are given the prefix 'gdb_module'. +Images may be provided in a number of formats including ELF (.img +extension), binary (.bin extension) and SREC (.srec extension). </PARA> +</SECT2> +<SECT2> +<TITLE>Building the GDB Stubs with the eCos Configuration Tool</TITLE> +<ORDEREDLIST> +<LISTITEM> +<PARA>1. Start with a new document - selecting the File->New +menu item if necessary to do this.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Choose the +<EMPHASIS>Build</EMPHASIS>-><EMPHASIS>Templates</EMPHASIS> + menu item, and then select the ARM CMA230 hardware.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>While still displaying the +<EMPHASIS>Build</EMPHASIS> +-> +<EMPHASIS>Templates</EMPHASIS> + dialog box, select the "stubs" package template to build a GDB +stub image. Click +<EMPHASIS>OK</EMPHASIS>.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Build eCos using +<EMPHASIS>Build</EMPHASIS> +-> +<EMPHASIS>Library</EMPHASIS></PARA> +</LISTITEM> +<LISTITEM> +<PARA>When the build completes, the image files can be found +in the bin/ subdirectory of the install tree. The GDB stub +ROM images have the prefix "gdb_module".</PARA> +</LISTITEM> +</ORDEREDLIST> +</SECT2> +<SECT2> +<TITLE>Building the GDB Stub ROMs with ecosconfig</TITLE> +<!-- <PARA>(See <XREF LINKEND="USING-ECOSCONFIG-ON-UNIX">)</PARA> --> +<ORDEREDLIST> +<LISTITEM> +<PARA>1. Make an empty directory to contain the build tree, +and cd into it.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>To build a GDB stub ROM image, enter the command:</PARA> +<PROGRAMLISTING>$ ecosconfig new cma230 stubs</PROGRAMLISTING> +</LISTITEM> +<LISTITEM> +<PARA>Enter the commands: + +<PROGRAMLISTING>$ ecosconfig tree +$ make</PROGRAMLISTING></PARA> +</LISTITEM> +<LISTITEM> +<PARA>When the build completes, the image files can be found +in the bin/ subdirectory of the install tree. The GDB stub +ROM images have the prefix "gdb_module".</PARA> +</LISTITEM> +</ORDEREDLIST> +</SECT2> +</SECT1> +<SECT1 id="setup-arm-ep7211"> +<TITLE><!-- <index></index> --><!-- <xref> -->Cirrus Logic ARM EP7211 Development +Board Hardware Setup</TITLE> +<PARA>eCos comes with two Flash ROM images that provide GDB support +for the Cirrus Logic EP7211 Development Board (also known as the +EDB7211).. Note that on some board revisions, the board is silk-screened +as EDB7111-2. The first Flash ROM image provides a port of the CygMon +ROM monitor, which includes a command-line interface and a GDB remote +stub. The second Flash ROM image provides a remote GDB stub only.</PARA> +<PARA>Both ROM images are provided in the directory loaders/arm-edb7211 +under the root of your eCos installation. CygMon images are prefixed +with the name 'edb7211_cygmon' and are +provided in a number of formats including binary (.bin extension) +and SREC (.srec) extension. GDB stub ROM images are given the prefix 'edb7211_gdb_module'. </PARA> +<PARA>The ROM images provided for the EP7211 Development Board must +be programmed into the FLASH. Please refer to the section titled +"Loading the ROM image into On-Board flash" on how to program the +ROM onto the board.</PARA> +<PARA>Both Cygmon and GDB Stub ROMS allow communication with GDB +via the serial connector labelled 'UART 1'. The +communication parameters are fixed at 38400 baud, 8 data bits, no +parity bit and 1 stop bit (8-N-1). No flow control is employed. +Connection to the host computer should be made using a null modem cable. +A gender changer may also be required. Note that the GDB Configuration tool +uses the serial port identifiers 0 and 1 to identify the EB7211 +serial ports UART1 and UART2 respectively.</PARA> +<PARA>Both eCos and the ROM images assume the core clock is generated +with a 3.6864 MHz PLL input. The CPU will be configured to run at +73.728MHz.</PARA> +<PARA>Note: The EP7211 CPU needs a two step RESET process. After +pressing the `URESET' pushbutton, the `WAKEUP' pushbutton +must be pressed to complete the process.</PARA> +<NOTE> +<PARA>When an eCos program is run on an EDB7211 board fitted with +either CygMon or a GDB stub ROM, then the code in ROM loses control. +This means that if you require the ability to remotely stop execution +on the target, or want thread debugging capabilities, you must include +GDB stub support when configuring eCos.</PARA> +</NOTE> +<SECT2> +<TITLE>Building programs for programming into FLASH</TITLE> +<PARA>If your application is to be run directly from FLASH, you +must configure eCos appropriately for "ROM" startup. This can be +done in the <EMPHASIS>eCos Configuration Tool</EMPHASIS> by setting +the "Startup type" HAL option to "ROM". If using the ecosconfig utility, +set the user_value of the CYG_HAL_STARTUP +option in ecos.ecc to "ROM".</PARA> +<PARA>When you have linked your application with eCos, you will +then have an ELF executable. To convert this into a format appropriate +for the Cirrus Logic FLASH download utility, or the dl_7xxx +utility on Linux, you can use the utility arm-elf-objcopy, as in +the following example:</PARA> +<PROGRAMLISTING>$ arm-elf-objcopy -O binary helloworld.exe helloworld.bin</PROGRAMLISTING> +<PARA>This will produce a binary format image helloworld.bin which +can be downloaded into FLASH.</PARA> +</SECT2> +<SECT2> +<TITLE>Building the GDB Stub FLASH ROM images</TITLE> +<PARA>Pre-built GDB stubs images are provided in the directory loaders/arm-edb7211 relative +to the root of your eCos installation, but here are instructions +on how to rebuild them if you should ever need to.</PARA> +<PARA>CygMon images are prefixed with the name 'cygmon' and +GDB stub ROM images are given the prefix 'gdb_module'. +Images may be provided in a number of formats including ELF (.img +extension), binary (.bin extension) and SREC (.srec extension). </PARA> +</SECT2> +<SECT2> +<TITLE>Building the ROM images with the eCos Configuration Tool</TITLE> +<ORDEREDLIST> +<LISTITEM> +<PARA>Start with a new document - selecting the +<EMPHASIS>File</EMPHASIS>-><EMPHASIS>New</EMPHASIS> + menu item if necessary to do this.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Choose the +<EMPHASIS>Build</EMPHASIS>-><EMPHASIS>Templates</EMPHASIS> + menu item, and then select the "Cirrus Logic development board" +hardware.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>While still displaying the +<EMPHASIS>Build</EMPHASIS> +-> +<EMPHASIS>Templates</EMPHASIS> + dialog box, select either the "stubs" package template to build +a GDB stub image, or the "cygmon" template to build the CygMon ROM +Monitor. Click +<EMPHASIS>OK</EMPHASIS>.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Build eCos using +<EMPHASIS>Build</EMPHASIS> +-> +<EMPHASIS>Library</EMPHASIS></PARA> +</LISTITEM> +<LISTITEM> +<PARA>When the build completes, the image files can be found +in the bin/ subdirectory of the install tree. GDB stub +ROM images have the prefix "gdb_module". CygMon images +have the prefix "cygmon".</PARA> +</LISTITEM> +</ORDEREDLIST> +</SECT2> +<SECT2> +<TITLE>Building the ROM images with ecosconfig</TITLE> +<!-- <PARA>(See <XREF LINKEND="USING-ECOSCONFIG-ON-UNIX">)</PARA> --> +<ORDEREDLIST> +<LISTITEM> +<PARA>Make an empty directory to contain the build tree, +and cd into it.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>To build a GDB stub ROM image, enter the command:</PARA> +<PROGRAMLISTING>$ ecosconfig new edb7xxx stubs</PROGRAMLISTING> +<PARA>or to build a CygMon ROM monitor image, enter the command:</PARA> +<PROGRAMLISTING>$ ecosconfig new edb7xxx cygmon</PROGRAMLISTING> +</LISTITEM> +<LISTITEM> +<PARA>Enter the commands:</PARA> +<PROGRAMLISTING>$ ecosconfig tree +$ make</PROGRAMLISTING> +</LISTITEM> +<LISTITEM> +<PARA>When the build completes, the image files can be found +in the bin/ subdirectory of the install tree. GDB stub +ROM images have the prefix "gdb_module". CygMon images +have the prefix "cygmon".</PARA> +</LISTITEM> +</ORDEREDLIST> +</SECT2> +<SECT2> +<TITLE><!-- <xref> -->Loading the ROM Image into On-board Flash</TITLE> +<PARA>Program images can be written into Flash memory by means of +a bootstrap program which is built into the EDB7211. This program +communicates with a support program on your host to download and +program an image into the Flash memory.</PARA> +<PARA>Cirrus Logic provides such a program for use with Windows/DOS. + eCos comes with a similar program which will run under Linux. The +basic operation of both programs is the same.</PARA> +<ORDEREDLIST> +<LISTITEM> +<PARA>Connect a serial line to 'UART 1'.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Power off the EDB7211.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Install jumper 'PROGRAM ENABLE' which +enables this special mode for downloading Flash images. Note that +some board revisions have this jumper labelled “BOOT ENABLE”.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Power on the EDB7211.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Execute the Flash writing program on your host. On Linux, +this would be:</PARA> +<PROGRAMLISTING> # dl_edb7xxx <PATH>/gdb_module.bin</PROGRAMLISTING> +<PARA>where '<PATH>' is the path to +the binary format version of the ROM image you wish to load, either +as built in the previous section or the "loaders/arm-edb7211/" subdirectory +of your eCos installation. The download tool defaults to 38400 baud and +device /dev/ttyS1 for communication. To change +these, specify them as parameters, e.g. + </PARA> +<PROGRAMLISTING># dl_edb7xxx <PATH>/gdb_module.bin 9600 /dev/ttyS0</PROGRAMLISTING> +</LISTITEM> +<LISTITEM> +<PARA>The download program will indicate that it is waiting +for the board to come alive. At this point, press 'RESET' and +then 'WAKEUP' switches in order. There should be +some indication of progress, first of the code being downloaded, +then of the programming process.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Upon completion of the programming, power off the EDB7211.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Remove the 'PROGRAM ENABLE/BOOT ENABLE' jumper.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Power on the EDB7211, press 'RESET' and 'WAKEUP'. + The new ROM image should now be running on the board.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>The GDB debugger will now be able to communicate with +the board to download and debug RAM based programs. + +This procedure also applies for loading ROM-startup eCos programs +into the on-board FLASH memory, given a binary format image of the +program from arm-elf-objcopy. Loading a ROM-startup eCos program +into Flash will overwrite the GDB Stub ROM/CygMon in Flash, +so you would have to reload the GDB Stub ROM/CygMon to +return to normal RAM-startup program development.</PARA> +</LISTITEM> +</ORDEREDLIST> +</SECT2> +<SECT2> +<TITLE>Building the Flash Downloader on Linux</TITLE> +<PARA>eCos provides a Flash download program suitable for use with +the EP7211 Development Board which will run on Linux. Follow these +steps to build this program. Note: at the time of the writing of +these instructions, the download program is built directly within +the eCos source repository since it is +not configuration specific.</PARA> +<PROGRAMLISTING> # cd <eCos install dir>/packages/hal/arm/edb7xxx/<replaceable>&Version;</replaceable>/support</PROGRAMLISTING> +<PROGRAMLISTING> # make</PROGRAMLISTING> +<PARA>(where '# ' is your shell prompt)</PARA> +<PARA>Note: this program was adapted from the Cirrus Logic original +DOS program and still contains some vestiges of that environment.</PARA> +</SECT2> +<SECT2> +<TITLE>Developing eCos Programs with the ARM Multi-ICE</TITLE> +<PARA>The EP7211 Development Board supports use of the ARM + Multi-processor EmbeddedICE(tm), also known as the + Multi-ICE. Full instructions on how to install and use the + Multi-ICE in conjunction with GDB are provided in the + <EMPHASIS>"GNUPro Toolkit Reference for eCos + ARM/Thumb"</EMPHASIS> manual. However, the following + platform-specific details should be noted.</PARA> +<PARA>You will need an ARM Multi-ICE Server configuration + file for the EP7211 Development Board. Here is a suggested + configuration file to use:</PARA> +<PROGRAMLISTING>======== File "720T.cfg" ======== +;Total IR length = 4 +[TITLE] +Multi-ICE configuration for EP7211 + +[TAP 0] +ARM720T + +[TAPINFO] +YES + +[Timing] +Low=0 +High=0 +Adaptive=OFF +==================================</PROGRAMLISTING> +<PARA>You must ensure that the board has the appropriate soldered +connections. For the EP7211 this involves connecting TEST0 and TEST1 +of the EP7211 to ground. To do this you must solder a wire from +ground at JP33 to TP8 and TP9.</PARA> +<PARA>With respect to using multiple devices simultaneously, note +that the EP7211 is not ID sensitive.</PARA> +<PARA>If you wish to view diagnostic output from your program that +was downloaded via the Multi-ICE, you will note that by default +the output on the serial line (as viewed by a terminal such as Hyperterm +in Windows, or cu in Unix) is in the form of GDB packets.</PARA> +<PARA>To get legible output, the solution is to set the "GDB Serial +port" to a different device from the "Diagnostic serial port", and +you should use the Diagnostic serial port to view the diagnostic +output.</PARA> +<PARA>Warning: The multi-ice-gdb-server will fail on startup if +the board has not been both reset and awakened before running the +server. </PARA> +<PARA>To resolve this, it is necessary to free up the connection +from within the ARM Multi-ICE server itself. However when this happens, +the next time you use GDB to load the program into the board, you +will see lots of "Readback did not match original data" messages +in the output of the multi-ice-gdb-server program. This indicates +your program did not load correctly, and you should restart the +multi-ice-gdb-server program, taking care to reset the board correctly +before reconnecting. </PARA> +<PARA>As a reminder, you must specify --config-dialog to the + multi-ice-gdb-server program to connect to the board + correctly. If you do not, the multi-ice-gdb-server program + will not be able to connect.</PARA> +</SECT2> +</SECT1> + +<SECT1 ID="setup-arm-ep7212"> +<TITLE><!-- <conditionaltext> -->Cirrus Logic ARM EP7212 Development Board +Hardware Setup</TITLE> +<PARA>The Cirrus Logic EP7212 Development Board is almost identical +to the EP7211 Development Board from a hardware setup viewpoint, +and is based on the same port of eCos. Therefore the earlier documentation +for the EP7211 Development Board can be considered equivalent, but +with the following changes:</PARA> +<ITEMIZEDLIST> +<LISTITEM> +<PARA>The first serial port is silk screened as "UART 1" on +the EP7211 Development Board, but is silk screened as "Serial Port +0" on the EP7212 Development Board. Similarly "UART 2" is silk screened +as "Serial Port 1" on the EP7212 Development Board.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>JP2 (used to control reprogramming of the FLASH) is not +silkscreened with "Boot Enable".</PARA> +</LISTITEM> +<LISTITEM> +<PARA>To setup the EP7212 Development Board for use with the +ARM Multi-ICE JTAG debugging interface unit, it is necessary to +connect TEST0 and TEST1 of the EP7212 to ground. On the Development +Board, this is accomplished by placing shorting blocks on JP47 and +JP48. When the shorting blocks are fitted, the board can only be +operated through the Multi-ICE - debugging over a serial line is +not possible.</PARA> +</LISTITEM> +<LISTITEM> +<PARA><!-- <conditionaltext> -->Pre-built GDB stubs are + provided in the directory + <FILENAME>loaders/arm-edb7212</FILENAME> relative to the + root of your eCos installation</PARA> +</LISTITEM> +<LISTITEM> +<PARA>When rebuilding the GDB stub ROM image, change the "Cirrus +Logic processor variant" option (CYGHWR_HAL_ARM_EDB7XXX_VARIANT) +from the EP7211 to the EP7212. This can be selected in the +<EMPHASIS>eCos Configuration Tool</EMPHASIS> +, or if using ecosconfig, can be set by uncommenting the user_value +property of this option in ecos.ecc and setting it to "EP7212".</PARA> +</LISTITEM> +</ITEMIZEDLIST> +</SECT1> +<SECT1 ID="setup-arm-ep7312"> +<TITLE><!-- <conditionaltext> -->Cirrus Logic ARM EP7312 Development Board +Hardware Setup</TITLE> +<PARA>The Cirrus Logic EP7312 Development Board is similar +to the EP7212 Development Board from a hardware setup viewpoint, +and is based on the same port of eCos.</PARA> +<PARA>When rebuilding the RedBoot ROM image or an eCos application, +change the "Cirrus Logic processor variant" option +(CYGHWR_HAL_ARM_EDB7XXX_VARIANT) +from the EP7211 to the EP7312. This can be selected in the +<EMPHASIS>eCos Configuration Tool</EMPHASIS> +, or if using ecosconfig, can be set by uncommenting the user_value +property of this option in ecos.ecc and setting it to "EP7312". +</PARA> +<PARA> +See the RedBoot documentation for building and installing RedBoot for this +target. Only RedBoot is supported as a boot image; ROMRAM startup is +recommended. +</PARA> +<SECT2 ID="ep7312-90MHz-operation"> +<TITLE>90MHz Operation</TITLE> +<PARA> +The EP7xxx targets offer a choice of clock speeds, from 18MHz to a maximum, +normally, of 72MHz. These are described as kHz values 18432 36864 49152 +and 73728 within the configuration tool. If you have a release which +supports it, you will also see 90317 as an available option here, for 90MHz +operation. +</PARA> +<PARA> +This option only applies to certain EP7312 hardware, not all EP7312 boards +support it. Do not select 90MHz when building RedBoot or your eCos +application unless you are absolutely sure that your board supports it. +</PARA> +<PARA> +If you do have a 90MHz board and wish to execute at 90MHz, it is in fact +not necessary to build RedBoot specially, if you build your eCos +application configured for 90MHz. RedBoot will run at 72MHz and your +application will run at 90MHz. If you do install a 90MHz RedBoot, then you +must build eCos for 90MHz or timing and baud rates on serial I/O will be +wrong. +</PARA> +<PARA> +In other words, code (either eCos app or RedBoot) built for 90MHz will +“change up a gear” when it starts up; but code built for 72MHz, +because it needs to run correctly on boards without the +“gearbox” does not change back down, so if you mix the two, +unexpected timing can result. To run a non-eCos application without any +hardware initialization code at 90MHz, you must install a specially-built +RedBoot. +</PARA> +</SECT2> +</SECT1> +<SECT1 id="setup-arm-ep7209"> +<TITLE>Cirrus Logic ARM EP7209 Development Board Hardware Setup</TITLE> +<PARA>Note: At time of writing, no EP7209 Development Board is available, +and consequently eCos has not been verified for use with the EP7209 +Development Board.</PARA> +<PARA>The Cirrus Logic EP7209 Development Board is almost identical +to the EP7212 Board in all respects, except that it is not fitted +with DRAM, nor has it a DRAM controller.</PARA> +<PARA>The only valid configuration for the EDB7209 is ROM based. +The STUBS and RAM startup modes are not available as no DRAM is +fitted.</PARA> +</SECT1> +<SECT1 id="setup-arm-clps7111"> +<TITLE><!-- <index></index> -->Cirrus Logic ARM CL-PS7111 Evaluation Board Hardware Setup</TITLE> +<PARA>The implementation of the port of eCos to the Cirrus Logic +ARM CL-PS7111 Evaluation Board (also known as EB7111) is based on +the EP7211 Development Board port.</PARA> +<PARA>For that reason, the setup required is identical to the EP7211 +Development Board as described above, with the following exceptions:</PARA> +<ITEMIZEDLIST> +<LISTITEM> +<PARA>The Cygmon ROM monitor is not supported</PARA> +</LISTITEM> +<LISTITEM> +<PARA>The ARM Multi-ICE is not supported</PARA> +</LISTITEM> +<LISTITEM> +<PARA><!-- <conditionaltext> -->Pre-built GDB stubs are provided in the +directory loaders/arm-eb7111 relative to the root of your +eCos installation</PARA> +</LISTITEM> +<LISTITEM> +<PARA>If rebuilding the GDB stub ROM image, change the "Cirrus +Logic processor variant" option (CYGHWR_HAL_ARM_EDB7XXX_VARIANT) +from the EP7211 to the CL_PS7111. This can be selected +in the +<EMPHASIS>eCos Configuration Tool</EMPHASIS> +, or if using ecosconfig, can be set by uncommenting the user_value +property of this option in ecos.ecc and setting it to "CL_PS7111"</PARA> +</LISTITEM> +</ITEMIZEDLIST> +<PARA>All remote serial communication is done with the serial I/O +connector</PARA> +<PROGRAMLISTING>/misc +% slow_cat.tcl < [path]/gdb_module.srec > /dev/ttyS0</PROGRAMLISTING> +<PARA>Power off the board, and change it to boot the GDB stubs in +big-endian mode by setting the switches like this:</PARA> +<PARA>SW1: 00000000 (all levers down) +SW2: 10001010</PARA> +<PARA>The GDB stubs allow communication with GDB using the serial +port at connector PJ7A (lower connector). The communication parameters +are fixed at 38400 baud, 8 data bits, no parity bit and 1 stop +bit (8-N-1). No flow control is employed. Connection to the host +computer should be made using a straight through serial cable.</PARA> +</SECT1> +<SECT1 id="setup-arm-ebsa285"> +<TITLE>StrongARM EBSA-285 Hardware Setup</TITLE> +<PARA>The eCos Developer’s Kit package comes with a ROM +image which provides GDB support for +the Intel® StrongARM® Evaluation Board EBSA-285. + Both eCos and the Stub ROM image assume the clocks are: 3.6864 +MHz PLL input for generating the core clock, and 50MHz osc input +for external clocks. An image of this ROM is also provided at <filename>loaders/arm-ebsa285/gdbload.bin</filename> under +the root of your eCos installation.</PARA> +<PARA>The ROM monitor image (an eCos GDB +stub) provided for the EBSA-285 board must be programmed into the +flash, replacing the Angel monitor on the board. Please refer to +the section titled "Loading the ROM Image into On-Board flash" on how +to program the ROM onto the board.</PARA> +<PARA>The Stub ROM allows communication with GDB via the serial +connector on the bulkhead mounting bracket COM0. The communication +parameters are fixed at 38400 baud, 8 data bits, no parity bit and +1 stop bit (8-N-1). No flow control is employed.</PARA> +<SECT2> +<TITLE>Building the GDB Stub FLASH ROM images</TITLE> +<PARA>Pre-built GDB stubs images are provided in the directory loaders/arm-ebsa285 relative +to the root of your eCos installation, but here are instructions +on how to rebuild them if you should ever need to.</PARA> +</SECT2> +<SECT2> +<TITLE>Building the GDB Stubs with the eCos Configuration Tool</TITLE> +<ORDEREDLIST> +<LISTITEM> +<PARA>Start with a new document - selecting the +<EMPHASIS>File</EMPHASIS> +-> +<EMPHASIS>New</EMPHASIS> + menu item if necessary to do this.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Choose the +<EMPHASIS>Build</EMPHASIS> +-> +<EMPHASIS>Templates</EMPHASIS> + menu item, and then select the StrongARM EBSA285 hardware.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>While still displaying the +<EMPHASIS>Build</EMPHASIS> +-> +<EMPHASIS>Templates</EMPHASIS> + dialog box, select the "stubs" package template to build a GDB +stub image. Click +<EMPHASIS>OK</EMPHASIS>.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Build eCos using +<EMPHASIS>Build</EMPHASIS> +-> +<EMPHASIS>Library</EMPHASIS></PARA> +</LISTITEM> +<LISTITEM> +<PARA>When the build completes, the image files can be found +in the bin/ subdirectory of the install tree. The GDB stub +ROM images have the prefix "gdb_module".</PARA> +</LISTITEM> +</ORDEREDLIST> +</SECT2> +<SECT2> +<TITLE>Building the GDB Stub ROMs with ecosconfig</TITLE> +<PARA>(See “Using ecosconfig on UNIX” on page 72)</PARA> +<ORDEREDLIST> +<LISTITEM> +<PARA>Make an empty directory to contain the build tree, +and cd into it.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>To build a GDB stub ROM image, enter the command: + +<PROGRAMLISTING>$ ecosconfig new ebsa285 stubs</PROGRAMLISTING></PARA> +</LISTITEM> +<LISTITEM> +<PARA>Enter the commands: + +<PROGRAMLISTING>$ ecosconfig tree +$ make</PROGRAMLISTING></PARA> +</LISTITEM> +<LISTITEM> +<PARA>When the build completes, the image files can be found +in the bin/ subdirectory of the install tree. The GDB stub +ROM images have the prefix "gdb_module".</PARA> +</LISTITEM> +</ORDEREDLIST> +</SECT2> +<SECT2> +<TITLE>Loading the ROM Image into On-board Flash</TITLE> +<PARA>There are several ways to install the eCos gdb stub ROM image +in the EBSA board’s flash memory. Once installed, the gdb +stub ROM provides standard eCos download and debug via the EBSA +board"s serial port. The options available include the +Linux based EBSA flash upgrade utility provided by Red Hat, direct writing +of the flash via MultiICE (JTAG) hardware debugger, and other flash management +utilities from Intel (these only support DOS, and proprietary ARM tools +and image formats). Only the Red Hat flash upgrade tool is supported +and tested in this release.</PARA> +<PARA>The flash upgrade tool requires the EBSA board to be configured +as a PCI slave (rather than a master, its normal operating mode) +and plugged into a Linux host computer"s PCI bus.</PARA> +<PARA>Configuring the board for flash loading: Follow the instructions +in the EBSA-285 Reference Manual, pages A-2 and A-3 to configure +the board as an add-in card, and enable flash blank programming. + Briefly: assuming the board was in the default setting to execute +as a bus master ("Host Bridge") make jumper 9 (J9), move jumper +10 (J10) to external reset (PCI_RST), and move jumper 15 +(J15) link 4-6-5 to connect 5-6 instead of 4-6.</PARA> +<PARA>Configuring the board for execution of eCos programs: Follow +the instructions in the EBSA-285 Reference Manual, pages A-2 and +A-3 to configure the board as a "Host Bridge" with "Central Function". + Briefly: unset J9, move J10 to on-board reset (BRD_RST), +and set J15 to make 4-6 instead of 5-6 (see page A-8 also). Plug +the card into its own PCI bus, not the Linux PC used for the flash-programming +process.</PARA> +<PARA>Building the Linux software: the Linux software sources are +in directory</PARA> +<PROGRAMLISTING> <BASE_DIR>/packages/hal/arm/ebsa285/v1_3/support/linux/safl_util</PROGRAMLISTING> +<PARA>in the eCos source repository. There are two parts to the +system: a loadable kernel module and the flash utility. The loadable +kernel module is safl.o and the utility is sa_flash. To +build:</PARA> +<PARA> cd to this directory, or a copy of it.</PARA> +<PARA> make</PARA> +<PARA>This builds safl.o and sa_flash. The kernel module +must be installed, and a device file created for it. Both of these +operations require root permissions. Create the device file by: </PARA> +<PROGRAMLISTING> % mknod /dev/safl c 10 178</PROGRAMLISTING> +<PARA>Programming the flash: switch off the EBSA-285, and remove +the EBSA-285 board from its PCI bus. Take appropriate anti-static +precautions. Configure it for flash loading as above, halt your +Linux system and turn it off. Install the EBSA-285 board in the +PCI bus of the Linux system and boot it up. (Single user is good enough, +assuming your image and safl_util build dir are on a local +disc partition.) Change directory to the safl_util directory, +then, to load the kernel module and flash an image onto the eval +board (as root): </PARA> +<PROGRAMLISTING> % insmod safl.o + % sa_flash <image_file></PROGRAMLISTING> +<PARA>Halt and turn off the Linux machine and remove the EBSA-285 +card. Take appropriate anti-static precautions. Configure it for +execution of eCos programs as above, and plug it into its own PCI +bus. Restart the Linux machine however you wish.</PARA> +<PARA>This information is replicated in the README file within the +safl_util directory and its parents, and in the EBSA-285 +Reference Manual from Intel, appendix A "Configuration Guide". +If in doubt, please refer to those documents also.</PARA> +<PARA>This procedure also applies for loading ROM-startup eCos programs +into the on-board flash memory, given a binary format image of the +program from arm-elf-objcopy. Loading a ROM-startup eCos program +into flash will overwrite the StubROM in flash, so you would have +to reload the StubROM to return to normal RAM-startup program development.</PARA> +</SECT2> +<SECT2> +<TITLE>Running your eCos Program Using GDB and the StubROM</TITLE> +<NOTE> +<PARA>You must first load the StubROM image into the flash memory +on the EBSA-285 board before doing this. See “Loading +the ROM Image into On-board Flash”, page 93 for details.</PARA> +</NOTE> +<PARA>Connect to the StubROM in the board and run your eCos program <PROGRAM> as</PARA> +<PARA>follows:</PARA> +<PROGRAMLISTING> $ arm-elf-gdb -nw <PROGRAM> + (gdb) set remotebaud 38400 + (gdb) target remote <DEVICE></PROGRAMLISTING> +<PARA>Where <DEVICE> is /dev/ttyS0 +or COM1: or similar, depending on your environment and how you connected +your serial line to the host computer. Expect some output here, +for example:</PARA> +<PROGRAMLISTING> Remote debugging using /dev/ttyS0 + 0x410026a4 in ?? ()</PROGRAMLISTING> +<PARA>then, to load the program</PARA> +<PROGRAMLISTING> (gdb) load + </PROGRAMLISTING> +<PARA>which will report locations and sizes of sections as they +load, then begin execution using</PARA> +<PROGRAMLISTING> (gdb) continue</PROGRAMLISTING> +<PARA>If you have no eCos program yet, but you want to connect to +the board just to verify serial communications, tell gdb "set endian +little" before anything else, so that it understands the board (GDB +normally infers this from information within the eCos program).</PARA> +<NOTE> +<PARA>When an eCos program is run on the EBSA-285 board, the GDB +stub in ROM loses control. This means that if you require the ability +to stop execution on the target remotely, or want thread debugging +capabilities, you must include GDB stub support when configuring +<PRODUCTNAME>eCos</PRODUCTNAME>.</PARA> +</NOTE> +</SECT2> +</SECT1> +<SECT1 id="setup-arm-ipaq"> +<TITLE><!-- <conditionaltext> --> <!-- NOTE: could not find it --><!-- <index></index> -->Compaq iPAQ PocketPC Hardware Setup</TITLE> +<PARA>For setting up the iPAQ to run with RedBoot, see the the <EMPHASIS>RedBoot +User's Guide</EMPHASIS>. Connections may be made using +the Compact Flash Ethernet interface. A serial cable may be connected +directly, or via the cradle. Serial communication uses the parameters +38400,8,N,1. The LCD/Touchscreen may also be used as an +interface to RedBoot and eCos applications.</PARA> +</SECT1> +<SECT1 id="setup-arm-aim711"> +<TITLE>Arm Industrial Module AIM 711 Hardware Setup</TITLE> +<PARA>The Arm Industrial Module AIM 711 comes with RedBoot installed +as the default boot loader.</PARA> +<PARA>For developing without having a finished custom board, a +starter-kit with a minimally configured board is available. It offers all the +connectors needed for development, including serial device, Ethernet, power +supply and an extra connector for the external bus.</PARA> +<SECT2> +<TITLE>Setup Hardware</TITLE> +<SECT3> +<TITLE>Power supply</TITLE> +<PARA>A 6V - 7.5V power supply must be connected to J2 or TB1. At +J2 the inner pin is V+ and at TB1 it is pin 1.</PARA> +</SECT3> +<SECT3> +<TITLE>Serial devices</TITLE> +<PARA>The AIM 711 has 3 serial devices, which are the debug and +diagnostic channel COM0 (/dev/ser0), the high performance 16550 +UART COM1 (/dev/ser1) and the second internal device COM2 +(/dev/ser2).</PARA> +<PARA>To use the debug channel, which is also the default for +RedBoot, the supplied DB9-male cable must be connected to +CN4. If the also available service board is used, the above +connector must be disabled by setting JP1.</PARA> +<PARA>COM1 is available over the RJ45 connector CN2. This device +can be configured as a RS232, RS422, RS485 or TTL level</PARA> +<PARA>COM2 is only available with TTL level at CN5.</PARA> +</SECT3> +<SECT3> +<TITLE>Ethernet</TITLE> +<PARA>The RJ45 connector CN1 is for Ethernet.</PARA> +</SECT3> +</SECT2> +<SECT2> +<TITLE>Installing RedBoot into FLASH</TITLE> +<SECT3> +<TITLE>Using RedBoot</TITLE> +<PARA>In order that Redboot can overwrite itself, Redboot is built as a ROMRAM image. </PARA> +<PARA>Load the RedBoot binary to the next free space: +<PROGRAMLISTING>RedBoot> load -m tftp -h 192.168.1.36 -r -b 0x40000 redboot.bin +Raw file loaded 0x00040000-0x00063233, assumed entry at 0x00040000</PROGRAMLISTING> +Store it in FLASH: +<PROGRAMLISTING>RedBoot> fis create RedBoot +An image named 'RedBoot' exists - continue (y/n)? y +... Erase from 0x02000000-0x02025000: ..................................... +... Program from 0x00040000-0x00063234 at 0x02000000: .......................... +.......... +... Erase from 0x021ff000-0x02200000: . +... Program from 0x007ff000-0x00800000 at 0x021ff000: .</PROGRAMLISTING> +Restart the AIM 711: +<PROGRAMLISTING>RedBoot> reset +... Resetting.</PROGRAMLISTING> +</PARA> +</SECT3> +<SECT3> +<TITLE>Using JTAG</TITLE> +<PARA>To rewrite the FLASH using JTAG the service board must be +used, which includes a JTAG connector.</PARA> +</SECT3> +</SECT2> +<SECT2> +<TITLE>More documentation</TITLE> +<PARA>For more information please look at +<ULINK URL="http://www.visionsystems.de/arm7.html">http://www.visionsystems.de/arm7.html</ULINK>.</PARA> +</SECT2> +</SECT1> +<SECT1 id="setup-sh-edk7708"> +<TITLE>SH3/EDK7708 Hardware Setup</TITLE> +<PARA>The eCos Developer’s Kit package comes with a ROM +which provides GDB support for the Hitachi EDK7708 board (a big-endian +and a little-endian version). Images of these ROMs are also provided +at <filename>loaders/sh-edk7708/gdbload.bin</filename> and + <filename>loaders/sh-edk7708le/gdbload.bin</filename> under +the root of your eCos installation.</PARA> +<PARA>The ROM is installed to socket U6 on the board. When using +the big-endian ROM, jumper 9 must be set to 2-3. When using the +little-endian ROM, jumper 9 must be set to 1-2. Attention should +be paid to the correct orientation of the ROM during installation. +Only replace the board"s existing ROM using a proper PLCC extraction +tool, as the socket would otherwise risk being damaged. </PARA> +<PARA>If you are going to program a new ROM or FLASH using the binary +image, you may have to experiment to get the right byte-order in +the device. Depending on the programming software you use, it might +be necessary to enable byte-swapping. If the GDB stub ROM/FLASH +you program does not work, try reversing the byte-order.</PARA> +<PARA>The GDB stub in the EPROM allows communication with GDB using +the serial port at connector J1. The communication parameters are +fixed at 38400 baud, 8 data bits, no parity bit and 1 stop bit (8-N-1). +No flow control is employed. Connection to the host computer should +be made using the dedicated serial cable included in the EDK package. </PARA> +<SECT2> +<TITLE>Installing the Stubs into FLASH</TITLE> +<SECT3> +<TITLE>Preparing the Binaries</TITLE> +<PARA>These two binary preparation steps are not strictly necessary +as the eCos distribution ships with pre-compiled binaries in the +directory loaders/sh-edk7708 and loaders/sh-edk7708le +relative to the installation root.</PARA> +<SECT4> +<TITLE>Building the ROM images with the eCos Configuration Tool</TITLE> +<ORDEREDLIST> +<LISTITEM> +<PARA>Start with a new document - selecting the +<EMPHASIS>File->New</EMPHASIS> + menu item if necessary to do this.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Choose the +<EMPHASIS>Build->Templates</EMPHASIS> + menu item, and then select the SH EDK7708 hardware.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>While still displaying the +<EMPHASIS>Build->Templates</EMPHASIS> + dialog box, select the “stubs” package template +to build a GDB stub. Click +<EMPHASIS>OK</EMPHASIS>.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>If building a little-endian image, disable the “Use +big-endian mode” option in the SH EDK7708 HAL (CYGHWR_HAL_SH_BIGENDIAN).</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Build eCos using +<EMPHASIS>Build->Library</EMPHASIS>. </PARA> +</LISTITEM> +<LISTITEM> +<PARA>When the build completes, the image files can be found +in the bin/ subdirectory of the install tree. GDB stub +ROM images have the prefix “gdb_module”.</PARA> +</LISTITEM> +</ORDEREDLIST> +</SECT4> +<SECT4> +<TITLE>Building the ROM images with ecosconfig</TITLE> +<ORDEREDLIST> +<LISTITEM> +<PARA>Make an empty directory to contain the build tree, +and cd into it.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>To build a GDB stub ROM image, enter the command: + +<PROGRAMLISTING>$ ecosconfig new edk7708 stubs</PROGRAMLISTING> + </PARA> +</LISTITEM> +<LISTITEM> +<PARA>If building a little-endian image, uncomment the user +value in ecos.ecc for CYGHWR_HAL_SH_BIGENDIAN +and change it to 0. </PARA> +</LISTITEM> +<LISTITEM> +<PARA>Enter the commands: + +<PROGRAMLISTING>$ ecosconfig tree +$ make </PROGRAMLISTING></PARA> +</LISTITEM> +<LISTITEM> +<PARA>When the build completes, the image files can be found +in the bin/ subdirectory of the install tree. GDB stub +ROM images have the prefix “gdb_module”.</PARA> +</LISTITEM> +</ORDEREDLIST> +</SECT4> +</SECT3> +<SECT3> +<TITLE> Installing the Stubs into ROM or FLASH</TITLE> +<ORDEREDLIST> +<LISTITEM> +<PARA>Program the binary image file gdb_module.bin +into ROM or FLASH referring to the instructions of your ROM programmer.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Plug the ROM/FLASH into socket U6. If the image +is little-endian set jumper 9 to 1-2. If the image is big-endian +set jumper 9 to 2-3.</PARA> +</LISTITEM> +</ORDEREDLIST> +</SECT3> +</SECT2> +</SECT1> +<SECT1 id="setup-sh-cq7708"> +<TITLE>SH3/CQ7708 Hardware Setup</TITLE> +<SECT2> +<TITLE>Preparing the board</TITLE> +<PARA>Make sure the DIP switches on the board are set as follows: + </PARA> +<PROGRAMLISTING>SW1-1 ON +SW1-2 OFF +SW1-3 ON +SW1-4 OFF</PROGRAMLISTING> +<PROGRAMLISTING>SW2-1 ON +SW2-2 ON +SW2-3 OFF +SW2-4 OFF</PROGRAMLISTING> +<PARA>If you are using a straight through serial cable which has +flow control lines, you will also need to cut JP12 (5-6) as the +flow control lines can cause NMIs.</PARA> +</SECT2> +<SECT2> +<TITLE>eCos GDB Stubs</TITLE> +<PARA>The eCos installation CD contains a copy of the eCos GDB stubs +in binary format which must be programmed into an EPROM or FLASH +and installed on the board.</PARA> +<SECT3> +<TITLE> Preparing the GDB stubs</TITLE> +<PARA>These stub preparation steps are not strictly necessary as +the eCos distribution ships with pre-compiled stubs in the directory +loaders/sh3-cq7708 relative to the installation root.</PARA> +</SECT3> +<SECT3> +<TITLE>Building the GDB stub image with the eCos Configuration Tool</TITLE> +<ORDEREDLIST> +<LISTITEM> +<PARA>Start with a new document - selecting the +<EMPHASIS>File->New</EMPHASIS> + menu item if necessary to do this.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Choose the +<EMPHASIS>Build->Templates</EMPHASIS> + menu item, and then select the SH3 cq7708 hardware.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>While still displaying the +<EMPHASIS>Build->Templates</EMPHASIS> + dialog box, select the stubs package template to build a GDB stub. +Click +<EMPHASIS>OK</EMPHASIS>.</PARA> +</LISTITEM> +<LISTITEM> +<PARA> Build eCos stubs using +<EMPHASIS>Build->Library</EMPHASIS>.</PARA> +</LISTITEM> +<LISTITEM> +<PARA> When the build completes, the image files can be found +in the +<FILENAME>bin/</FILENAME> + subdirectory of the install tree. GDB stub images have the prefix +<FILENAME>gdb_module</FILENAME>.</PARA> +</LISTITEM> +</ORDEREDLIST> +</SECT3> +<SECT3> +<TITLE> Building the GDB stub image with ecosconfig</TITLE> +<ORDEREDLIST> +<LISTITEM> +<PARA>Make an empty directory to contain the build tree, +and cd into it.</PARA> +</LISTITEM> +<LISTITEM> +<PARA> To build a GDB stub ROM image, enter the command: + +<PROGRAMLISTING>$ ecosconfig new cq7708 stubs </PROGRAMLISTING></PARA> +</LISTITEM> +<LISTITEM> +<PARA> Enter the commands: + +<PROGRAMLISTING>$ ecosconfig tree +$ make</PROGRAMLISTING></PARA> +</LISTITEM> +<LISTITEM> +<PARA>When the build completes, the image files can be found +in the +<FILENAME>bin/</FILENAME> + subdirectory of the install tree. GDB stub images have the prefix +<FILENAME>gdb_module</FILENAME>. </PARA> +</LISTITEM> +</ORDEREDLIST> +</SECT3> +</SECT2> +<SECT2> +<TITLE>Programming the stubs in EPROM/FLASH</TITLE> +<PARA>The board can use different sizes of ROMs. Use this table +to adjust the board’s jumpers to the ROM sizes you are +using.</PARA> +<PROGRAMLISTING>size(kbit) JP7 JP9 JP10 JP11 +256 2-3 2-3 open open +512 1-2 2-3 open open +1000 1-2 open open 2-3 +2000 1-2 1-2 open 2-3 +4000 1-2 1-2 short 2-3 +8000 1-2 1-2 short 1-2</PROGRAMLISTING> +<PARA>There are two ways to program the stubs. We advise you to +use method 1, since it is simpler. Method 2 is unsupported and requires +a bit of fiddling.</PARA> +<PARA><EMPHASIS>Method 1: </EMPHASIS> </PARA> +<PARA>Program the binary stub image into two EPROMs, E and O. EPROM +E should contain the even bytes, and O the odd bytes (your EPROM +programmer should have the ability to split the image).</PARA> +<PARA>EPROM E should be installed in socket IC8, and EPROM O should +be installed in socket IC4.</PARA> +<PARA>Set JP6 to 16 bit mode (1-2 soldered, 2-3 cut) Set SW1-4 +to ON and SW2-1 to OFF.</PARA> +<PARA></PARA> +<PARA><EMPHASIS>Method2: </EMPHASIS> </PARA> +<PARA>Assuming that the stub binary is smaller than 32 KB, you can +install it in a single EPROM.</PARA> +<PARA>Compile the <FILENAME>mkcqrom.c</FILENAME> program +found in the <FILENAME>misc</FILENAME> directory.</PARA> +<PARA>Use it to convert the binary image to the required format. +See the <FILENAME>mkcqrom.c</FILENAME> source for a +description of what is done, and why it is necessary. </PARA> +<PROGRAMLISTING> % mkcqrom gdb_module.bin gdb_mangled.bin</PROGRAMLISTING> +<PARA>Program the <FILENAME>gdb_mangled.bin</FILENAME> file +into an EPROM and install it in socket IC4</PARA> +<PARA>Set JP6 to 8 bit mode (cut 1-2, solder 2-3)</PARA> +<PARA>The GDB stubs allow communication with GDB using the serial +port at connector CN7. The communication parameters are fixed at +38400 baud, 8 data bits, no parity bit and 1 stop bit (8-N-1). No +flow control is employed. Connection to the host computer should +be made using a straight through serial cable.</PARA> +</SECT2> +</SECT1> +<SECT1 id="setup-sh-hs7729pci"> +<TITLE>SH3/HS7729PCI Hardware Setup</TITLE> +<PARA>Please see the RedBoot manual for instructions on how to prepare +the board for use with eCos.</PARA> +</SECT1> +<SECT1 id="setup-sh-se77x9"> +<TITLE>SH3/SE77x9 Hardware Setup</TITLE> +<PARA>Please see the RedBoot manual for instructions on how to prepare +the board for use with eCos.</PARA> +</SECT1> +<SECT1 id="setup-sh-cq7750"> +<TITLE>SH4/CQ7750 Hardware Setup</TITLE> +<SECT2> +<TITLE>Preparing the board</TITLE> +<PARA>Make sure the DIP switches on the board are set as follows: + </PARA> +<PROGRAMLISTING>SW1-1 ON +SW1-2 OFF +SW1-3 ON +SW1-4 OFF</PROGRAMLISTING> +<PROGRAMLISTING>SW2-1 ON +SW2-2 ON +SW2-3 OFF +SW2-4 OFF</PROGRAMLISTING> +<PARA>If you are using a straight through serial cable which has +flow control lines, you will also need to cut JP12 (5-6) as the +flow control lines can cause NMIs.</PARA> +</SECT2> +<SECT2> +<TITLE>eCos GDB Stubs</TITLE> +<PARA>The eCos installation CD contains a copy of the eCos GDB stubs +in binary format which must be programmed into an EPROM or FLASH +and installed on the board.</PARA> +<SECT3> +<TITLE> Preparing the GDB stubs</TITLE> +<PARA>These stub preparation steps are not strictly necessary as +the eCos distribution ships with pre-compiled stubs in the directory +loaders/sh3-cq7708 relative to the installation root.</PARA> +</SECT3> +<SECT3> +<TITLE>Building the GDB stub image with the eCos Configuration Tool</TITLE> +<ORDEREDLIST> +<LISTITEM> +<PARA>Start with a new document - selecting the +<EMPHASIS>File->New</EMPHASIS> + menu item if necessary to do this.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Choose the +<EMPHASIS>Build->Templates</EMPHASIS> + menu item, and then select the SH3 cq7708 hardware.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>While still displaying the +<EMPHASIS>Build->Templates</EMPHASIS> + dialog box, select the stubs package template to build a GDB stub. +Click +<EMPHASIS>OK</EMPHASIS>.</PARA> +</LISTITEM> +<LISTITEM> +<PARA> Build eCos stubs using +<EMPHASIS>Build->Library</EMPHASIS>.</PARA> +</LISTITEM> +<LISTITEM> +<PARA> When the build completes, the image files can be found +in the +<FILENAME>bin/</FILENAME> + subdirectory of the install tree. GDB stub images have the prefix +<FILENAME>gdb_module</FILENAME>.</PARA> +</LISTITEM> +</ORDEREDLIST> +</SECT3> +<SECT3> +<TITLE> Building the GDB stub image with ecosconfig</TITLE> +<ORDEREDLIST> +<LISTITEM> +<PARA>Make an empty directory to contain the build tree, +and cd into it.</PARA> +</LISTITEM> +<LISTITEM> +<PARA> To build a GDB stub ROM image, enter the command: + +<PROGRAMLISTING>$ ecosconfig new cq7708 stubs </PROGRAMLISTING></PARA> +</LISTITEM> +<LISTITEM> +<PARA> Enter the commands: + +<PROGRAMLISTING>$ ecosconfig tree +$ make</PROGRAMLISTING></PARA> +</LISTITEM> +<LISTITEM> +<PARA>When the build completes, the image files can be found +in the +<filename>bin/</filename> + subdirectory of the install tree. GDB stub images have the prefix +<filename>gdb_module</filename>. </PARA> +</LISTITEM> +</ORDEREDLIST> +</SECT3> +</SECT2> +<SECT2> +<TITLE>Programming the stubs in EPROM/FLASH</TITLE> +<PARA>The board can use different sizes of ROMs. Use this table +to adjust the board’s jumpers to the ROM sizes you are +using.</PARA> +<PROGRAMLISTING>size(kbit) JP7 JP9 JP10 JP11 +256 2-3 2-3 open open +512 1-2 2-3 open open +1000 1-2 open open 2-3 +2000 1-2 1-2 open 2-3 +4000 1-2 1-2 short 2-3 +8000 1-2 1-2 short 1-2</PROGRAMLISTING> +<PARA>There are two ways to program the stubs. We advise you to +use method 1, since it is simpler. Method 2 is unsupported and requires +a bit of fiddling.</PARA> +<PARA><EMPHASIS>Method 1: </EMPHASIS> </PARA> +<PARA>Program the binary stub image into two EPROMs, E and O. EPROM +E should contain the even bytes, and O the odd bytes (your EPROM +programmer should have the ability to split the image).</PARA> +<PARA>EPROM E should be installed in socket IC8, and EPROM O should +be installed in socket IC4.</PARA> +<PARA>Set JP6 to 16 bit mode (1-2 soldered, 2-3 cut) Set SW1-4 +to ON and SW2-1 to OFF.</PARA> +<PARA></PARA> +<PARA><EMPHASIS>Method2: </EMPHASIS> </PARA> +<PARA>Assuming that the stub binary is smaller than 32 KB, you can +install it in a single EPROM.</PARA> +<PARA>Compile the <filename>mkcqrom.c</filename> program +found in the <FILENAME>misc</FILENAME> directory.</PARA> +<PARA>Use it to convert the binary image to the required format. +See the <FILENAME>mkcqrom.c</FILENAME> source for a +description of what is done, and why it is necessary. </PARA> +<PROGRAMLISTING> % mkcqrom gdb_module.bin gdb_mangled.bin</PROGRAMLISTING> +<PARA>Program the <FILENAME>gdb_mangled.bin</FILENAME> file +into an EPROM and install it in socket IC4</PARA> +<PARA>Set JP6 to 8 bit mode (cut 1-2, solder 2-3)</PARA> +<PARA>The GDB stubs allow communication with GDB using the serial +port at connector CN7. The communication parameters are fixed at +38400 baud, 8 data bits, no parity bit and 1 stop bit (8-N-1). No +flow control is employed. Connection to the host computer should +be made using a straight through serial cable.</PARA> +</SECT2> +</SECT1> +<SECT1 id="setup-sh-se7751"> +<TITLE>SH4/SE7751 Hardware Setup</TITLE> +<PARA>Please see the RedBoot manual for instructions on how to prepare +the board for use with eCos.</PARA> +</SECT1> +<SECT1 id="setup-v850-cebsa1"> +<TITLE>NEC CEB-V850/SA1 Hardware Setup</TITLE> +<PARA>The CEB-V850 board is fitted with a socketed EPROM. The internal +Flash of the V850 supplied with the CEB-V850 boards defaults to +vectoring into this EPROM. A GDB stub image should be programmed +into an EPROM fitted to this board, and a pre-built image is provided +at <FILENAME>loaders/v850-ceb_v850/v850sa1/gdb_module.bin </FILENAME>under +the root of your eCos installation.</PARA> +<PARA>The EPROM is installed to the socket labelled U7 on the board. +Attention should be paid to the correct orientation of the EPROM +during installation. </PARA> +<PARA>When programming an EPROM using the binary image, be careful +to get the byte order correct. It needs to be little-endian. If +the EPROM burner software has a hex-editor, check that the first +few bytes of the image look similar to: </PARA> +<PROGRAMLISTING>00000000: 0018 8007 5e02 0000 0000 0000 0000 0000</PROGRAMLISTING> +<PARA>If the byte order is wrong you will see 1800 instead of 0018 +etc. Use the EPROM burner software to make a byte-swap before you +burn to image to the EPROM. </PARA> +<PARA>If the GDB stub EPROM you burn does not work, try reversing +the byte-order, even if you think you have it the right way around. +At least one DOS-based EPROM burner program is known to have the +byte-order upside down.</PARA> +<PARA>The GDB stub in the EPROM allows communication with GDB using +the serial port. The communication parameters are fixed at 38400 +baud, 8 data bits, no parity bit and 1 stop bit (8-N-1). No flow +control is employed. Connection to the host computer should be made +using a dedicated serial cable as specified in the CEB-V850/SA1 +manual.</PARA> +<SECT2> +<TITLE>Installing the Stubs into ROM</TITLE> +<SECT3> +<TITLE>Preparing the Binaries</TITLE> +<PARA>These two binary preparation steps are not strictly necessary +as the eCos distribution ships with pre-compiled binaries in the +directory loaders/v850-ceb_v850 relative to the +installation root.</PARA> +<SECT4> +<TITLE>Building the ROM images with the eCos Configuration Tool</TITLE> +<ORDEREDLIST> +<LISTITEM> +<PARA>Start with a new document - selecting the +<EMPHASIS>File->New</EMPHASIS> + menu item if necessary to do this.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Choose the +<EMPHASIS>Build->Templates</EMPHASIS> + menu item, and then select the NEC CEB-V850/SA1 hardware.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>While still displaying the +<EMPHASIS>Build->Templates</EMPHASIS> + dialog box, select the “stubs” package template +to build a GDB stub. Click +<EMPHASIS>OK</EMPHASIS>.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Build eCos using +<EMPHASIS>Build->Library</EMPHASIS>. </PARA> +</LISTITEM> +<LISTITEM> +<PARA>When the build completes, the image files can be found +in the bin/ subdirectory of the install tree. GDB stub +ROM images have the prefix “gdb_module”.</PARA> +</LISTITEM> +</ORDEREDLIST> +</SECT4> +<SECT4> +<TITLE>Building the ROM images with ecosconfig</TITLE> +<ORDEREDLIST> +<LISTITEM> +<PARA>Make an empty directory to contain the build tree, +and cd into it. </PARA> +</LISTITEM> +<LISTITEM> +<PARA>To build a GDB stub ROM image, enter the command: + +<PROGRAMLISTING>$ ecosconfig new ceb-v850 stubs </PROGRAMLISTING></PARA> +</LISTITEM> +<LISTITEM> +<PARA>Enter the commands: + +<PROGRAMLISTING>$ ecosconfig tree +$ make</PROGRAMLISTING> + </PARA> +</LISTITEM> +<LISTITEM> +<PARA>When the build completes, the image files can be found +in the bin/ subdirectory of the install tree. GDB stub +ROM images have the prefix “gdb_module”.</PARA> +</LISTITEM> +</ORDEREDLIST> +</SECT4> +</SECT3> +<SECT3> +<TITLE> Installing the Stubs into ROM or FLASH</TITLE> +<ORDEREDLIST> +<LISTITEM> +<PARA> Program the binary image file gdb_module.bin +into ROM or FLASH referring to the instructions of your ROM + programmer. </PARA> +</LISTITEM> +<LISTITEM> +<PARA> Plug the ROM/FLASH into the socket as described +at the beginning of this section.</PARA> +</LISTITEM> +</ORDEREDLIST> +</SECT3> +</SECT2> +<SECT2> +<TITLE>Debugging with the NEC V850 I.C.E.</TITLE> +<PARA>eCos applications may be debugged using the NEC V850 In Circuit +Emulator (I.C.E.) A PC running Microsoft Windows is required in +order to run the NEC ICE software and drivers. In addition Red Hat +have developed a “libremote” server application +named v850ice.exe which is used on the PC connected to the I.C.E. +in order to allow connections from GDB.</PARA> +<PARA>The I.C.E. must be physically connected to a Windows NT system +through NEC"s PCI or PC Card interface. A driver, DLLs, +and application are provided by NEC to control the I.C.E.</PARA> +<PARA>v850ice is a Cygwin based server that runs on the NT system +and provides an interface between the gdb client and the I.C.E. +software. v850-elf-gdb may be run on the Windows NT system or on +a remote system. v850-elf-gdb communicates with the libremote server +using the gdb remote protocol over a TCP/IP socket. v850ice +communicates with the I.C.E. by calling functions in the NECMSG.DLL provided +by NEC.</PARA> +<SECT3> +<TITLE>INITIAL SETUP</TITLE> +<ORDEREDLIST> +<LISTITEM> +<PARA>Configure the hardware including the I.C.E., SA1 or +SB1 Option Module, and target board. Install the interface card +in the Windows NT system. Reference NEC"s documentation +for interface installation, jumper settings, etc.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Install the Windows NT device driver provided by NEC.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Copy the NEC DLLs, MDI application, and other support +files to a directory on the Windows NT system. The standard location +is C:\NecTools32. This directory will be referred to as +the "libremote server directory" in this document. v850ice.exe must +also be copied to this directory after being built. The required +files are: cpu.cfg, Nec.cfg, MDI.EXE, NECMSG.DLL, EX85032.DLL, +V850E.DLL, IE850.MON, IE850E.MON, and D3037A.800.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Make certain the file cpu.cfg contains the line:</PARA> +<PROGRAMLISTING>CpuOption=SA1</PROGRAMLISTING> +<PARA>if using a V850/SA1 module, or:</PARA> +<PROGRAMLISTING>CpuOption=SB1</PROGRAMLISTING> +<PARA>if using a V850/SB1 module.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Set the environment variable IEPATH to point to the libremote +server</PARA> +<PARA>directory.</PARA> +</LISTITEM> +</ORDEREDLIST> +</SECT3> +<SECT3> +<TITLE>BUILD PROCEDURES</TITLE> +<PARA>A pre-built v850ice.exe executable is supplied in the loaders/v850-ceb_v850 directory +relative to the root of the eCos installation. However the following process +will allow the rebuilding of this executable if required:</PARA> +<PARA>For this example assume the v850ice libremote tree has been +copied to a directory named "server". The directory structure will +be similar to the following diagram:</PARA> +<PARA><PROGRAMLISTING> server + | + devo + / \ + config libremote + / \ + lib v850ice</PROGRAMLISTING></PARA> +<PARA>Build the v850ice source as follows. Be sure to use the native +Cygwin compiler tools that were supplied alongside eCos.</PARA> +<PARA>cd server +mkdir build +cd build +../devo/configure --target=v850-elf --host=i686-pc-cygwin +make</PARA> +<PARA>The resultant libremote server image (v850ice.exe) can be +found in build/libremote/v850ice. Copy v850ice.exe +to the lib remote server directory.</PARA> +</SECT3> +<SECT3> +<TITLE>V850ICE.EXE EXECUTION</TITLE> +<PARA>The v850ice command line syntax is:</PARA> +<PARA>v850ice [-d] [-t addr] [port number]</PARA> +<PARA>The optional -d option enables debug output. The -t option +is associated with thread debugging - see the "eCos thread debugging" +section below for details. By default v850ice listens on port 2345 +for an attach request from a gdb client. A different port number +may be specified on the command line.</PARA> +<PARA>To run the libremote server:</PARA> +<ORDEREDLIST> +<LISTITEM> +<PARA>Power on the I.C.E. and target board.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Open a Cygwin window.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>Run v850ice.</PARA> +</LISTITEM> +<LISTITEM> +<PARA>You will see the MDI interface window appear. In this +window you should see the "Connected to In-Circuit Emulator" message. + In the Cygwin window, the libremote server will indicate it is +ready to accept a gdb client connection with the message "v850ice: + listening on port 2345."</PARA> +</LISTITEM> +</ORDEREDLIST> +</SECT3> +<SECT3> +<TITLE>V850-ELF-GDB EXECUTION</TITLE> +<PARA>Run the v850-elf-gdb client to debug the V850 target. It +is necessary to issue certain configuration commands to the I.C.E. +software. These commands may be issued directly in the MDI window +or they may be issued from the gdb client through the "monitor" +command.</PARA> +<PARA>On the Cosmo CEB-V850 board, on-chip Flash is mapped at address +0x0, the on-board EPROM at 0x100000 and the on-board RAM at 0xfc0000. +Since a stand alone V850 will start executing from address 0x0 on +reset, it is normal to load either an application or a bootstrap +loader for Flash at this address. eCos programs may be built to +boot from Flash or the on-board EPROM. If building for the on-board +EPROM, it would be expected that the Flash will contain the default +CEB-V850 flash contents. An ELF format version of the default contents +may be found in the eCos distribution with the name v850flash.img.</PARA> +<PARA>In stand alone operation, normally the code in this flash image +would have been programmed into the V850 on the Cosmo board, and +this would cause it to vector into the on-board EPROM to run the +application located there. In the case of eCos, this application +may be a GDB stub ROM application, allowing the further download +to RAM over serial of actual applications to debug.</PARA> +<PARA>As an example, we shall demonstrate how to use the I.C.E. +to download the v850flash.img and GDB stub EPROM image using I.C.E. +emulator memory only, and not requiring any actual programming of +devices.</PARA> +<PARA>v850-elf-gdb -nw +(gdb) file v850flash.img +(gdb) target remote localhost:2345 +(gdb) monitor reset +(gdb) monitor cpu r=256 a=16 +(gdb) monitor map r=0x100000-L 0x80000 +(gdb) monitor map u=0xfc0000-L 0x40000 +(gdb) monitor pinmask k +(gdb) monitor step +(gdb) monitor step +(gdb) monitor step +(gdb) monitor step +(gdb) load +(gdb) detach +(gdb) file gdb_module.img +(gdb) target remote localhost:2345 +(gdb) load +(gdb) continue</PARA> +<PARA>NOTE: The four "monitor step" commands are only required the +first time the board is connected to the I.C.E., otherwise the program +will fail.</PARA> +<PARA>This is because of a limitation of the I.C.E. hardware that +means that the first time it is used, the "map" commands are not +acted on and the addresses "0x100000" and "0xfc0000" are not mapped. +This can be observed using the command "td e-20" in the MDI application"s +console to display the trace buffer, which will show that the contents +of address 0x100000 are not valid. Subsequent runs do not require +the "monitor step" commands.</PARA> +<PARA>It is unusual to load two executable images to a target through +gdb. From the example above notice that this is accomplished by +attaching to the libremote server, loading the flash image, detaching, +reattaching, and loading the ROM/RAM image. It is more +normal to build an executable image that can be executed directly. +In eCos this is achieved by selecting either the ROM or ROMRAM startup +type, and optionally enable building for the internal FLASH. The +I.C.E. emulator memory can emulate both the internal FLASH and the +EPROM, so real hardware programming is not required.</PARA> +<PARA>Upon running this example you will notice that the libremote +server does not exit upon detecting a detach request, but simply +begins listening for the next attach request. To cause v850ice +to terminate, issue the "monitor quit" or "monitor exit" command +from the gdb client. v850ice will then terminate with the next +detach request. (You can also enter control-c in the Cygwin/DOS +window where v850ice is running.)</PARA> +</SECT3> +<SECT3> +<TITLE>MDI INTERFACE VS. GDB INTERFACE</TITLE> +<PARA>If a filename is referenced in an MDI command, whether the +command is entered in the MDI window or issued from the gdb client +with the monitor command, the file must reside on the Windows NT +libremote server system. When specifying a filename when entering +a command in the MDI window it is obvious that a server local file +is being referenced. When issuing an MDI command from the gdb client, the +user must remember that the command line is simply passed to the +I.C.E. software on the server system. The command is executed by +the I.C.E. software as though it were entered locally.</PARA> +<PARA>Executable images may be loaded into the V850 target by entering +the "load" command in the MDI window or with the gdb "load" command. + If the MDI load command is used, the executable image must be located +on the server system and must be in S Record format. If the gdb +load command is used, the executable image must be located on the +client system and must be in ELF format.</PARA> +<PARA>Be aware that the gdb client is not aware of debugger commands +issued from the MDI window. It is possible to cause the gdb client +and the I.C.E. software to get out of sync by issuing commands from +both interfaces during the same debugging session.</PARA> +</SECT3> +<SECT3> +<TITLE>eCos THREAD DEBUGGING</TITLE> +<PARA>eCos and the V850 I.C.E. libremote server have been written +to work together to allow debugging of eCos threads. This is an +optional feature, disabled by default because of the overheads trying +to detect a threaded program involves.</PARA> +<PARA>Obviously thread debugging is not possible for programs with +"RAM" startup type, as they are expected to operate underneath a +separate ROM monitor (such as a GDB stub ROM), that itself would +provide its own thread debugging capabilities over the serial line. +Thread debugging is relevant only for programs built for Flash, ROM, +or ROMRAM startup.</PARA> +<PARA>To configure the libremote server to support thread debugging, +use the command:</PARA> +<PARA><PROGRAMLISTING>(gdb) monitor syscallinfo ADDRESS</PROGRAMLISTING></PARA> +<PARA>at the GDB console prompt, where ADDRESS is the address of +the syscall information structure included in the applications. +In eCos this has been designed to be located at a consistent address +for each CPU model (V850/SA1 or V850/SB1). It +may be determined from an eCos executable using the following command +at a cygwin bash prompt:</PARA> +<PARA><PROGRAMLISTING>v850-elf-nm EXECUTABLE | grep hal_v85x_ice_syscall_info</PROGRAMLISTING></PARA> +<PARA>At the current time, this address is 0xfc0400 for a Cosmo +board fitted with a V850/SA1, or 0xfc0540 for a Cosmo board +fitted with a V850/SB1.</PARA> +<PARA>So for example, the GDB command for the SB1 would be:</PARA> +<PARA><PROGRAMLISTING>(gdb) monitor syscallinfo 0xfc0540</PROGRAMLISTING></PARA> +<PARA>Given that the syscallinfo address is fixed over all eCos +executables for a given target, it is possible to define it on the +libremote command line as well using the "-t" option, for example:</PARA> +<PARA><PROGRAMLISTING>bash$ v850ice -t 0xfc0400 +v850ice: listening on port 2345</PROGRAMLISTING></PARA> +</SECT3> +</SECT2> +</SECT1> +<SECT1 id="setup-v850-cebsb1"> +<TITLE>NEC CEB-V850/SB1 Hardware Setup</TITLE> +<PARA>The instructions for setting up the CEB-V850/SB1 +are virtually identical to those of the CEB-V850/SA1 above. +The only significant differences are that pre-built loaders are available +at loaders/v850-ceb_v850/v850sb1 within +the eCos installation. Binaries supporting boards with both 16MHz +and 8MHz clock speeds are supplied. Also when building applications, +or rebuilding the stubs for a V850/SB1 target, then the +V850 CPU variant must be changed in the CEB-V850 HAL to the SB1.</PARA> +</SECT1> +<SECT1 id="setup-i386-pc"> +<TITLE>i386 PC Hardware Setup</TITLE> +<para> +eCos application on the PC can be run in three ways: via RedBoot, +loaded directly from a floppy disk, or loaded by the GRUB bootloader. +</para> +<sect2> +<title>RedBoot Support</title> +<PARA>For information about setting up the PC to run with RedBoot, +consult the RedBoot User"s Guide. If using serial debugging, +the serial line runs at 38400 baud 8-N-1 and should be connected +to the debug host using a null modem cable. If ethernet debugging +is required, an i82559 compatible network interface card, such as +an Intel EtherExpress Pro 10/100, should be installed +on the target PC and connected to the development PC running GDB. +When RedBoot is configured appropriately to have an IP address set, +then GDB will be able to debug directly over TCP/IP to the +target PC.</PARA> +</sect2> +<sect2> +<title>Floppy Disk Support</title> +<para> +If an application is built with a startup type of FLOPPY, then it is +configured to be a self-booting image that must be written onto a +formatted floppy disk. This will erase any existing file system or +data that is already on the disk, so proceed +with caution. +</para> +<para> +To write an application to floppy disk, it must first be converted to +a pure binary format. This is done with the following command: +</para> +<screen width=72> +$ <userinput>i386-elf-objcopy -O binary app.elf app.bin</userinput> +</screen> +<para> +Here <filename>app.elf</filename> is the final linked application +executable, in ELF format (it may not have a <filename>.elf</filename> +extension). The file <filename>app.bin</filename> is the resulting +pure binary file. This must be written to the floppy disk with the +following command: +<screen width=72> +$ <userinput>dd conv=sync if=app.bin of=/dev/fd0</userinput> +</screen> +</para> +<para>For NT Cygwin users, this can be done by first ensuring that the raw +floppy device is mounted as <filename>/dev/fd0</filename>. To check if this +is the case, type the command <command>mount</command> at the Cygwin bash +prompt. If the floppy drive is already mounted, it will be listed as something +similar to the following line:</para> +<screen> \\.\a: /dev/fd0 user binmode</screen> +<para>If this line is not listed, then mount the floppy drive using the command: +</para> +<screen>$ <userinput>mount -f -b //./a: /dev/fd0</userinput></screen> +<para>To actually install the boot image on the floppy, use the command:</para> +<screen> +$ <userinput>dd conv=sync if=app.bin of=/dev/fd0</userinput> +</screen> +<para>Insert this floppy in the A: drive of the PC to be used as a target +and ensure that the BIOS is configured to boot from A: by default. On reset, +the PC will boot from the floppy and the eCos application will load +itself and execute immediately.</para> +<note><title>NOTE</title> +<para>Unreliable floppy media may cause the write to silently fail. This +can be determined if the RedBoot image does not correctly +boot. In such cases, the floppy should be (unconditionally) reformatted +using the <command>fdformat</command> command on Linux, or +<command>format a: /u</command> on DOS/Windows. If this fails, try a +different disk.</para> +</note> +</sect2> +<sect2> +<title>GRUB Bootloader Support (version 0.97)</title> +<para> +If an application is built with the GRUB startup type, it is +configured to be loaded by the GRUB bootloader. +</para> +<para> +GRUB is an open source boot loader that supports many different +operating systems. It is available from +<ulink +url="http://www.gnu.org/software/grub">http://www.gnu.org/software/grub</ulink>. +The latest version of GRUB should be downloaded from there and installed. +In Red Hat Linux version 7.2 and later it is the default bootloader +for Linux and therefore is already installed. +</para> +<para> +To install GRUB on a floppy disk from Linux you need to execute the +following commands: +</para> +<screen> +$ <userinput>mformat a:</userinput> +$ <userinput>mount /mnt/floppy</userinput> +$ <userinput>grub-install --root-directory=/mnt/floppy '(fd0)'</userinput> +Probing devices to guess BIOS drives. This may take a long time. +Installation finished. No error reported. +This is the contents of the device map /mnt/floppy/boot/grub/device.map. +Check if this is correct or not. If any of the lines is incorrect, +fix it and re-run the script `grub-install'. + +(fd0) /dev/fd0 +$ <userinput>cp $ECOS_REPOSITORY/packages/hal/i386/pc/current/misc/menu.lst /mnt/floppy/boot/grub</userinput> +$ <userinput>umount /mnt/floppy</userinput> +</screen> +<para> +The file <filename>menu.lst</filename> is an example GRUB menu +configuration file. It contains menu items to load some of the +standard eCos tests from floppy or from partition zero of the first +hard disk. You should, of course, customize this file to load your own +application. Alternatively you can use the command-line interface of +GRUB to input commands yourself. +</para> +<para> +Applications can be installed, or updated simply by copying them to +the floppy disk at the location expected by the +<filename>menu.lst</filename> file. For booting from floppy disks it +is recommended that the executable be stripped of all debug and symbol +table information before copying. This reduces the size of the file +and can make booting faster. +</para> +<para> +To install GRUB on a hard disk, refer to the GRUB documentation. Be +warned, however, that if you get this wrong it may compromise any +existing bootloader that exists on the hard disk and may make any +other operating systems unbootable. Practice on floppy disks or +sacrificial hard disks first. On machines running Red Hat Linux +version 7.2 and later, you can just add your own menu items to the +<filename>/boot/grub/menu.lst</filename> file that already exists. +</para> +</sect2> +<sect2> +<title>GRUB 2 Bootloader Support (version 1.98)</title> +<para> +If an application is built with the GRUB startup type, it is +configured to be loaded by the GRUB bootloader. +</para> +<para> +GRUB 2 is an open source boot loader that supports many different +operating systems. GRUB 2 is the sucessor to the legacy GRUB boot +loader. It has been rewritten and requires a new configuration +file that is different from the legacy GRUB loader. +It is available from +<ulink +url="http://www.gnu.org/software/grub">http://www.gnu.org/software/grub</ulink>. +The latest version of GRUB should be downloaded from there and installed. +Cygwin users will need to install the GRand Unified Bootloader package on their +system. +</para> +<para> +To install GRUB 2 on a disk drive from Cygwin you will first need to +format your disk. Begin by launching a windows Command Prompt with +ADMINISTRATOR priviledges. This example assumes that your destination +drive is E and the filesystem type is FAT32. +</para> +<screen> +$ <userinput>format e: /fs:fat32 /q</userinput> + +The type of the file system is FAT32. +WARNING, ALL DATA ON NON-REMOVABLE DISK +DRIVE E: WILL BE LOST! +Proceed with Format (Y/N)? y +QuickFormatting 512M +Initializing the File Allocation Table (FAT)... +Volume label (11 characters, ENTER for none)? +Format complete. +</screen> +<para> +When your drive is finished formatting, Cygwin will automatically +mount the drive under /cygdrive/e. Next, launch a bash shell. +Cygwin users should run their shell as ADMINISTRATOR otherwise +the grub-install program will fail. To install GRUB we need to +know the device name for your disk. A second disk drive is usually +called /dev/sdb. The C: drive is usually called /dev/sda. Determine +your device name by reading the /proc/partitions file. +This example uses /dev/sdb as input to the GRUB install program. +</para> +<screen> +$ <userinput>cat /proc/partitions</userinput> +major minor #blocks name + 8 0 156290904 sda + 8 1 102400 sda1 + 8 2 156185600 sda2 + 8 16 156290904 sdb + 8 17 524288 sdb1 + +$ <userinput>grub-install --root-directory=/cygdrive/e /dev/sdb</userinput> +Installation finished. No error reported. + +$ <userinput>cp $ECOS_REPOSITORY/packages/hal/i386/pc/current/misc/grub.cfg /cygdrive/e/boot/grub</userinput> + +$ <userinput>cp redboot.elf /cygdrive/e/boot</userinput> +</screen> +<para> +After installing GRUB 2, we need to a copy a configuration +file for grub to use. The file <filename>grub.cfg</filename> is an example +configuration file that loads redboot.elf. You should, of course, customize +this file to load your own application. Alternatively you can use the command-line +interface of GRUB to input commands yourself. Applications can be installed or +updated simply by copying them to the location expected by the +<filename>grub.cfg</filename> file. In this example the /boot directory is used. +</para> +<para> +When installing GRUB on a hard disk, refer to the GRUB documentation. Be +warned, however, that if you get this wrong it may compromise any +existing bootloader that exists on the hard disk and may make any +other operating systems unbootable. Practice on a spare disk or +sacrificial hard disks first. +</para> +</sect2> +<sect2> +<title>Debugging FLOPPY and GRUB Applications</title> +<para> +When RedBoot loads an application it also provides debugging services +in the form of GDB remote protocol stubs. When an application is +loaded stand-alone from a floppy disk, or by GRUB, these services are +not present. To allow these application to be debugged, it is possible +to include GDB stubs into the application. +</para> +<para> +To do this, set the "Support for GDB stubs" +(<literal>CYGDBG_HAL_DEBUG_GDB_INCLUDE_STUBS</literal>) configuration +option. Following this any application built will allow GDB to connect +to the debug serial port (by default serial device 0, also known as +COM1) whenever the application takes an exception, or if a Control-C +is typed to the debug port. Ethernet debugging is not supported. +</para> +<para> +The option "Enable initial breakpoint" +(<literal>CYGDBG_HAL_DEBUG_GDB_INITIAL_BREAK</literal>) causes the HAL +to take a breakpoint immediately before calling cyg_start(). This +gives the developer a chance to set any breakpoints or inspect the +system state before it proceeds. The configuration sets this option by +default if GDB stubs are included, and this is not a RedBoot build. To +make the application execute immediately either disable this option, +or disable <literal>CYGDBG_HAL_DEBUG_GDB_INCLUDE_STUBS</literal>. +</para> +</sect2> +</SECT1> +<SECT1 id="setup-synth-i386linux"> +<TITLE><!-- <conditionaltext> --><!-- <index></index> -->i386/Linux Synthetic Target Setup</TITLE> +<PARA>When building for the synthetic Linux target, the resulting +binaries are native Linux applications with the HAL providing suitable +bindings between the eCos kernel and the Linux kernel.</PARA> +<NOTE> +<PARA>Please be aware that the current implementation of the Linux +synthetic target does not allow thread-aware debugging.</PARA> +</NOTE> +<PARA>These Linux applications cannot be run on a Windows system. +However, it is possible to write a similar HAL emulation for the +Windows kernel if such a testing target is desired.</PARA> +<SECT2> +<TITLE>Tools</TITLE> + +<PARA>For the synthetic target, eCos relies on features not available +in native compilers earlier than gcc-2.95.1. It also requires version +2.9.5 or later of the GNU linker. If you have gcc-2.95.1 or later +and ld version 2.9.5 or later, then you do not need to build new +tools. eCos does not support earlier versions. You can check the compiler +version using <COMMAND>gcc -v</COMMAND> +and the linker version using <COMMAND>ld +-v</COMMAND>.</PARA> + +<PARA>If you have native tools that are sufficiently recent for +use with eCos, you should be aware that by default eCos assumes +that the tools <COMMAND>i686-pc-linux-gnu-gcc</COMMAND>, <COMMAND>i686-pc-linux-gnu-ar</COMMAND>, + <COMMAND>i686-pc-linux-gnu-ld</COMMAND>, and <COMMAND>i686-pc-linux-gnu-objcopy</COMMAND> are +on your system and are the correct versions for use with eCos. But +instead, you can tell eCos to use your native tools by editing the +configuration value "Global command prefix" (CYGBLD_GLOBAL_COMMAND_PREFIX) +in your eCos configuration. If left empty (i.e. set to the empty +string) eCos will use your native tools when building.</PARA> +<PARA>If you have any difficulties, it is almost certainly easiest +overall to rebuild the tools as described on: <ULINK URL="http://ecos.sourceware.org/getstart.html">http://ecos.sourceware.org/getstart.html</ULINK></PARA> +</SECT2> +</SECT1> + + +</appendix> diff --git a/ecos/doc/sgml/user-guide/user-guide.sgml b/ecos/doc/sgml/user-guide/user-guide.sgml new file mode 100755 index 0000000..d2f3104 --- /dev/null +++ b/ecos/doc/sgml/user-guide/user-guide.sgml @@ -0,0 +1,141 @@ +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [ + +<!-- Begin Document Specific Declarations --> + +<?Fm: Validation Off> + +<!ENTITY ui "µITRON"> +<!ENTITY cygnus-full "Cygnus Solutions"> +<!ENTITY cygnus-legal-notice SYSTEM "CYGNUS-TERMS"> +<!ENTITY ecos-license SYSTEM "ecos-license.sgml"> +<!ENTITY introduction SYSTEM "introduction.sgml"> +<!ENTITY installation SYSTEM "installation.sgml"> +<!ENTITY programming SYSTEM "programming.sgml"> +<!ENTITY config-tool SYSTEM "config-tool.sgml"> +<!ENTITY programming-concepts-and-techniques SYSTEM "programming-concepts-techniques.sgml"> +<!ENTITY configuration SYSTEM "configuration.sgml"> +<!ENTITY target-setup SYSTEM "target-setup.sgml"> +<!ENTITY real-time-characterization SYSTEM "real-time-characterization.sgml"> + +<!NOTATION PNG SYSTEM "PNG"> +<!ENTITY send-pr SYSTEM "send-pr.sgml"> +<!ENTITY graphic1 SYSTEM "pix/config-f1.png" NDATA png> +<!ENTITY graphic2 SYSTEM "pix/repos-relocate.png" NDATA png> +<!ENTITY graphic3 SYSTEM "pix/save-as-dialog.png" NDATA png> +<!ENTITY graphic4 SYSTEM "pix/open-dialog.png" NDATA png> +<!ENTITY graphic5 SYSTEM "pix/html-help.png" NDATA png> +<!ENTITY graphic6 SYSTEM "pix/settings-viewers.png" NDATA png> +<!ENTITY graphic7 SYSTEM "pix/configwin.png" NDATA png> +<!ENTITY graphic8 SYSTEM "pix/conflictwin.png" NDATA png> +<!ENTITY graphic9 SYSTEM "pix/propwin.png" NDATA png> +<!ENTITY graphic10 SYSTEM "pix/memorywin.png" NDATA png> +<!ENTITY graphic11 SYSTEM "pix/regprops.png" NDATA png> +<!ENTITY graphic12 SYSTEM "pix/memregions.png" NDATA png> +<!ENTITY graphic13 SYSTEM "pix/memreloc.png" NDATA png> +<!ENTITY graphic14 SYSTEM "pix/BuildPackages.png" NDATA png> +<!ENTITY graphic15 SYSTEM "pix/toolsplatforms.png" NDATA png> +<!ENTITY graphic16 SYSTEM "pix/modifyplatform.png" NDATA png> +<!ENTITY graphic17 SYSTEM "pix/addplatform.png" NDATA png> +<!ENTITY graphic18 SYSTEM "pix/templates.png" NDATA png> +<!ENTITY graphic19 SYSTEM "pix/ToolsOptions.png" NDATA png> +<!ENTITY graphic20 SYSTEM "pix/Conflicts.png" NDATA png> +<!ENTITY graphic21 SYSTEM "pix/find-dialog.png" NDATA png> +<!ENTITY graphic22 SYSTEM "pix/buildoptions.png" NDATA png> +<!ENTITY graphic23 SYSTEM "pix/build-tools2.png" NDATA png> +<!ENTITY graphic24 SYSTEM "pix/user-tools-dialog.png" NDATA png> +<!ENTITY graphic25 SYSTEM "pix/ch-properties-dialog.png" NDATA png> +<!ENTITY graphic26 SYSTEM "pix/connection.png" NDATA png> +<!ENTITY graphic27 SYSTEM "pix/run-tests.png" NDATA png> +<!ENTITY graphic28 SYSTEM "pix/addfromfolder.png" NDATA png> +<!ENTITY graphic29 SYSTEM "pix/bash.png" NDATA png> +<!ENTITY graphic30 SYSTEM "pix/comprepos.png" NDATA png> +<!ENTITY graphic31 SYSTEM "pix/admin.png" NDATA png> +<!ENTITY graphic32 SYSTEM "pix/settings-display.png" NDATA png> +<!ENTITY graphic33 SYSTEM "pix/settings-confict.png" NDATA png> +<!ENTITY graphic34 SYSTEM "pix/settings-runtests.png" NDATA png> +<!ENTITY programming-graphic1 SYSTEM "pix/config-f1.png" NDATA png> +<!ENTITY programming-graphic2 SYSTEM "pix/templates01.png" NDATA png> +<!ENTITY programming-graphic3 SYSTEM "pix/ARMStartup01.png" NDATA png> +<!ENTITY programming-graphic4 SYSTEM "pix/build-lib01.png" NDATA png> +<!ENTITY programming-graphic5 SYSTEM "pix/save-as-dialog.png" NDATA png> +<!ENTITY programming-graphic6 SYSTEM "pix/build-tools2.png" NDATA png> +<!ENTITY programming-graphic7 SYSTEM "pix/user-tools-dialog.png" NDATA png> +<!ENTITY programming-graphic8 SYSTEM "pix/build-tests01.png" NDATA png> +<!ENTITY programming-graphic9 SYSTEM "pix/twothreads2.png" NDATA png> + +<!-- <!ENTITY version CDATA "<version>"> --> +<!ENTITY Version CDATA "<version>"> + +<!-- End Document Specific Declarations --> + +]> + +<BOOK ID="ECOS-USER-GUIDE"> + <bookinfo> + <TITLE>eCos User Guide</TITLE> + <copyright><year>2001, 2002, 2003, 2004, 2009, 2010, 2011</year><holder>Free Software Foundation, Inc.</holder></copyright> + + <legalnotice> + <title>Documentation licensing terms</title> +<para>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 +<ulink url="http://www.opencontent.org/openpub/">http://www.opencontent.org/openpub/</ulink>). +</para> +<para> +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. +</para> + </legalnotice> + <legalnotice> + <title>Trademarks</title> +<para>Altera® and Excalibur™ are trademarks of Altera Corporation.</para> +<para>AMD® is a registered trademark of Advanced Micro Devices, Inc.</para> +<para>ARM®, StrongARM®, Thumb®, ARM7™, ARM9™ is a registered trademark of Advanced RISC Machines, Ltd.</para> +<para>Cirrus Logic® and Maverick™ are registered trademarks of Cirrus Logic, Inc.</para> +<para>Cogent™ is a trademark of Cogent Computer Systems, Inc.</para> +<para>Compaq® is a registered trademark of the Compaq Computer Corporation.</para> +<para>eCos® is a registered trademark of eCosCentric Limited.</para> +<para>Fujitsu® is a registered trademark of Fujitsu Limited.</para> +<para>IBM®, and PowerPC™ are trademarks of International Business Machines Corporation.</para> +<para>IDT® is a registered trademark of Integrated Device Technology Inc.</para> +<para>Intel®, i386™, Pentium®, StrataFlash® and XScale™ are trademarks of Intel Corporation.</para> +<para>Intrinsyc® and Cerf™ are trademarks of Intrinsyc Software, Inc.</para> +<para>Linux® is a registered trademark of Linus Torvalds. </para> +<para>Matsushita™ and Panasonic® are trademarks of the Matsushita Electric Industrial Corporation.</para> +<para>Microsoft®, Windows®, Windows NT® and Windows XP® are registered trademarks of Microsoft Corporation, Inc. </para> +<para>MIPS®, MIPS32™ MIPS64™, 4K&trade, 5K™ Atlas™ and Malta™ are trademarks of MIPS Technologies, Inc.</para> +<para>Motorola®, ColdFire® is a trademark of Motorola, Inc.</para> +<para>NEC® V800™, V850™, V850/SA1™, V850/SB1™, VR4300™, and VRC4375™ are trademarks of NEC Corporation.</para> +<para>PMC-Sierra® RM7000™ and Ocelot™ are trademarks of PMC-Sierra Incorporated. </para> +<para>Red Hat, RedBoot™, GNUPro®, and Insight™ are trademarks of Red Hat, Inc. </para> +<para>Samsung® and CalmRISC™ are trademarks or registered trademarks of Samsung, Inc. </para> +<para>Sharp® is a registered trademark of Sharp Electronics Corp.</para> +<para>SPARC® is a registered trademark of SPARC International, Inc., and is used under license by Sun Microsystems, Inc. </para> +<para>Sun Microsystems® and Solaris® are registered trademarks of Sun Microsystems, Inc. </para> +<para>SuperH™ and Renesas™ are trademarks owned by Renesas Technology Corp.</para> +<para>Texas Instruments®, OMAP™ and Innovator™ are trademarks of Texas Instruments Incorporated.</para> +<para>Toshiba® is a registered trademark of the Toshiba Corporation.</para> +<para>UNIX® is a registered trademark of The Open Group. </para> +<para>All other brand and product names, trademarks, and copyrights are the +property of their respective owners. </para> + </legalnotice> + </bookinfo> + + + &introduction; + &installation; + &programming; + &config-tool; + &programming-concepts-and-techniques; + &configuration; + + <part id="appendices"> + <title>Appendixes</title> + &target-setup; + &real-time-characterization; + &ecos-license; + </part> + +</BOOK> |
