summaryrefslogtreecommitdiffstats
path: root/doc/started/sample.t
diff options
context:
space:
mode:
authorJoel Sherrill <joel.sherrill@OARcorp.com>2003-10-02 18:01:48 +0000
committerJoel Sherrill <joel.sherrill@OARcorp.com>2003-10-02 18:01:48 +0000
commit48cd0b8e254d7fedc447d672f932d565f47d7b59 (patch)
treea51d08622fc0665c1f8751749c7d571d02b1ee50 /doc/started/sample.t
parente931dbbebada7045e9820793fa6d05ab6e5479e0 (diff)
downloadrtems-48cd0b8e254d7fedc447d672f932d565f47d7b59.tar.bz2
2003-10-02 Joel Sherrill <joel@OARcorp.com>
* 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.
Diffstat (limited to 'doc/started/sample.t')
-rw-r--r--doc/started/sample.t208
1 files changed, 174 insertions, 34 deletions
diff --git a/doc/started/sample.t b/doc/started/sample.t
index b474f6483a..87b6e778b6 100644
--- a/doc/started/sample.t
+++ b/doc/started/sample.t
@@ -6,21 +6,22 @@
@c $Id$
@c
-@chapter Building the Sample Application
+@chapter Building the Sample Applications
-@section Unarchive the Sample Application
-
-Use the following command to unarchive the sample application:
-
-@example
-cd tools
-tar xzf ../archive/hello_world_c.tgz
-@end example
+The RTEMS distribution includes a number of sample C, C++,
+Ada, and networking applications. This chapter will provide
+an overview of those sample applications.
+@c
+@c Set the Environment Variable RTEMS_MAKEFILE_PATH
+@c
@section Set the Environment Variable RTEMS_MAKEFILE_PATH
-RTEMS_MAKEFILE_PATH must point to the appropriate directory containing
-RTEMS build for our target and board support package combination.
+The sample application sets use the RTEMS Application Makefiles.
+This requires that the environment variable
+@code{RTEMS_MAKEFILE_PATH} point to the appropriate directory containing
+the installed RTEMS image built to target your particular CPU and
+board support package combination.
@example
export RTEMS_MAKEFILE_PATH=<INSTALLATION_POINT>/<BOARD_SUPPORT_PACKAGE>
@@ -33,35 +34,22 @@ NOTE: In release 4.0, BSPs were installed at
@code{<INSTALLATION_POINT>/rtems/<BOARD_SUPPORT_PACKAGE>}. This
was changed to be more in compliance with GNU standards.
-@section Build the Sample Application
-
-Use the following command to start the build of the sample hello
-world application:
-
-@example
-cd hello_world_c
-make
-@end example
-
NOTE: GNU make is the preferred @code{make} utility. Other @code{make}
implementations may work but all testing is done with GNU make.
If no errors are detected during the sample application build, it is
-reasonable to assume that the build of the GNU C/C++ Cross Compiler Tools
+reasonable to assume that the build of the GNU Cross Compiler Tools
for RTEMS and RTEMS itself for the selected host and target
combination was done properly.
-@section Application Executable
-
-If the sample application has successfully been built, then the application
-executable is placed in the following directory:
-
-@example
-hello_world_c/o-optimize/<filename>.exe
-@end example
+@c
+@c Executing the Sample Applications
+@c
+@section Executing the Sample Applications
-How this executable is downloaded to the target board is very dependent
-on the BOARD_SUPPORT_PACKAGE selected. The following is a list of
+How each sample application executable is downloaded
+to your target board and executed is very dependent
+on the board you are using. The following is a list of
commonly used BSPs classified by their RTEMS CPU family and pointers
to instructions on how to use them. [NOTE: All file names should be
prepended with @value{RTEMSUNTAR}/c/src/lib/libbsp.]
@@ -69,6 +57,14 @@ prepended with @value{RTEMSUNTAR}/c/src/lib/libbsp.]
@need 1000
@table @b
+@item arm/edp7312
+The arm/edp7312 BSP is for the ARM7-based Cogent EDP7312 board.
+
+@item c4x/c4xsim
+The c4x/c4xsim BSP is designed to execute on any member of
+the Texas Instruments C3x/C4x DSP family using only on-CPU
+peripherals for the console and timers.
+
@item i386/pc386
See @code{i386/pc386/HOWTO}
@@ -93,6 +89,22 @@ See @code{m68k/mvme162/README}.
@item m68k/mvme167
See @code{m68k/mvme167/README}.
+@item mips/jmr3904
+This is a BSP for the Toshiba TX3904 evaluation board
+simulator included with @code{mipstx39-rtems-gdb}. The
+BSP is located in @code{mips/jmr3904}.
+The TX3904 is a MIPS R3000 class CPU with serial ports and timers
+integrated with the processor. This BSP can be used with
+either real hardware or with the simulator included with
+@code{mipstx39-rtems-gdb}. An application can be run on the simulator
+by executing the following commands upon entering @code{mipstx39-rtems-gdb}:
+
+@example
+target sim --board=jmr3904
+load
+run
+@end example
+
@item powerpc/mcp750
See @code{powerpc/motorola_shared/README}.
@@ -121,6 +133,135 @@ run
RTEMS has many more BSPs and new BSPs for commercial boards and CPUs
with on-CPU peripherals are generally welcomed.
+@c
+@c C/C++ Sample Applications
+@c
+@section C/C++ Sample Applications
+
+The C/C++ sample application set includes a number of simple applications.
+Some demonstrate some basic functionality in RTEMS such as writing
+a file, closing it, and reading it back while others can serve as
+starting points for RTEMS applications or libraries. Start by
+unarchiving them so you can peruse them. Use a command similar to
+the following to unarchive the sample applications:
+
+@example
+cd tools
+tar xjf ../archive/examples-VERSION.tgz
+@end example
+
+The sample applications most likely to be of interest to you are:
+
+@itemize @bullet
+@item hello_world_c - C Hello World application with a simple
+RTEMS configuration and an entry point not called @code{main()}.
+
+@item simple_main - Very simple program starting at @code{main()}
+and shutting down RTEMS via @code{exit()} without any other operations.
+It uses the default configuration inside RTEMS which is only
+intended to satisfy @code{autoconf} probes and extremely simple
+console-based applications.
+
+@item libcpp - Simple C++ library for RTEMS showing how to build an
+application library written in C++.
+
+@item psx_sched_report - POSIX Scheduler Reporter is a program
+that prints out some scheduler attributes of the RTEMS POSIX API.
+
+@end itemize
+
+Each tests is found in a separate subdirectory and built using the
+same command sequence. The @code{hello_world_c} sample will be used
+as an example.
+
+@c
+@c Build the C Hello World Application
+@c
+@subheading Build the C Hello World Application
+
+Use the following command to start the build of the sample hello
+world application:
+
+@example
+cd hello_world_c
+make
+@end example
+
+
+If the sample application has successfully been built, then the application
+executable is placed in the following directory:
+
+@example
+hello_world_c/o-optimize/<filename>.exe
+@end example
+
+The other C/C++ sample applications are built using a similar procedure.
+
+@c
+@c Ada Sample Applications
+@c
+@section Ada Sample Applications
+
+The Ada sample application set primarily includes a
+a simple Hello World Ada program which can be used
+as a starting point for GNAT/RTEMS applications.
+Use the following command to unarchive the Ada sample
+applications:
+
+@example
+cd tools
+tar xzf ../archive/hello_world_ada.tgz
+@end example
+
+@subheading Create a BSP Specific Makefile
+
+Currently, the procedure for building and linking an Ada application
+is a bit more difficult than a C or C++ application. This is certainly
+an opportunity for a volunteer project.
+
+At this time, there is a
+
+Provided are example Makefiles for multiple BSPs. Copy one of these to
+the file Makefile.<BOARD_SUPPORT_PACKAGE> and edit it as appropriate for
+your local configuration.
+
+Use the <INSTALLATION_POINT> and <BOARD_SUPPORT_PACKAGE> specified when
+configuring and installing RTEMS.
+
+@section Build the Sample Application
+
+Use the following command to start the build of the sample application:
+
+@example
+cd tools/hello_world_ada
+make -f Makefile.<BOARD_SUPPORT_PACKAGE>
+@end example
+
+NOTE: GNU make is the preferred @code{make} utility. Other @code{make}
+implementations may work but all testing is done with GNU make.
+
+If the BSP specific modifications to the Makefile were correct and
+no errors are detected during the sample application build, it is
+reasonable to assume that the build of the GNAT/RTEMS Cross Compiler Tools
+for RTEMS and RTEMS itself for the selected host and target
+combination was done properly.
+
+@section Application Executable
+
+If the sample application has successfully been build, then the application
+executable is placed in the following directory:
+
+@example
+tools/hello_world_ada/o-optimize/<filename>.exe
+@end example
+
+How this executable is downloaded to the target board is very dependent
+on the BOARD_SUPPORT_PACKAGE selected.
+----------------------------------------------------
+
+@c
+@c More Information on RTEMS Application Makefiles
+@c
@section More Information on RTEMS Application Makefiles
The hello world sample application is a simple example of an
@@ -131,5 +272,4 @@ capturing the configuration information used to build
RTEMS specific to your BSP. Building an RTEMS application
for different BSPs is as simple as switching the
setting of @code{RTEMS_MAKEFILE_PATH}. This Makefile
-system is described in the file
-@code{make/README}.
+system is described in the file @code{make/README}.