[ae68ff0] | 1 | @c |
---|
[6449498] | 2 | @c COPYRIGHT (c) 1988-2002. |
---|
[ae68ff0] | 3 | @c On-Line Applications Research Corporation (OAR). |
---|
| 4 | @c All rights reserved. |
---|
| 5 | @c |
---|
[139b2e4a] | 6 | @c $Id$ |
---|
| 7 | @c |
---|
[ae68ff0] | 8 | |
---|
| 9 | @chapter Directory Structure |
---|
| 10 | |
---|
| 11 | The RTEMS directory structure is designed to meet |
---|
| 12 | the following requirements: |
---|
| 13 | |
---|
| 14 | @itemize @bullet |
---|
| 15 | @item encourage development of modular components. |
---|
| 16 | |
---|
| 17 | @item isolate processor and target dependent code, while |
---|
| 18 | allowing as much common source code as possible to be shared |
---|
[aa41429] | 19 | across multiple processors and target boards. |
---|
[ae68ff0] | 20 | |
---|
| 21 | @item allow multiple RTEMS users to perform simultaneous |
---|
| 22 | compilation of RTEMS and its support facilities for different |
---|
| 23 | processors and targets. |
---|
| 24 | @end itemize |
---|
| 25 | |
---|
| 26 | The resulting directory structure has processor and |
---|
[aa41429] | 27 | board dependent source files isolated from generic files. When |
---|
| 28 | RTEMS is configured and built, object directories and |
---|
| 29 | an install point will be automatically created based upon |
---|
| 30 | the target CPU family and BSP selected. |
---|
| 31 | |
---|
| 32 | The placement of object files based upon the selected BSP name |
---|
| 33 | ensures that object files are not mixed across CPUs or targets. |
---|
| 34 | This in combination with the makefiles allows the specific |
---|
[ae68ff0] | 35 | compilation options to be tailored for a particular target |
---|
| 36 | board. For example, the efficiency of the memory subsystem for |
---|
| 37 | a particular target board may be sensitive to the alignment of |
---|
| 38 | data structures, while on another target board with the same |
---|
| 39 | processor memory may be very limited. For the first target, the |
---|
| 40 | options could specify very strict alignment requirements, while |
---|
[818ab36a] | 41 | on the second the data structures could be @i{packed} to conserve |
---|
[ae68ff0] | 42 | memory. It is impossible to achieve this degree of flexibility |
---|
| 43 | without providing source code. |
---|
[aa41429] | 44 | |
---|
[818ab36a] | 45 | The RTEMS source tree is organized based on the following variables: |
---|
[ae68ff0] | 46 | |
---|
| 47 | @itemize @bullet |
---|
| 48 | |
---|
[aa41429] | 49 | @item functionality, |
---|
| 50 | @item target processor family, |
---|
| 51 | @item target processor model, |
---|
| 52 | @item peripherals, and |
---|
| 53 | @item target board. |
---|
[ae68ff0] | 54 | |
---|
| 55 | @end itemize |
---|
| 56 | |
---|
[aa41429] | 57 | Each of the following sections will describe the |
---|
| 58 | contents of the directories in the RTEMS source |
---|
| 59 | tree. The top of the tree will be referenced |
---|
| 60 | as @code{$@{RTEMS_ROOT@}} in this discussion. |
---|
[ae68ff0] | 61 | |
---|
| 62 | @c |
---|
[aa41429] | 63 | @c Top Level Tree |
---|
[ae68ff0] | 64 | @c |
---|
| 65 | |
---|
[aa41429] | 66 | @c @ifset use-ascii |
---|
[ae68ff0] | 67 | @example |
---|
| 68 | @group |
---|
[aa41429] | 69 | rtems-VERSION |
---|
| 70 | | |
---|
| 71 | +--------+----+----+----+--+-----+---+------+-----+ |
---|
| 72 | | | | | | | | | | |
---|
| 73 | aclocal automake c contrib cpukit doc make scripts tools |
---|
[ae68ff0] | 74 | @end group |
---|
| 75 | @end example |
---|
[aa41429] | 76 | @c @end ifset |
---|
[ae68ff0] | 77 | |
---|
| 78 | @ifset use-tex |
---|
| 79 | @end ifset |
---|
| 80 | |
---|
| 81 | @ifset use-html |
---|
| 82 | @html |
---|
| 83 | @end html |
---|
| 84 | @end ifset |
---|
| 85 | |
---|
| 86 | @table @code |
---|
[aa41429] | 87 | @item $@{RTEMS_ROOT@}/aclocal/ |
---|
| 88 | This directory contains the custom M4 macros which are available to |
---|
| 89 | the various GNU autoconf @code{configure.ac} scripts throughout |
---|
| 90 | the RTEMS source tree. GNU autoconf interprets @code{configure.ac} |
---|
| 91 | files to produce the @code{configure} files used to tailor |
---|
| 92 | RTEMS build for a particular host and target environment. The |
---|
| 93 | contents of this directory will not be discussed further in this |
---|
| 94 | document. |
---|
| 95 | |
---|
| 96 | @item $@{RTEMS_ROOT@}/automake/ |
---|
| 97 | This directory contains the custom GNU automake fragments |
---|
| 98 | which are used to support the various @code{Makefile.am} |
---|
| 99 | files throughout the RTEMS source tree. The |
---|
| 100 | contents of this directory will not be discussed |
---|
| 101 | further in this document. |
---|
| 102 | |
---|
| 103 | @item $@{RTEMS_ROOT@}/c/ |
---|
| 104 | This directory is the root of the portions of the RTEMS source |
---|
| 105 | tree which must be built tailored for a particular CPU model |
---|
| 106 | or BSP. The contents of this directory will be discussed |
---|
| 107 | in the @ref{Directory Structure c/ Directory} section. |
---|
| 108 | |
---|
| 109 | @item $@{RTEMS_ROOT@}/contrib/ |
---|
| 110 | This directory contains contributed support software. Currently |
---|
| 111 | this directory contains the RPM specifications for cross-compilers |
---|
| 112 | hosted on GNU/Linux that target Cygwin and Solaris. The |
---|
| 113 | cross-compilers produced using these specifications are then |
---|
| 114 | used in a Canadian cross build procedure to produce the Cygwin |
---|
| 115 | and Solaris hosted RTEMS toolsets on a GNU/Linux host. This |
---|
| 116 | directory will not be discussed further in this document. |
---|
| 117 | |
---|
| 118 | @item $@{RTEMS_ROOT@}/cpukit/ |
---|
| 119 | This directory is the root for all of the "multilib'able" |
---|
| 120 | portions of RTEMS. This is a GNU way of saying the the |
---|
| 121 | contents of this directory can be compiled like the |
---|
| 122 | C Library (@code{libc.a}) and the functionality is |
---|
| 123 | neither CPU model nor BSP specific. The source code |
---|
| 124 | for most RTEMS services reside under this directory. |
---|
| 125 | The contents of this directory will be discussed |
---|
| 126 | in the @ref{Directory Structure CPUKit Directory} section. |
---|
| 127 | |
---|
| 128 | @item $@{RTEMS_ROOT@}/doc/ |
---|
| 129 | This directory is the root for all RTEMS documentation. |
---|
| 130 | The source for RTEMS is written in GNU TeXinfo and |
---|
| 131 | used to produce HTML, PDF, and "info" files. |
---|
| 132 | The RTEMS documentation is configured, built, |
---|
| 133 | and installed separately from the RTEMS executive and tests. |
---|
| 134 | The contents of this directory will be discussed |
---|
| 135 | in the @ref{Directory Structure Documentation Directory} section. |
---|
| 136 | |
---|
| 137 | @item $@{RTEMS_ROOT@}/make/ |
---|
| 138 | This directory contains files which support the |
---|
| 139 | RTEMS Makefile's. From a user's perspective, the |
---|
| 140 | most important parts are found in the @code{custom/} |
---|
| 141 | subdirectory. Each ".cfg" file in this directory |
---|
| 142 | is associated with a specific BSP and describes |
---|
| 143 | the CPU model, compiler flags, and procedure to |
---|
| 144 | a produce an executable for the target board. |
---|
| 145 | These files are described in detail in the |
---|
| 146 | @b{RTEMS BSP and Device Driver Development Guide} |
---|
| 147 | and will not be discussed further in this document. |
---|
| 148 | |
---|
| 149 | @item $@{RTEMS_ROOT@}/scripts/ |
---|
| 150 | This directory contains the RPM specifications for the |
---|
| 151 | prebuilt cross-compilation toolsets provided by the |
---|
| 152 | RTEMS project. There are separate subdirectories |
---|
| 153 | for each of the components in the RTEMS Cross Compilation |
---|
| 154 | Environment including @code{binutils/}, @code{gcc3newlib/}, |
---|
| 155 | and @code{gdb/}. This directory is configured, built, |
---|
| 156 | and installed separately from the RTEMS executive |
---|
| 157 | and tests. This directory will not be discussed further |
---|
| 158 | in this document. |
---|
| 159 | |
---|
| 160 | @item $@{RTEMS_ROOT@}/tools/ |
---|
| 161 | This directory contains RTEMS specific support utilities which |
---|
| 162 | execute on the development host. These utilities are divided |
---|
| 163 | into subdirectories based upon whether they are used in the process |
---|
| 164 | of building RTEMS and applications, are CPU specific, or are |
---|
| 165 | used to assist in updating the RTEMS source tree and applications. |
---|
| 166 | The support utilities used in the process of building RTEMS are |
---|
| 167 | described in @ref{RTEMS Specific Utilities}. These are the |
---|
| 168 | only components of this subtree that will be discussed in this |
---|
| 169 | document. |
---|
[ae68ff0] | 170 | |
---|
[aa41429] | 171 | @end table |
---|
[ae68ff0] | 172 | |
---|
| 173 | |
---|
| 174 | |
---|
[aa41429] | 175 | @c |
---|
| 176 | @c c/ Directions |
---|
| 177 | @c |
---|
[818ab36a] | 178 | @section c/ Directory |
---|
[ae68ff0] | 179 | |
---|
[aa41429] | 180 | The @code{$@{RTEMS_ROOT@}/c/} directory was formerly |
---|
| 181 | the root directory of all RTEMS source code. At this time, it contains |
---|
| 182 | the root directory for only those RTEMS components |
---|
| 183 | which must be compiled or linked in a way that is specific to a |
---|
| 184 | particular CPU model or board. This directory contains the |
---|
| 185 | following subdirectories: |
---|
| 186 | |
---|
| 187 | @table @code |
---|
| 188 | @item $@{RTEMS_ROOT@}/c/src/ |
---|
| 189 | This directory is logically the root for the RTEMS components |
---|
| 190 | which are CPU model or board dependent. Thus this directory |
---|
| 191 | is the root for the BSPs and the various Test Suites as well |
---|
| 192 | as CPU model and BSP dependent libraries. The contents of |
---|
| 193 | this directory are discussed in the |
---|
| 194 | @ref{Directory Structure c/src/ Directory} section. |
---|
| 195 | |
---|
| 196 | @item $@{RTEMS_ROOT@}/c/make/ |
---|
| 197 | This directory is used to generate the file @code{target.cfg} |
---|
| 198 | which is installed as part of the Application Makefiles. This |
---|
| 199 | file contains settings for various Makefile variables to |
---|
| 200 | tailor them to the particular CPU model and BSP configured. |
---|
[ae68ff0] | 201 | |
---|
| 202 | @end table |
---|
| 203 | |
---|
[aa41429] | 204 | @c |
---|
| 205 | @c c/src/ Directory |
---|
| 206 | @c |
---|
[818ab36a] | 207 | @subsection c/src/ Directory |
---|
[ae68ff0] | 208 | |
---|
[aa41429] | 209 | As mentioned previously, this directory is logically |
---|
| 210 | the root for the RTEMS components |
---|
| 211 | which are CPU model or board dependent. The |
---|
| 212 | following is a list of the subdirectories in this |
---|
| 213 | directorie and a description of each. |
---|
[ae68ff0] | 214 | |
---|
[aa41429] | 215 | @table @code |
---|
| 216 | @item $@{RTEMS_ROOT@}/c/src/ada-tests/ |
---|
| 217 | This directory contains the test suite for the Ada |
---|
| 218 | language bindings to the Classic API. |
---|
| 219 | |
---|
| 220 | @item $@{RTEMS_ROOT@}/c/src/lib/ |
---|
[818ab36a] | 221 | This directory contains the directories @code{libbsp} |
---|
| 222 | and @code{libcpu/} which contain the source code for |
---|
| 223 | the Board Support Packages (BSPs) and CPU Model |
---|
| 224 | specific source code for RTEMS. |
---|
| 225 | |
---|
| 226 | The @code{libbsp/} is organized based upon the CPU |
---|
| 227 | family and boards BSPs. The contents of @code{libbsp/} |
---|
| 228 | are discussed briefly in |
---|
| 229 | @ref{Directory Structure c/src/lib/libbsp BSP Directory} |
---|
| 230 | and presented in detail in the |
---|
| 231 | @b{RTEMS BSP and Device Driver Development Guide}. |
---|
| 232 | |
---|
| 233 | The @code{libcpu/} directory is also organized by |
---|
| 234 | CPU family with further divisions based upon CPU |
---|
| 235 | model and features that are shared across CPU models |
---|
| 236 | such as caching and DMA. |
---|
[aa41429] | 237 | |
---|
| 238 | @item $@{RTEMS_ROOT@}/c/src/libchip/ |
---|
| 239 | This directory contains device drivers for various |
---|
| 240 | peripheral chips which are designed to be CPU and |
---|
| 241 | board dependent. This directory contains a variety |
---|
| 242 | of drivers for serial devices, network interface |
---|
| 243 | controllers, and real-time clocks. |
---|
| 244 | |
---|
| 245 | @item $@{RTEMS_ROOT@}/c/src/libmisc/ |
---|
| 246 | This directory contains support facilities which |
---|
| 247 | are RTEMS specific but otherwise unclassified. In |
---|
| 248 | general, they do not adhere to a standard API. |
---|
| 249 | Among the support facilities in this directory are |
---|
| 250 | a @code{/dev/null} device driver, the Stack |
---|
| 251 | Overflow Checker, a mini-shell, the CPU and |
---|
| 252 | rate monotonic period usage monitoring libraries, |
---|
| 253 | and a utility to "dump a buffer" in a nicely |
---|
| 254 | formatted way similar to many ROM monitors. |
---|
| 255 | |
---|
| 256 | @item $@{RTEMS_ROOT@}/c/src/libnetworking/ |
---|
| 257 | This directory contains the networking components which |
---|
| 258 | might be tailored based upon the particular BSP. This |
---|
| 259 | includes the RTEMS telnetd, httpd, and ftpd servers. |
---|
| 260 | |
---|
| 261 | @item $@{RTEMS_ROOT@}/c/src/librdbg/ |
---|
| 262 | This directory contains the Ethernet-based remote debugging |
---|
| 263 | stub. This software must be built to be intimately aware |
---|
| 264 | of a particular CPU model. |
---|
| 265 | |
---|
| 266 | @item $@{RTEMS_ROOT@}/c/src/librtems++/ |
---|
[818ab36a] | 267 | This directory contains C++ classes which map to the RTEMS |
---|
| 268 | Classic API. |
---|
[aa41429] | 269 | |
---|
| 270 | @item $@{RTEMS_ROOT@}/c/src/make/ |
---|
[818ab36a] | 271 | This directory is used to generate the bulk of the supporting |
---|
| 272 | rules files which are installed as part of the Application Makefiles. |
---|
| 273 | This file contains settings for various Makefile variables to |
---|
| 274 | tailor them to the particular CPU model and BSP configured. |
---|
[aa41429] | 275 | |
---|
| 276 | @item $@{RTEMS_ROOT@}/c/src/optman/ |
---|
[818ab36a] | 277 | This directory contains stubs for the RTEMS Classic API |
---|
| 278 | Managers which are considered optional and whose use |
---|
| 279 | may be explicitly forbidden by an application. All of the |
---|
| 280 | directive implementations in this Optional Managers |
---|
| 281 | return @code{E_NOTCONFIGURED}. |
---|
[aa41429] | 282 | |
---|
| 283 | @item $@{RTEMS_ROOT@}/c/src/tests/ |
---|
| 284 | This directory contains the test suites for the |
---|
| 285 | various RTEMS APIs and support libraries. This |
---|
| 286 | contents of this directory are discussed in the |
---|
[818ab36a] | 287 | @ref{Directory Structure c/src/tests/ Test Suites} section. |
---|
[aa41429] | 288 | |
---|
| 289 | @item $@{RTEMS_ROOT@}/c/src/wrapup/ |
---|
[818ab36a] | 290 | This directory is responsible for taking the individual |
---|
| 291 | libraries and objects built in each of the components |
---|
| 292 | in the RTEMS source tree and bundling them together to form |
---|
| 293 | the single RTEMS library @code{librtemsbsp.a}. This |
---|
| 294 | library contains all BSP and CPU model specific software. |
---|
[aa41429] | 295 | |
---|
| 296 | @end table |
---|
[ae68ff0] | 297 | |
---|
| 298 | @c |
---|
[818ab36a] | 299 | @c c/src/lib/libbsp BSP Directory |
---|
[ae68ff0] | 300 | @c |
---|
| 301 | |
---|
[818ab36a] | 302 | @subsubsection c/src/lib/libbsp BSP Directory |
---|
[ae68ff0] | 303 | |
---|
| 304 | The "libbsp" directory contains a directory for each CPU family supported |
---|
| 305 | by RTEMS. Beneath each CPU directory is a directory for each BSP for that |
---|
| 306 | processor family. |
---|
| 307 | |
---|
| 308 | @c |
---|
| 309 | @c Tree 7 - C BSP Library |
---|
| 310 | @c |
---|
| 311 | |
---|
[db91520] | 312 | The "libbsp" directory provides all the BSPs provided with this |
---|
[ae68ff0] | 313 | release of the RTEMS executive. The subdirectories are |
---|
| 314 | divided, as discussed previously, based on specific processor |
---|
| 315 | family, then further breaking down into specific target board |
---|
| 316 | environments. The "shmdr" subdirectory provides the |
---|
| 317 | implementation of a shared memory driver which supports the |
---|
| 318 | multiprocessing portion of the executive. In addition, two |
---|
| 319 | starting point subdirectories are provided for reference. The |
---|
| 320 | "no_cpu" subdirectory provides a template BSP which can be used |
---|
| 321 | to develop a specific BSP for an unsupported target board. The |
---|
| 322 | "stubdr" subdirectory provides stubbed out BSPs. These files |
---|
| 323 | may aid in preliminary testing of the RTEMS development |
---|
| 324 | environment that has been built for no particular target in mind. |
---|
| 325 | |
---|
| 326 | Below each CPU dependent directory is a directory for each target BSP |
---|
| 327 | supported in this release. |
---|
| 328 | |
---|
| 329 | Each BSP provides the modules which comprise an RTEMS BSP. The |
---|
| 330 | modules are separated into the subdirectories "clock", "console", |
---|
| 331 | "include", "shmsupp", "startup", and "timer" as shown in the following |
---|
| 332 | figure: |
---|
| 333 | |
---|
| 334 | @c |
---|
| 335 | @c Tree 8 - Each BSP |
---|
| 336 | @c |
---|
| 337 | |
---|
[818ab36a] | 338 | @c @ifset use-ascii |
---|
[ae68ff0] | 339 | @example |
---|
| 340 | @group |
---|
| 341 | Each BSP |
---|
| 342 | | |
---|
| 343 | +-----------+----------+-----+-----+----------+----------+ |
---|
| 344 | | | | | | | |
---|
| 345 | clock console include shmsupp startup timer |
---|
| 346 | @end group |
---|
| 347 | @end example |
---|
[818ab36a] | 348 | @c @end ifset |
---|
[ae68ff0] | 349 | |
---|
[818ab36a] | 350 | @c |
---|
| 351 | @c c/src/tests/ Test Suites |
---|
| 352 | @c |
---|
| 353 | @subsection c/src/tests/ Test Suites |
---|
| 354 | |
---|
| 355 | This directory provides all of the RTEMS Test Suite |
---|
| 356 | except those for the Classic API Ada95 binding |
---|
| 357 | This includes the single processor tests, multiprocessor tests, |
---|
| 358 | timing tests, library tests, and sample tests. Additionally, |
---|
| 359 | subdirectories for support functions and test related header |
---|
| 360 | files are provided. The following table lists the test suites |
---|
| 361 | currently included with the RTEMS and the directory in which |
---|
| 362 | they may be located: |
---|
| 363 | |
---|
| 364 | @table @code |
---|
| 365 | |
---|
| 366 | @item $@{RTEMS_ROOT@}/c/src/tests/itrontests/ |
---|
| 367 | This directory contains the test suite for the |
---|
| 368 | RTEMS ITRON API. |
---|
| 369 | |
---|
| 370 | @item $@{RTEMS_ROOT@}/c/src/tests/libtests/ |
---|
| 371 | This directory contains the test suite for the |
---|
| 372 | various RTEMS support components. |
---|
| 373 | |
---|
| 374 | @item $@{RTEMS_ROOT@}/c/src/tests/mptests/ |
---|
| 375 | This directory contains the test suite for the |
---|
| 376 | multiprocessor support in the Classic API. |
---|
| 377 | The tests provided address two node configurations |
---|
| 378 | and provide coverage for the multiprocessor code found |
---|
| 379 | in RTEMS. |
---|
| 380 | |
---|
| 381 | @item $@{RTEMS_ROOT@}/c/src/tests/psxtests/ |
---|
| 382 | This directory contains the test suite for the |
---|
| 383 | RTEMS POSIX API. |
---|
| 384 | |
---|
| 385 | @item $@{RTEMS_ROOT@}/c/src/tests/samples/ |
---|
| 386 | This directory provides sample application tests |
---|
| 387 | which aid in the testing a newly built RTEMS environment, a new |
---|
| 388 | BSP, or as starting points for the development of an application |
---|
| 389 | using the RTEMS executive. They are discussed in |
---|
| 390 | @ref{Sample Applications}. |
---|
| 391 | |
---|
| 392 | @item $@{RTEMS_ROOT@}/c/src/tests/sptests/ |
---|
| 393 | This directory contains the test suite for the RTEMS |
---|
| 394 | Classic API when executing on a single processor. |
---|
| 395 | The tests were originally designed to provide |
---|
| 396 | near complete test coverage for the the entire |
---|
| 397 | executive code. With the addition of multiple APIs, |
---|
| 398 | this is no longer the case as some SuperCore functionality |
---|
| 399 | is not available through the Classic API. Thus |
---|
| 400 | some functionality in the SuperCore is only covered |
---|
| 401 | by tests in the POSIX API and ITRON API Test Suites. |
---|
| 402 | |
---|
| 403 | @item $@{RTEMS_ROOT@}/c/src/tests/support/ |
---|
| 404 | This directory contains support software and header files |
---|
| 405 | for the various test suites. |
---|
| 406 | |
---|
| 407 | @item $@{RTEMS_ROOT@}/c/src/tests/tmitrontests/ |
---|
| 408 | This directory contains the timing test suite for |
---|
| 409 | the RTEMS ITRON API. |
---|
| 410 | |
---|
| 411 | @item $@{RTEMS_ROOT@}/c/src/tests/tmtests/ |
---|
| 412 | This directory contains the timing test suite for |
---|
| 413 | the RTEMS Classic API. This include tests that |
---|
| 414 | benchmark each directive in the Classic API |
---|
| 415 | as well as a set of critical SuperCore functions. |
---|
| 416 | These tests are important for helping to verify |
---|
| 417 | that RTEMS performs as expected on your target hardware. |
---|
| 418 | It is not uncommon to discover mistakes in board |
---|
| 419 | initialization such as caching being disabled as |
---|
| 420 | a side-effect of analyzing the results of these tests. |
---|
| 421 | |
---|
| 422 | @item $@{RTEMS_ROOT@}/c/src/tests/tools/ |
---|
| 423 | This directory contains tools which execute on |
---|
| 424 | the development host and aid in executing and |
---|
| 425 | evaluating the results of the test suite. The |
---|
| 426 | tools @code{difftest} compares the output of one |
---|
| 427 | or more tests with the expected output. If you |
---|
| 428 | place the output of all the @code{tmtests/} in |
---|
| 429 | a single file, then the utility @code{sorttimes} |
---|
| 430 | will be able to produce a report organizing the |
---|
| 431 | execution times by manager. |
---|
| 432 | |
---|
| 433 | @end table |
---|
[ae68ff0] | 434 | |
---|
| 435 | |
---|
[aa41429] | 436 | @c |
---|
[818ab36a] | 437 | @c CPUKit Directory |
---|
[aa41429] | 438 | @c |
---|
[818ab36a] | 439 | @section CPUKit Directory |
---|
[ae68ff0] | 440 | |
---|
[818ab36a] | 441 | @c The @code{cpukit/} directory structure is as follows: |
---|
[ae68ff0] | 442 | |
---|
| 443 | @c |
---|
[818ab36a] | 444 | @c CPUKit Tree |
---|
[ae68ff0] | 445 | @c |
---|
| 446 | |
---|
[818ab36a] | 447 | @c @ifset use-ascii |
---|
| 448 | @c @example |
---|
| 449 | @c @group |
---|
| 450 | @c CPUKit |
---|
| 451 | @c | |
---|
| 452 | @c +-----------+----------+-----------+----------+ |
---|
| 453 | @c | | | | | |
---|
| 454 | @c posix rtems sapi score wrapup |
---|
| 455 | @c @end group |
---|
| 456 | @c @end example |
---|
| 457 | @c @end ifset |
---|
[ae68ff0] | 458 | |
---|
[818ab36a] | 459 | The @code{cpukit/} directory contains a set of subdirectories which |
---|
| 460 | contains the source files comprising the executive portion of |
---|
| 461 | the RTEMS development environment as well as portable support |
---|
| 462 | libraries such as support for the C Library and filesystems. |
---|
| 463 | The API specific and "SuperCore" (e.g. @code{score/} directory) |
---|
| 464 | source code files are separated into distinct directory trees. |
---|
[ae68ff0] | 465 | |
---|
[818ab36a] | 466 | The following is a description of each of the subdirectories |
---|
| 467 | under @code{cpukit/}: |
---|
[ae68ff0] | 468 | |
---|
[818ab36a] | 469 | @table @code |
---|
[ae68ff0] | 470 | |
---|
[818ab36a] | 471 | @item $@{RTEMS_ROOT@}/cpukit/aclocal/ |
---|
| 472 | This directory contains the custom M4 macros which are available to |
---|
| 473 | the various GNU autoconf @code{configure.ac} scripts throughout |
---|
| 474 | the CPU Kit portion of the RTEMS source tree. |
---|
| 475 | GNU autoconf interprets @code{configure.ac} |
---|
| 476 | files to produce the @code{configure} files used to tailor |
---|
| 477 | RTEMS build for a particular host and target environment. The |
---|
| 478 | contents of this directory will not be discussed further in this |
---|
| 479 | document. |
---|
[ae68ff0] | 480 | |
---|
[818ab36a] | 481 | @item $@{RTEMS_ROOT@}/cpukit/ada/ |
---|
| 482 | This directory contains the Ada95 language bindings to the |
---|
| 483 | RTEMS Classic API. |
---|
| 484 | |
---|
| 485 | @item $@{RTEMS_ROOT@}/cpukit/automake/ |
---|
| 486 | This directory contains files which are "Makefile fragments." |
---|
| 487 | They are included as required by the various @code{Makefile.am} |
---|
| 488 | files throughout the CPU Kit portion of the RTEMS source tree. |
---|
| 489 | |
---|
| 490 | @item $@{RTEMS_ROOT@}/cpukit/include/ |
---|
| 491 | This directory contains header files which are private to |
---|
| 492 | RTEMS and not considered to be owned by any other component |
---|
| 493 | in the CPU Kit. |
---|
| 494 | |
---|
| 495 | @item $@{RTEMS_ROOT@}/cpukit/itron/ |
---|
| 496 | This directory contains the implementation of the |
---|
| 497 | ITRON API. |
---|
| 498 | |
---|
| 499 | @item $@{RTEMS_ROOT@}/cpukit/libblock/ |
---|
| 500 | This directory contains support code for using |
---|
| 501 | Block Devices such as hard drives, floppies, and |
---|
| 502 | CD-ROMs. It includes the generic IO primitives |
---|
| 503 | for block device drivers, disk caching support, |
---|
| 504 | and a RAM disk block device driver. |
---|
| 505 | |
---|
| 506 | @item $@{RTEMS_ROOT@}/cpukit/libcsupport/ |
---|
| 507 | This directory contains the RTEMS specific support routines |
---|
| 508 | for the Newlib C Library. This includes what are referred |
---|
| 509 | to as system calls and found in section 2 of the traditional |
---|
| 510 | UNIX manual. In addition, it contains a thread-safe |
---|
| 511 | implementation of the Malloc family of routines as well |
---|
| 512 | as BSD and POSIX services not found in Newlib. |
---|
| 513 | |
---|
| 514 | @item $@{RTEMS_ROOT@}/cpukit/libfs/ |
---|
| 515 | This directory contains the various non-networked |
---|
| 516 | filesystem implementations for RTEMS. It includes |
---|
| 517 | the In-Memory FileSystem (IMFS), the mini-IMFS, |
---|
| 518 | and FAT filesystems. |
---|
| 519 | |
---|
| 520 | @item $@{RTEMS_ROOT@}/cpukit/libnetworking/ |
---|
| 521 | This directory contains the port of the FreeBSD |
---|
| 522 | TCP/IP stack to RTEMS. |
---|
| 523 | |
---|
| 524 | @item $@{RTEMS_ROOT@}/cpukit/librpc/ |
---|
| 525 | This directory contains the port of the FreeBSD |
---|
| 526 | RPC/XDR source to RTEMS. |
---|
| 527 | |
---|
| 528 | @item $@{RTEMS_ROOT@}/cpukit/posix/ |
---|
| 529 | This directory contains the RTEMS implementation |
---|
| 530 | of the threading portions of the POSIX API. |
---|
| 531 | |
---|
| 532 | @item $@{RTEMS_ROOT@}/cpukit/rtems/ |
---|
| 533 | This directory contains the implementation of the |
---|
| 534 | Classic API. |
---|
| 535 | |
---|
| 536 | @item $@{RTEMS_ROOT@}/cpukit/sapi/ |
---|
| 537 | This directory contains the implementation of RTEMS |
---|
| 538 | services which are required but beyond the realm |
---|
| 539 | of any standardization efforts. It includes |
---|
| 540 | initialization, shutdown, and IO services. |
---|
| 541 | |
---|
| 542 | @item $@{RTEMS_ROOT@}/cpukit/score/ |
---|
| 543 | This directory contains the "SuperCore" of RTEMS. |
---|
| 544 | All APIs are implemented in terms of SuperCore services. |
---|
| 545 | For example, Classic API tasks, POSIX threads, and ITRON |
---|
| 546 | tasks are all implemented in terms of SuperCore threads. |
---|
| 547 | This provides a common infrastructure and a high degree |
---|
| 548 | of interoperability between the APIs. For example, |
---|
| 549 | services from all APIs may be used by any task/thread |
---|
| 550 | independent of the API used to create it. |
---|
| 551 | |
---|
| 552 | Within the @code{score/} directory the CPU dependent modules are found. |
---|
| 553 | The @code{score/cpu/} subdirectory contains a subdirectory for each |
---|
| 554 | target CPU supported by the @value{RELEASE} release of the RTEMS |
---|
| 555 | executive. Each processor directory contains the CPU dependent |
---|
| 556 | code necessary to host RTEMS. The @code{no_cpu} directory provides a |
---|
| 557 | starting point for developing a new port to an unsupported |
---|
| 558 | processor. The files contained within the @code{no_cpu} directory |
---|
| 559 | may also be used as a reference for the other ports to specific |
---|
| 560 | processors. |
---|
[ae68ff0] | 561 | |
---|
[818ab36a] | 562 | @item $@{RTEMS_ROOT@}/cpukit/wrapup/ |
---|
| 563 | This directory is responsible for taking the individual |
---|
| 564 | libraries and objects built in each of the components |
---|
| 565 | in the RTEMS CPU Kit source tree and bundling them |
---|
| 566 | together to form the single RTEMS library @code{librtemscpu.a}. This |
---|
| 567 | library contains all BSP and CPU model specific software. |
---|
[ae68ff0] | 568 | |
---|
[818ab36a] | 569 | @end table |
---|
[ae68ff0] | 570 | |
---|
| 571 | @c |
---|
[818ab36a] | 572 | @c Documentation Directory |
---|
[ae68ff0] | 573 | @c |
---|
[818ab36a] | 574 | @section Documentation Directory |
---|
[ae68ff0] | 575 | |
---|
[818ab36a] | 576 | This directory contains the source code for all RTEMS documentation |
---|
| 577 | in @code{TexInfo} format as well as utilities used in the generation |
---|
| 578 | of the RTEMS documentation set. This source code is used to produce |
---|
| 579 | the RTEMS documentation in various formats including PDF, HTML, |
---|
| 580 | and PostScript. |
---|
[ae68ff0] | 581 | |
---|
[818ab36a] | 582 | @table @code |
---|
[ae68ff0] | 583 | |
---|
[818ab36a] | 584 | @item $@{RTEMS_ROOT@}/doc/FAQ/ |
---|
| 585 | This directory contains the source code for the @cite{RTEMS Frequently Asked |
---|
| 586 | Questions (FAQ) Collection}. |
---|
| 587 | |
---|
| 588 | @item $@{RTEMS_ROOT@}/doc/user/ |
---|
| 589 | This directory contains the source code for the @cite{RTEMS |
---|
| 590 | Applications C User's Guide} which documents the Classic API. |
---|
| 591 | |
---|
| 592 | @item $@{RTEMS_ROOT@}/doc/ada_user/ |
---|
| 593 | This directory contains the source code for the @cite{RTEMS |
---|
| 594 | Applications Ada User's Guide} which documents the Ada95 |
---|
| 595 | binding to the Classic API. This manual is produced from |
---|
| 596 | from the same source base as the @cite{RTEMS Application |
---|
| 597 | C User's Guide}. |
---|
| 598 | |
---|
| 599 | @item $@{RTEMS_ROOT@}/doc/bsp_howto/ |
---|
| 600 | This directory contains the source code for the |
---|
| 601 | @cite{RTEMS BSP and Device Driver Development Guide}. |
---|
| 602 | |
---|
| 603 | @item $@{RTEMS_ROOT@}/doc/common/ |
---|
| 604 | This directory contains the source code for the files which |
---|
| 605 | are shared across multiple manuals in the RTEMS Documentation Set. |
---|
| 606 | This includes the copyright page as well as the timing |
---|
| 607 | tables which can be filled in on a per BSP basis in the |
---|
| 608 | CPU supplements. |
---|
| 609 | |
---|
| 610 | @item $@{RTEMS_ROOT@}/doc/develenv/ |
---|
| 611 | This directory contains the source code for the |
---|
| 612 | @cite{RTEMS Development Environment Guide}. This is |
---|
| 613 | the document you are currently reading. |
---|
| 614 | |
---|
| 615 | @item $@{RTEMS_ROOT@}/doc/filesystem/ |
---|
| 616 | This directory contains the source code for the |
---|
| 617 | @cite{RTEMS Filesystem Design Guide}. This manual |
---|
| 618 | is a continuous work in process as it attempts to |
---|
| 619 | capture the design of the interface between system |
---|
| 620 | calls and filesystem implementations as well as the |
---|
| 621 | information required by those implementing filesystems. |
---|
| 622 | |
---|
| 623 | @item $@{RTEMS_ROOT@}/doc/gnu_docs/ |
---|
| 624 | This directory contains the scripts which assist in |
---|
| 625 | generating HTML for the GNU tools in the RTEMS Cross |
---|
| 626 | Development Environment set. |
---|
| 627 | |
---|
| 628 | @item $@{RTEMS_ROOT@}/doc/images/ |
---|
| 629 | This directory contains the source code for the graphics |
---|
| 630 | used in the HTML version of the RTEMS Documentation. |
---|
| 631 | |
---|
| 632 | @item $@{RTEMS_ROOT@}/doc/itron3.0/ |
---|
| 633 | This directory contains the source code for the |
---|
| 634 | @cite{RTEMS ITRON 3.0 API User's Guide}. |
---|
| 635 | |
---|
| 636 | @item $@{RTEMS_ROOT@}/doc/networking/ |
---|
| 637 | This directory contains the source code for the |
---|
| 638 | @cite{RTEMS Network Supplement}. |
---|
| 639 | |
---|
| 640 | @item $@{RTEMS_ROOT@}/doc/new_chapters/ |
---|
| 641 | This directory contains the source code for the new documentation |
---|
| 642 | components which have not yet been collected into a new manual or |
---|
| 643 | merged into an existing document. Currently, this primarily |
---|
| 644 | contains draft documentation for some portions of |
---|
| 645 | the facilities implemented in @code{$@{RTEMS_ROOT@}/c/src/libmisc/}. |
---|
| 646 | |
---|
| 647 | @item $@{RTEMS_ROOT@}/doc/porting/ |
---|
| 648 | This directory contains the source code for the |
---|
| 649 | @cite{RTEMS Porting Guide}. |
---|
| 650 | |
---|
| 651 | @item $@{RTEMS_ROOT@}/doc/posix1003.1/ |
---|
| 652 | This directory contains the source code for the |
---|
| 653 | @cite{RTEMS POSIX 1003.1 Compliance Guide}. |
---|
| 654 | |
---|
| 655 | @item $@{RTEMS_ROOT@}/doc/posix_users/ |
---|
| 656 | This directory contains the source code for the |
---|
| 657 | @cite{RTEMS POSIX API User's Guide}. It is important to |
---|
| 658 | note that RTEMS' support for POSIX is a combination of |
---|
| 659 | functionality provided by RTEMS and the Newlib C Library |
---|
| 660 | so some functionality is documented by Newlib. |
---|
| 661 | |
---|
| 662 | @item $@{RTEMS_ROOT@}/doc/relnotes/ |
---|
| 663 | This directory contains the source code for a formally |
---|
| 664 | release notes document. This has not been used for |
---|
| 665 | recent RTEMS releases. |
---|
| 666 | |
---|
| 667 | @item $@{RTEMS_ROOT@}/doc/rgdb_specs/ |
---|
| 668 | This directory contains the source code for the |
---|
| 669 | @cite{RTEMS Remote Debugger Server Specifications}. |
---|
| 670 | |
---|
| 671 | @item $@{RTEMS_ROOT@}/doc/rtems_gdb/ |
---|
| 672 | This directory contains the source code for the |
---|
| 673 | @cite{RTEMS/GDB User's Guide}. |
---|
| 674 | |
---|
| 675 | @item $@{RTEMS_ROOT@}/doc/started/ |
---|
| 676 | This directory contains the source code for the |
---|
| 677 | @cite{Getting Started with RTEMS for C/C++ Users} manual. |
---|
| 678 | |
---|
| 679 | @item $@{RTEMS_ROOT@}/doc/started_ada/ |
---|
| 680 | This directory contains the source code for the |
---|
| 681 | @cite{Getting Started with RTEMS for Ada Users} manual. |
---|
| 682 | |
---|
| 683 | @item $@{RTEMS_ROOT@}/doc/supplements/ |
---|
| 684 | This directory contains the source code for the various |
---|
| 685 | RTEMS CPU Supplements. |
---|
| 686 | the |
---|
| 687 | |
---|
| 688 | @item $@{RTEMS_ROOT@}/doc/tools/ |
---|
| 689 | This directory contains the source code for the tools |
---|
| 690 | used on the development host to assist in producing the |
---|
| 691 | RTEMS Documentation. The most important of these tools |
---|
| 692 | is @code{bmenu} which generates the hierarchical node |
---|
| 693 | linking commands based upon chapter, section, and |
---|
| 694 | subsection organization. |
---|
[ae68ff0] | 695 | |
---|
[818ab36a] | 696 | @end table |
---|