The ServiceMgr module manages all the UIA Services. The ServiceMgr module
itself can be plugged with different low level transport functions to
support different methods for getting information between the target
and instrumentation host. Some of these methods (e.g. File) only support
sending information from the target to the host. They do not support
sending information from the host to the target.
The ServiceMgr module also supports two different topologies.
The ServiceMgr module contains the generic configuration.
Many of these configuration values change
depending on the device. The ServiceMgr module uses the
ti.uia.family.Settings module to fill in values if they are not set by
the application.
The ServiceMgr does expose many configuration parameters to allow users
to modify the default behavior.
- Tasks: The ServiceMgr module might have up to two tasks:
transfer agent task and receive task. The receive task only
recieves control messages from the instrumentation host and
forwards it on the the transfer agent task.
The transfer agent task is responsible for everything else
(e.g. period management, event collection, communicating with
remote cores in a multicore configuration, sending UIA Packets
to the instrumentation host, etc.).
The application can specify the stack sizes and placement of
these task via the ServiceMgr.
If there is only one task needed, the parameters for the
receive task is ignored.
const ServiceMgr_WAIT_FOREVER |
 |
Wait forever constant that can be used in ServiceMgr_getFreePacket
#define ServiceMgr_WAIT_FOREVER (UInt)~(0)
enum ServiceMgr_Reason |
 |
Used in the ProcessCallback to denote the reason
typedef enum ServiceMgr_Reason {
ServiceMgr_Reason_PERIODEXPIRED,
ServiceMgr_Reason_REQUESTENERGY,
ServiceMgr_Reason_INCOMINGMSG
} ServiceMgr_Reason;
DETAILS
ServiceMgr_Reason_PERIODEXPIRED: the
ProcessCallback is being
called because it is time to collect events and send them.
ServiceMgr_Reason_REQUESTENERGY: the
ProcessCallback is being
called because the service requested energy to perform some action.
ServiceMgr_Reason_INCOMINGMSG: the
ProcessCallback is being
called because there is an incoming message for the service.
enum ServiceMgr_Topology |
 |
Used to define UIA topology
typedef enum ServiceMgr_Topology {
ServiceMgr_Topology_SINGLECORE,
ServiceMgr_Topology_MULTICORE
} ServiceMgr_Topology;
DETAILS
If UIA is configured for multicore, all events and messages are routed
via the master core to the non-master cores. Choosing multicore requires
setting the
master config.
If UIA is configured for Topology_SINGLECORE, each core on the device
communicates with the instrumentation host directly.
typedef ServiceMgr_ProcessCallback |
 |
Function prototype for the processMsg callback
DETAILS
A ProcessCallback function must be supplied by every service.
The function is provided in the
register function.
For a description of the ServiceMgr_Reason parameter, please refer
to
Reason.
The UIPacket_Hdr field is only used in the
Reason_INCOMINGMSG
case. For any other reason, this value is NULL.
typedef ServiceMgr_ServiceId |
 |
Used by services to generate a serviceId
typedef opaque ServiceMgr_ServiceId;
DETAILS
Services needs to define a ServiceId in their xdc file.
Then the ServiceMgr module will assign a unique value to it during
build time.
For example in ti.uia.service.Rta.xdc there is the following line:
readonly config ServiceMgr.ServiceId SERVICEID;
Control command type
config ServiceMgr_A_invalidProcessCallbackFxn // module-wide |
 |
Assert raised invalid processCallbackFxn is supplied
extern const Assert_Id ServiceMgr_A_invalidProcessCallbackFxn;
config ServiceMgr_A_invalidServiceId // module-wide |
 |
Assert raised when calling API with invalid ServiceId
extern const Assert_Id ServiceMgr_A_invalidServiceId;
config ServiceMgr_masterProcId // module-wide |
 |
Processor that communicates to the instrumentation host
extern const UInt16 ServiceMgr_masterProcId;
DETAILS
This value denotes which core in a multiple core topology is
the master core. All routing of UIA data to the instrumentation
host is done via this core.
The procId corresponds to Ipc's MultiProc value.
For single processor systems, or where there is no routing of
data via an intermediate core, this value is ignored.
config ServiceMgr_maxCtrlPacketSize // module-wide |
 |
Size of control message packets in bytes
extern const SizeT ServiceMgr_maxCtrlPacketSize;
DETAILS
This size includes the UIAPacket header. This value's default
depends on the device.
config ServiceMgr_maxEventPacketSize // module-wide |
 |
Size of Event packets in bytes
extern const SizeT ServiceMgr_maxEventPacketSize;
DETAILS
This size includes the UIAPacket header. This value's default
depends on the device.
config ServiceMgr_numEventPacketBufs // module-wide |
 |
Number of UIAPacket events on the processor
extern const Int ServiceMgr_numEventPacketBufs;
config ServiceMgr_numIncomingCtrlPacketBufs // module-wide |
 |
Number of incoming Ctrl buffers on the master processor
extern const Int ServiceMgr_numIncomingCtrlPacketBufs;
config ServiceMgr_numOutgoingCtrlPacketBufs // module-wide |
 |
Number of outgoing Ctrl buffers on the processor
extern const Int ServiceMgr_numOutgoingCtrlPacketBufs;
config ServiceMgr_periodInMs // module-wide |
 |
Period in miliseconds of ServiceMgr's transfer agent
extern const Int ServiceMgr_periodInMs;
DETAILS
The transfer agent runs at the configured period. It checks to see
if a service's period has expired. If it has expired, the service's
ProcessCallback is called with the
Reason_PERIODEXPIRED reason.
A service should not set it's period to a value less than the ServiceMgr
module'speriod. A service's period should be a multiple of the
ServiceMgr module's period. If it is not, it will called at the rounded
up period. For example, if ServiceMgr.periodInMs = 100 and a service
sets its period to 250. That service will be called every 300
milliseconds.
This value does not guarantee that the transfer agent will run at this
rate. Even if the period has expired, the transfer agent will not run
until the current running Task has yielded and there are no other higher
priority Tasks ready.
Default is 100ms.
config ServiceMgr_rxTaskPriority // module-wide |
 |
Priority of the Transfer Agent Task
extern const Int ServiceMgr_rxTaskPriority;
DETAILS
Default is 1, the lowest priority.
config ServiceMgr_rxTaskStackSize // module-wide |
 |
Transfer Agent Task stack size in MAUs
extern const SizeT ServiceMgr_rxTaskStackSize;
DETAILS
The recommended size is 2048 bytes.
config ServiceMgr_supportControl // module-wide |
 |
Configure whether control messages are supported
extern const Bool ServiceMgr_supportControl;
DETAILS
Default is determined based on the device and transport type.
The application should only set this if
transportType
is TransportType_USER and it is plugging in a new set
of transport functions. The transport function package should
specify how to set this parameter.
config ServiceMgr_topology // module-wide |
 |
Used to define UIA topology
DETAILS
If Topology_MULTICORE is chosen, the ServiceMgr will use Ipc to
discover the core configuration and to communicate between the cores.
UIA will route the outbound packets from each core through the master
core. UIA will also route messages received by the master core to
their intended recipient.
If UIA is configured for Topology_SINGLECORE, each core on the device
communicates with the instrumentation host directly.
The default is Topology_SINGLECORE.
config ServiceMgr_transferAgentPriority // module-wide |
 |
Priority of the Transfer Agent Task
extern const Int ServiceMgr_transferAgentPriority;
DETAILS
Default is 1, the lowest priority.
config ServiceMgr_transferAgentStackSize // module-wide |
 |
Transfer Agent Task stack size in MAUs
extern const SizeT ServiceMgr_transferAgentStackSize;
DETAILS
The recommended size is 2048 bytes.
config ServiceMgr_transportFxns // module-wide |
 |
Transport functions used to communicate to the instrumentation host
DETAILS
These functions are setup by default based on the device.
The user can explicitly set this parameter if the default is not
appropriate.
ServiceMgr_freePacket() // module-wide |
 |
Function to return an unused packet back to the ServiceMgr module
ARGUMENTS
packet
Pointer to a UIAPacket
DETAILS
This function can be used to return an unused packet back to the
ServiceMgr module. It must only return packets that were obtained via
the
getFreePacket function.
ServiceMgr_getFreePacket() // module-wide |
 |
Function to obtain a free UIA packet
ARGUMENTS
type
Requested type of packet
timeout
Return after this many system time units
RETURNS
Pointer to a packet if successful. NULL if timeout.
DETAILS
The service can specify what type of packet it wants with the
first parameter. Currently only UIAPacket_HdrType_Msg and
UIAPacket_HdrType_EventPkt are supported.
The function fills in the HdrType field of the packet automatically
for the service. All other fields are un-initialized.
ServiceMgr_getNumServices() // module-wide |
 |
Returns the number of services present in the system
Int ServiceMgr_getNumServices();
RETURNS
Number of services
ServiceMgr_requestEnergy() // module-wide |
 |
Function to request energy for a service
ARGUMENTS
id
Service id of the service
DETAILS
Generally services do not maintain an active thread.
They may request the ServiceMgr module to call the
ProcessCallback in the context of the transfer agent.
This can be accomplished via this function.
ServiceMgr_sendPacket() // module-wide |
 |
Send a UIAPacket to the instrumentation host
ARGUMENTS
packet
UIAPacket to be sent
RETURNS
TRUE denotes success and the packet is
no longer owned by the caller. FALSE denotes
failure and the packet is still owned by the caller.
DETAILS
All UIAPacket fields except for SenderAdrs must be filled in.
The caller loses ownership of the packet once it is successfully sent.
If this function fails, the caller still owns the packet. It can re-use
it or free it via the
freePacket function.
ServiceMgr_setPeriod() // module-wide |
 |
Allows services to set their event collection period
ARGUMENTS
id
Service id of the service
periodInMs
Requested period in milliseconds
DETAILS
ServiceMgr's period should be a multiple of the ServiceMgr's period
(
periodInMs). If it is not, they will called at the rounded
up period. For example, if ServiceMgr.periodInMs = 100 and a service sets
its period to 250. That service will be called every 300 milliseconds.
Module-Wide Built-Ins |
 |
// Get this module's unique id
Bool ServiceMgr_Module_startupDone();
// Test if this module has completed startup
// The heap from which this module allocates memory
Bool ServiceMgr_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 ServiceMgr_Module_getMask();
// Returns the diagnostics mask for this module
Void ServiceMgr_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
const ServiceMgr.WAIT_FOREVER |
 |
Wait forever constant that can be used in ServiceMgr_getFreePacket
XDCscript usage |
meta-domain |
const ServiceMgr.WAIT_FOREVER = ~(0);
C SYNOPSIS
enum ServiceMgr.Reason |
 |
Used in the ProcessCallback to denote the reason
XDCscript usage |
meta-domain |
values of type ServiceMgr.Reason
const ServiceMgr.Reason_PERIODEXPIRED;
const ServiceMgr.Reason_REQUESTENERGY;
const ServiceMgr.Reason_INCOMINGMSG;
DETAILS
ServiceMgr_Reason_PERIODEXPIRED: the
ProcessCallback is being
called because it is time to collect events and send them.
ServiceMgr_Reason_REQUESTENERGY: the
ProcessCallback is being
called because the service requested energy to perform some action.
ServiceMgr_Reason_INCOMINGMSG: the
ProcessCallback is being
called because there is an incoming message for the service.
C SYNOPSIS
enum ServiceMgr.Topology |
 |
Used to define UIA topology
XDCscript usage |
meta-domain |
values of type ServiceMgr.Topology
const ServiceMgr.Topology_SINGLECORE;
const ServiceMgr.Topology_MULTICORE;
DETAILS
If UIA is configured for multicore, all events and messages are routed
via the master core to the non-master cores. Choosing multicore requires
setting the
master config.
If UIA is configured for Topology_SINGLECORE, each core on the device
communicates with the instrumentation host directly.
C SYNOPSIS
metaonly enum ServiceMgr.TransportType |
 |
Used to specify the type of transport for UIA to use
XDCscript usage |
meta-domain |
values of type ServiceMgr.TransportType
const ServiceMgr.TransportType_ETHERNET;
const ServiceMgr.TransportType_FILE;
const ServiceMgr.TransportType_USER;
const ServiceMgr.TransportType_NULL;
DETAILS
TransportType defines what the underlying transport will be used. In
a multi-core topology, this parameter is only relevant for the
masterProcId core. The masterProcId core uses the TransportType
to determine how to get the data off the target.
- TransportType_ETHERNET: Use the Ethernet transport. On a SYS/BIOS
system, this uses the NDK. The application is responsible for
adding the NDK into the application and initializing it.
- TransportType_FILE: Use the File transport.
On a SYS/BIOS system, this transport requires a JTAG connection.
- TransportType_USER: This allows the application to specify their
own transport functions.
- TransportType_NULL: No transport functions are needed. This should
only be used on the non-masterProcId cores.
config ServiceMgr.A_invalidProcessCallbackFxn // module-wide |
 |
Assert raised invalid processCallbackFxn is supplied
XDCscript usage |
meta-domain |
msg: "A_invalidProcessCallbackFxn: Callback cannot be NULL"
};
C SYNOPSIS
config ServiceMgr.A_invalidServiceId // module-wide |
 |
Assert raised when calling API with invalid ServiceId
XDCscript usage |
meta-domain |
msg: "A_invalidServiceId: ServiceId out of range"
};
C SYNOPSIS
config ServiceMgr.masterProcId // module-wide |
 |
Processor that communicates to the instrumentation host
XDCscript usage |
meta-domain |
ServiceMgr.masterProcId = UInt16 0;
DETAILS
This value denotes which core in a multiple core topology is
the master core. All routing of UIA data to the instrumentation
host is done via this core.
The procId corresponds to Ipc's MultiProc value.
For single processor systems, or where there is no routing of
data via an intermediate core, this value is ignored.
C SYNOPSIS
config ServiceMgr.maxCtrlPacketSize // module-wide |
 |
Size of control message packets in bytes
XDCscript usage |
meta-domain |
ServiceMgr.maxCtrlPacketSize = SizeT undefined;
DETAILS
This size includes the UIAPacket header. This value's default
depends on the device.
C SYNOPSIS
config ServiceMgr.maxEventPacketSize // module-wide |
 |
Size of Event packets in bytes
XDCscript usage |
meta-domain |
ServiceMgr.maxEventPacketSize = SizeT undefined;
DETAILS
This size includes the UIAPacket header. This value's default
depends on the device.
C SYNOPSIS
config ServiceMgr.numEventPacketBufs // module-wide |
 |
Number of UIAPacket events on the processor
XDCscript usage |
meta-domain |
ServiceMgr.numEventPacketBufs = Int 2;
C SYNOPSIS
config ServiceMgr.numIncomingCtrlPacketBufs // module-wide |
 |
Number of incoming Ctrl buffers on the master processor
XDCscript usage |
meta-domain |
ServiceMgr.numIncomingCtrlPacketBufs = Int 2;
C SYNOPSIS
config ServiceMgr.numOutgoingCtrlPacketBufs // module-wide |
 |
Number of outgoing Ctrl buffers on the processor
XDCscript usage |
meta-domain |
ServiceMgr.numOutgoingCtrlPacketBufs = Int 2;
C SYNOPSIS
config ServiceMgr.periodInMs // module-wide |
 |
Period in miliseconds of ServiceMgr's transfer agent
XDCscript usage |
meta-domain |
ServiceMgr.periodInMs = Int 100;
DETAILS
The transfer agent runs at the configured period. It checks to see
if a service's period has expired. If it has expired, the service's
ProcessCallback is called with the
Reason_PERIODEXPIRED reason.
A service should not set it's period to a value less than the ServiceMgr
module'speriod. A service's period should be a multiple of the
ServiceMgr module's period. If it is not, it will called at the rounded
up period. For example, if ServiceMgr.periodInMs = 100 and a service
sets its period to 250. That service will be called every 300
milliseconds.
This value does not guarantee that the transfer agent will run at this
rate. Even if the period has expired, the transfer agent will not run
until the current running Task has yielded and there are no other higher
priority Tasks ready.
Default is 100ms.
C SYNOPSIS
config ServiceMgr.rxTaskPriority // module-wide |
 |
Priority of the Transfer Agent Task
XDCscript usage |
meta-domain |
ServiceMgr.rxTaskPriority = Int 1;
DETAILS
Default is 1, the lowest priority.
C SYNOPSIS
config ServiceMgr.rxTaskStackSize // module-wide |
 |
Transfer Agent Task stack size in MAUs
XDCscript usage |
meta-domain |
ServiceMgr.rxTaskStackSize = SizeT 2048;
DETAILS
The recommended size is 2048 bytes.
C SYNOPSIS
config ServiceMgr.supportControl // module-wide |
 |
Configure whether control messages are supported
XDCscript usage |
meta-domain |
ServiceMgr.supportControl = Bool undefined;
DETAILS
Default is determined based on the device and transport type.
The application should only set this if
transportType
is TransportType_USER and it is plugging in a new set
of transport functions. The transport function package should
specify how to set this parameter.
C SYNOPSIS
config ServiceMgr.topology // module-wide |
 |
Used to define UIA topology
XDCscript usage |
meta-domain |
DETAILS
If Topology_MULTICORE is chosen, the ServiceMgr will use Ipc to
discover the core configuration and to communicate between the cores.
UIA will route the outbound packets from each core through the master
core. UIA will also route messages received by the master core to
their intended recipient.
If UIA is configured for Topology_SINGLECORE, each core on the device
communicates with the instrumentation host directly.
The default is Topology_SINGLECORE.
C SYNOPSIS
config ServiceMgr.transferAgentPriority // module-wide |
 |
Priority of the Transfer Agent Task
XDCscript usage |
meta-domain |
ServiceMgr.transferAgentPriority = Int 1;
DETAILS
Default is 1, the lowest priority.
C SYNOPSIS
config ServiceMgr.transferAgentStackSize // module-wide |
 |
Transfer Agent Task stack size in MAUs
XDCscript usage |
meta-domain |
ServiceMgr.transferAgentStackSize = SizeT 2048;
DETAILS
The recommended size is 2048 bytes.
C SYNOPSIS
config ServiceMgr.transportFxns // module-wide |
 |
Transport functions used to communicate to the instrumentation host
XDCscript usage |
meta-domain |
DETAILS
These functions are setup by default based on the device.
The user can explicitly set this parameter if the default is not
appropriate.
C SYNOPSIS
metaonly config ServiceMgr.common$ // module-wide |
 |
Common module configuration parameters
XDCscript usage |
meta-domain |
DETAILS
All modules have this configuration parameter. Its name
contains the '$' character to ensure it does not conflict with
configuration parameters declared by the module. This allows
new configuration parameters to be added in the future without
any chance of breaking existing modules.
metaonly config ServiceMgr.customTransportType // module-wide |
 |
Custom transport used to send the records to an instrumentation host
XDCscript usage |
meta-domain |
ServiceMgr.customTransportType = String null;
metaonly config ServiceMgr.rxTaskStackSection // module-wide |
 |
Memory section for Receiving Task's stack
XDCscript usage |
meta-domain |
ServiceMgr.rxTaskStackSection = String null;
DETAILS
If this parameter is not set then the Task.defaultStackSection is used.
See the Task module for instructions on creating a stack section in
a different memory segment.
metaonly config ServiceMgr.transferAgentStackSection // module-wide |
 |
Memory section for Transfer Agent Task's stack
XDCscript usage |
meta-domain |
ServiceMgr.transferAgentStackSection = String null;
DETAILS
If this parameter is not set then the Task.defaultStackSection is used.
See the Task module for instructions on creating a stack section in
a different memory segment.
metaonly config ServiceMgr.transportType // module-wide |
 |
Determines the transport that UIA will be configured for
XDCscript usage |
meta-domain |
DETAILS
For a given transport type, UIA picks an appropriate transport
implementation to use based on your device. This is specified by the
ti.uia.family.Settings module. Refer to the examples for configuring
the actual transport implementation.
If someone writes an new transport (e.g. RapidIO),
they can be plugged in by setting the TransportType
to TransportType_USER and then plugging
the transportFxns manually. It must also set up the following parameters
as directed by the new transport developer.
- ServiceMgr.supportControl: does the transport support receiving
messages from the host. For example TransportFile does not.
- ServiceMgr.maxEventPacketSize: Max size of an outgoing event packet. For
example TransportNdk uses 1472 (emac size minus headers)
- ServiceMgr.maxCtrlPacketSize: Max size of the message packets. This can
be zero if supportControl is false.
Here is an example of plugging the transport XYZ into the ServiceMgr:
var ServiceMgr = xdc.useModule('ti.uia.runtime.ServiceMgr');
ServiceMgr.transportType = ServiceMgr.TransportType_USER;
var xyzTransport = {
initFxn: '&TransportXYZ_init',
startFxn: '&TransportXYZ_start',
recvFxn: '&TransportXYZ_recv',
sendFxn: '&TransportXYZ_send',
stopFxn: '&TransportXYZ_stop',
exitFxn: '&TransportXYZ_exit'
};
ServiceMgr.transportFxns = xyzTransport;
ServiceMgr.maxEventPacketSize = 1024
ServiceMgr.maxCtrlPacketSize = 1024;
ServiceMgr.supportControl = true;
metaonly ServiceMgr.register() // module-wide |
 |
Register a services with the ServiceMgr module
XDCscript usage |
meta-domain |
ARGUMENTS
id
Service id of the service (refer to
ServiceId).
processCallbackFxn
Service's callback function.
periodInMs
Period of the service.
DETAILS
All service's must register with the ServiceMgr module statically.
Refer to
periodInMs for a description of the period parameter.