Ready for Alpha release
[keystone-rtos/rm-lld.git] / rm.h
diff --git a/rm.h b/rm.h
index 0a14033f12460de03438982e70d185a141c5d197..d74afb4c4b64f0b8d77c262dd9dbe8735c31126b 100644 (file)
--- a/rm.h
+++ b/rm.h
@@ -56,8 +56,83 @@ extern "C" {
  *
  *   @section intro  Introduction
  *
- *   The Resource Manager 
- *  
+ *   The Resource Manager (RM) is designed to provide an easy to use, extensible
+ *   uinified resource management solution on TI devices.  RM can be integrated by 
+ *   a system application to provide resource management services to the system 
+ *   temporally (pre-main/post-main) and spatially (system subcomponents, task,
+ *   cores).
+ *
+ *   The RM architecture is instance based.  All RM resource management services 
+ *   must originate from a RM instance.  Resource permissions are assigned by a 
+ *   system integrator using RM instance names provided during the initialization
+ *   of each RM instance in use.  There are three types of RM instances, all of
+ *   which can be used by the system to request resource management services:
+ *    - Server - Manages all resource data structures including the resource
+ *               allocators, the permissions policies, and a simple NameServer.
+ *               There can only be one Server per RM ecosystem.  If two Servers
+ *               are initialized within a system they must manage mutually
+ *               exclusive sets of device resources.  There is no limit to the 
+ *               number of Client and Client Delegate instances that can connect
+ *               to the Server
+ *    - Client - Used by system components to request resource services.  There is
+ *               no limit to the number of Clients a system can have.  Client
+ *               names must be unique since resource permissions are assigned based
+ *               on RM instance names.  Clients can connect to at most one Server
+ *               or Client Delegate, but not both at the same time.
+ *    - Client Delegate (CD) - At the moment the CD is not different from the
+ *                             Client.  However, in the future the CD will be able
+ *                             to act as a proxy for the Server.  The CD will be
+ *                             able to satisfy some service requests from Clients,
+ *                             offloading some processing from the Server.  This 
+ *                             feature will be helpful in situations where a
+ *                             slower data path exists between the Server and
+ *                             CD/Client instances.  There is no limit to the number
+ *                             of Clients that can connect to a CD.  The CD can
+ *                             connect to at most one Server.
+ *
+ *   RM instances communicate via a generic transport interface.  The RM transport
+ *   interface expects the application to configure and manage the transport data paths
+ *   between RM instances.  This allows RM to easily extend to different device 
+ *   configurations and different devices entirely.
+ *
+ *   RM utilizes the BDS-licensed, open source, Flattened Device Tree format to 
+ *   specify what resources are managed by RM as well as the RM instance permissions
+ *   for managed resources.  The Global Resource List or GRL defines all device 
+ *   resources and their ranges that will be tracked by the RM Server.  Addition or 
+ *   subtraction of resources from RM requires one modify only the GRL.  RM source code
+ *   changes are not required to add or subtract resources from RM's umbrella of 
+ *   management.  RM Policies specify resource permissions for the RM instances.  There
+ *   are two types of Policies:
+ *    - Global Policy - Provided to the Server at initialization and defines the 
+ *                      resource permissions for all RM instances in the system.
+ *                      All service requests will be validated against the Global
+ *                      Policy on the Server.  If the RM instance is found to not
+ *                      hold the privileges for the request a denial of the service
+ *                      will be issued back to the requesting instance.
+ *    - Static Policy - Optionally provided to Client and CD instances at
+ *                      initialization.  Allows these instances to statically 
+ *                      allocate resources.  This feature is typically used
+ *                      for RM instances that must allocate resources prior
+ *                      to the transport connection to the Server being established.
+ *                      Resources allocated via any Static Policies will
+ *                      be validated against the Global Policy once the transport 
+ *                      to the Server has been fully established.  If a Static
+ *                      Policy request fails validation with the Global Policy the
+ *                      RM instance that issued the static request will be placed
+ *                      into a locked state.  The locked state prevents any further
+ *                      service requests from the instance.
+ *
+ *   Combined, the GRL and Policy Device Tree implementations allow RM to easily extend 
+ *   to new resources without the need to recompile the RM source code.
+ *
+ *   RM instances currently provides the following resource services:
+ *    - Allocate (initialize) - Allocate a resource for initialization
+ *    - Allocate (usage)      - Allocate a resource for use
+ *    - Free                  - Free an allocated resource (The free must originate
+ *                              from the RM instance that allocated the resource
+ *    - Map resource to name  - Map a specified resource to a NameServer name
+ *    - Unmap named resource  - Unmap a resource from an existing NameServer name
+ *    - Get resource by name  - Returns a resource based on a provided NameServer name
  */
  
 /* Define RM_API as a master group in Doxygen format and add all RM API