Merge remote-tracking branch 'origin/xdccore-I-dr' into master_ggentree
diff --git a/src/packages/xdc/rov/support/ScalarStructs_xdc.xdt b/src/packages/xdc/rov/support/ScalarStructs_xdc.xdt
index e87372e..282a9fa 100644
--- a/src/packages/xdc/rov/support/ScalarStructs_xdc.xdt
+++ b/src/packages/xdc/rov/support/ScalarStructs_xdc.xdt
@@ -9,6 +9,7 @@
* Texas Instruments - initial implementation
*
* --/COPYRIGHT--*/
+%var q = "`";
/*! @_nodoc
* ======== ScalarStructs ========
* Structures used to read scalar types from an arbitrary address
@@ -27,8 +28,8 @@
* @p
*
* As a result, it's possible to use the structures below together with
- * Program.fetchStruct() to fetch scalar values; e.g., the following can
- * be used to read a 32-bit value from address addr:
+ * `q`Program.fetchStruct()`q` to fetch scalar values; e.g., the following can
+ * be used to read a 32-bit value from address `q`addr`q`:
*
* @p(code)
* var v; // value located at address specified by addr
diff --git a/src/packages/xdc/runtime/archdocs/xdc_runtime_arch.rst b/src/packages/xdc/runtime/archdocs/xdc_runtime_arch.rst
index 8deb6e2..a8af23c 100644
--- a/src/packages/xdc/runtime/archdocs/xdc_runtime_arch.rst
+++ b/src/packages/xdc/runtime/archdocs/xdc_runtime_arch.rst
@@ -5,13 +5,15 @@
Revision History
================
-+------------+------------+------------------------------------------+
-| Version | Date | Description |
-+============+============+==========================================+
-| 0.1 | 2/12/2019 | First draft |
-+------------+------------+------------------------------------------+
-| 0.2 | 6/1/2019 | Added internal xdc.runtime.Core material |
-+------------+------------+------------------------------------------+
++------------+------------+-------------------------------------------+
+| Version | Date | Description |
++============+============+===========================================+
+| 0.1 | 2/12/2019 | First draft |
++------------+------------+-------------------------------------------+
+| 0.2 | 6/1/2019 | Added internal xdc.runtime.Core material |
++------------+------------+-------------------------------------------+
+| 0.3 | 1/20/2020 | Added SysMin, Text, and Timestamp content |
++------------+------------+-------------------------------------------+
Introduction
============
@@ -28,7 +30,7 @@
While this document attempts to explain all the key details related to
the xdc.runtime package, certain details are bound to be left out. For
further explanation of such missing details, please refer to
-`RTSCpedia <http://104.154.111.176/docs-tip>`__ and or the source code
+`RTSCpedia <http://rtsc.eclipseprojects.io/docs-tip>`__ and or the source code
of xdc.runtime.
Terms & Abbreviations
@@ -37,7 +39,7 @@
+-------------+-----------------------------------------------------------------------------------------------------------------------------+
| package | A named collection of modules which forms a component |
+-------------+-----------------------------------------------------------------------------------------------------------------------------+
-| module | The RTSC equivalent of a Java of C++ class |
+| module | The RTSC equivalent of a Java or C++ class |
+-------------+-----------------------------------------------------------------------------------------------------------------------------+
| interface | The RTSC equivalent of a Java Class |
+-------------+-----------------------------------------------------------------------------------------------------------------------------+
@@ -51,19 +53,19 @@
Much of the text and organization of this document is derived from the
xdc.runtime documentation maintained in the
-`RTSCpedia <http://104.154.111.176/docs-tip>`__ - a wiki provided by
+`RTSCpedia <http://rtsc.eclipseprojects.io/docs-tip>`__ - a wiki provided by
`eclipse.org <https://www.eclipse.org/>`__ as part of the `Eclipse RTSC
project <https://projects.eclipse.org/projects/technology.rtsc>`__.
-+------+---------------------------------------------------------------------------------------+---------------+
-| # | Title | Author |
-+------+---------------------------------------------------------------------------------------+---------------+
-| 1. | `XDCtools User's Guide <http://104.154.111.176/docs-tip/XDCtools_User%27s_Guide>`__ | David Russo |
-+------+---------------------------------------------------------------------------------------+---------------+
-| 2. | `RTSC Glossary <http://104.154.111.176/docs-tip/Glossary>`__ | David Russo |
-+------+---------------------------------------------------------------------------------------+---------------+
-| 3. | `RTSC Bibliography <http://104.154.111.176/docs-tip/Bibliography>`__ | David Russo |
-+------+---------------------------------------------------------------------------------------+---------------+
++------+-----------------------------------------------------------------------------------------------+---------------+
+| # | Title | Author |
++------+-----------------------------------------------------------------------------------------------+---------------+
+| 1. | `XDCtools User's Guide <http://rtsc.eclipseprojects.io/docs-tip/XDCtools_User%27s_Guide>`__ | David Russo |
++------+-----------------------------------------------------------------------------------------------+---------------+
+| 2. | `RTSC Glossary <http://rtsc.eclipseprojects.io/docs-tip/Glossary>`__ | David Russo |
++------+-----------------------------------------------------------------------------------------------+---------------+
+| 3. | `RTSC Bibliography <http://rtsc.eclipseprojects.io/docs-tip/Bibliography>`__ | David Russo |
++------+-----------------------------------------------------------------------------------------------+---------------+
xdc.runtime Package
===================
@@ -101,7 +103,7 @@
In addition to the services above, the xdc.runtime package provides
low-level "internal" machine interface that supports the `RTSC
Interface Definition
-Language <http://104.154.111.176/docs-tip/Glossary#RTSC_IDL>`__
+Language <http://rtsc.eclipseprojects.io/docs-tip/Glossary#RTSC_IDL>`__
(IDL) compiler. This IDL allows module developer to formally specify
the interface of a module in a C-like declarative language, and the
compiler generates both C and JavaScript "stubs" that reference
@@ -187,7 +189,7 @@
suitable for virtually any embedded application. In particular, it
includes a single module, Memory that supports
-- multiple heaps and allows each heap to manage its heap in a
+- multiple heaps and allows each heap to manage its memory in a
memory-specific or application-specific manner;
- aligned allocations on any boundary supported by the underlying
@@ -205,19 +207,19 @@
The xdc.runtime package contains several modules that work together
to provide modular and extensible memory management support. This
support is centered on the
-`Memory <http://104.154.111.176/cdoc-tip/index.html#xdc/runtime/Memory.html>`__
+`Memory <http://rtsc.eclipseprojects.io/cdoc-tip/index.html#xdc/runtime/Memory.html>`__
module that enables the application to allocate and free memory. All
memory allocations are eventually "handled" by a module that
implements the
-`IHeap <http://104.154.111.176/cdoc-tip/index.html#xdc/runtime/IHeap.html>`__
+`IHeap <http://rtsc.eclipseprojects.io/cdoc-tip/index.html#xdc/runtime/IHeap.html>`__
interface. These modules are responsible for managing a region of
memory in a manner appropriate for the application.
Two such modules are provided in the xdc.runtime package:
-1. `HeapMin <http://104.154.111.176/cdoc-tip/index.html#xdc/runtime/HeapMin.html>`__ - a module that simply maintains a "high water" mark for each managed memory block and never frees memory, and
+1. `HeapMin <http://rtsc.eclipseprojects.io/cdoc-tip/index.html#xdc/runtime/HeapMin.html>`__ - a module that simply maintains a "high water" mark for each managed memory block and never frees memory, and
-2. `HeapStd <http://104.154.111.176/cdoc-tip/index.html#xdc/runtime/HeapStd.html>`__ - a module that uses the ANSI C standard library functions ``malloc()`` and ``free()``.
+2. `HeapStd <http://rtsc.eclipseprojects.io/cdoc-tip/index.html#xdc/runtime/HeapStd.html>`__ - a module that uses the ANSI C standard library functions ``malloc()`` and ``free()``.
While it is possible to create new implementations of the IHeap
interface that provide more sophisticated or even
@@ -234,9 +236,9 @@
is specified by the developer by setting the Memory module's
defaultHeapInstance configuration parameter. If this parameter is
not explicitly set by the developer, an instance of
-`xdc.runtime.HeapStd <http://104.154.111.176/cdoc-tip/index.html#xdc/runtime/HeapStd.html>`__
+`xdc.runtime.HeapStd <http://rtsc.eclipseprojects.io/cdoc-tip/index.html#xdc/runtime/HeapStd.html>`__
(of size
-`Memory.defaultHeapSize <http://104.154.111.176/cdoc-tip/index.html#xdc/runtime/Memory.html#default.Heap.Size>`__)
+`Memory.defaultHeapSize <http://rtsc.eclipseprojects.io/cdoc-tip/index.html#xdc/runtime/Memory.html#default.Heap.Size>`__)
will be assigned to this parameter.
|image1|
@@ -287,10 +289,10 @@
xdc.runtime modules is updated "atomically". The xdc.runtime package
atomically updates global data by always "entering the System gate"
(via
-`Gate\_enterSystem() <http://104.154.111.176/cdoc-tip/index.html#xdc/runtime/Gate.html#enter.System>`__)
+`Gate\_enterSystem() <http://rtsc.eclipseprojects.io/cdoc-tip/index.html#xdc/runtime/Gate.html#enter.System>`__)
prior to accessing the global data and "leaving the System gate"
(via
-`Gate\_leaveSystem() <http://104.154.111.176/cdoc-tip/index.html#xdc/runtime/Gate.html#leave.System>`__)
+`Gate\_leaveSystem() <http://rtsc.eclipseprojects.io/cdoc-tip/index.html#xdc/runtime/Gate.html#leave.System>`__)
once the update is complete.
While gates make it easy to protect shared data structures and
@@ -336,14 +338,14 @@
The xdc.runtime package contains modules that work together to
provide support for serializing access to shared data structures.
This section focuses on the
-`Gate <http://104.154.111.176/cdoc-tip/index.html#xdc/runtime/Gate.html>`__
+`Gate <http://rtsc.eclipseprojects.io/cdoc-tip/index.html#xdc/runtime/Gate.html>`__
module which is used to "enter" and "leave" critical sections of
code that access shared data.
Use of this module is illustrated by a series of examples that take
advantage of one other distinguished xdc.runtime module:
-- `GateNull <http://104.154.111.176/cdoc-tip/index.html#xdc/runtime/GateNull.html>`__ - a module that is used to eliminate unnecessary serialization
+- `GateNull <http://rtsc.eclipseprojects.io/cdoc-tip/index.html#xdc/runtime/GateNull.html>`__ - a module that is used to eliminate unnecessary serialization
overhead for those situations where data is known to be accessed
by one thread at a time; e.g., in single threaded systems or for
modules that are known to be used by just one thread in a
@@ -352,7 +354,7 @@
Obviously the most interesting examples will require a "real" gate;
i.e., one that serializes access to a shared data structure in a
multi-threaded application. `Extending xdc.runtime
-Gates <http://104.154.111.176/docs-tip/Extending_xdc.runtime_Gates>`__
+Gates <http://rtsc.eclipseprojects.io/docs-tip/Extending_xdc.runtime_Gates>`__
provides an example that uses `posix
mutexes <http://pubs.opengroup.org/onlinepubs/9699919799/>`__ and
illustrates how, using services commonly provided by an RTOS, the
@@ -370,7 +372,7 @@
Any module may declare that it is
-"`gated <http://104.154.111.176/docs-tip/Glossary#GatedModule>`__";
+"`gated <http://rtsc.eclipseprojects.io/docs-tip/Glossary#GatedModule>`__";
i.e., that the module protects internal data shared among multiple
threads in the system via an xdc.runtime.Gate instance. Gated
modules always have at least one gate instance created implicitly.
@@ -379,7 +381,7 @@
configuration parameter during configuration.
Modules enter and leave gates via the methods provided by the
-`xdc.runtime.Gate <http://104.154.111.176/cdoc-tip/index.html#xdc/runtime/Gate.html>`__
+`xdc.runtime.Gate <http://rtsc.eclipseprojects.io/cdoc-tip/index.html#xdc/runtime/Gate.html>`__
module. This Gate module provides methods that enable modules to
enter (and leave) their gate as well as dynamically create and
delete gates associated with their instance objects. Users of gated
@@ -392,11 +394,11 @@
In addition to the services provided to implement thread-safe
modules, the Gate module also provides access to the distinguished
"System gate" via
-`Gate\_enterSystem() <http://104.154.111.176/cdoc-tip/index.html#xdc/runtime/Gate.html#enter.System>`__
+`Gate\_enterSystem() <http://rtsc.eclipseprojects.io/cdoc-tip/index.html#xdc/runtime/Gate.html#enter.System>`__
and
-`Gate\_leaveSystem <http://104.154.111.176/cdoc-tip/index.html#xdc/runtime/Gate.html#leave.System>`__.
+`Gate\_leaveSystem <http://rtsc.eclipseprojects.io/cdoc-tip/index.html#xdc/runtime/Gate.html#leave.System>`__.
In fact, this System gate is the gate associated with the gated
-`xdc.runtime.System <http://104.154.111.176/cdoc-tip/index.html#xdc/runtime/System.html>`__
+`xdc.runtime.System <http://rtsc.eclipseprojects.io/cdoc-tip/index.html#xdc/runtime/System.html>`__
module. This one gate is used throughout the xdc.runtime package to
serialize access to global data and it's only used when the duration
of the critical section is known to be *deterministic and very
@@ -485,26 +487,28 @@
controlled in real-time within deployed systems. This section
focuses on those modules that are used to generate "events",
enable/disable their generation, and display the events:
-`Log <http://104.154.111.176/cdoc-tip/index.html#xdc/runtime/Log.html>`__,
-`Diags <http://104.154.111.176/cdoc-tip/index.html#xdc/runtime/Diags.html>`__,
+`Log <http://rtsc.eclipseprojects.io/cdoc-tip/index.html#xdc/runtime/Log.html>`__,
+`Diags <http://rtsc.eclipseprojects.io/cdoc-tip/index.html#xdc/runtime/Diags.html>`__,
and
-`LoggerSys <http://104.154.111.176/cdoc-tip/index.html#xdc/runtime/LoggerSys.html>`__,
+`LoggerSys <http://rtsc.eclipseprojects.io/cdoc-tip/index.html#xdc/runtime/LoggerSys.html>`__,
respectively.
Use of these modules is illustrated by a series of examples that
take advantage of two other distinguished xdc.runtime modules:
-1. `Main <http://104.154.111.176/cdoc-tip/index.html#xdc/runtime/Main.html>`__
+1. `Main <http://rtsc.eclipseprojects.io/cdoc-tip/index.html#xdc/runtime/Main.html>`__
- a module whose configuration applies to all code that is *not* a RTSC
module; e.g., existing C code bases, and
-2. `Defaults <http://104.154.111.176/cdoc-tip/index.html#xdc/runtime/Defaults.html>`__
+2. `Defaults <http://rtsc.eclipseprojects.io/cdoc-tip/index.html#xdc/runtime/Defaults.html>`__
- a module whose configuration applies to all RTSC modules (including Main),
unless explicitly overridden on a per-module basis.
Architecture
------------
+Loggers
+~~~~~~~
For the purpose of logging, *every line* of code in an application
is treated as being part of some RTSC module. All code falls into
one of three classes:
@@ -513,23 +517,23 @@
2. code that is part of a dynamically registered module. Code can
dynamically register itself as a module through the
- `xdc.runtime.Registry <http://104.154.111.176/cdoc-tip/index.html#xdc/runtime/Registry.html>`__
+ `xdc.runtime.Registry <http://rtsc.eclipseprojects.io/cdoc-tip/index.html#xdc/runtime/Registry.html>`__
module.
3. all other code. Any code that is not part of a RTSC module or a
registered module is considered to be part of the distinguished
- `xdc.runtime.Main <http://104.154.111.176/cdoc-tip/index.html#xdc/runtime/Main.html>`__
+ `xdc.runtime.Main <http://rtsc.eclipseprojects.io/cdoc-tip/index.html#xdc/runtime/Main.html>`__
module.
All RTSC target modules, including
-`xdc.runtime.Main <http://104.154.111.176/cdoc-tip/index.html#xdc/runtime/Main.html>`__,
+`xdc.runtime.Main <http://rtsc.eclipseprojects.io/cdoc-tip/index.html#xdc/runtime/Main.html>`__,
have a
- current "event mask" - a set of event categories that are enabled for
the module,
- an optional
- `ILogger <http://104.154.111.176/cdoc-tip/index.html#xdc/runtime/ILogger.html>`__
+ `ILogger <http://rtsc.eclipseprojects.io/cdoc-tip/index.html#xdc/runtime/ILogger.html>`__
service provider - a module that handles events generated by the
module, and
@@ -539,9 +543,9 @@
required string name.
The
-`Log\_print <http://104.154.111.176/cdoc-tip/index.html#xdc/runtime/Log.html#print6>`__
+`Log\_print <http://rtsc.eclipseprojects.io/cdoc-tip/index.html#xdc/runtime/Log.html#print6>`__
or
-`Log\_write <http://104.154.111.176/cdoc-tip/index.html#xdc/runtime/Log.html#write8>`__
+`Log\_write <http://rtsc.eclipseprojects.io/cdoc-tip/index.html#xdc/runtime/Log.html#write8>`__
methods are used to generate or log "events". These methods are
simply in-line macros that conditionally invoke the calling module's
underlying ILogger service provider to "handle" the events. This
@@ -555,7 +559,7 @@
The initial value of a module's event mask is specified during
configuration and may be changed at runtime via
-`Diags\_setMask() <http://104.154.111.176/cdoc-tip/index.html#xdc/runtime/Diags.html#set.Mask>`__.
+`Diags\_setMask() <http://rtsc.eclipseprojects.io/cdoc-tip/index.html#xdc/runtime/Diags.html#set.Mask>`__.
Beyond the parameters passed to Log\_print (or Log\_write), the id
of the module that called Log\_print (or Log\_write) is communicated
@@ -567,14 +571,14 @@
Two ILogger service providers are included in the xdc.runtime
package:
-1. `LoggerBuf <http://104.154.111.176/cdoc-tip/index.html#xdc/runtime/LoggerBuf.html>`__
+1. `LoggerBuf <http://rtsc.eclipseprojects.io/cdoc-tip/index.html#xdc/runtime/LoggerBuf.html>`__
- copies events to a circular buffer in a fixed small number of
cycles and is suitable for real-time high-frequency event
sources, and
-2. `LoggerSys <http://104.154.111.176/cdoc-tip/index.html#xdc/runtime/LoggerSys.html>`__
+2. `LoggerSys <http://rtsc.eclipseprojects.io/cdoc-tip/index.html#xdc/runtime/LoggerSys.html>`__
- outputs events as they occur using
- `System\_printf() <http://104.154.111.176/cdoc-tip/index.html#xdc/runtime/System.html#printf>`__
+ `System\_printf() <http://rtsc.eclipseprojects.io/cdoc-tip/index.html#xdc/runtime/System.html#printf>`__
and is suitable for initial development or low-rate non-real-time
event sources.
@@ -583,7 +587,7 @@
of course, filter events and call LoggerBuf or LoggerSys. For
information about creating and deploying a custom logger see
`Extending xdc.runtime
-Logging <http://104.154.111.176/docs-tip/Extending_xdc.runtime_Logging>`__.
+Logging <http://rtsc.eclipseprojects.io/docs-tip/Extending_xdc.runtime_Logging>`__.
As part of an application's configuration step, developers "bind"
zero or more ILogger service providers to the modules that comprise
@@ -592,6 +596,76 @@
Events generated by modules *without* an ILogger service provider
are silently ignored.
+Timestamps
+~~~~~~~~~~
+
+.. Requirement
+ | REQ_TAG(SYSBIOS-881), REQ_TAG(SYSBIOS-882), REQ_TAG(SYSBIOS-883)
+ | REQ_TAG(SYSBIOS-884), REQ_TAG(SYSBIOS-885)
+
+By definition, real-time systems require some means to track and
+measure elapsed time. However, different systems use very different
+methods. Some systems leverage platform-specific timer peripherals
+while others use application-specific data streams that are known to
+produce data at a fixed rate (i.e., telephony TDM data). The choice of
+how to measure time is application and platform specific, so it is
+important that the timer services provided by xdc.runtime enable the
+system integrator to specify an appropriate time source.
+
+In addition to variations in how time is measured, different
+applications have very different precision and range
+requirements. Applications that only require millisecond precision
+often don't require more than 32-bits of range (almost 50 days),
+whereas measurements used to causally relate events in a multi-core
+system requires near nanosecond precision (yielding less than 5
+seconds of range from a 32-bit value). In fact, it is not unusual for
+a single application to require more than one timer with different
+precision and range requirements.
+
+The xdc.runtime package contains several modules that need timestamps;
+e.g., LoggerBuf and LoggerSys. These modules obtain timestamps from
+other modules that implement the xdc.runtime.ITimestampProvider
+interface. Two such modules are provided in the xdc.runtime package:
+
+1. `TimestampNull <http://rtsc.eclipseprojects.io/cdoc-tip/index.html#xdc/runtime/TimestampNull.html>`__
+ - a timestamp provider that always returns a timestamp of 0, and
+
+2. `TimestampStd <http://rtsc.eclipseprojects.io/cdoc-tip/index.html#xdc/runtime/TimestampStd.html>`__
+ - a timestamp provider that uses the ANSI C Standard Library function clock() to obtain timestamps.
+
+The xdc.runtime.Timestamp module provides a platform-independent
+interface that is sufficient for simple timestamping needs. This
+module makes use of platform-specific implementations which can take
+advantage of underlying hardware support, for example. Rather than
+define a single "provider" interface that is sufficient for the needs
+of the Timestamp module, the xdc.runtime package defines two
+interfaces:
+
+1. `ITimestampClient <http://rtsc.eclipseprojects.io/cdoc-tip/index.html#xdc/runtime/ITimestampClient.html>`__
+ - defines the platform-independent interface provided by Timestamp, and
+
+2. `ITimestampProvider <http://rtsc.eclipseprojects.io/cdoc-tip/index.html#xdc/runtime/ITimestampProvider.html>`__
+ - defines the interface provided by platform-specific implementations and inherits from ITimestampClient
+
+While it may seem odd that underlying timestamp provider
+implementations must implement the same interface as ITimestampClient,
+this design enables applications to call timestamp providers directly,
+when necessary, to leverage platform-specific capabilities. Suppose
+there is device specific timestamp provider, say Timestamp64, that
+provides additional methods that put an underlying timer into special
+low-power modes. Since this Timestamp64 module must implement
+ITimestampClient (because ITimestampProvider inherits from
+ITimestampClient), developers that need to leverage the low-power
+functionality can mechanically replace existing calls to Timestamp
+methods with calls to Timestamp64 methods and be sure the application
+will continue to function properly. The figure below illustrates the
+relationship between the the various timestamp interfaces and modules
+provided by xdc.runtime as well as this hypothetical Timestamp64
+timestamp.
+
+|RuntimeTime|
+
+
Real-Time Diagnostics: Error Handling
=====================================
@@ -615,19 +689,19 @@
controlled in real-time within deployed systems. This section
focuses on those modules that are used to raise and handle errors
and provide assertion support:
-`Error <http://104.154.111.176/cdoc-tip/index.html#xdc/runtime/Error.html>`__
+`Error <http://rtsc.eclipseprojects.io/cdoc-tip/index.html#xdc/runtime/Error.html>`__
and
-`Assert <http://104.154.111.176/cdoc-tip/index.html#xdc/runtime/Assert.html>`__,
+`Assert <http://rtsc.eclipseprojects.io/cdoc-tip/index.html#xdc/runtime/Assert.html>`__,
respectively.
Use of these modules is illustrated by a series of examples that
take advantage of two other distinguished xdc.runtime modules:
-1. `Main <http://104.154.111.176/cdoc-tip/index.html#xdc/runtime/Main.html>`__
+1. `Main <http://rtsc.eclipseprojects.io/cdoc-tip/index.html#xdc/runtime/Main.html>`__
- a module whose configuration applies to all code that is *not*
a RTSC module; e.g., existing C code bases, and
-2. `Defaults <http://104.154.111.176/cdoc-tip/index.html#xdc/runtime/Defaults.html>`__
+2. `Defaults <http://rtsc.eclipseprojects.io/cdoc-tip/index.html#xdc/runtime/Defaults.html>`__
- a module whose configuration applies to all RTSC modules
(including Main), unless explicitly overridden on a per-module
basis.
@@ -657,7 +731,7 @@
second category is managed by the Assert module. Rather than use
simple fixed-length error numbers, the xdc.runtime package uniformly
employs an opaque Error\_Block structure to "raise" errors via
-`Error\_raise() <http://104.154.111.176/cdoc-tip/index.html#xdc/runtime/Error.html#raise>`__.
+`Error\_raise() <http://rtsc.eclipseprojects.io/cdoc-tip/index.html#xdc/runtime/Error.html#raise>`__.
Functions that raise errors are passed a pointer to an Error\_Block
structure which is passed to Error\_raise() when an error is
detected. When an error is raised, the Error\_Block structure
@@ -686,11 +760,92 @@
assertions remain in the final application, if any.
When an assertion violation is detected, an
-`Assert.E\_assertFailed <http://104.154.111.176/cdoc-tip/index.html#xdc/runtime/Assert.html#/.E_assert/.Failed>`__
+`Assert.E\_assertFailed <http://rtsc.eclipseprojects.io/cdoc-tip/index.html#xdc/runtime/Assert.html#/.E_assert/.Failed>`__
error is raised (via Error\_raise()) with a NULL Error\_Block
reference; so, assertions are handled using the same error handling
hooks as "normal" errors.
+Real-Time Diagnostics: Text
+===========================
+
+Functional Goals
+----------------
+Adding "printf-like" statements to a C code base not only increases
+code space (the instructions to put arguments in registers and call a
+function) but it can significantly increase an application's data
+space requirements; each "printf-like" format string is added to a
+data section reserved for constants and the size of section can grow
+quickly as more and more logging statements are added. While it's not
+possible to stop the strings used in Log_print() statements from
+taking up space in the target, it is possible to completely eliminate
+the
+
+ * format strings by used by Log_write(),
+ * error messages emitted by Error_raise(), and
+ * assertion messages triggered by Assert_isTrue()
+
+Since each of these strings is declared in the RTSC specification,
+it's possible to sequester these strings into a compressed table that
+*does not* be loaded on to the embedded system for normal operation.
+These statically declared strings can be "encoded" into a single
+32-bit quantity that encodes _references_ to both the string itself
+and where the string is defined. These references can be interpreted
+by a host computer to display to the user the complete message while
+the embedded system can enjoy the benefits of detailed tracing and
+understandable error messages produced deterministically and with
+small footprint.
+
+While the logger architecture enables deterministic execution time for
+logging, there is a need to also minimize the overall footprint
+overhad for these diagnostics.
+
+Architecture
+------------
+
+.. Requirement
+ | REQ_TAG(SYSBIOS-886), REQ_TAG(SYSBIOS-887), REQ_TAG(SYSBIOS-888)
+ | REQ_TAG(SYSBIOS-889), REQ_TAG(SYSBIOS-890), REQ_TAG(SYSBIOS-891)
+ | REQ_TAG(SYSBIOS-892), REQ_TAG(SYSBIOS-893), REQ_TAG(SYSBIOS-894)
+ | REQ_TAG(SYSBIOS-895), REQ_TAG(SYSBIOS-896), REQ_TAG(SYSBIOS-897)
+ | REQ_TAG(SYSBIOS-898)
+
+In lieu of a mask and a format string as initial arguments,
+Log_write() takes a Log_Event. A Log_Event is an opaque reference to a
+structure that contains a mask and a format string. How does this
+help? By eliminating direct references to literal strings in the C
+sources, the C compiler only sees an integer index being passed to
+Log_write() and never needs to allocate space for the constant format
+string. During configuration, it's possible to generate a table of all
+Log_Event format strings, define Log_Event as an index into this
+table, and arrange for this table to loaded in a separate output
+section. Since this table is only needed when the event is "decoded",
+the table (with the strings) does not need to be loaded into the
+target's memory; events can be decoded by host-based development tools
+which simply lookup the event based on the index supplied by
+Log_write().
+
+The Error and Assert modules follow a similar pattern and *all*
+"event" strings are included in a single table that is created
+and managed by the `xdc.runtime.Text <http://rtsc.eclipseprojects.io/cdoc-tip/index.html#xdc/runtime/Text.html>`__ module.
+
+To eliminate the runtime strings you must configure the Text module to
+place all strings in a special section that will not be loaded onto
+the target.
+
+.. code-block:: c
+ :linenos:
+
+ var Text = xdc.module("xdc.runtime.Text");
+ Text.isLoaded = false;
+
+In addtion to providing the ability to remove the many of the static
+strings from the embeded application's runtime image, the Text module
+provides a functional interface used in the implementation of other
+module's to generate output buffers with the fully qualified names of
+any module in the system using a 16-bit Id; e.g., the single 37 byte
+string ``"ti/sysbios/family/arm/a15/smp/Cache"`` is represented by just 2
+bytes on the target.
+
System Services
===============
@@ -723,9 +878,9 @@
support module with an implementation appropriate for the new
execution environment; no change to the application's sources are
required and, if you're porting between
-`platforms <http://104.154.111.176/docs-tip/Glossary#PlatformDefinition>`__
+`platforms <http://rtsc.eclipseprojects.io/docs-tip/Glossary#PlatformDefinition>`__
with the same
-`target <http://104.154.111.176/docs-tip/Glossary#TargetDefinition>`__,
+`target <http://rtsc.eclipseprojects.io/docs-tip/Glossary#TargetDefinition>`__,
no recompilation is required.
Architecture Introduction
@@ -735,11 +890,11 @@
the minimal set of services necessary to enable modular application
startup and shutdown as well as basic message display.
-1. `Startup <http://104.154.111.176/cdoc-tip/index.html#xdc/runtime/Startup.html>`__
+1. `Startup <http://rtsc.eclipseprojects.io/cdoc-tip/index.html#xdc/runtime/Startup.html>`__
- a module that provides a framework for the orderly
initialization of modules *prior* to main(), and
-2. `System <http://104.154.111.176/cdoc-tip/index.html#xdc/runtime/System.html>`__
+2. `System <http://rtsc.eclipseprojects.io/cdoc-tip/index.html#xdc/runtime/System.html>`__
- a module that provides exit handling similar to the ANSI C
atexit() mechanism as well as basic printf() message output.
@@ -747,11 +902,11 @@
one of two other distinguished xdc.runtime modules that provide the
"back end" support functions required by the System module:
-1. `SysMin <http://104.154.111.176/cdoc-tip/index.html#xdc/runtime/SysMin.html>`__
+1. `SysMin <http://rtsc.eclipseprojects.io/cdoc-tip/index.html#xdc/runtime/SysMin.html>`__
- a self-contained module appropriate for deeply embedded
applications or early system development, and
-2. `SysStd <http://104.154.111.176/cdoc-tip/index.html#xdc/runtime/SysStd.html>`__
+2. `SysStd <http://rtsc.eclipseprojects.io/cdoc-tip/index.html#xdc/runtime/SysStd.html>`__
- a module that relies on standard ANSI C runtime library
functions such as putchar() and fflush() and is appropriate for
systems with an already functional ANSI C Standard I/O library.
@@ -771,7 +926,7 @@
registers necessary to initialize the module's internal data
structures, for example. Modules specify that they have startup
functions via the
-`@ModuleStartup <http://104.154.111.176/docs-tip/XDCspec_-_%40ModuleStartup>`__
+`@ModuleStartup <http://rtsc.eclipseprojects.io/docs-tip/XDCspec_-_%40ModuleStartup>`__
attribute in their module specification file. The Startup module
runs these startup functions prior to the application's main() entry
point and provides numerous configuration parameters to enable the
@@ -822,18 +977,18 @@
initialization to, at a minimum, setup a C call stack.
2. Run user-supplied reset function (see
- `Startup.resetFxn <http://104.154.111.176/cdoc-tip/index.html#xdc/runtime/Startup.html#reset/.Fxn>`__).
+ `Startup.resetFxn <http://rtsc.eclipseprojects.io/cdoc-tip/index.html#xdc/runtime/Startup.html#reset/.Fxn>`__).
3. Perform additional target-specific initialization to a complete C
execution environment for subsequent steps.
4. Run user-supplied "first functions" (See
- `Startup.firstFxns <http://104.154.111.176/cdoc-tip/index.html#xdc/runtime/Startup.html#first/.Fxns>`__).
+ `Startup.firstFxns <http://rtsc.eclipseprojects.io/cdoc-tip/index.html#xdc/runtime/Startup.html#first/.Fxns>`__).
5. Run all module initialization functions.
6. Run user-supplied last functions (See
- `Startup.lastFxns <http://104.154.111.176/cdoc-tip/index.html#xdc/runtime/Startup.html#last/.Fxns>`__).
+ `Startup.lastFxns <http://rtsc.eclipseprojects.io/cdoc-tip/index.html#xdc/runtime/Startup.html#last/.Fxns>`__).
7. Call main().
@@ -865,15 +1020,15 @@
Specific information about each environment's startup sequence is
provided by the topics indexed in the table below.
-+----------------------+-------------------------------------------------------------------------------------------------------------------------+
-| **Target Family** | **Detailed Boot Sequence Information** |
-+======================+=========================================================================================================================+
-| TI | `TI Compiler Runtime Startup Sequence <http://104.154.111.176/docs-tip/Using_xdc.runtime_Startup/TI>`__ |
-+----------------------+-------------------------------------------------------------------------------------------------------------------------+
-| Gnu Unix | `GNU Native Compiler Runtime Startup Sequence <http://104.154.111.176/docs-tip/Using_xdc.runtime_Startup/GNU>`__ |
-+----------------------+-------------------------------------------------------------------------------------------------------------------------+
-| Microsoft | `Microsoft Compiler Runtime Startup Sequence <http://104.154.111.176/docs-tip/Using_xdc.runtime_Startup/Microsoft>`__ |
-+----------------------+-------------------------------------------------------------------------------------------------------------------------+
++----------------------+---------------------------------------------------------------------------------------------------------------------------------+
+| **Target Family** | **Detailed Boot Sequence Information** |
++======================+=================================================================================================================================+
+| TI | `TI Compiler Runtime Startup Sequence <http://rtsc.eclipseprojects.io/docs-tip/Using_xdc.runtime_Startup/TI>`__ |
++----------------------+---------------------------------------------------------------------------------------------------------------------------------+
+| Gnu Unix | `GNU Native Compiler Runtime Startup Sequence <http://rtsc.eclipseprojects.io/docs-tip/Using_xdc.runtime_Startup/GNU>`__ |
++----------------------+---------------------------------------------------------------------------------------------------------------------------------+
+| Microsoft | `Microsoft Compiler Runtime Startup Sequence <http://rtsc.eclipseprojects.io/docs-tip/Using_xdc.runtime_Startup/Microsoft>`__ |
++----------------------+---------------------------------------------------------------------------------------------------------------------------------+
Module Initialization
~~~~~~~~~~~~~~~~~~~~~
@@ -881,7 +1036,7 @@
Every module can optionally define a startup function which is
called before main(). Modules declare that they want to participate
in this startup sequence via the
-`@ModuleStartup <http://104.154.111.176/docs-tip/XDCspec_-_%40ModuleStartup>`__
+`@ModuleStartup <http://rtsc.eclipseprojects.io/docs-tip/XDCspec_-_%40ModuleStartup>`__
attribute in the module's spec file. Modules that use this attribute
must also implement the following startup function:
@@ -897,7 +1052,7 @@
value other than Startup\_DONE, it will be called in a subsequent
pass with this return value passed in as state. To ensure this
process terminates, no startup function is ever called more than
-`Startup.maxPasses <http://104.154.111.176/cdoc-tip/index.html#xdc/runtime/Startup.html#max/.Passes>`__
+`Startup.maxPasses <http://rtsc.eclipseprojects.io/cdoc-tip/index.html#xdc/runtime/Startup.html#max/.Passes>`__
times.
For situations in which the startup of one module depends upon
@@ -966,10 +1121,10 @@
depending on the product and stage of development, the System module
relies on a user supplied module that implements these very basic
functions (defined by the
-`ISystemSupport <http://104.154.111.176/cdoc-tip/index.html#xdc/runtime/ISystemSupport.html>`__
+`ISystemSupport <http://rtsc.eclipseprojects.io/cdoc-tip/index.html#xdc/runtime/ISystemSupport.html>`__
interface). Developers specify the module that implements these
functions by setting the
-`System.SupportProxy <http://104.154.111.176/cdoc-tip/index.html#xdc/runtime/System.html#.Support.Proxy>`__
+`System.SupportProxy <http://rtsc.eclipseprojects.io/cdoc-tip/index.html#xdc/runtime/System.html#.Support.Proxy>`__
configuration parameter.
|image4|
@@ -992,11 +1147,51 @@
|image5|
+SysMin
+^^^^^^
+
+.. Requirement
+ | REQ_TAG(SYSBIOS-913), REQ_TAG(SYSBIOS-914), REQ_TAG(SYSBIOS-915)
+ | REQ_TAG(SYSBIOS-916), REQ_TAG(SYSBIOS-917), REQ_TAG(SYSBIOS-918)
+ | REQ_TAG(SYSBIOS-919), REQ_TAG(SYSBIOS-920)
+
+The SysStd module uses putchar() and fflush() for basic character output.
+However, SysMin simply copies characters to a pre-configured static buffer
+for character output and provides a configuration parameter that allows you
+to specify how these characters are output when System_flush() is called. As
+a result, SysMin can be used in applications that need to avoid all
+references to the ANSI C Standard Library I/O functions.
+
+With the exception of exit(), atexit(), and abort(), the System module does
+not directly reference any ANSI C Standard Library functions; any other
+references are the result of the System module's supporting module
+System.SupportProxy. If the System.SupportProxy configuration parameter is
+not set, it defaults to SysMin.
+
+By default, the SysMin support module will call fwrite() to output characters
+written to its internal buffer. To eliminate this reference, it is sufficient
+to define your own output function, say myOutputFxn, and set SysMin.outputFxn
+to reference this function.
+
+.. code-block:: c
+ :linenos:
+
+ var System = xdc.useModule("xdc.runtime.System");
+ var SysMin = xdc.useModule("xdc.runtime.SysMin");
+ SysMin.outputFxn = "&myOutputFxn";
+ System.SupportProxy = SysMin; /* not really necessary since this is the default */
+
+Of course there may be other reasons why the use of SysMin is not
+appropriate. For example, you may want to output characters at the time they
+are generated rather than buffering them. In this case, you'll need to create
+your own ISystemProvider module. For information about how to create a new
+ISystemProvider module see Extending xdc.runtime System.
+
System Concurrency support
~~~~~~~~~~~~~~~~~~~~~~~~~~
The System module is a `gated
-module <http://104.154.111.176/docs-tip/Glossary#GatedModule>`__.
+module <http://rtsc.eclipseprojects.io/docs-tip/Glossary#GatedModule>`__.
The gate associated with the System module, also called the "System
gate", is a used for two purposes:
@@ -1004,18 +1199,18 @@
serializing concurrent accesses to global data; and
2. to protect small critical regions within the application via the
- `Gate\_enterSystem() <http://104.154.111.176/cdoc-tip/index.html#xdc/runtime/Gate.html#enter.System>`__
+ `Gate\_enterSystem() <http://rtsc.eclipseprojects.io/cdoc-tip/index.html#xdc/runtime/Gate.html#enter.System>`__
and
- `Gate\_leaveSystem() <http://104.154.111.176/cdoc-tip/index.html#xdc/runtime/Gate.html#leave.System>`__
+ `Gate\_leaveSystem() <http://rtsc.eclipseprojects.io/cdoc-tip/index.html#xdc/runtime/Gate.html#leave.System>`__
APIs.
|image6|
For more information about using the xdc.runtime package in
multi-threaded applications, see `Multi-Threading
-Support <http://104.154.111.176/docs-tip/Working_with_xdc.runtime#Multi-Threading_Support>`__.
+Support <http://rtsc.eclipseprojects.io/docs-tip/Working_with_xdc.runtime#Multi-Threading_Support>`__.
`Using xdc.runtime
-Gates <http://104.154.111.176/docs-tip/Using_xdc.runtime_Gates>`__
+Gates <http://rtsc.eclipseprojects.io/docs-tip/Using_xdc.runtime_Gates>`__
contains more details about gates, how to protect shared data
structures using gates, and how to create new gates.
@@ -1067,7 +1262,7 @@
their implementation, minimizing the total application runtime
footprint, and ensuring consistent behavior. Moreover, this design also
enables efficient trace of the lifecycle of any module's instances via
-`Event Logging <#real-time-diagnostics-event-logging>`__.
+`Event Logging <#real\-time-diagnostics-event-logging>`__.
The xdc.runtime.Core module is simple a collection of functions used in
the creation and destruction of *all* module instances. But, this module
@@ -1249,7 +1444,7 @@
However, many similarities exist between this implementation and the
construct/destruct implementation illustrated
-`above <#instance-constructdestruct-support>`__. In fact, the
+`above <#instance-construct-destruct-support>`__. In fact, the
*ModA*\ \_Params\_init() method is identical and is omitted below. The
primary difference between the two forms of instance creation is that
create/delete must handle to case where memory is not available and
@@ -1322,43 +1517,6 @@
ModA_delete(&inst); /* finalize inst */
-[TBD] Timestamp
-===============
-
-Architecture
-------------
-
-.. Requirement
- | REQ_TAG(SYSBIOS-881), REQ_TAG(SYSBIOS-882), REQ_TAG(SYSBIOS-883)
- | REQ_TAG(SYSBIOS-884), REQ_TAG(SYSBIOS-885)
-
-
-[TBD] Text
-==========
-
-Architecture
-------------
-
-.. Requirement
- | REQ_TAG(SYSBIOS-886), REQ_TAG(SYSBIOS-887), REQ_TAG(SYSBIOS-888)
- | REQ_TAG(SYSBIOS-889), REQ_TAG(SYSBIOS-890), REQ_TAG(SYSBIOS-891)
- | REQ_TAG(SYSBIOS-892), REQ_TAG(SYSBIOS-893), REQ_TAG(SYSBIOS-894)
- | REQ_TAG(SYSBIOS-895), REQ_TAG(SYSBIOS-896), REQ_TAG(SYSBIOS-897)
- | REQ_TAG(SYSBIOS-898)
-
-
-[TBD] SysMin
-============
-
-Architecture
-------------
-
-.. Requirement
- | REQ_TAG(SYSBIOS-913), REQ_TAG(SYSBIOS-914), REQ_TAG(SYSBIOS-915)
- | REQ_TAG(SYSBIOS-916), REQ_TAG(SYSBIOS-917), REQ_TAG(SYSBIOS-918)
- | REQ_TAG(SYSBIOS-919), REQ_TAG(SYSBIOS-920)
-
-
.. |image0| image:: ./media/image4.png
:width: 6.48958in
:height: 3.28125in
@@ -1383,3 +1541,6 @@
.. |image7| image:: ./media/image11.png
:width: 5.66667in
:height: 4.20833in
+.. |RuntimeTime| image:: ./media/RuntimeTime.png
+ :width: 5.66667in
+ :height: 4.20833in
\ No newline at end of file
