From ea0777e4ee35c7a67274771200233efabd2797b0 Mon Sep 17 00:00:00 2001 From: Chris Johns Date: Fri, 1 Apr 2016 12:20:13 +1100 Subject: Review changes from Chris Mayfield. --- user/overview/index.rst | 54 +++++++++++++++++++------------------- user/start/basics.rst | 70 +++++++++++++++++++++++++++---------------------- user/start/index.rst | 4 +-- 3 files changed, 67 insertions(+), 61 deletions(-) diff --git a/user/overview/index.rst b/user/overview/index.rst index bcb2a14..39e2846 100644 --- a/user/overview/index.rst +++ b/user/overview/index.rst @@ -6,8 +6,8 @@ Overview Welcome to the :ref:term:`RTEMS` User Manual. -This document covers all the topic required as a user of RTEMS to use the RTEMS -operating system. +This document covers all the topics required as a user of RTEMS to use the +RTEMS operating system. RTEMS, Real-Time Executive for Multiprocessor Systems, is a real-time executive (kernel) which provides a high performance environment for embedded @@ -15,7 +15,7 @@ applications including the following features: .. sidebar:: Developers - Developers should look at the :r:url:`devel` for technical information the + Developers should look at the :r:url:`devel` for technical information. The design and development of RTEMS is located there. - multitasking capabilities @@ -61,9 +61,9 @@ interdependent, asynchronous or cyclical event streams. Deadlines can be further characterized as either hard or soft based upon the value of the results when produced after the deadline has passed. A deadline -is hard if the results have no value or if their use will result in a -catastrophic event. In contrast, results which are produced after a soft -deadline may have some value. +is hard if the results have no value after the deadline has passed, or a +catastophic event results from their intended use if not completed on time. In +contrast, results produced after a soft deadline may still have some value. Another distinguishing requirement of real-time application systems is the ability to coordinate or manage a large number of concurrent activities. Since @@ -84,7 +84,7 @@ complicate each and every characteristic of a real-time system. Real-time Executive =================== -Fortunately, real-time operating systems or real-time executives serve as a +Fortunately, real-time operating systems, or real-time executives, serve as a cornerstone on which to build the application system. A real-time multitasking executive allows an application to be cast into a set of logical, autonomous processes or tasks which become quite manageable. Each task is internally @@ -99,19 +99,19 @@ CPU instruction set to support efficient multitasking. By causing tasks to travel through well-defined state transitions, system calls permit an application to demand-switch between tasks in response to real-time events. -By proper grouping of responses to stimuli into separate tasks, a system can -now asynchronously switch between independent streams of execution, directly -responding to external stimuli as they occur. This allows the system design to -meet critical performance specifications which are typically measured by -guaranteed response time and transaction throughput. The multiprocessor -extensions of RTEMS provide the features necessary to manage the extra -requirements introduced by a system distributed across several processors. It -removes the physical barriers of processor boundaries from the world of the -system designer, enabling more critical aspects of the system to receive the -required attention. Such a system, based on an efficient real-time, -multiprocessor executive, is a more realistic model of the outside world or -environment for which it is designed. As a result, the system will always be -more logical, efficient, and reliable. +By properly grouping stimuli responses into separate tasks a system can now +asynchronously switch between independent streams of execution. This allows the +system to directly respond to external stimuli as they occur, as well as meet +critical performance specifications that are typically measured by guaranteed +response time and transaction throughput. The multiprocessor extensions of +RTEMS provide the features necessary to manage the extra requirements +introduced by a system distributed across several processors. It removes the +physical barriers of processor boundaries from the world of the system +designer, enabling more critical aspects of the system to receive the required +attention. Such a system, based on an efficient real-time, multiprocessor +executive, is a more realistic model of the outside world or environment for +which it is designed. As a result, the system will always be more logical, +efficient, and reliable. By using the directives provided by RTEMS, the real-time applications developer is freed from the problem of controlling and synchronizing multiple tasks and @@ -124,14 +124,14 @@ sophisticated real-time applications is significantly reduced. Open Source =========== -RTEMS is an open source operating and an open source project. As a user you -have access to all the source code and we encourage you to work with the source -code and to integrate the processes used to build tools, the kernel and any 3rd -party libraries into your project's configuration management processes. The -RTEMS project is always improving the way it develivers the kernel to you and -so your feedback is important. +RTEMS is an open source operating system and an open source project. As a user, +you have access to all the source code. We encourage you to work with the +source code and integrate the provided processes used to build tools, the +kernel and any 3rd party libraries into your project's configuration management +processes. The RTEMS project is always improving the way it develivers the +kernel to you and so your feedback is important. What we used in the RTEMS project to develop and maintain RTEMS does not -dictate what you use to develop and maintain your project. You can and should +dictate what you use to develop and maintain your project. You can, and should, select the work-flow that best suites the demands of your project and what you are delivering. diff --git a/user/start/basics.rst b/user/start/basics.rst index fad3e83..7888994 100644 --- a/user/start/basics.rst +++ b/user/start/basics.rst @@ -6,37 +6,42 @@ Prefixes ======== -You will see the term **prefix** referred to thoughout this documentation and -in a wide number of software packages you can download from the internet. A -**prefix** is a path on your computer a software package is built and installed -under. Packages that have a **prefix** will place all parts under the *prefix -path*. On a host computer like Linux the packages you install from your -distribution typically use a platform specific standard *prefix*. For example -on Linux it is :file:`/usr` and on FreeBSD it is :file:`/usr/local`. - -We recommend you **do not** use the standard *prefix* when installing RTEMS -Tools. If you are building the tools as a normal user and not as ``root`` the -RTEMS Source Builder (RSB) will fail if the *prefix* is not writable. We -recommend you leave the standand *prefix* for the packages your operating -system installs. - -A further reason not use the standard *prefix* is to allow more than one +You will see the term :ref:term:`prefix` referred to thoughout this +documentation and in a wide number of software packages you can download from +the internet. A **prefix** is the path on your computer a software package is +built and installed under. Packages that have a **prefix** will place all parts +under the **prefix** path. On a host computer like Linux the packages you +install from your distribution typically use a platform specific standard +**prefix**. For example on Linux it is :file:`/usr` and on FreeBSD it is +:file:`/usr/local`. + +We recommend you *DO NOT* use the standard **prefix** when installing the RTEMS +Tools. The standard **prefix** is the default **prefix** each package built by +the RSB contains. If you are building the tools when logged in as a *Standard +User* and not as the *Super User* (``root``) or *Administrator* the RTEMS +Source Builder (RSB) *will* fail and report an error if the default **prefix** +is not writable. We recommend you leave the standand **prefix** for the +packages your operating system installs or software you manually install such +as applications. + +A further reason not to use the standard **prefix** is to allow more than one version of RTEMS to exist on your host machine at a time. The ``autoconf`` and -``automake`` tools required by RTEMS are not versioned and vary between RTEMS -versions. If you use a single *prefix* there is a chance things from different -versions may interact. This should not happen but it could. - -For POSIX or Unix hosts the RTEMS Project uses :file:`/opt/rtems` as a standard -*prefix*. We view this *prefix* as a production level path and we place -development versions under a different *prefix* away from the production -versions. Under this top level *prefix* we place the various versions we need -for development, for example the version 4.11.0 *prefix* would be -:file:`/opt/rtems/4.11.0`. If an update called 4.11.1 is released the *prefix* -would be :file:`/opt/rtems/4.11.1`. These are recommendations and the choice of -what you use is entirly yours. You may decide to have a single path for all -RTEMS 4.11 releases of :file:`/opt/rtems/4.11`. - -For Windows a typical prefix is :file:`C:\\opt\\rtems` and as an MSYS2 path +``automake`` tools required by RTEMS are not versioned and vary between the +various versions of RTEMS. If you use a single **prefix** such as the standard +**prefix** there is a chance parts from a package of different versions may +interact. This should not happen but it can. + +For POSIX or Unix hosts, the RTEMS Project uses :file:`/opt/rtems` as it's +standard **prefix**. We view this **prefix** as a production level path, and we +prefer to place development versions under a different **prefix** away from the +production versions. Under this top level **prefix** we place the various +versions we need for development. For example the version 4.11.0 **prefix** +would be :file:`/opt/rtems/4.11.0`. If an update called 4.11.1 is released the +**prefix** would be :file:`/opt/rtems/4.11.1`. These are recommendations and +the choice of what you use is entirely yours. You may decide to have a single +path for all RTEMS 4.11 releases of :file:`/opt/rtems/4.11`. + +For Windows a typical **prefix** is :file:`C:\\opt\\rtems` and as an MSYS2 path this is :file:`/c/opt/rtems`. .. _project_sandboxing: @@ -45,8 +50,9 @@ Project Sandboxing ================== Project specific sandboxes let you have a number of projects running in -parallel with each project in its own sandbox. You simply have a prefix per -project and under that prefix you create a simple yet repeatable structure. +parallel with each project in its own sandbox. You simply have a +:ref:term:`prefix` per project and under that prefix you create a simple yet +repeatable structure. As an example lets say I have a large disk mounted under :file:`/bd` for *Big Disk*. As ``root`` create a directory called ``projects`` and give the diff --git a/user/start/index.rst b/user/start/index.rst index 03432c1..a41ab5d 100644 --- a/user/start/index.rst +++ b/user/start/index.rst @@ -6,8 +6,8 @@ Getting Started =============== RTEMS is an open source real-time operating system. As a user you have access -to all the source code and this `Getting Started`_ section will show you how -you build the RTEMS compiler tools, kernel and 3rd party libraries from source. +to all the source code. This ``Getting Started`` section will show you how you +build the RTEMS compiler tools, kernel and 3rd party libraries from source. .. include:: basics.rst .. include:: depend.rst -- cgit v1.2.3