** --------------------------------------------------------------- ** RTL-POSIXTRACE 1.0 package ** README ** (c) 2002 Andres Terrasa (DSIC-UPV) ** ** INDEX: 1.- What is RTL-POSIXTRACE 1.0 2.- Software and documentation 3.- Tracing support and Kernel Trace 4.- Authors, license and copyright 5.- Disclaimer 6.- Bugs ** ** --------------------------------------------------------------- 1.- WHAT IS RTL-POSIXTRACE 1.0 ========================== This package adds (most of) the tracing support defined in the POSIX Trace standard to Open RT-Linux 3.1. The POSIX Trace standard defines a set of portable interfaces for tracing applications. This standard was recently approved (September 2000) and now can be found integrated with the rest of POSIX 1003.1 standards in a single document issued in 2001 after the approval of both the IEEE-SA Standards Board and the Open Group. The name of this document is "1003.1(TM) Standard for Information Technology--Portable Operating System Interface (POSIX) (Base Specifications, Issue 6)". If interested, you can buy a CDROM copy of this document in http://www.opengroup.org. (By the time I'm writing this, it is also possible to get free access to an http version of the document from the Open Group web site). As in many implementations of standards, the support provided by this package doesn't conform all the aspects of the entire approved Trace standard, although differences are actually very few. The main reason for this (slight) lack of conformance is that some aspects of the standard had to be adapted, in order to meet the RT-Linux philosophy; in particular, the fact of having only one running (real-time) application at a time, but potentially formed by a set of real-time tasks plus one or more Linux processes. Other aspects of the Trace standard were discarded, since they were either not appropriate for a small real-time kernel as RT-Linux or very difficult to implement. The decision of which functionality to discard was straightforward, since the Trace standard is defined as a mandatory core support plus three additional levels of optional support; RTL-POSIXTRACE 1.0 completely implements the core and one of this optional levels, while the other two are not supported. Overall, the implementation is intended to be as close to the standard as possible while maintaining the natural way that RT-Linux applications work. 2.- SOFTWARE AND DOCUMENTATION ========================== This package is formed by a software patch (rtl_3.1-posixtrace.patch) plus the following documentation files: * "README". The file you're now reading. * "INSTALL". Contains the installation guide of the software patch. * "ChangeLog". Keeps track of the changes being introduced to the software. * "doc/posixtrace.pdf". Contains a brief introduction to the POSIX Trace standard, including both an explanation of its main concepts and a review of its functions. If you don't know anything about POSIX tracing, you probably should start reading this. For further information, the best source is standard document itself. * "doc/rtl-pt1.0.pdf". This file explains the peculiarities of the RTL-POSIXTRACE software and how to use it. It covers which parts of the standard are currently supported and points out any difference between the standard definition and the package support. It also presents a full example of use. Once you have patched the RT-Linux distribution with the RTL-POSIXTRACE patch, you can find (and run) this example, as well as some others, in the "examples/posixtrace" directory. 3.- TRACING SUPPORT AND KERNEL TRACE ================================ RTL-POSIXTRACE 1.0 supports, first and foremost, a great part of the interface functions defined in the Trace standard, in order to allow RT-Linux applications to use POSIX tracing. Obviously, in order to do so, some parts of RT-Linux itself have been modified. One of the main changes has been to instrument the RT-Linux scheduler code in order to generate trace information (such as context switches, assignment of resources, invocation of system calls, etc.); this information, once retrieved, can be very useful to the real-time programmer. This system information can be retrieved and processed by the application, but the RTL-POSIXTRACE package incorporates a facility that does this automatically. This facility, called "kernel trace", automatically collects and processes the system tracing information, and then generates some files that can be either interpreted by a graphical display tool (called Quivi) or directly by the programmer. The kernel trace facility has been implemented as a kernel module called rtl_ktrace.o and a Linux process called ktrace_analyzer, which work together. The rtl_ktrace module is loaded automatically with all the other RT-Linux kernel modules; the ktrace_analyzer process has to be manually started before the real-time application starts running. More information about this facility can be found on the "doc/rtl-pt1.0.pdf" file. Examples of use are placed in the directory "examples/posixtrace/ktrace". If you're not interested in using this feature, you may just not load the rtl_ktrace.o module when running your application. 4.- AUTHORS, LICENSE AND COPYRIGHT ============================== RTL-POSIXTRACE 1.0 has been developed by Andres Terrasa, Ana Garcia-Fornes and Agustin Espinosa. An early version was implemented by Ignacio Paches and Andres Terrasa. All of us belong to the Technical University of Valencia (UPV), Spain. This software is licensed under the terms of the GNU's General Public License V2 (http://www.gnu.org/copyleft/gpl.html). In the near future, it will probably be included as a part of the OCERA (Open Components for Embedded RT-Linux Applications) project (http://www.ocera.org). "RT-Linux" (Real-Time Linux) is a trademark of Finite State Machine Labs, Inc. (www.fsmlabs.com). Open RT-Linux can be used free of royalties under the terms of the Open RTLinux Patent License Version 2.0 (see file PATENT in the Open RT-Linux distribution for details). "POSIX" and "1003.1" are registered trademarks of the Institute of Electrical and Electronic Engineers, Inc. 5.- DISCLAIMER ========== This software comes with no guarantee. At all. 6.- BUGS ==== Still many, I'm sure. Please report any to aterrasa@dsic.upv.es, as well as suggestions and comments.