Merge remote-tracking branch 'origin/xdccore-H-sasha' into master_ggentree
diff --git a/src/packages/xdc/runtime/.gitignore b/src/packages/xdc/runtime/.gitignore
index 4ed2cb2..c191854 100644
--- a/src/packages/xdc/runtime/.gitignore
+++ b/src/packages/xdc/runtime/.gitignore
@@ -35,7 +35,3 @@
 TimestampNull.h
 TimestampStd.h
 Types.h
-
-## don't ignore some of the docs
-!docs/Core.drawio
-!docs/xdc_runtime_arch.docx
diff --git a/src/packages/xdc/runtime/archdocs/Core.drawio b/src/packages/xdc/runtime/archdocs/Core.drawio
new file mode 100644
index 0000000..e36e12d
--- /dev/null
+++ b/src/packages/xdc/runtime/archdocs/Core.drawio
@@ -0,0 +1 @@
+<mxfile modified="2019-06-17T16:14:52.377Z" host="www.draw.io" agent="Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/75.0.3770.90 Safari/537.36" etag="iVPgoTQURSI_kdsiQxo6" version="10.7.7" type="device"><diagram name="Page-1" id="efa7a0a1-bf9b-a30e-e6df-94a7791c09e9">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</diagram></mxfile>
\ No newline at end of file
diff --git a/src/packages/xdc/runtime/archdocs/media/image10.png b/src/packages/xdc/runtime/archdocs/media/image10.png
new file mode 100644
index 0000000..b26ba8a
--- /dev/null
+++ b/src/packages/xdc/runtime/archdocs/media/image10.png
Binary files differ
diff --git a/src/packages/xdc/runtime/archdocs/media/image11.png b/src/packages/xdc/runtime/archdocs/media/image11.png
new file mode 100644
index 0000000..26be2d3
--- /dev/null
+++ b/src/packages/xdc/runtime/archdocs/media/image11.png
Binary files differ
diff --git a/src/packages/xdc/runtime/archdocs/media/image4.png b/src/packages/xdc/runtime/archdocs/media/image4.png
new file mode 100644
index 0000000..d70ba24
--- /dev/null
+++ b/src/packages/xdc/runtime/archdocs/media/image4.png
Binary files differ
diff --git a/src/packages/xdc/runtime/archdocs/media/image5.png b/src/packages/xdc/runtime/archdocs/media/image5.png
new file mode 100644
index 0000000..c306f4d
--- /dev/null
+++ b/src/packages/xdc/runtime/archdocs/media/image5.png
Binary files differ
diff --git a/src/packages/xdc/runtime/archdocs/media/image6.png b/src/packages/xdc/runtime/archdocs/media/image6.png
new file mode 100644
index 0000000..570df02
--- /dev/null
+++ b/src/packages/xdc/runtime/archdocs/media/image6.png
Binary files differ
diff --git a/src/packages/xdc/runtime/archdocs/media/image7.png b/src/packages/xdc/runtime/archdocs/media/image7.png
new file mode 100644
index 0000000..74f9150
--- /dev/null
+++ b/src/packages/xdc/runtime/archdocs/media/image7.png
Binary files differ
diff --git a/src/packages/xdc/runtime/archdocs/media/image8.png b/src/packages/xdc/runtime/archdocs/media/image8.png
new file mode 100644
index 0000000..a2dc0c1
--- /dev/null
+++ b/src/packages/xdc/runtime/archdocs/media/image8.png
Binary files differ
diff --git a/src/packages/xdc/runtime/archdocs/media/image9.png b/src/packages/xdc/runtime/archdocs/media/image9.png
new file mode 100644
index 0000000..41fc23f
--- /dev/null
+++ b/src/packages/xdc/runtime/archdocs/media/image9.png
Binary files differ
diff --git a/src/packages/xdc/runtime/docs/xdc_runtime_arch.docx b/src/packages/xdc/runtime/archdocs/xdc_runtime_arch.docx
similarity index 76%
rename from src/packages/xdc/runtime/docs/xdc_runtime_arch.docx
rename to src/packages/xdc/runtime/archdocs/xdc_runtime_arch.docx
index ea13d40..3b21d7c 100644
--- a/src/packages/xdc/runtime/docs/xdc_runtime_arch.docx
+++ b/src/packages/xdc/runtime/archdocs/xdc_runtime_arch.docx
Binary files differ
diff --git a/src/packages/xdc/runtime/archdocs/xdc_runtime_arch.rst b/src/packages/xdc/runtime/archdocs/xdc_runtime_arch.rst
new file mode 100644
index 0000000..96881cc
--- /dev/null
+++ b/src/packages/xdc/runtime/archdocs/xdc_runtime_arch.rst
@@ -0,0 +1,1310 @@
+========================
+XDC Runtime Architecture
+========================
+
+Revision History
+================
+
++------------+------------+------------------------------------------+
+| Version    | Date       | Description                              |
++============+============+==========================================+
+| 0.1        | 2/12/2019  | First draft                              |
++------------+------------+------------------------------------------+
+| 0.2        | 6/1/2019   | Added internal xdc.runtime.Core material |
++------------+------------+------------------------------------------+
+
+Introduction
+============
+
+Purpose & Scope
+---------------
+
+This document is intended to explain and illustrate the inner workings
+of the xdc.runtime package.
+
+Disclaimer
+----------
+
+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
+of xdc.runtime.
+
+Terms & Abbreviations
+---------------------
+
++-------------+-----------------------------------------------------------------------------------------------------------------------------+
+| package     | A named collection of modules which forms a component                                                                       |
++-------------+-----------------------------------------------------------------------------------------------------------------------------+
+| module      | The RTSC equivalent of a Java of C++ class                                                                                  |
++-------------+-----------------------------------------------------------------------------------------------------------------------------+
+| interface   | The RTSC equivalent of a Java Class                                                                                         |
++-------------+-----------------------------------------------------------------------------------------------------------------------------+
+| RTSC        | Real-Time Software Components - a portable C based component model appropriate for resource constrained embedded systems.   |
++-------------+-----------------------------------------------------------------------------------------------------------------------------+
+| XDCtools    | A collection of host tools for the development of RTSC components                                                           |
++-------------+-----------------------------------------------------------------------------------------------------------------------------+
+
+References
+----------
+
+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
+`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   |
++------+---------------------------------------------------------------------------------------+---------------+
+
+xdc.runtime Package
+===================
+
+Functional Goals
+----------------
+
+The xdc.runtime package contains many low-level modules that work
+together to provide "core" services appropriate for any embedded
+C/C++ application:
+
+-  *memory management*: basic memory allocation and freeing from
+   multiple heaps
+
+-  *concurrency support*: low-level critical region protection
+   mechanisms
+
+-  *real-time diagnostics*: printf-like logging, error management, and
+   assertion support
+
+-  *system services*: system initialization and shutdown (exit(),
+   atexit(), abort(), etc.) and basic character output (printf())
+
+-  *core instance support*: common runtime functions that manage the
+   life-cycle of all instances defined by any module; e.g., support for
+   the static or dynamic creation and deletion of any module's instance
+   objects.
+
+All of these services provide portable C interfaces that are
+appropriate for virtually any 16, 32, and 64-bit embedded
+microprocessor; from highly resource constrained 16-bit CPUs with as
+little as 1K bytes of RAM and 32K bytes of Flash (MSP430F2274) to
+64-bit CPUs with gigabyte address spaces (AM57x).
+
+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>`__
+(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
+implementation functions provided by the module developer.
+
+Architectural Introduction
+--------------------------
+
+The services provided by the xdc.runtime package are partition into
+numerous modules. The relationship between the modules in the
+xdc.runtime package and the services they provide is depicted in the
+figure below.
+
+|image0|
+
+All of the modules and interfaces provided in the xdc.runtime
+package are supplied in portable C source code form. In addition,
+all of the modules are designed to be thread-safe and, where
+necessary, use the Gate module to serialize access to global data
+structures.
+
+In order to ensure platform independence, those modules that require
+platform-specific services are designed to support one (or more)
+platform-specific "service providers". Each of these providers
+implements one of the interfaces supplied. Simple implementations of
+each service provider interface are also included in this package.
+
+Memory Management
+=================
+
+Functional Goals
+----------------
+
+Memory management within embedded systems often requires
+
+-  explicit management of distinct memory "classes";
+
+-  control over alignment of critical buffers;
+
+-  deterministic memory allocation, support for variable length
+   allocation; and in some cases
+
+-  the ability to eliminate *all* runtime allocation and freeing of
+   memory
+
+Explicit use of different "classes" of memory, such as high-speed
+on-chip memory versus bulk external DRAM, is critical for embedded
+real-time applications. For example, careful use and efficient
+management of precious high-speed on-chip memory often determines
+whether an application meets its real-time deadlines or not. Even
+with different classes of memory, to get full entitlement from
+modern CPU cores, it is important that critical buffers be allocated
+on appropriate address boundaries - either for improved cache
+performance or to take advantage of specialized "zero overhead"
+looping constructs.
+
+Different applications have widely differing "policy" requirements.
+For example, traditional embedded applications do not need, nor can
+they afford, extra memory management code to allow the system to
+automatically free memory from a terminated thread. On the other
+hand, some embedded systems allow for the execution of untrusted
+(but not malicious) code. In this case, the robustness requirements
+of the system all but require a memory manager that can track the
+ownership of every allocated memory block. Similarly, because
+real-time applications provide "guaranteed" response times for
+certain events and variable length memory allocators often have
+execution times that vary as a function of the number and size of
+previous allocations, real-time applications generally take one of
+two approaches to dynamic heap memory management:
+
+1. use "fixed size" block allocation algorithms which have deterministic
+   execution times but have poor memory utilization, or
+
+2. use a distinguished "low priority" thread to perform all functions
+   that require memory allocation so the "real-time" threads never
+   stall waiting to allocate or free memory.
+
+From these examples, it's clear that embedded systems have unique
+memory management requirements and that no one memory allocation
+algorithm is appropriate for all embedded applications.
+
+The xdc.runtime package provides core memory management functions
+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
+   memory-specific or application-specific manner;
+
+-  aligned allocations on any boundary supported by the underlying
+   hardware;
+
+-  static placement of buffers required by other modules that create
+   objects at configuration-time; and
+
+-  zero-space-overhead allocations that do not require "allocation
+   header" information to be retained on each allocation.
+
+Architecture Introduction
+-------------------------
+
+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>`__
+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>`__
+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
+
+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()``.
+
+While it is possible to create new implementations of the IHeap
+interface that provide more sophisticated or even
+application-specific memory management policies, most users will
+rely on IHeap implementations from their preferred RTOS (such as
+TI's SYS/BIOS).
+
+Architecture
+------------
+
+The Memory module's methods take a first parameter that identifies
+the heap from which to allocate memory. This parameter may be NULL
+and, in this case, a "default heap" will be used. The "default heap"
+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>`__
+(of size
+`Memory.defaultHeapSize <http://104.154.111.176/cdoc-tip/index.html#xdc/runtime/Memory.html#default.Heap.Size>`__)
+will be assigned to this parameter.
+
+|image1|
+
+The Memory module itself does very little work: it simply delegates
+"real" memory management to the specified heap instance object. This
+makes clients of Memory portable, but where do the heap instances
+get created? If they are created by the application, the code that
+creates these instances is not portable to other applications;
+because it contains direct references to specific heap managers. Of
+course, applications can factor this "non portable" code into a
+single place and pass IHeap instance handles to other parts of the
+application that need memory allocation services. But, an even
+better solution is to entirely eliminate the runtime creation of
+IHeap instances in favor of static creation. In this case, not only
+do we eliminate unnecessary code, but we improve the portability of
+the code by eliminating direct references to application-specific
+heap managers.
+
+Memory simply provides the "glue" between portable clients and
+underlying modules, heap managers, which actually manage the memory.
+But the xdc.runtime package only provides two heap managers, HeapMin
+and HeapStd, and these modules have limited usefulness; HeapMin does
+not reuse freed memory and HeapStd has no advantage over malloc()
+and free(). So where do you get "real" heap managers that realize
+the benefits promised by the xdc.runtime package's memory
+architecture? Heap managers are available from RTOS providers (such
+as TI's SYS/BIOS).
+
+Concurrency Support
+===================
+
+Functional Goals
+----------------
+
+Each embedded application runs in a unique environment with specific
+mechanisms for managing multiple threads; some use a real-time
+operating system while others simply run a control loop that
+coordinates with interrupt service routines. The Gate module
+provides an RTOS independent interface that allows applications to
+portably protect shared data structures in multi-threaded
+environments by simply "entering a gate" prior to using the data and
+"leaving the gate" once access is no longer required.
+
+Gates are also used internally by the xdc.runtime package. In order
+to allow the xdc.runtime functions to be called from different
+threads, it is important that any global data managed by the
+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>`__)
+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>`__)
+once the update is complete.
+
+While gates make it easy to protect shared data structures and
+ensure the functional correctness of a multi-threaded application,
+it is important to minimize the time spent within a gate; the longer
+a thread operates within a gate the greater the chance that this
+thread will interfere with the timely operation of other threads in
+the system. If two (or more) threads need to enter the same gate,
+all but one will be suspended until the thread in the gate leaves
+*even if the thread inside the gate has lower priority than the
+blocked threads*. Worse, for performance reasons, some gates work by
+disabling *all* scheduling while inside the gate; even threads that
+are not trying to modify the data protected by the gate are
+potentially affected.
+
+By carefully selecting the type of gate used to protect shared data
+structures and associating each shared data structure with a unique
+gate, it is possible to strike a balance between the runtime
+overhead caused by frequent gate method calls and the scheduling
+latency engendered by unnecessarily blocking the execution of
+threads that are operating on unrelated data.
+
+The xdc.runtime package
+
+-  enables creation of portable thread-safe code with shared data
+   structures,
+
+-  provides a distinguished "System gate" to efficiently protect very
+   short critical sections,
+
+-  supports gates on both a per-module and a per-instance basis for
+   modules that need to operate within a gate for periods longer
+   than the worst-case scheduling latency allowed by the
+   application, and
+
+-  allows system integrators to configure gates to achieve the proper
+   balance between runtime overhead and scheduling latency for their
+   application.
+
+Architecture Introduction
+-------------------------
+
+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>`__
+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
+  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
+  multi-threaded application.
+
+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>`__
+provides an example that uses `posix
+mutexes <http://pubs.opengroup.org/onlinepubs/9699919799/>`__ and
+illustrates how, using services commonly provided by an RTOS, the
+xdc.runtime package can be made thread-safe with respect to that
+RTOS.
+
+Architecture
+------------
+
+Any module may declare that it is
+"`gated <http://104.154.111.176/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.
+However, it is possible to override the creation of this gate by
+explicitly creating it and assigning it to the module's common$.gate
+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>`__
+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
+modules don't need to use these methods (they are for use within the
+implementation of RTSC modules) and should consult the documentation
+of each gated module used to understand how best to balance the
+module's need to protect shared data structures and the
+application's scheduling latency requirements.
+
+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>`__
+and
+`Gate\_leaveSystem <http://104.154.111.176/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>`__
+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
+short*.
+
+Using the System gate to protect logically independent data
+structures is contrary to the design principle that, to minimize
+scheduling latency effects, you should use a unique gate for
+independent data structures. This exception exists because, *if* the
+duration of time required to update these independent structures is
+always very short (less than any application's maximum scheduling
+latency requirements), the System gate can be implemented very
+efficiently by simply disabling *all* scheduling while inside the
+gate. While this may sound excessive, it often results in a
+significant overall performance gain, keeps data space requirements
+to a minimum with just one gate, and has no impact to scheduling
+latency.
+
+|image2|
+
+Deadlocks
+~~~~~~~~~
+
+Although it is possible to "nest" gates - enter a gate while inside
+another gate - care should be taken to avoid deadlocks; e.g., thread
+1 enters gate a, thread 2 enters gate b, thread 1 tries to enter
+gate b and blocks waiting for thread 2 to leave, but thread 2 tries
+to enter gate a and blocks waiting for thread 1 to leave. One way to
+avoid deadlocks is to ensure that nested gates are always entered in
+the same order.
+
+Since the System gate is used throughout the xdc.runtime and the
+modules in this package are widely used, you should never enter
+another gate while inside the System gate. If another thread enters
+the same gate *and* makes a call to an xdc.runtime method, such as
+System\_printf(), there is a risk of deadlock.
+
+The System gate should *only* be used to protect low-level data
+structures where the total execution time within the gate has a
+constant upper bound independent of the data being protected.
+
+Scheduling Latency
+~~~~~~~~~~~~~~~~~~
+
+Undisciplined use of gates can lead to scheduling latencies that
+violate a system's real-time constraints. Since the System gate is
+used to protect a wide variety of independent data structures, it is
+important to keep the time within the System gate to an absolute
+minimum. Similarly, when assigning gates to gated modules it's
+important to minimize sharing gates between different modules; while
+sharing can reduce your application's data footprint, you risk
+creating unnecessary scheduling blockages.
+
+Real-Time Diagnostics: Event Logging
+====================================
+
+Functional Goals
+----------------
+
+The xdc.runtime package's logging support enables developers to
+embed "printf-like" Log statements virtually *anywhere* in an
+embedded real-time code base. In addition to the traditional
+printf() format string and arguments, each Log statement is
+associated with a calling module and an "event mask" - a bit mask
+that identifies the "type" of statement. The Log statements
+
+-  provide all the functionality of a "normal" printf,
+
+-  can be enabled or disabled at runtime on a per-module and per-type
+   basis, and
+
+-  have fixed low execution time independent of the arguments passed.
+
+Applications can be configured to eliminate the data space required
+for the format strings, permanently disable (or enable) selected
+statements, eliminate the code space required for runtime control,
+and provide application-specific handling of the "events" produced
+by these statements. All of these configuration options are possible
+*without requiring re-compilation of any source code*.
+
+Architecture Introduction
+-------------------------
+
+The xdc.runtime package contains several modules that work together
+to provide rich application diagnostic support that can be
+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>`__,
+and
+`LoggerSys <http://104.154.111.176/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>`__
+   - 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>`__
+   - a module whose configuration applies to all RTSC modules (including Main),
+   unless explicitly overridden on a per-module basis.
+
+Architecture
+------------
+
+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:
+
+1. code that is part of a RTSC module
+
+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>`__
+   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>`__
+   module.
+
+All RTSC target modules, including
+`xdc.runtime.Main <http://104.154.111.176/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>`__
+   service provider - a module that handles events generated by the
+   module, and
+
+-  an optional string name used to display the source of events
+
+All dynamically registered modules also have an event mask and a
+required string name.
+
+The
+`Log\_print <http://104.154.111.176/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>`__
+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
+service provider is called only if:
+
+1. the module has a non-null ILogger service provider, and
+
+2. the mask argument passed to Log\_print (or the mask of the event
+   passed to Log\_write) anded with the calling module's current
+   "event mask" is non-zero
+
+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>`__.
+
+Beyond the parameters passed to Log\_print (or Log\_write), the id
+of the module that called Log\_print (or Log\_write) is communicated
+to the ILogger service provider so that it knows the source of the
+events. This information, possibly in addition to a timestamp
+recorded by the ILogger service provider, can be used to correlate
+events from multiple sources (even from different CPUs).
+
+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>`__
+   - 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>`__
+   - outputs events as they occur using
+   `System\_printf() <http://104.154.111.176/cdoc-tip/index.html#xdc/runtime/System.html#printf>`__
+   and is suitable for initial development or low-rate non-real-time
+   event sources.
+
+Custom ILogger service providers can easily be created to address
+platform or application specific needs. These custom providers can,
+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>`__.
+
+As part of an application's configuration step, developers "bind"
+zero or more ILogger service providers to the modules that comprise
+the application. Each module in a system can have a different
+ILogger service provider or they can all share the same provider.
+Events generated by modules *without* an ILogger service provider
+are silently ignored.
+
+Real-Time Diagnostics: Error Handling
+=====================================
+
+Functional Goals
+----------------
+
+Each embedded application runs in a unique environment with specific
+resource requirements and, as a result, adopts application-specific
+*policies* for managing runtime errors; e.g., reset-and-reboot,
+catch-and-retry, log-and-continue, or a combination of these
+policies for different parts of the system. The xdc.runtime package
+provides a set of mechanisms for raising and handling runtime errors
+that enables code to be written once and used in *any* application -
+independent of the application's error handling policies.
+
+Architecture Introduction
+-------------------------
+
+The xdc.runtime package contains several modules that work together
+to provide rich application diagnostic support that can be
+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>`__
+and
+`Assert <http://104.154.111.176/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>`__
+   - 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>`__
+   - a module whose configuration applies to all RTSC modules
+   (including Main), unless explicitly overridden on a per-module
+   basis.
+
+Architecture
+------------
+
+The xdc.runtime package supports two distinct "categories" of error:
+
+1. *errors* that are explicitly checked for and handled by the code, and
+
+2. *assertion violations* that arise when the current application state
+   is inconsistent with the range of states required by a piece of
+   code.
+
+The first category of errors is managed by the Error module and the
+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>`__.
+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
+records the source of the error, a unique ID for for the error, a
+message format string, and up to two arguments associated with this
+particular occurrence.
+
+Using an Error\_Block structure has several advantages. Perhaps most
+importantly, the information about the source of the error as well
+as data specific to the particular occurrence is efficiently copied
+into the structure for later processing. In effect, Error\_raise()
+combines the efficiency of a simple error code with the richness of
+a printf at the site of the error. Since the error information is
+simply recorded in the Error\_Block structure, the application
+developer can control when and how the information will be formatted
+and displayed.
+
+Similar to the standard C assert() macro, the Assert module's
+methods are interspersed with other code to add runtime checks -
+primarily during early development - that ensure the code is being
+called in the appropriate context. Unlike the standard C assert
+support, the Assert module provides greater flexibility in managing
+the messages displayed, the message string space overhead, and the
+runtime handling of failures. In addition, because the Assert
+methods build atop the Diags module, you can precisely control which
+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>`__
+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.
+
+System Services
+===============
+
+Functional Goals
+----------------
+
+Each embedded application runs in a unique environment with specific
+resource requirements and, as a result, adopts application-specific
+*policies* for basic character output, application startup, and
+shutdown. The xdc.runtime package provides an extensible
+platform-independent framework for application startup (from
+processor boot), initialization, and shutdown. In addition, it
+provides a platform-independent interface for character output which
+allows for platform-specific implementations that can range from
+simple memory writes to a circular buffer to flow-controlled output
+via a platform-specific I/O device.
+
+The System and Startup modules provide the foundation for early
+application "bring up", and continue to serve in deployed
+applications to manage the initialization of higher-level services
+and provide simple "fail-safe" diagnostics. These modules together
+with, say, the SysMin system support module are sufficient to enable
+complete C-based application development using "printf" debugging.
+
+Because Startup and System are platform-independent, entire embedded
+applications can be ported to alternative execution environments
+(Unix or Windows workstations, for example) without making any
+change to their sources. Porting to a different environment involves
+a simple reconfiguration of the application to replace the System
+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>`__
+with the same
+`target <http://104.154.111.176/docs-tip/Glossary#TargetDefinition>`__,
+no recompilation is required.
+
+Architecture Introduction
+-------------------------
+
+The xdc.runtime package contains two modules that together provide
+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>`__
+   - 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>`__
+   - a module that provides exit handling similar to the ANSI C
+   atexit() mechanism as well as basic printf() message output.
+
+Use of these modules is illustrated by a series of examples that use
+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>`__
+   - 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>`__
+   - 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.
+
+Startup Architecture
+--------------------
+
+Every module in an application can optionally supply a "startup"
+function that *must* be run prior to the first use of the module by
+application code. This startup function might read memory mapped
+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>`__
+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
+developer to augment the startup process with custom C functions.
+
+The System module, on the other hand, provides mechanisms for
+modules (initialized under the control of Startup) to shutdown.
+Between the initialization of the application's modules and shutdown
+of the application, System is also used to perform simple character
+output via "printf-like" methods. By not supporting all the format
+specifications required by a full ANSI C Standard implementation of
+printf(), these methods provide a much smaller and faster
+implementation that satisfies most uses and can be embedded in very
+small applications.
+
+Finally, the System module also provides a low-level "gate" that is
+used to protect global data structures maintained within the
+xdc.runtime package; this gate allows multi-threaded applications to
+safely use the xdc.runtime package's modules concurrently. This same
+gate can also be used by application code.
+
+Startup and initialization
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The Startup module provides a standard mechanism for the orderly
+initialization of all modules within an application *before* main()
+begins. The Startup module defines just two entry points that need
+to be integrated into the execution environment's startup code. Once
+this is done, Startup handles the initialization of all other
+modules in the application - xdc.runtime modules as well as any
+other modules used by the application.
+
+Boot Sequence and Control Points
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This section describes the sequence of events that occurs
+immediately after a device is reset until execution reaches the
+application's main() function. It also identifies the specific
+points during this boot sequence at which user provided functions
+("boot hooks") are called.
+
+|image3|
+
+All targets follow the same set of boot sequence steps. In outline,
+the target independent boot sequence steps are:
+
+1. Immediately after CPU reset, perform target-specific CPU
+   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>`__).
+
+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>`__).
+
+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>`__).
+
+7. Call main().
+
+The reset function (in step 2 above) is run as early as possible in
+the boot sequence. In fact, for some targets it is called before the
+C environment is fully initialized; static variables may not be
+fully initialized, for example. To maximize portability, reset
+functions should only assume that a C stack is initialized.
+
+Although the functions in steps 4-6 are C functions, they are run
+during normal C++ static object initialization. This has two
+consequences:
+
+1. Since the ANSI C++ Language Standard does not provide a means to
+   control the order of execution of static constructors, the
+   initialization of application modules may not run before a C++
+   constructor runs. If you need to use a **module** (for memory
+   allocation, for example) before step 6 completes and all modules
+   are initialized, your code must explicitly call Startup\_exec()
+   before using any other module in the system. It is safe to call
+   Startup\_exec() more than once. So, you may call it from each C++
+   constructor that needs a module's services.
+
+2. If you are using a target that does not support C++, you must
+   explicitly call Startup\_exec() prior to using any module's
+   services. You can simply call Startup\_exec() as the first step
+   in main(), for example.
+
+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>`__   |
++----------------------+-------------------------------------------------------------------------------------------------------------------------+
+
+Module Initialization
+~~~~~~~~~~~~~~~~~~~~~
+
+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>`__
+attribute in the module's spec file. Modules that use this attribute
+must also implement the following startup function:
+
+.. code-block:: c
+
+    Int Mod_Module_startup(Int state);
+
+where "Mod" is the name of the module requesting startup support.
+
+The parameter to the startup function serves as "state variable"
+whose initial value will be Startup\_NOTDONE (0) and whose final
+value will eventually be Startup\_DONE (-1). If startup() returns a
+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>`__
+times.
+
+For situations in which the startup of one module depends upon
+another having completed its startup processing, the following
+function is automatically defined for all modules and proxies:
+
+.. code-block:: c
+
+    Bool Mod_Module_startupDone();
+
+where "Mod" is the name of some module or proxy. These predicates
+can be used as guards inside of a startup function to probe whether
+a particular module has completed its own startup processing. As a
+convenience, the function Startup\_rtsDone() probes the necessary
+set of xdc.runtime modules required to support a module instance
+create, and should be called before any startup-time instance
+creation and/or memory allocation is performed.
+
+.. code-block:: c
+   :linenos:
+
+    Int Mod_Module_startup(Int state)
+    {
+        if (!Startup_rtsDone()) {
+            return (Startup_NOTDONE);
+        }
+
+        // other code
+
+        return (Startup_DONE);
+    }
+
+System Module Architecture
+--------------------------
+
+The System module provides mechanisms for modules (initialized under
+the control of Startup) to shutdown. Between the initialization of
+the application's modules and shutdown of the application, System is
+also used to perform simple character output via "printf-like"
+methods. By not supporting all the format specifications required by
+a full ANSI C Standard implementation of printf(), these methods
+provide a much smaller and faster implementation that satisfies most
+uses and can be embedded in very small applications.
+
+Finally, the System module also provides a low-level "gate" that is
+used to protect global data structures maintained within the
+xdc.runtime package; this gate allows multi-threaded applications to
+safely use the xdc.runtime package's modules concurrently. This same
+gate can also be used by application code.
+
+System Character output and shutdown
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The System module provides a facade for two key system level areas:
+character output and program termination. Since application
+termination and basic character output can be very different
+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>`__
+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>`__
+configuration parameter.
+
+|image4|
+
+The xdc.runtime package includes two system support proxy options:
+SysMin and SysStd. These modules are sufficient for early
+development but, because they are written to be 100% portable, they
+don't take advantage of any platform-specific features (such as an
+embedded UART). Fortunately it is easy to create a custom system
+support module that can be bound to System as easily as SyMin or
+SysStd and takes full advantage advantage of your platform's
+execution environment.
+
+Customizing the System module requires that the end-user specify a
+module that implements the ISystemSupport interface as the "proxy"
+for the required platform or application-specific services.
+
+The relationship between the System module and an ISystemSupport
+proxy is illustrated in the figure below.
+
+|image5|
+
+System Concurrency support
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The System module is a `gated
+module <http://104.154.111.176/docs-tip/Glossary#GatedModule>`__.
+The gate associated with the System module, also called the "System
+gate", is a used for two purposes:
+
+1. to protect critical regions within the xdc.runtime package by
+   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>`__
+   and
+   `Gate\_leaveSystem() <http://104.154.111.176/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>`__.
+`Using xdc.runtime
+Gates <http://104.154.111.176/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.
+
+Core Instance Support
+=====================
+
+Functional Goals
+----------------
+
+The RTSC runtime model is intended support any real-time embedded system
+and to usefully scale down to systems with extremely tight memory
+constraints - as little as 1KB of RAM and 32KB of Flash - while
+providing a uniform modular object oriented API for all target code. To
+make this possible, RTSC module instances can be created statically,
+dynamically using the heap, or dynamically using *any* memory managed by
+the application. This allows applications to work with object oriented
+APIs *without requiring any runtime heap memory management*.
+
+It's also important that low-level module instance objects, such as
+queues and semaphores, are capable of being dynamically created entirely
+from stack memory. Stack memory management can be done
+*deterministically*, with effectively *no runtime overhead*, and without
+any possibility of fragmentation issues inherent in heap memory
+management. This makes stack memory ideal for small embedded systems
+with must operate in a fail-safe manner within strict real-time
+constraints. Thus, the non-heap instance construction methods must also
+support memory dynamically allocated by the runtime stack (i.e.,
+ordinary C automatic variables).
+
+Finally, it's important to ensure that a single module implementation be
+able support the full range of embedded applications - from the largest
+embedded system to tiny 1KB RAM systems. It must be easy for modules to
+support *all* forms of instance creation *without any additional
+runtime* code.
+
+Architecture Introduction
+-------------------------
+
+All RTSC modules share a common design pattern similar to C++ or Java
+classes: each module is associated with a module state object and
+optionally defines an instance constructor. Both modules and instances
+optionally supply methods that implicitly operate on the state of the
+module or instance. Unlike instance objects that may be conditionally
+created at runtime, module state objects are singletons that are
+statically defined just once (i.e., before the application starts).
+
+The purpose of xdc.runtime.Core module is to provide common code for the
+implementation of all module constructors and destructors, simplifying
+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>`__.
+
+The xdc.runtime.Core module is simple a collection of functions used in
+the creation and destruction of *all* module instances. But, this module
+is itself *never* directly called by application-level code; it is only
+used in the *implementation* of RTSC modules.
+
+Architecture
+-------------
+
+All RTSC module instance constructor methods follow a common pattern:
+
+-  arguments that lack a reasonable default appear first,
+
+-  if it's possible for the constructor to fail, an Error\_Block pointer
+   is passed as the last argument,
+
+-  all other arguments are encapsulated in a "Params" structure and
+   passed as a pointer to the constructor,
+
+-  if the Params pointer is NULL, the module's specified default values
+   for these parameters are used, otherwise, the referenced "Params"
+   structure must be initialized via a *Mod*\ \_Params\_init() function
+   and only parameters of interest need be updated prior to invoking the
+   module's constructor,
+
+-  memory for heap-based instance objects is allocated by the module's
+   "create" method whereas memory for stack-based and static objects is
+   allocated by the caller and passed as the first parameter to the
+   module's "construct" method.
+
+Leveraging this common pattern, the xdc.runtime.Core module defines a
+small set of functions that encapsulates the common code for all
+instance object memory management in the system. To ensure the
+xdc.runtime.Core functions are applicable to *any* module's instances, a
+uniform description of each instance type, in the form of a const
+xdc\_runtime\_Core\_ObjDesc structure, is passed to the construction
+methods.
+
+.. code-block:: c
+   :linenos:
+
+    struct xdc_runtime_Core_ObjDesc {
+        CPtr         fxnTab;    /* pointer to module fxns */
+        Types_Link   *modLink;  /* link to runtime instances */
+        SizeT        objAlign;  /* alignment of instance object */
+        IHeap_Handle objHeap;   /* heap from which obj is allocated */
+        SizeT        objName;   /* offset into obj for name pointer */
+        SizeT        objSize;   /* sizeof obj (including header) */
+        CPtr         prmsInit;  /* pointer to default Mod_Params */
+        SizeT        prmsSize;  /* size of these default parameters */
+    };
+
+The xdc\_runtime\_Core\_ObjDesc structure together with a static
+constant structure of module-specific parameter defaults provide *all*
+the information necessary for the Core module's functions to create
+instances for any RTSC module. This includes the management of optional
+parameters to a module's instance constructors.
+
+It is up to each module to define its own the static and dynamic
+constructors that are directly invoked by the application. In practice,
+these functions are nothing more than a few lines of code which "wrap"
+calls to the xdc.runtime.Core module's functions followed by a call to a
+module-specific instance state initialization function.
+
+The figure below illustrates the general instance construction pattern
+as well as the relationship between a module, say ModX, its constant
+descriptor structure, and the xdc.runtime.Core module's functions.
+
+|image7|
+
+The sections below illustrate, in greater detail, how a hypothetical
+module, *ModA*, uses the xdc.runtime.Core functions to implement its
+constructors. To simplify these sections, we do not show every possible
+variation allowed by xdc.runtime.Core; e.g., although the possibility of
+errors occurring in constructors is supported by xdc.runtime.Core, the
+examples below assume *ModA*\ \_construct never fails.
+
+Instance construct/destruct Support
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This section illustrates the use of xdc.runtime.Core functions in the
+implementation of the construct/destruct methods of a hypothetical
+module named *ModA*. To support module instance objects that are not
+necessarily allocated from the heap, a pointer to a *ModA*\ \_Struct is
+passed from the application to the constructor; allocation this
+structure is the responsibility of the caller.
+
+For the purpose of this example, we suppose that *ModA* supplies two
+functions: *ModA*\ \_Instance\_init and *ModA*\ \_Instance\_finalize
+which are called to perform any module-specific initialization or
+finalization of *ModA* instances.
+
+**ModA\_Params\_init**
+
+.. code-block:: c
+
+    void ModA_Params_init(ModA_Params *prms)
+    {
+        if (prms != NULL) {
+            xdc_runtime_Core_assignParams__I(
+                prms,
+                &ModA_Object__PARAMS__C,
+                sizeof(ModA_Params),
+                sizeof(xdc_runtime_IInstance_Params)
+            );
+        }
+    }
+
+**ModA\_construct**
+
+.. code-block:: c
+
+    void ModA_construct(ModA_Struct *obj,
+                        const ModA_Params *paramsPtr);
+    {
+        ModA_Params prms;
+
+        /* common instance initialization */
+        xdc_runtime_Core_constructObject__I(
+            &ModA_Object__DESC__C, /* instance description */
+            obj,                   /* memory for instance object */
+            &prms,                 /* tmp memory for all params */
+            (xdc_CPtr)paramsPtr,   /* params supplied by caller */
+            0,                     /* unused (for backward compat) */
+            NULL                   /* optional error block */
+        );
+
+        /* module-specific initialization */
+        ModA_Instance_init((xdc_Ptr)obj, &prms);
+    }
+
+**ModA\_destruct**
+
+.. code-block:: c
+
+    void ModA_destruct(ModA_Struct *obj)
+    {
+        xdc_runtime_Core_deleteObject__I(
+            &ModA_Object__DESC__C,
+            obj,
+            (xdc_Fxn)ModA_Instance_finalize,
+            -1,
+            TRUE
+        );
+    }
+
+
+The methods defined above support the instance lifecycle pattern shown
+below.
+
+.. code-block:: c
+
+    ModA_Struct inst;               /* alloc space for instance */
+    ModA_Params params;             /* alloc space for params */
+
+    ModA_Params_init(&params);      /* init params to defaults */
+    params.foo = 3;                 /* change one or more params ... */
+         :
+    ModA_construct(&inst, &params); /* fully initialize inst */
+
+    ModA_doSomething(&inst, ...);     /* invoke ModA methods ... */
+         :
+    ModA_destruct(&inst);           /* finalize inst */
+
+
+Instance create/delete Support
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This section illustrates the use of xdc\_runtime\_Core functions in the
+implementation of the create/delete methods of a hypothetical module
+named *ModA*. Recall that create/delete supports module instance
+lifecycles that use heap memory.
+
+However, many similarities exist between this implementation and the
+construct/destruct implementation illustrated
+`above <#instance-constructdestruct-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
+simply return a failure to the caller.
+
+As above, we suppose that *ModA* supplies two functions:
+*ModA*\ \_Instance\_init and *ModA*\ \_Instance\_finalize which are
+called to perform any module-specific initialization or finalization of
+*ModA* instances.
+
+**ModA\_create**
+
+.. code-block:: c
+
+    ModA_Handle ModA_create(const ModA_Params *paramsPtr,
+                            xdc_runtime_Error_Block *eb)
+    {
+        ModA_Params prms;
+        ModA_Object *obj;
+
+        /* common instance initialization */
+        obj = xdc_runtime_Core_createObject(
+            &ModA_Object__DESC__C, /* instance description */
+            NULL,                 /* memory for instance object */
+            &prms,                /* tmp memory for all params */
+            (xdc_CPtr)paramsPtr,  /* params supplied by caller */
+            0,                    /* unused (for backward compat) */
+            eb);                  /* needed for heap alloc failures */
+
+        if (obj == NULL) {
+            return NULL;
+        }
+
+        /* module-specific initialization */
+        ModA_Instance_init(obj, &prms);
+        return obj;
+    }
+
+**ModA\_delete**
+
+.. code-block:: c
+
+    void ModA_delete(ModA_Handle *instp)
+    {
+        xdc_runtime_Core_deleteObject(
+            &ModA_Object__DESC__C,
+            *((ModA_Object**)instp),
+            NULL,
+            -1,
+            FALSE);
+        *((ModA_Handle*)instp) = NULL;
+    }
+
+
+The methods defined above support the instance lifecycle pattern shown
+below.
+
+.. code-block:: c
+
+    ModA_Handle inst;               /* handle returned by create */
+    ModA_Params params;             /* alloc space for params */
+
+    ModA_Params_init(&params);      /* init params to defaults */
+    params.foo = 3;                 /* change one or more params ... */
+         :
+    inst = ModA_create(&params, NULL); /* fully initialize inst */
+
+    ModA_doSomething(inst, ...);      /* invoke ModA methods ... */
+         :
+    ModA_delete(&inst);             /* finalize inst */
+
+
+.. |image0| image:: ./media/image4.png
+   :width: 6.48958in
+   :height: 3.28125in
+.. |image1| image:: ./media/image5.png
+   :width: 7.26042in
+   :height: 2.72917in
+.. |image2| image:: ./media/image6.png
+   :width: 6.66667in
+   :height: 3.15625in
+.. |image3| image:: ./media/image7.png
+   :width: 6.41667in
+   :height: 5.32292in
+.. |image4| image:: ./media/image8.png
+   :width: 7.30208in
+   :height: 2.80208in
+.. |image5| image:: ./media/image9.png
+   :width: 6.20833in
+   :height: 4.72917in
+.. |image6| image:: ./media/image10.png
+   :width: 4.75000in
+   :height: 4.58333in
+.. |image7| image:: ./media/image11.png
+   :width: 5.66667in
+   :height: 4.20833in
diff --git a/src/packages/xdc/runtime/docs/Core.drawio b/src/packages/xdc/runtime/docs/Core.drawio
deleted file mode 100644
index 003aca2..0000000
--- a/src/packages/xdc/runtime/docs/Core.drawio
+++ /dev/null
@@ -1 +0,0 @@
-<mxfile modified="2019-06-03T16:12:07.377Z" host="www.draw.io" agent="Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/74.0.3729.169 Safari/537.36" etag="aHR9pZemKhUlAEkkvoW7" version="10.7.4" type="device"><diagram name="Page-1" id="efa7a0a1-bf9b-a30e-e6df-94a7791c09e9">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</diagram></mxfile>
\ No newline at end of file