source: rtems/doc/started/sample.t @ 48cd0b8e

4.104.114.84.95
Last change on this file since 48cd0b8e was 48cd0b8e, checked in by Joel Sherrill <joel.sherrill@…>, on Oct 2, 2003 at 6:01:48 PM

2003-10-02 Joel Sherrill <joel@…>

  • Makefile.am, binaries.t, buildc.t, intro.t, nextstep.t, require.t, sample.t, started.texi: General improvements and merge enough Ada information to justify dropping the Ada specific manual. There is likely still Ada specific information to merge though.
  • Property mode set to 100644
File size: 8.4 KB
Line 
1@c
2@c  COPYRIGHT (c) 1988-2002.
3@c  On-Line Applications Research Corporation (OAR).
4@c  All rights reserved.
5@c
6@c  $Id$
7@c
8
9@chapter Building the Sample Applications
10
11The RTEMS distribution includes a number of sample C, C++,
12Ada, and networking applications.  This chapter will provide
13an overview of those sample applications.
14
15@c
16@c Set the Environment Variable RTEMS_MAKEFILE_PATH
17@c
18@section Set the Environment Variable RTEMS_MAKEFILE_PATH
19
20The sample application sets use the RTEMS Application Makefiles.
21This requires that the environment variable
22@code{RTEMS_MAKEFILE_PATH} point to the appropriate directory containing
23the installed RTEMS image built to target your particular CPU and
24board support package combination.
25
26@example
27export RTEMS_MAKEFILE_PATH=<INSTALLATION_POINT>/<BOARD_SUPPORT_PACKAGE>
28@end example
29
30Where <INSTALLATION_POINT> and <BOARD_SUPPORT_PACKAGE> are those used when
31configuring and installing RTEMS.
32
33NOTE:  In release 4.0, BSPs were installed at
34@code{<INSTALLATION_POINT>/rtems/<BOARD_SUPPORT_PACKAGE>}.  This
35was changed to be more in compliance with GNU standards.
36
37NOTE: GNU make is the preferred @code{make} utility.  Other @code{make}
38implementations may work but all testing is done with GNU make.
39
40If no errors are detected during the sample application build, it is
41reasonable to assume that the build of the GNU Cross Compiler Tools
42for RTEMS and RTEMS itself for the selected host and target
43combination was done properly.
44
45@c
46@c Executing the Sample Applications
47@c
48@section Executing the Sample Applications
49
50How each sample application executable is downloaded
51to your target board and executed is very dependent
52on the board you are using.  The following is a list of
53commonly used BSPs classified by their RTEMS CPU family and pointers
54to instructions on how to use them.  [NOTE: All file names should be
55prepended with @value{RTEMSUNTAR}/c/src/lib/libbsp.]
56
57@need 1000
58@table @b
59
60@item arm/edp7312
61The arm/edp7312 BSP is for the ARM7-based Cogent EDP7312 board.
62
63@item c4x/c4xsim
64The c4x/c4xsim BSP is designed to execute on any member of
65the Texas Instruments C3x/C4x DSP family using only on-CPU
66peripherals for the console and timers.
67
68@item i386/pc386
69See @code{i386/pc386/HOWTO}
70
71@item i386/pc486
72The i386/pc386 BSP specially compiled for an i486-class CPU.
73
74@item i386/pc586
75The i386/pc386 BSP specially compiled for a Pentium-class CPU.
76
77@item i386/pc686
78The i386/pc386 BSP specially compiled for a Pentium II.
79
80@item i386/pck6
81The i386/pc386 BSP specially compiled for an AMD K6.
82
83@item m68k/gen68360
84This BSP is for a MC68360 CPU.  See @code{m68k/gen68360/README} for details.
85
86@item m68k/mvme162
87See @code{m68k/mvme162/README}.
88
89@item m68k/mvme167
90See @code{m68k/mvme167/README}.
91
92@item mips/jmr3904
93This is a BSP for the Toshiba TX3904 evaluation board
94simulator included with @code{mipstx39-rtems-gdb}.  The
95BSP is located in @code{mips/jmr3904}.
96The TX3904 is a MIPS R3000 class CPU with serial ports and timers
97integrated with the processor.  This BSP can be used with
98either real  hardware or with the simulator included with
99@code{mipstx39-rtems-gdb}.  An application can be run on the simulator
100by executing the following commands upon entering @code{mipstx39-rtems-gdb}:
101
102@example
103target sim --board=jmr3904
104load
105run
106@end example
107
108@item powerpc/mcp750
109See @code{powerpc/motorola_shared/README}.
110
111@item powerpc/mvme230x
112See @code{powerpc/motorola_shared/README.MVME2300}.
113
114@item powerpc/psim
115This is a BSP for the PowerPC simulator included with @code{powerpc-rtems-gdb}.
116The simulator is complicated to initialize by hand.  The user is referred
117to the script @code{powerpc/psim/tools/psim}.
118
119@item sparc/erc32
120The ERC32 is a radiation hardened SPARC V7.  This BSP can be used with
121either real ERC32 hardware or with the simulator included with
122@code{sparc-rtems-gdb}.  An application can be run on the simulator
123by executing the following commands upon entering @code{sparc-rtems-gdb}:
124
125@example
126target sim
127load
128run
129@end example
130
131@end table
132
133RTEMS has many more BSPs and new BSPs for commercial boards and CPUs
134with on-CPU peripherals are generally welcomed.
135
136@c
137@c  C/C++ Sample Applications
138@c
139@section C/C++ Sample Applications
140
141The C/C++ sample application set includes a number of simple applications.
142Some demonstrate some basic functionality in RTEMS such as writing
143a file, closing it, and reading it back while others can serve as
144starting points for RTEMS applications or libraries.  Start by
145unarchiving them so you can peruse them.  Use a command similar to
146the following to unarchive the sample applications:
147
148@example
149cd tools
150tar xjf ../archive/examples-VERSION.tgz
151@end example
152
153The sample applications most likely to be of interest to you are:
154
155@itemize @bullet
156@item hello_world_c - C Hello World application with a simple
157RTEMS configuration and an entry point not called @code{main()}.
158
159@item simple_main - Very simple program starting at @code{main()}
160and shutting down RTEMS via @code{exit()} without any other operations.
161It uses the default configuration inside RTEMS which is only
162intended to satisfy @code{autoconf} probes and extremely simple
163console-based applications.
164
165@item libcpp - Simple C++ library for RTEMS showing how to build an
166application library written in C++.
167
168@item psx_sched_report - POSIX Scheduler Reporter is a program
169that prints out some scheduler attributes of the RTEMS POSIX API.
170
171@end itemize
172
173Each tests is found in a separate subdirectory and built using the
174same command sequence.  The @code{hello_world_c} sample will be used
175as an example.
176
177@c
178@c Build the C Hello World Application
179@c
180@subheading Build the C Hello World Application
181
182Use the following command to start the build of the sample hello
183world application:
184
185@example
186cd hello_world_c
187make
188@end example
189
190
191If the sample application has successfully been built, then the application
192executable is placed in the following directory:
193
194@example
195hello_world_c/o-optimize/<filename>.exe
196@end example
197
198The other C/C++ sample applications are built using a similar procedure.
199
200@c
201@c  Ada Sample Applications
202@c
203@section Ada Sample Applications
204
205The Ada sample application set primarily includes a
206a simple Hello World Ada program which can be used
207as a starting point for GNAT/RTEMS applications.
208Use the following command to unarchive the Ada sample
209applications:
210
211@example
212cd tools
213tar xzf ../archive/hello_world_ada.tgz
214@end example
215
216@subheading Create a BSP Specific Makefile
217
218Currently, the procedure for building and linking an Ada application
219is a bit more difficult than a C or C++ application.  This is certainly
220an opportunity for a volunteer project.
221
222At this time, there is a
223
224Provided are example Makefiles for multiple BSPs.  Copy one of these to
225the file Makefile.<BOARD_SUPPORT_PACKAGE> and edit it as appropriate for
226your local configuration.
227
228Use the  <INSTALLATION_POINT> and <BOARD_SUPPORT_PACKAGE> specified when
229configuring and installing RTEMS.
230
231@section Build the Sample Application
232
233Use the following command to start the build of the sample application:
234
235@example
236cd tools/hello_world_ada
237make -f Makefile.<BOARD_SUPPORT_PACKAGE>
238@end example
239
240NOTE: GNU make is the preferred @code{make} utility.  Other @code{make}
241implementations may work but all testing is done with GNU make.
242
243If the BSP specific modifications to the Makefile were correct and
244no errors are detected during the sample application build, it is
245reasonable to assume that the build of the GNAT/RTEMS Cross Compiler Tools
246for RTEMS and RTEMS itself for the selected host and target
247combination was done properly.
248
249@section Application Executable
250
251If the sample application has successfully been build, then the application
252executable is placed in the following directory:
253
254@example
255tools/hello_world_ada/o-optimize/<filename>.exe
256@end example
257
258How this executable is downloaded to the target board is very dependent
259on the BOARD_SUPPORT_PACKAGE selected.
260----------------------------------------------------
261
262@c
263@c More Information on RTEMS Application Makefiles
264@c
265@section More Information on RTEMS Application Makefiles
266
267The hello world sample application is a simple example of an
268RTEMS application that uses the RTEMS Application Makefile
269system.  This Makefile system simplifies building
270RTEMS applications by providing Makefile templates and
271capturing the configuration information used to build
272RTEMS specific to your BSP.  Building an RTEMS application
273for different BSPs is as simple as switching the
274setting of @code{RTEMS_MAKEFILE_PATH}.  This Makefile
275system is described in the file @code{make/README}.
Note: See TracBrowser for help on using the repository browser.