Target Communication Framework Services - WR_Module

Loader Service

Version History

Version Date Change
0.2 2013-08-20 green light
0.1 2013-05-23 Initial contribution

Overview

WR_Module service is an interface to the target loader.

The service supports:

Commands are encoded as zero terminated JSON strings.

The service uses standard format for error reports, see Error Report Format.

Commands

getCapabilities

C • <token> • WR_Module • getCapabilities • <string: context ID> •

The command reports WR_Module service capabilities to clients so they can adjust to different implementations of the service. When called with a null ("") context ID the full list of supported load and unload command are returned, otherwise context specific capabilities are returned. Example for a RTP context the load of a DKM will not be present.

Reply:


R • <token><error report><object: capabilities data><capabilities data>null
 ⇒ <object>

Capability data is a list of properties. All properties are optional. Predefined capabilities are:

All properties are optional. Predefined properties are:

A possible extention would be "SharedLibrary".

Example :

 
   WR_Module getCapabilities "myId"
   {"load":{"KernelModule":true},"unload":{"KernelModule":true}}

Get Children


C • <token> • WR_Module • getChildren • <string: context ID><object : Properties>

This command retrieves the children list of the given context ID. The root node is represented by a ProcessID.

The Properties parameter is optionnal. It is used to filter the ID enumeration.


<object of Properties>
    ⇒ null
    ⇒ { "Filter": < object : Property> }


<object of Property>
    ⇒ null
    ⇒ <object>

Predefined <object : Property> are :

Reply:


R • <token><error report><array of context IDs><array of context IDs>
    ⇒ null
    ⇒ [ ]
    ⇒ [ <context IDs> ]

<context IDs> ⇒ <context ID> ⇒ <context IDs>, <context ID>

Predefined tree node is:

 Process ID :  <string>  - This is the root node. This ID must be valid regarding the Process service, and this context must have the memory group attribute.
      ⇒  Module ID :  <string>  - This ID identifies a Module node.
         ⇒  Undef SymbolList ID :  <string>  - This ID identifies the list of undefined symbols
         ⇒  Common SymbolList ID :  <string>  - This ID identify the list COMMON symbols
         ⇒  SectionList ID :  <string>  - This ID identifies a list of sections
         ⇒  SegmentList ID :  <string>  - This ID identifies a list of segments

Example of valid queries:

 
   WR_Module getChildren ["myId"] {Filter:{"Type":"KernelModule"}}
   WR_Module getChildren ["myId"] null
   WR_Module getChildren ["myId1","myId2"]
   WR_Module getChildren ["myId"]
   WR_Module getChildren []
   WR_Module getChildren null

Get Properties


C • <token> • WR_Module • getProperties • <array of context IDs><array of context IDs>
    ⇒ null
    ⇒ [ ]
    ⇒ [ <context ID list> ]

<context ID list><string: context ID><context ID list> , <string: context ID>

The command retrieves context info for given context IDs. Command allows to query multiple contexts at once. The root node context ID must be a ProcessID that is a memory context.

Reply:


R • <token><error report><array of context data><array of context data>
    ⇒ null
    ⇒ [ ]
    ⇒ [ <context data list> ]

<context data list><context data><context data list> , <context data>

<context data>
    ⇒ null
    ⇒ <object>

Context data object should, at least, contain member "ID" : <string>. Context data is expected to be cached by clients. Cached context data should by flushed when a module event (changed, added or removed) is received.

Predefined context properties represented by Module ID are:

Predefined context properties represented by Undef Symbols list ID are:

Predefined context properties represented by Common Symbols list ID are:

Predefined context properties represented by Segment List are:

Predefined context properties represented by Section List are:


Predefined <object : symbolList> are :

Predefined <object : Section> are:

Predefined <object : Segment> are:

Today there is no predefined <object : Signatures> value.

load


C • <token> • WR_Module • load • <string : context ID><string : file name><object :  options>

The command loads the given module for the given symbol group of the execution context ID.
The full "file name" is the path of the target module to load. This path is translated by the path map if needed.

This new file will be listed like other modules known by the agent.
Module IDs are valid across TCF services.

The "options" are described by the vxWorks documentation. The service WR_TargetDataBase could be used to have more information about this options.

Predefined <object : Options> are:

Example:

   tcf WR_Module load <Context ID>  <file name>  {"LoadFlags":0}

If the load command is invoked with the LOAD_IGNORE_IF_IDENTICAL option and if there is already an instance of the module on the target then the target loader does not load another instance of the module and the <Module ID> returned by the service is NULL.

Reply:


R  •  <token><error report><Module ID>

The reply result will be posted at the end of the load command, there is no timing guaranty whith the event module added.

Predefined module data properties are:


unload


C • <token> • WR_Module • unload • <string: Module ID><object :  options>

This command unloads a given module defined by its "Module ID".

The option list must match with the options list defined by the getParameterList.

The "options" are described by the vxWorks documentation. The service WR_TargetDataBase could be used to have more information about this options.

Predefined <object : Options> are:

Example:

   tcf WR_Module unload <Module ID>  {"UnloadFlags":0}

Reply:


R  •  <token><error report>

The reply result will be posted at the end of the unload command, there is no timing guaranty whith the event module removed.


Events

WR_Module service events are sent to notify clients about module list changes. The purpose of these events is to let all clients know about which modules were added or removed.

 
E • WR_Module • moduleAdded|moduleChanged|moduleRemoved • <string memory context ID><array of Module IDs> •
<array of module IDs> ⇒ null ⇒ [ ] ⇒ [ <modules ID list> ]

The <string module ID> is usable with the getContext command.

moduleAdded
Is sent when a module is successfully added to the vxWorks system.
moduleRemoved
Is sent when a module is successfully removed from the vxWorks system.