source: rtems-docs/develenv/develenv.rst @ 11d2a74

4.115am
Last change on this file since 11d2a74 was 11d2a74, checked in by Amar Takhar <verm@…>, on 01/16/16 at 15:51:05

Fix warnings.

  • Property mode set to 100644
File size: 50.7 KB
Line 
1:orphan:
2
3
4
5.. COMMENT: %**end of header
6
7.. COMMENT: COPYRIGHT (c) 1989-2013.
8
9.. COMMENT: On-Line Applications Research Corporation (OAR).
10
11.. COMMENT: All rights reserved.
12
13.. COMMENT: Master file
14
15.. COMMENT: Joel's Questions
16
17.. COMMENT: 1.  Why does paragraphindent only impact makeinfo?
18
19.. COMMENT: 2.  Why does paragraphindent show up in HTML?
20
21.. COMMENT: COPYRIGHT (c) 1988-2002.
22
23.. COMMENT: On-Line Applications Research Corporation (OAR).
24
25.. COMMENT: All rights reserved.
26
27.. COMMENT: The following determines which set of the tables and figures we will use.
28
29.. COMMENT: We default to ASCII but if available TeX or HTML versions will
30
31.. COMMENT: be used instead.
32
33.. COMMENT: @clear use-html
34
35.. COMMENT: @clear use-tex
36
37.. COMMENT: The following variable says to use texinfo or html for the two column
38
39.. COMMENT: texinfo tables.  For somethings the format does not look good in html.
40
41.. COMMENT: With our adjustment to the left column in TeX, it nearly always looks
42
43.. COMMENT: good printed.
44
45.. COMMENT: Custom whitespace adjustments.  We could fiddle a bit more.
46
47.. COMMENT: variable substitution info:
48
49.. COMMENT: @set LANGUAGE C
50
51.. COMMENT: the language is @value{LANGUAGE}
52
53.. COMMENT: NOTE:  don't use underscore in the name
54
55.. COMMENT: Title Page Stuff
56
57.. COMMENT: I don't really like having a short title page.  -joel
58
59.. COMMENT: @shorttitlepage RTEMS Development Environment Guide
60
61===================================
62RTEMS Development Environment Guide
63===================================
64
65.. COMMENT: COPYRIGHT (c) 1988-2015.
66
67.. COMMENT: On-Line Applications Research Corporation (OAR).
68
69.. COMMENT: All rights reserved.
70
71.. COMMENT: The following puts a space somewhere on an otherwise empty page so we
72
73.. COMMENT: can force the copyright description onto a left hand page.
74
75COPYRIGHT © 1988 - 2015.
76
77On-Line Applications Research Corporation (OAR).
78
79The authors have used their best efforts in preparing
80this material.  These efforts include the development, research,
81and testing of the theories and programs to determine their
82effectiveness.  No warranty of any kind, expressed or implied,
83with regard to the software or the material contained in this
84document is provided.  No liability arising out of the
85application or use of any product described in this document is
86assumed.  The authors reserve the right to revise this material
87and to make changes from time to time in the content hereof
88without obligation to notify anyone of such revision or changes.
89
90The RTEMS Project is hosted at http://www.rtems.org.  Any
91inquiries concerning RTEMS, its related support components, or its
92documentation should be directed to the Community Project hosted athttp://www.rtems.org.
93
94Any inquiries for commercial services including training, support, custom
95development, application development assistance should be directed tohttp://www.rtems.com.
96
97.. COMMENT: This prevents a black box from being printed on "overflow" lines.
98
99.. COMMENT: The alternative is to rework a sentence to avoid this problem.
100
101RTEMS Development Environment Guide
102###################################
103
104.. COMMENT: COPYRIGHT (c) 1989-2011.
105
106.. COMMENT: On-Line Applications Research Corporation (OAR).
107
108.. COMMENT: All rights reserved.
109
110Introduction
111############
112
113This document describes the RTEMS development
114environment.  Discussions are provided for the following topics:
115
116- the directory structure used by RTEMS,
117
118- usage of the GNU Make utility within the RTEMS
119  development environment,
120
121- sample applications, and
122
123- the RTEMS specific utilities.
124
125RTEMS was designed as a reusable software component.
126Highly reusable software such as RTEMS is typically distributed
127in the form of source code without providing any support tools.
128RTEMS is the foundation for a complex family of facilities
129including board support packages, device drivers, and support
130libraries.  The RTEMS Development Environment is not a CASE
131tool.  It is a collection of tools designed to reduce the
132complexity of using and enhancing the RTEMS family.  Tools are
133provided which aid in the management of the development,
134maintenance, and usage of RTEMS, its run-time support
135facilities, and applications which utilize the executive.
136
137A key component of the RTEMS development environment
138is the GNU family of free tools.  This is  robust set of
139development and POSIX compatible tools for which source code is
140freely available.  The primary compilers, assemblers, linkers,
141and make utility used by the RTEMS development team are the GNU
142tools.  They are highly portable supporting a wide variety of
143host computers and, in the case of the development tools, a wide
144variety of target processors.
145
146It is recommended that the RTEMS developer become
147familiar with the RTEMS Development Environment before
148proceeding with any modifications to the executive source tree.
149The source code for the executive is very modular and source
150code is divided amongst directories based upon functionality as
151well as dependencies on CPU and target board.  This organization
152is aimed at isolating and minimizing non-portable code.  This
153has the immediate result that adding support for a new CPU or
154target board requires very little "wandering" around the source
155tree.
156
157.. COMMENT: COPYRIGHT (c) 1989-2010.
158
159.. COMMENT: On-Line Applications Research Corporation (OAR).
160
161.. COMMENT: All rights reserved.
162
163Directory Structure
164###################
165
166The RTEMS directory structure is designed to meet
167the following requirements:
168
169- encourage development of modular components.
170
171- isolate processor and target dependent code, while
172  allowing as much common source code as possible to be shared
173  across multiple processors and target boards.
174
175- allow multiple RTEMS users to perform simultaneous
176  compilation of RTEMS and its support facilities for different
177  processors and targets.
178
179The resulting directory structure has processor and
180board dependent source files isolated from generic files.  When
181RTEMS is configured and built, object directories and
182an install point will be automatically created based upon
183the target CPU family and BSP selected.
184
185The placement of object files based upon the selected BSP name
186ensures that object files are not mixed across CPUs or targets.
187This in combination with the makefiles allows the specific
188compilation options to be tailored for a particular target
189board.  For example, the efficiency of the memory subsystem for
190a particular target board may be sensitive to the alignment of
191data structures, while on another target board with the same
192processor memory may be very limited.  For the first target, the
193options could specify very strict alignment requirements, while
194on the second the data structures could be *packed* to conserve
195memory.  It is impossible to achieve this degree of flexibility
196without providing source code.
197
198The RTEMS source tree is organized based on the following variables:
199
200- functionality,
201
202- target processor family,
203
204- target processor model,
205
206- peripherals, and
207
208- target board.
209
210Each of the following sections will describe the
211contents of the directories in the RTEMS source
212tree.  The top of the tree will be referenced
213as ``${RTEMS_ROOT}`` in this discussion.
214
215.. COMMENT: Top Level Tree
216
217.. COMMENT: @ifset use-ascii
218.. code:: c
219
220    rtems-VERSION
221    |
222    +--------+----+----+----+--+-----+---+-------+--------+
223    |        |    |    |       |     |   |       |        |
224    aclocal automake c contrib  cpukit doc make testsuites tools
225
226.. COMMENT: @end ifset
227
228``${RTEMS_ROOT}/aclocal/``
229    This directory contains the custom M4 macros which are available to
230    the various GNU autoconf ``configure.ac`` scripts throughout
231    the RTEMS source tree.  GNU autoconf interprets ``configure.ac``
232    files to produce the ``configure`` files used to tailor
233    RTEMS build for a particular host and target environment.  The
234    contents of this directory will not be discussed further in this
235    document.
236
237``${RTEMS_ROOT}/automake/``
238    This directory contains the custom GNU automake fragments
239    which are used to support the various ``Makefile.am``
240    files throughout the RTEMS source tree.  The
241    contents of this directory will not be discussed
242    further in this document.
243
244``${RTEMS_ROOT}/c/``
245    This directory is the root of the portions of the RTEMS source
246    tree which must be built tailored for a particular CPU model
247    or BSP.  The contents of this directory will be discussed
248    in the `c/ Directory`_ section.
249
250``${RTEMS_ROOT}/contrib/``
251    This directory contains contributed support software.  Currently
252    this directory contains the RPM specifications for cross-compilers
253    hosted on GNU/Linux that target various operating systems
254    including MinGW, Cygwin, FreeBSD, and Solaris.  The
255    cross-compilers produced using these specifications are then
256    used in a Canadian cross build procedure to produce the various
257    RTEMS toolsets on a GNU/Linux host.
258    This directory also contains RPM specifications for the
259    prebuilt cross-compilation toolsets provided by the
260    RTEMS project.  There are separate subdirectories
261    for each of the components in the RTEMS Cross Compilation
262    Environment unde the  ``contrib/crossrpms/`` directory.
263    This directory is configured, built, and installed separately
264    from the RTEMS executive and tests.  This directory will not
265    be discussed further in this document.
266
267``${RTEMS_ROOT}/cpukit/``
268    This directory is the root for all of the "multilib’able"
269    portions of RTEMS.  This is a GNU way of saying the
270    contents of this directory can be compiled like the
271    C Library (``libc.a``) and the functionality is
272    neither CPU model nor BSP specific.  The source code
273    for most RTEMS services reside under this directory.
274    The contents of this directory will be discussed
275    in the `CPU Kit Directory`_ section.
276
277``${RTEMS_ROOT}/doc/``
278    This directory is the root for all RTEMS documentation.
279    The source for RTEMS is written in GNU TeXinfo and
280    used to produce HTML, PDF, and "info" files.
281    The RTEMS documentation is configured, built,
282    and installed separately from the RTEMS executive and tests.
283    The contents of this directory will be discussed
284    in the `Documentation Directory`_ section.
285
286``${RTEMS_ROOT}/make/``
287    This directory contains files which support the
288    RTEMS Makefile’s.  From a user’s perspective, the
289    most important parts are found in the ``custom/``
290    subdirectory.  Each ".cfg" file in this directory
291    is associated with a specific BSP and describes
292    the CPU model, compiler flags, and procedure to
293    produce an executable for the target board.
294    These files are described in detail in the*RTEMS BSP and Device Driver Development Guide*
295    and will not be discussed further in this document.
296
297``${RTEMS_ROOT}/testsuites/``
298    This directory contains the test suites for the
299    various RTEMS APIs and support libraries.  The
300    contents of this directory are discussed in the `testsuites/ Test Suites`_ section.
301
302``${RTEMS_ROOT}/tools/``
303    This directory contains RTEMS specific support utilities which
304    execute on the development host.  These utilities are divided
305    into subdirectories based upon whether they are used in the process
306    of building RTEMS and applications, are CPU specific, or are
307    used to assist in updating the RTEMS source tree and applications.
308    The support utilities used in the process of building RTEMS are
309    described in `RTEMS Specific Utilities`_.  These are the
310    only components of this subtree that will be discussed in this
311    document.
312
313.. COMMENT: c/ Directions
314
315c/ Directory
316============
317
318The ``${RTEMS_ROOT}/c/`` directory was formerly
319the root directory of all RTEMS source code.  At this time, it contains
320the root directory for only those RTEMS components
321which must be compiled or linked in a way that is specific to a
322particular CPU model or board.  This directory contains the
323following subdirectories:
324
325``${RTEMS_ROOT}/c/src/``
326    This directory is logically the root for the RTEMS components
327    which are CPU model or board dependent.  Thus this directory
328    is the root for the BSPs and the Ada Test Suites as well
329    as CPU model and BSP dependent libraries.  The contents of
330    this directory are discussed in the `c/src/ Directory`_ section.
331
332.. COMMENT: c/src/ Directory
333
334c/src/ Directory
335----------------
336
337As mentioned previously, this directory is logically
338the root for the RTEMS components
339which are CPU model or board dependent.  The
340following is a list of the subdirectories in this
341directory and a description of each.
342
343``${RTEMS_ROOT}/c/src/aclocal/``
344    This directory contains the custom M4 macros which are available to
345    the various GNU autoconf ``configure.ac`` scripts throughout
346    this portion of the RTEMS source tree.  GNU autoconf interprets``configure.ac`` files to produce the ``configure`` files used
347    to tailor RTEMS build for a particular host and target environment.  The
348    contents of this directory will not be discussed further in this
349    document.
350
351``${RTEMS_ROOT}/c/src/ada/``
352    This directory contains the Ada95 language bindings to the
353    RTEMS Classic API.
354
355``${RTEMS_ROOT}/c/src/ada-tests/``
356    This directory contains the test suite for the Ada
357    language bindings to the Classic API.
358
359``${RTEMS_ROOT}/c/src/automake/``
360    This directory contains files which are "Makefile fragments."
361    They are included as required by the various ``Makefile.am``
362    files throughout this portion of the RTEMS source tree.
363
364``${RTEMS_ROOT}/c/src/lib/``
365    This directory contains the directories ``libbsp/``
366    and ``libcpu/`` which contain the source code for
367    the Board Support Packages (BSPs) and CPU Model
368    specific source code for RTEMS.
369    The ``libbsp/`` is organized based upon the CPU
370    family and boards BSPs.  The contents of ``libbsp/``
371    are discussed briefly in `c/src/lib/libbsp BSP Directory`_
372    and presented in detail in the*RTEMS BSP and Device Driver Development Guide*.
373    The ``libcpu/`` directory is also organized by
374    CPU family with further divisions based upon CPU
375    model and features that are shared across CPU models
376    such as caching and DMA.
377
378``${RTEMS_ROOT}/c/src/libchip/``
379    This directory contains device drivers for various
380    peripheral chips which are designed to be CPU and
381    board dependent.  This directory contains a variety
382    of drivers for serial devices, network interface
383    controllers, shared memory and real-time clocks.
384
385``${RTEMS_ROOT}/c/src/librtems++/``
386    This directory contains C++ classes which map to the RTEMS
387    Classic API.
388
389``${RTEMS_ROOT}/c/src/make/``
390    This directory is used to generate the bulk of the supporting
391    rules files which are installed as part of the Application Makefiles.
392    This file contains settings for various Makefile variables to
393    tailor them to the particular CPU model and BSP configured.
394
395``${RTEMS_ROOT}/c/src/nfsclient/``
396    This directory contains a Network File System (NFS) client
397    for RTEMS.  With this file system, a user’s application can
398    access files on a remote computer.
399
400``${RTEMS_ROOT}/c/src/optman/``
401    This directory contains stubs for the RTEMS Classic API
402    Managers which are considered optional and whose use
403    may be explicitly forbidden by an application.  All of the
404    directive implementations in this Optional Managers
405    return ``E_NOTCONFIGURED``.
406
407``${RTEMS_ROOT}/c/src/support/``
408    This directory exists solely to generate the RTEMS
409    version string which includes the RTEMS version,
410    CPU architecture, CPU model, and BSP name.
411
412``${RTEMS_ROOT}/c/src/wrapup/``
413    This directory is responsible for taking the individual
414    libraries and objects built in each of the components
415    in the RTEMS source tree and bundling them together to form
416    the single RTEMS library ``librtemsbsp.a``.  This
417    library contains all BSP and CPU model specific software.
418
419.. COMMENT: c/src/lib/libbsp BSP Directory
420
421c/src/lib/libbsp BSP Directory
422~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
423
424The "libbsp" directory contains a directory for each CPU family supported
425by RTEMS.  Beneath each CPU directory is a directory for each BSP for that
426processor family.
427
428.. COMMENT: Tree 7 - C BSP Library
429
430The "libbsp" directory provides all the BSPs provided with this
431release of the RTEMS executive.  The subdirectories are
432divided,  as discussed previously, based on specific processor
433family, then further broken down into specific target board
434environments.  The "no_cpu" subdirectory provides a starting point
435template BSP which can be used to develop a specific BSP for an
436unsupported target board.  The files in this subdirectory may aid
437in preliminary testing of the RTEMS development environment that has
438been built for no particular target in mind.
439
440Below each CPU dependent directory is a directory for each target BSP
441supported in this release.
442
443Each BSP provides the modules which comprise an RTEMS BSP.  The
444modules are separated into the subdirectories "clock", "console",
445"include", "shmsupp", "startup", and "timer" as shown in the following
446figure:
447
448.. COMMENT: Tree 8 - Each BSP
449
450.. COMMENT: @ifset use-ascii
451.. code:: c
452
453    Each BSP
454    |
455    +-----------+----------+-----+-----+----------+----------+
456    |           |          |           |          |          |
457    clock      console    include     shmsupp    startup     timer
458
459.. COMMENT: @end ifset
460
461.. COMMENT: CPU Kit Directory
462
463CPU Kit Directory
464=================
465
466.. COMMENT: The @code{cpukit/} directory structure is as follows:
467
468.. COMMENT: CPU Kit Tree
469
470.. COMMENT: @ifset use-ascii
471
472.. COMMENT: @example
473
474.. COMMENT: @group
475
476.. COMMENT: cpukit
477
478.. COMMENT: |
479
480.. COMMENT: +-+-+-+-+
481
482.. COMMENT: |           |          |           |          |
483
484.. COMMENT: posix       rtems       sapi       score     wrapup
485
486.. COMMENT: @end group
487
488.. COMMENT: @end example
489
490.. COMMENT: @end ifset
491
492The ``cpukit/`` directory contains a set of subdirectories which
493contains the source files comprising the executive portion of
494the RTEMS development environment as well as portable support
495libraries such as support for the C Library and filesystems.
496The API specific and "SuperCore" (e.g. ``score/`` directory)
497source code files are separated into distinct directory trees.
498
499The following is a description of each of the subdirectories
500under ``cpukit/``:
501
502``${RTEMS_ROOT}/cpukit/aclocal/``
503    This directory contains the custom M4 macros which are available to
504    the various GNU autoconf ``configure.ac`` scripts throughout
505    the CPU Kit portion of the RTEMS source tree.
506    GNU autoconf interprets ``configure.ac``
507    files to produce the ``configure`` files used to tailor
508    RTEMS build for a particular host and target environment.  The
509    contents of this directory will not be discussed further in this
510    document.
511
512``${RTEMS_ROOT}/cpukit/automake/``
513    This directory contains files which are "Makefile fragments."
514    They are included as required by the various ``Makefile.am``
515    files throughout the CPU Kit portion of the RTEMS source tree.
516
517``${RTEMS_ROOT}/cpukit/ftpd/``
518    This directory contains the RTEMS ftpd server.
519
520``${RTEMS_ROOT}/cpukit/httpd/``
521    This directory contains the port of the GoAhead
522    web server to RTEMS.
523
524``${RTEMS_ROOT}/cpukit/include/``
525    This directory contains header files which are private to
526    RTEMS and not considered to be owned by any other component
527    in the CPU Kit.
528
529``${RTEMS_ROOT}/cpukit/libblock/``
530    This directory contains support code for using
531    Block Devices such as hard drives, floppies, and
532    CD-ROMs.  It includes the generic IO primitives
533    for block device drivers, disk caching support,
534    and a RAM disk block device driver.
535
536``${RTEMS_ROOT}/cpukit/libcsupport/``
537    This directory contains the RTEMS specific support routines
538    for the Newlib C Library.  This includes what are referred
539    to as system calls and found in section 2 of the traditional
540    UNIX manual.   In addition, it contains a thread-safe
541    implementation of the Malloc family of routines as well
542    as BSD and POSIX services not found in Newlib.
543
544``${RTEMS_ROOT}/cpukit/libfs/``
545    This directory contains the various non-networked
546    filesystem implementations for RTEMS.  It includes
547    the In-Memory FileSystem (IMFS), the mini-IMFS,
548    and FAT filesystems.
549
550``${RTEMS_ROOT}/cpukit/libi2c/``
551    This directory contains the RTEMS I2C framework.
552
553``${RTEMS_ROOT}/cpukit/libmd/``
554    This directory contains a port of the standard MD5
555    checksum code.
556
557``${RTEMS_ROOT}/c/src/libmisc/``
558    This directory contains support facilities which
559    are RTEMS specific but otherwise unclassified.  In
560    general, they do not adhere to a standard API.
561    Among the support facilities in this directory are
562    a ``/dev/null`` device driver, the Stack
563    Overflow Checker, a mini-shell, the CPU and
564    rate monotonic period usage monitoring libraries,
565    and a utility to "dump a buffer" in a nicely
566    formatted way similar to many ROM monitors.
567
568``${RTEMS_ROOT}/cpukit/libnetworking/``
569    This directory contains the port of the FreeBSD
570    TCP/IP stack to RTEMS.
571
572``${RTEMS_ROOT}/cpukit/librpc/``
573    This directory contains the port of the FreeBSD
574    RPC/XDR source to RTEMS.
575
576``${RTEMS_ROOT}/cpukit/libpci/``
577    This directory contains RTEMS PCI Library.
578
579``${RTEMS_ROOT}/cpukit/posix/``
580    This directory contains the RTEMS implementation
581    of the threading portions of the POSIX API.
582
583``${RTEMS_ROOT}/cpukit/pppd/``
584    This directory contains a port of the free implementation
585    of the PPPD network protocol.
586
587``${RTEMS_ROOT}/cpukit/rtems/``
588    This directory contains the implementation of the
589    Classic API.
590
591``${RTEMS_ROOT}/cpukit/sapi/``
592    This directory contains the implementation of RTEMS
593    services which are required but beyond the realm
594    of any standardization efforts.  It includes
595    initialization, shutdown, and IO services.
596
597``${RTEMS_ROOT}/cpukit/score/``
598    This directory contains the "SuperCore" of RTEMS.
599    All APIs are implemented in terms of SuperCore services.
600    For example, Classic API tasks and POSIX threads
601    are all implemented in terms of SuperCore threads.
602    This provides a common infrastructure and a high degree
603    of interoperability between the APIs.  For example,
604    services from all APIs may be used by any task/thread
605    independent of the API used to create it.
606    Within the ``score/`` directory the CPU dependent modules are found.
607    The ``score/cpu/`` subdirectory contains a subdirectory for each
608    target CPU supported by this release of the RTEMS
609    executive.  Each processor directory contains the CPU dependent
610    code necessary to host RTEMS.  The ``no_cpu`` directory provides a
611    starting point for developing a new port to an unsupported
612    processor.  The files contained within the ``no_cpu`` directory
613    may also be used as a reference for the other ports to specific
614    processors.
615
616``${RTEMS_ROOT}/cpukit/shttpd/``
617    This directory contains the port of the Simple HTTPD
618    web server to RTEMS.
619
620``${RTEMS_ROOT}/cpukit/telnetd/``
621    This directory contains the RTEMS telnetd server.
622
623``${RTEMS_ROOT}/cpukit/wrapup/``
624    This directory is responsible for taking the individual
625    libraries and objects built in each of the components
626    in the RTEMS CPU Kit source tree and bundling them
627    together to form the single RTEMS library ``librtemscpu.a``.  This
628    library contains all BSP and CPU model specific software.
629
630``${RTEMS_ROOT}/cpukit/zlib/``
631    This directory contains a port of the GNU Zlib compression
632    library to RTEMS.
633
634.. COMMENT: testsuites/ Test Suites
635
636testsuites/ Test Suites
637=======================
638
639This directory provides all of the RTEMS Test Suite
640except those for the Classic API Ada95 binding
641This includes the single processor tests, multiprocessor tests,
642timing tests, library tests, and sample tests.   Additionally,
643subdirectories for support functions and test related header
644files are provided.  The following table lists the test suites
645currently included with the RTEMS and the directory in which
646they may be located:
647
648``${RTEMS_ROOT}/testsuites/libtests/``
649    This directory contains the test suite for the
650    various RTEMS support components.
651
652``${RTEMS_ROOT}/testsuites/mptests/``
653    This directory contains the test suite for the
654    multiprocessor support in the Classic API.
655    The tests provided address two node configurations
656    and provide coverage for the multiprocessor code found
657    in RTEMS.
658
659``${RTEMS_ROOT}/testsuites/psxtests/``
660    This directory contains the test suite for the
661    RTEMS POSIX API.
662
663``${RTEMS_ROOT}/testsuites/samples/``
664    This directory provides sample application tests
665    which aid in the testing a newly built RTEMS environment, a new
666    BSP, or as starting points for the development of an application
667    using the RTEMS executive.  They are discussed in `Sample Applications`_.
668
669``${RTEMS_ROOT}/testsuites/sptests/``
670    This directory contains the test suite for the RTEMS
671    Classic API when executing on a single processor.
672    The tests were originally designed to provide
673    near complete test coverage for the entire
674    executive code.  With the addition of multiple APIs,
675    this is no longer the case as some SuperCore functionality
676    is not available through the Classic API.  Thus
677    some functionality in the SuperCore is only covered
678    by tests in the POSIX API Test Suites.
679
680``${RTEMS_ROOT}/testsuites/support/``
681    This directory contains support software and header files
682    for the various test suites.
683
684``${RTEMS_ROOT}/testsuites/tmtests/``
685    This directory contains the timing test suite for
686    the RTEMS Classic API.  This include tests that
687    benchmark each directive in the Classic API
688    as well as a set of critical SuperCore functions.
689    These tests are important for helping to verify
690    that RTEMS performs as expected on your target hardware.
691    It is not uncommon to discover mistakes in board
692    initialization such as caching being disabled as
693    a side-effect of analyzing the results of these tests.
694
695``${RTEMS_ROOT}/testsuites/tools/``
696    This directory contains tools which execute on
697    the development host and aid in executing and
698    evaluating the results of the test suite.  The
699    tools ``difftest`` compares the output of one
700    or more tests with the expected output.  If you
701    place the output of all the ``tmtests/`` in
702    a single file, then the utility ``sorttimes``
703    will be able to produce a report organizing the
704    execution times by manager.
705
706.. COMMENT: Documentation Directory
707
708Documentation Directory
709=======================
710
711This directory contains the source code for all RTEMS documentation
712in ``TexInfo`` format as well as utilities used in the generation
713of the RTEMS documentation set.  This source code is used to produce
714the RTEMS documentation in various formats including PDF, HTML,
715and PostScript.
716
717``${RTEMS_ROOT}/doc/ada_user/``
718    This directory contains the source code for the *RTEMS
719    Applications Ada User’s Guide* which documents the Ada95
720    binding to the Classic API.  This manual is produced from
721    from the same source base as the *RTEMS Application
722    C User’s Guide*.
723
724``${RTEMS_ROOT}/doc/bsp_howto/``
725    This directory contains the source code for the*RTEMS BSP and Device Driver Development Guide*.
726
727``${RTEMS_ROOT}/doc/common/``
728    This directory contains the source code for the files which
729    are shared across multiple manuals in the RTEMS Documentation Set.
730    This includes the copyright page as well as the timing
731    tables which can be filled in on a per BSP basis in the
732    CPU supplements.
733
734``${RTEMS_ROOT}/doc/cpu_supplement/``
735    This directory contains the source code for the
736    RTEMS CPU Supplement.
737
738``${RTEMS_ROOT}/doc/develenv/``
739    This directory contains the source code for the*RTEMS Development Environment Guide*.  This is
740    the document you are currently reading.
741
742``${RTEMS_ROOT}/doc/filesystem/``
743    This directory contains the source code for the*RTEMS Filesystem Design Guide*.  This manual
744    is a continuous work in process as it attempts to
745    capture the design of the interface between system
746    calls and filesystem implementations as well as the
747    information required by those implementing filesystems.
748
749``${RTEMS_ROOT}/doc/images/``
750    This directory contains the source code for the graphics
751    used in the HTML version of the RTEMS Documentation.
752
753``${RTEMS_ROOT}/doc/networking/``
754    This directory contains the source code for the*RTEMS Network Supplement*.
755
756``${RTEMS_ROOT}/doc/new_chapters/``
757    This directory contains the source code for the new documentation
758    components which have not yet been collected into a new manual or
759    merged into an existing document.  Currently, this primarily
760    contains draft documentation for some portions of
761    the facilities implemented in ``${RTEMS_ROOT}/c/src/libmisc/``.
762
763``${RTEMS_ROOT}/doc/porting/``
764    This directory contains the source code for the*RTEMS Porting Guide*.
765
766``${RTEMS_ROOT}/doc/posix1003.1/``
767    This directory contains the source code for the*RTEMS POSIX 1003.1 Compliance Guide*.
768
769``${RTEMS_ROOT}/doc/posix_users/``
770    This directory contains the source code for the*RTEMS POSIX API User’s Guide*.  It is important to
771    note that RTEMS’ support for POSIX is a combination of
772    functionality provided by RTEMS and the Newlib C Library
773    so some functionality is documented by Newlib.
774
775``${RTEMS_ROOT}/doc/relnotes/``
776    This directory contains the source code for a formally
777    release notes document.  This has not been used for
778    recent RTEMS releases.
779
780``${RTEMS_ROOT}/doc/started/``
781    This directory contains the source code for the*Getting Started with RTEMS for C/C++ Users* manual.
782
783``${RTEMS_ROOT}/doc/tools/``
784    This directory contains the source code for the tools
785    used on the development host to assist in producing the
786    RTEMS Documentation.  The most important of these tools
787    is ``bmenu`` which generates the hierarchical node
788    linking commands based upon chapter, section, and
789    subsection organization.
790
791``${RTEMS_ROOT}/doc/user/``
792    This directory contains the source code for the *RTEMS
793    Applications C User’s Guide* which documents the Classic API.
794
795.. COMMENT: COPYRIGHT (c) 1989-2007.
796
797.. COMMENT: On-Line Applications Research Corporation (OAR).
798
799.. COMMENT: All rights reserved.
800
801
802Sample Applications
803###################
804
805Introduction
806============
807
808The RTEMS source distribution includes a set of sample applications
809that are located in the ``${RTEMS_ROOT}/testsuites/samples/``
810directory.  These applications are intended to illustrate the
811basic format of RTEMS single and multiple processor
812applications and the use of some features.  In addition, these
813relatively simple applications can be used to test locally
814developed board support packages and device drivers as they
815exercise a critical subset of RTEMS functionality that is often
816broken in new BSPs.
817
818Some of the following sample applications will be covered in
819more detail in subsequent sections:
820
821*Hello World*
822    The RTEMS Hello World test is provided in
823    the subdirectory ``${RTEMS_ROOT}/testsuites/samples/hello/``.
824    This test is helpful when testing new RTEMS development environment.
825
826*Clock Tick*
827    The ``${RTEMS_ROOT}/testsuites/samples/ticker/``
828    subdirectory provides a test for verification of clock chip
829    device drivers of BSPs.
830
831*Base Single Processor*
832    A simple single processor test similar to those in the
833    single processor test suite is provided in ``${RTEMS_ROOT}/testsuites/samples/base_sp/``.
834
835*Base Multiple Processor*
836    A simple two node multiprocessor test capable of testing an newly
837    developed MPCI layer is provided in ``${RTEMS_ROOT}/testsuites/samples/base_mp/``.
838
839*Capture*
840    The RTEMS Capture test is provided in
841    the subdirectory ``${RTEMS_ROOT}/testsuites/samples/capture/``.
842    This is an interactive test which demonstrates the capabilities
843    of the RTEMS Capture Engine.  It includes a few test threads
844    which generate interesting execution patterns.  Look at the
845    file ``${RTEMS_ROOT}/testsuites/samples/capture/capture.scn``
846    for a sample session.
847
848*Constructor/Destructor C++ Test*
849    The ``${RTEMS_ROOT}/testsuites/samples/cdtest/``
850    subdirectory provides a simple C++ application using
851    constructors and destructors.  It is only built when
852    C++ is enabled and its primary purpose is to demonstrate
853    that global constructors and destructors work.  Since this
854    requires that the linker script for your BSP be correct, this is
855    an important test.
856
857*File IO*
858    The RTEMS File IO test is provided in
859    the subdirectory ``${RTEMS_ROOT}/testsuites/samples/fileio/``.
860    This is an interactive test which allows the user to interact with
861    an ATA/IDE device.  It will read the partition table and allow the
862    user to dynamically mount one of the FAT32 partitions it finds.
863    Commands are also provided to write and read files on the disk.
864
865*IO Stream*
866    The RTEMS IO Stream test is provided in
867    the subdirectory ``${RTEMS_ROOT}/testsuites/samples/iostream/``.
868    This test is a simple C++ application which demonstrates that
869    C++ iostreams are functional. This requires that the RTEMS C++
870    run-time support is functioning properly.  This test is only
871    build when C++ is enabled.
872
873*Network Loopback Test*
874    The ``${RTEMS_ROOT}/testsuites/samples/loopback/``
875    directory contains a sample test that demonstrates the use of
876    sockets and the loopback network device.  It does not require
877    the presence of network hardware in order to run.
878    It is only built if RTEMS was configured with networking enabled.
879
880*Minimum Size Test*
881    The directory``${RTEMS_ROOT}/testsuites/samples/minimum/``
882    contains a simple RTEMS program that results in a non-functional
883    executable.  It is intended to show the size of a minimum footprint
884    application based upon the current RTEMS configuration.
885
886*Nanoseconds*
887    The RTEMS Nanoseconds test is provided in
888    the subdirectory ``${RTEMS_ROOT}/testsuites/samples/nsecs/``.
889    This test demonstrates that the BSP has support for nanosecond
890    timestamp granularity.  It prints the time of day and uptime multiple
891    times as quickly as possible.  It should be possible from the output
892    to determine if your BSP has nanosecond accurate clock support
893    and it is functional.
894
895*Paranoia Floating Point Test*
896    The directory ``${RTEMS_ROOT}/testsuites/samples/paranoia/``
897    contains the public domain floating point and math library test.
898
899*Point-to-Point Protocol Daemon*
900    The RTEMS Point-to-Point Protocol Daemon test is provided in
901    the subdirectory ``${RTEMS_ROOT}/testsuites/samples/pppd/``.
902    This test primarily serves as the baseline for a user application
903    using the PPP protocol.
904
905*Unlimited Object Allocation*
906    The ``${RTEMS_ROOT}/testsuites/samples/unlimited/``
907    directory contains a sample test that demonstrates the use of the*unlimited* object allocation configuration option to RTEMS.
908
909The sample tests are written using the Classic API so the reader
910should be familiar with the terms used and
911material presented in the *RTEMS Applications Users Guide*.
912
913Hello World
914===========
915
916This sample application is in the following directory:
917.. code:: c
918
919    ${RTEMS_ROOT}/testsuites/samples/hello/
920
921It provides a rudimentary test of the BSP start up
922code and the console output routine.  The C version of this
923sample application uses the printf function from the RTEMS
924Standard C Library to output messages.   The Ada version of this
925sample uses the TEXT_IO package to output the hello messages.
926The following messages are printed:
927.. code:: c
928
929    *** HELLO WORLD TEST \***
930    Hello World
931    \*** END OF HELLO WORLD TEST \***
932
933These messages are printed from the application’s
934single initialization task.  If the above messages are not
935printed correctly, then either the BSP start up code or the
936console output routine is not operating properly.
937
938Clock Tick
939==========
940
941This sample application is in the following directory:
942.. code:: c
943
944    ${RTEMS_ROOT}/testsuites/samples/ticker/
945
946This application is designed as a simple test of the
947clock tick device driver.  In addition, this application also
948tests the printf function from the RTEMS Standard C Library by
949using it to output the following messages:
950.. code:: c
951
952    *** CLOCK TICK TEST \***
953    TA1 - tm_get - 09:00:00   12/31/1988
954    TA2 - tm_get - 09:00:00   12/31/1988
955    TA3 - tm_get - 09:00:00   12/31/1988
956    TA1 - tm_get - 09:00:05   12/31/1988
957    TA1 - tm_get - 09:00:10   12/31/1988
958    TA2 - tm_get - 09:00:10   12/31/1988
959    TA1 - tm_get - 09:00:15   12/31/1988
960    TA3 - tm_get - 09:00:15   12/31/1988
961    TA1 - tm_get - 09:00:20   12/31/1988
962    TA2 - tm_get - 09:00:20   12/31/1988
963    TA1 - tm_get - 09:00:25   12/31/1988
964    TA1 - tm_get - 09:00:30   12/31/1988
965    TA2 - tm_get - 09:00:30   12/31/1988
966    TA3 - tm_get - 09:00:30   12/31/1988
967    \*** END OF CLOCK TICK TEST \***
968
969The clock tick sample application utilizes a single
970initialization task and three copies of the single application
971task.  The initialization task prints the test herald, sets the
972time and date, and creates and starts the three application
973tasks before deleting itself.  The three application tasks
974generate the rest of the output.  Every five seconds, one or
975more of the tasks will print the current time obtained via the
976tm_get directive.  The first task, TA1, executes every five
977seconds, the second task, TA2, every ten seconds, and the third
978task, TA3, every fifteen seconds. If the time printed does not
979match the above output, then the clock device driver is not
980operating properly.
981
982Base Single Processor Application
983=================================
984
985This sample application is in the following directory:
986.. code:: c
987
988    ${RTEMS_ROOT}/testsuites/samples/base_sp/
989
990It provides a framework from which a single processor
991RTEMS application can be developed. The use of the task argument
992is illustrated.  This sample application uses the printf
993function from the RTEMS Standard C Library or TEXT_IO functions
994when using the Ada version to output the following messages:
995.. code:: c
996
997    *** SAMPLE SINGLE PROCESSOR APPLICATION \***
998    Creating and starting an application task
999    Application task was invoked with argument (0) and has id of 0x10002
1000    \*** END OF SAMPLE SINGLE PROCESSOR APPLICATION \***
1001
1002The first two messages are printed from the
1003application’s single initialization task.  The final messages
1004are printed from the single application task.
1005
1006Base Multiple Processor Application
1007===================================
1008
1009This sample application is in the following directory:
1010.. code:: c
1011
1012    ${RTEMS_ROOT}/testsuites/samples/base_mp/
1013
1014It provides a framework from which a multiprocessor
1015RTEMS application can be developed. This directory has a
1016subdirectory for each node in the multiprocessor system.  The
1017task argument is used to distinguish the node on which the
1018application task is executed.  The first node will print the
1019following messages:
1020.. code:: c
1021
1022    *** SAMPLE MULTIPROCESSOR APPLICATION \***
1023    Creating and starting an application task
1024    This task was invoked with the node argument (1)
1025    This task has the id of 0x10002
1026    \*** END OF SAMPLE MULTIPROCESSOR APPLICATION \***
1027
1028The second node will print the following messages:
1029.. code:: c
1030
1031    *** SAMPLE MULTIPROCESSOR APPLICATION \***
1032    Creating and starting an application task
1033    This task was invoked with the node argument (2)
1034    This task has the id of 0x20002
1035    \*** END OF SAMPLE MULTIPROCESSOR APPLICATION \***
1036
1037The herald is printed from the application’s single
1038initialization task on each node.  The final messages are
1039printed from the single application task on each node.
1040
1041In this sample application, all source code is shared
1042between the nodes except for the node dependent configuration
1043files.  These files contains the definition of the node number
1044used in the initialization of the  RTEMS Multiprocessor
1045Configuration Table. This file is not shared because the node
1046number field in the RTEMS Multiprocessor Configuration Table
1047must be unique on each node.
1048
1049Constructor/Destructor C++ Application
1050======================================
1051
1052This sample application is in the following directory:
1053.. code:: c
1054
1055    ${RTEMS_ROOT}/testsuites/samples/cdtest/
1056
1057This sample application demonstrates that RTEMS is
1058compatible with C++ applications.  It uses constructors,
1059destructor, and I/O stream output in testing these various
1060capabilities.  The board support package responsible for this
1061application must support a C++ environment.
1062
1063This sample application uses the printf function from
1064the RTEMS Standard C Library to output the following messages:
1065.. code:: c
1066
1067    Hey I'M in base class constructor number 1 for 0x400010cc.
1068    Hey I'M in base class constructor number 2 for 0x400010d4.
1069    Hey I'M in derived class constructor number 3 for 0x400010d4.
1070    \*** CONSTRUCTOR/DESTRUCTOR TEST \***
1071    Hey I'M in base class constructor number 4 for 0x4009ee08.
1072    Hey I'M in base class constructor number 5 for 0x4009ee10.
1073    Hey I'M in base class constructor number 6 for 0x4009ee18.
1074    Hey I'M in base class constructor number 7 for 0x4009ee20.
1075    Hey I'M in derived class constructor number 8 for 0x4009ee20.
1076    Testing a C++ I/O stream
1077    Hey I'M in derived class constructor number 8 for 0x4009ee20.
1078    Derived class - Instantiation order 8
1079    Hey I'M in base class constructor number 7 for 0x4009ee20.
1080    Instantiation order 8
1081    Hey I'M in base class constructor number 6 for 0x4009ee18.
1082    Instantiation order 6
1083    Hey I'M in base class constructor number 5 for 0x4009ee10.
1084    Instantiation order 5
1085    Hey I'M in base class constructor number 4 for 0x4009ee08.
1086    Instantiation order 5
1087    \*** END OF CONSTRUCTOR/DESTRUCTOR TEST \***
1088    Hey I'M in base class constructor number 3 for 0x400010d4.
1089    Hey I'M in base class constructor number 2 for 0x400010d4.
1090    Hey I'M in base class constructor number 1 for 0x400010cc.
1091
1092Minimum Size Test
1093=================
1094
1095This sample application is in the following directory:
1096.. code:: c
1097
1098    ${RTEMS_ROOT}/testsuites/samples/minimum/
1099
1100This sample application is designed to produce the
1101minimum code space required for any RTEMS application
1102based upon the current RTEMS configuration and
1103BSP.  In many situations, the bulk of this executable
1104consists of hardware and RTEMS initialization, basic
1105infrastructure such as malloc(), and RTEMS and
1106hardware shutdown support.
1107
1108Nanosecond Granularity Application
1109==================================
1110
1111This sample application is in the following directory:
1112.. code:: c
1113
1114    ${RTEMS_ROOT}/testsuites/samples/nsecs/
1115
1116This sample application exercises the Clock Driver
1117for this BSP and demonstrates its ability to generate
1118accurate timestamps.  This application does this by
1119exercising the time subsystem in three ways:
1120
1121- Obtain Time of Day Twice Back to Back
1122
1123- Obtain System Up Time Twice Back to Back
1124
1125- Use System Up Time to Measure Loops
1126
1127The following is an example of what the output of this
1128test may appear like:
1129.. code:: c
1130
1131    *** NANOSECOND CLOCK TEST \***
1132    10 iterations of getting TOD
1133    Start: Sat Mar 24 11:15:00 2007:540000
1134    Stop : Sat Mar 24 11:15:00 2007:549000 --> 0:9000
1135    Start: Sat Mar 24 11:15:00 2007:3974000
1136    Stop : Sat Mar 24 11:15:00 2007:3983000 --> 0:9000
1137    Start: Sat Mar 24 11:15:00 2007:7510000
1138    Stop : Sat Mar 24 11:15:00 2007:7519000 --> 0:9000
1139    Start: Sat Mar 24 11:15:00 2007:11054000
1140    Stop : Sat Mar 24 11:15:00 2007:11063000 --> 0:9000
1141    Start: Sat Mar 24 11:15:00 2007:14638000
1142    Stop : Sat Mar 24 11:15:00 2007:14647000 --> 0:9000
1143    Start: Sat Mar 24 11:15:00 2007:18301000
1144    Stop : Sat Mar 24 11:15:00 2007:18310000 --> 0:9000
1145    Start: Sat Mar 24 11:15:00 2007:21901000
1146    Stop : Sat Mar 24 11:15:00 2007:21910000 --> 0:9000
1147    Start: Sat Mar 24 11:15:00 2007:25526000
1148    Stop : Sat Mar 24 11:15:00 2007:25535000 --> 0:9000
1149    Start: Sat Mar 24 11:15:00 2007:29196000
1150    Stop : Sat Mar 24 11:15:00 2007:29206000 --> 0:10000
1151    Start: Sat Mar 24 11:15:00 2007:32826000
1152    Stop : Sat Mar 24 11:15:00 2007:32835000 --> 0:9000
1153    10 iterations of getting Uptime
1154    0:38977000 0:38986000 --> 0:9000
1155    0:40324000 0:40332000 --> 0:8000
1156    0:41636000 0:41645000 --> 0:9000
1157    0:42949000 0:42958000 --> 0:9000
1158    0:44295000 0:44304000 --> 0:9000
1159    0:45608000 0:45617000 --> 0:9000
1160    0:46921000 0:46930000 --> 0:9000
1161    0:48282000 0:48291000 --> 0:9000
1162    0:49595000 0:49603000 --> 0:8000
1163    0:50908000 0:50917000 --> 0:9000
1164    10 iterations of getting Uptime with different loop values
1165    loop of 10000 0:119488000 0:119704000 --> 0:216000
1166    loop of 20000 0:124028000 0:124463000 --> 0:435000
1167    loop of 30000 0:128567000 0:129220000 --> 0:653000
1168    loop of 40000 0:133097000 0:133964000 --> 0:867000
1169    loop of 50000 0:137643000 0:138728000 --> 0:1085000
1170    loop of 60000 0:142265000 0:143572000 --> 0:1307000
1171    loop of 70000 0:146894000 0:148416000 --> 0:1522000
1172    loop of 80000 0:151519000 0:153260000 --> 0:1741000
1173    loop of 90000 0:156145000 0:158099000 --> 0:1954000
1174    loop of 100000 0:160770000 0:162942000 --> 0:2172000
1175    \*** END OF NANOSECOND CLOCK TEST \***
1176
1177Paranoia Floating Point Application
1178===================================
1179
1180This sample application is in the following directory:
1181.. code:: c
1182
1183    ${RTEMS_ROOT}/testsuites/samples/paranoia/
1184
1185This sample application uses a public domain floating
1186point and math library test to verify these capabilities of the
1187RTEMS executive.  Deviations between actual and expected results
1188are reported to the screen.  This is a very extensive test which
1189tests all mathematical and number conversion functions.
1190Paranoia is also very large and requires a long period of time
1191to run.   Problems which commonly prevent this test from
1192executing to completion include stack overflow and FPU exception
1193handlers not installed.
1194
1195Network Loopback Test
1196=====================
1197
1198This sample application is in the following directory:
1199.. code:: c
1200
1201    ${RTEMS_ROOT}/testsuites/samples/loopback/
1202
1203This sample application uses the network loopback device to
1204demonstrate the use of the RTEMS TCP/IP stack.  This sample
1205test illustrates the basic configuration and initialization
1206of the TCP/IP stack as well as simple socket usage.
1207
1208.. COMMENT: COPYRIGHT (c) 1989-2007.
1209
1210.. COMMENT: On-Line Applications Research Corporation (OAR).
1211
1212.. COMMENT: All rights reserved.
1213
1214RTEMS Specific Utilities
1215########################
1216
1217This section describes the additional commands
1218available within the *RTEMS Development Environment*.  Although
1219some of these commands are of general use, most are included to
1220provide some capability necessary to perform a required function
1221in the development of the RTEMS executive, one of its support
1222components, or an RTEMS based application.
1223
1224Some of the commands are implemented as C programs.
1225However, most commands are implemented as Bourne shell scripts.
1226Even if the current user has selected a different shell, the
1227scripts will automatically invoke the Bourne shell during their
1228execution lifetime.
1229
1230The commands are presented in UNIX manual page style
1231for compatibility and convenience.  A standard set of paragraph
1232headers were used for all of the command descriptions.  If a
1233section contained no data, the paragraph header was omitted to
1234conserve space.  Each of the permissible paragraph headers and
1235their contents are described below:
1236
1237``SYNOPSIS``
1238    describes the command syntax
1239
1240``DESCRIPTION``
1241    a full description of the command
1242
1243``OPTIONS``
1244    describes each of the permissible options for the command
1245
1246``NOTES``
1247    lists any special noteworthy comments about the command
1248
1249``ENVIRONMENT``
1250    describes all environment variables utilized by the command
1251
1252``EXAMPLES``
1253    illustrates the use of the command with specific examples
1254
1255``FILES``
1256    provides a list of major files that the command references
1257
1258``SEE ALSO``
1259    lists any relevant commands which can be consulted
1260
1261Most environment variables referenced by the commands
1262are defined for the RTEMS Development Environment during the
1263login procedure.  During login, the user selects a default RTEMS
1264environment through the use of the Modules package.  This tool
1265effectively sets the environment variables to provide a
1266consistent development environment for a specific user.
1267Additional environment variables within the RTEMS environment
1268were set by the system administrator during installation.  When
1269specifying paths, a command description makes use of these
1270environment variables.
1271
1272When referencing other commands in the SEE ALSO
1273paragraph, the following notation is used:   command(code).
1274Where command is the name of a related command, and code is a
1275section number.  Valid section numbers are as follows:
1276
1277``1``
1278    Section 1 of the standard UNIX documentation
1279
1280``1G``
1281    Section 1 of the GNU documentation
1282
1283``1R``
1284    a manual page from this document, the RTEMS Development Environment Guide
1285
1286For example, ls(1) means see the standard ls command
1287in section 1 of the UNIX documentation.  gcc020(1G) means see
1288the description of gcc020 in section 1 of the GNU documentation.
1289
1290.. COMMENT: packhex
1291
1292packhex - Compress Hexadecimal File
1293===================================
1294
1295**SYNOPSIS**
1296
1297.. code:: c
1298
1299    packhex <source >destination
1300
1301**DESCRIPTION**
1302
1303packhex accepts Intel Hexadecimal or Motorola Srecord
1304on its standard input and attempts to pack as many contiguous
1305bytes as possible into a single hexadecimal record.  Many
1306programs output hexadecimal records which are less than 80 bytes
1307long (for human viewing).  The overhead required by each
1308unnecessary record is significant and packhex can often reduce
1309the size of the download image by 20%.  packhex attempts to
1310output records which are as long as the hexadecimal format
1311allows.
1312
1313**OPTIONS**
1314
1315This command has no options.
1316
1317**EXAMPLES**
1318
1319Assume the current directory contains the Motorola
1320Srecord file download.sr. Then executing the command:
1321.. code:: c
1322
1323    packhex <download.sr >packed.sr
1324
1325will generate the file packed.sr which is usually
1326smaller than download.sr.
1327
1328**CREDITS**
1329
1330The source for packhex first appeared in the May 1993
1331issue of Embedded Systems magazine.  The code was downloaded
1332from their BBS.  Unfortunately, the author’s name was not
1333provided in the listing.
1334
1335.. COMMENT: unhex
1336
1337unhex - Convert Hexadecimal File into Binary Equivalent
1338=======================================================
1339
1340**SYNOPSIS**
1341
1342.. code:: c
1343
1344    unhex \[-valF] \[-o file] \[file \[file ...] ]
1345
1346**DESCRIPTION**
1347
1348unhex accepts Intel Hexadecimal, Motorola Srecord, or
1349TI ’B’ records and converts them to their binary equivalent.
1350The output may sent to standout or may be placed in a specified
1351file with the -o option.  The designated output file may not be
1352an input file.  Multiple input files may be specified with their
1353outputs logically concatenated into the output file.
1354
1355**OPTIONS**
1356
1357This command has the following options:
1358
1359``v``
1360    Verbose
1361
1362``a base``
1363    First byte of output corresponds with base
1364    address
1365
1366``l``
1367    Linear Output
1368
1369``o file``
1370    Output File
1371
1372``F k_bits``
1373    Fill holes in input with 0xFFs up to k_bits * 1024 bits
1374
1375**EXAMPLES**
1376
1377The following command will create a binary equivalent
1378file for the two Motorola S record files in the specified output
1379file binary.bin:
1380.. code:: c
1381
1382    unhex -o binary.bin downloadA.sr downloadB.sr
1383
1384Command and Variable Index
1385##########################
1386
1387There are currently no Command and Variable Index entries.
1388
1389.. COMMENT: @printindex fn
1390
1391Concept Index
1392#############
1393
1394There are currently no Concept Index entries.
1395
1396.. COMMENT: @printindex cp
Note: See TracBrowser for help on using the repository browser.