155 TR-157 Amendment 3 Software Module Guidelines

Version 1.0

[1] Broadband Forum (BBF) has defined an object model for managing the software modules in a CPE. The BBF Software Modules object defines Execution Environments, Deployment Units, and Execution Units. These concepts are mapped in the following table.

Table 155.1 Mapping of concepts

Software Modules Concept OSGi Concept
Execution Environment OSGi Framework
Deployment Unit Bundle
Execution Unit Bundle

There can be multiple Execution Environments of the same or different types. The parent Execution Environment is either the native environment, for example Linux, or it can be another Framework. A BBF Deployment Unit and Execution Unit both map to a bundle since there is no need to separate those concepts in OSGi. An implementation of this object model should have access to all the Execution Environments as the Deployment Units and Execution Units are represented in a single table.

This section is not a specification in the normal sense. The intention of this chapter is to provide guidelines for implementers of the [4] TR-157a3 Internet Gateway Device Software Modules on an OSGi Framework.

155.1 Management Agent

The Broadband Forum TR-157 Software Modules standard provides a uniform view of the different execution environments that are available in a device. Execution Environments can model the underlying operating system, an OSGi framework, or other environments that support managing the execution of code.

Most parameters in the Software Modules object model map very well to their OSGi counter parts. However, there are a number of issues that require support from a management agent. This management agent must maintain state to implement the contract implied by the Software Modules standard. For example, the OSGi Framework does not have an Initial Start Level, an OSGi Framework always starts at an environment property defined start level. However, the standard requires that a Framework must start at a given level after it is launched.

There are many other actions that require a management agent to provide the functionality required by TR-157 that is not build into the OSGi Framework since the standard requires a view that covers the whole device, not just the OSGi environment. The assumed architecture is depicted in Figure 155.1.

Figure 155.1 Management Agent Architecture

Management Agent Architecture

155.2 Parameter Mapping

The following table provides OSGi specific information for the different parameters in the Software Modules object model.

Table 155.2 OSGi Specific Information for the BBF Software Modules object model

TR-069 Software Module

Object Parameter

Mapping in case of OSGi
Device.SoftwareModules.

 ExecEnvNumberOfEntries

 DeploymentUnitNumberOfEntries

 ExecutionUnitNumberOfEntries

Device.SoftwareModules.ExecEnv.{i}.

 Enable

Indicates whether or not this OSGi Framework is enabled. Disabling an enabled OSGi Framework must stop it, while enabling a disabled OSGi Framework must launch it. When an Execution Environment is disabled, Bundles installed in that OSGi Framework will be unaffected, but any Bundles on that OSGi Framework are automatically made inactive. When an OSGi Framework is disabled it is impossible to make changes to the installed bundles, install new bundles, or query any information about the bundles. Disabling the OSGi Framework could place the device in a non-manageable state. For example, if the OSGi Framework runs the Protocol Adapter or has a management agent then it is possible that the device can no longer be restarted.

 Status

Indicates the status of the OSGi Framework. Enumeration of:

  • Up - The OSGi Framework is up and running.

  • Error - The OSGi Framework could not be launched.

  • Disabled - The OSGi Framework is not enabled

 Reset

Setting this parameter to true causes this OSGi Framework to revert back to the state it was in when the device last issued a 0 BOOTSTRAP Inform event (bootstrap). The following requirements dictate what must happen for the reset to be complete:

  • The system must restore the set of bundles that were present at the last bootstrap event. That means that installed bundles since that moment must be uninstalled, updated bundles rolled back, and uninstalled bundles re-installed.

  • The OSGi Framework must roll back to the version it had during the previous rollback.

  • The OSGi Framework must be restarted after the previous requirements have been met.

The value of this parameter is not part of the device configuration and is always false when read.

 Alias

A non-volatile handle used to reference this instance for alias based addressing.

 Name

A Name that adequately distinguishes this OSGi Framework from all other OSGi Frameworks. This must be the OSGi Framework UUID as stored in the org.osgi.framework.uuid property.

 Type

Indicates the complete type and specification version of this ExecEnv. For an OSGi Framework it must be:

OSGi <version>

Where the <version> is the value of the framework property org.osgi.framework.version

 InitialRunLevel

The run level that this ExecEnv will be in upon startup (whether that is caused by a CPE Boot or the Execution Environment starting). Run levels map to directly OSGi start levels. However, the OSGi Framework has no concept of an initial start level, it can use the org.osgi.framework.startlevel.beginning environment property but this requires a management to control it. A management agent must therefore handle this value and instruct the OSGi Framework to move to this start level after a reboot.

If the value of CurrentRunLevel is set to -1, then the value of this parameter is irrelevant when read. Setting its value to -1 must have no impact on the start level of this OSGi Framework.

 RequestedRunLevel

Sets the start level of this OSGi Framework, meaning that altering this parameter's value will change the value of the CurrentRunLevel asynchronously. Start levels dictate which Bundles will be started. Setting this value when CurrentRunLevel is -1 must have no impact on the start Level of this OSGi Framework. The value of this parameter is not part of the device configuration and must always be -1 when read.

 CurrentRunLevel

The start level that this OSGi Framework is currently operating in. This value is altered by changing the RequestedRunLevel parameter. Upon startup (whether that is caused by a CPE Boot or the Execution Environment starting) CurrentRunLevel must be set equal to InitialRunLevel by some management agent.

If Run Levels are not supported by this OSGi Framework then CurrentRunLevel must be -1.

 Version

The Version of this OSGi Framework as specified by its Vendor. This is not the version of its specification. Must be the value of the System Bundle's getVersion() method.

 Vendor

The vendor that produced this OSGi Framework, the value of the org.osgi.framework.vendor Framework property.

 ParentExecEnv

The value must be the path name of a row in the ExecEnv table, it can either be the operating system or another OSGi Framework if the framework is nested. If the referenced object is deleted, the parameter value must be set to an empty string. If this value is an empty string then this is the Primary Execution Environment.

 AllocatedDiskSpace

Implementation specific.

 AvailableDiskSpace

Implementation specific.

 AllocatedMemory

Implementation specific.

 AvailableMemory

Implementation specific.

 ProcessorRefList

Comma-separated list of paths into the DeviceInfo.Processor table. If the referenced object is deleted, the corresponding item must be removed from the list. Represents the processors that this OSGi Framework has available to it.

 ActiveExecutionUnits

Comma-separated list of paths into the ExecutionUnit table. If the referenced object is deleted, the corresponding item must be removed from the list. Represents the Bundles currently active on this OSGi Framework.

Device.SoftwareModules.

    DeploymentUnit.{i}.

This table serves as the Bundles inventory and contains status information about each Bundle. A new instance of this table gets created during the installation of a Bundle.

 UUID

A Universally Unique Identifier either provided by the ACS, or generated by the CPE, at the time of Deployment Unit Installation. The format of this value is defined by [2] RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace Version 3 (Name-Based) and [5] TR-069a3 CPE WAN Management Protocol. This value must not be altered when the Bundle is updated. A management agent should use the UUID as the bundle location since the location plays the same role.

 DUID

The Bundle id from the getBundleId() method.

 Alias

A non-volatile handle used to reference this instance.

 Name

Indicates the Bundle Symbolic Name of this Bundle. The value of this parameter is used in the generation of the UUID based on the rules defined in [5] TR-069a3 CPE WAN Management Protocol.

 Status

Indicates the status of this Bundle. Enumeration of:

  • Installing - This bundle is in the process of being Installed and should transition to the Installed state. This state will never be visible in an OSGi Framework.

  • Installed - This bundle has been successfully installed.This maps to the Bundle INSTALLED or RESOLVED state.

  • Updating - This bundle is in the process of being updated and should transition to the Installed state. This state will never be visible in an OSGi Framework.

  • Uninstalling - This bundle is in the process of being uninstalled and should transition to the uninstalled state.This state will never be visible in an OSGi Framework.

  • Uninstalled - This bundle has been successfully uninstalled. This state will never be visible in an OSGi Framework.

 Resolved

Indicates whether or not this DeploymentUnit has resolved all of its dependencies. Must be true if this Bundle's state is ACTIVE, STARTING, STOPPING, or RESOLVED. Otherwise it must be false.

 URL

Contains the URL used by the most recent ChangeDUState RPC to either Install or Update this Bundle. This must be remembered by a management agent since this information is not available in a Bundle.

 Description

Textual description of this Bundle, must be the value of the Bundle-Description manifest header or an empty string if not present.

 Vendor

The author of this DeploymentUnit formatted as a domain name. The value of this parameter is used in the generation of the UUID based on the rules defined in [5] TR-069a3 CPE WAN Management Protocol. The recommended value is the value of the Bundle-Vendor header.

 Version

Version of this Bundle, it mist be he value of the geVersion() method.

 VendorLogList

Empty String

 VendorConfigList

Empty String

 ExecutionUnitList

A path into the ExecutionUnit table for the corresponding ExecutionUnit for this Bundle, which is also the bundle since the relation is 1:1.

 ExecutionEnvRef

The value must be the path name of a row in the ExecEnv table of the corresponding OSGi Framework.

Device.SoftwareModules.

     ExecutionUnit.{i}.

This table serves as the Execution Unit inventory and contains both status information about each Execution Unit as well as configurable parameters for each Execution Unit. This list contains all the bundles since in an OSGi Framework Deployment Unit and Execution Unit are mapped to Bundles.

 EUID

Table wide identifier for a bundle chosen by the OSGi Framework during installation of the associated DeploymentUnit. The value must be unique across ExecEnv instances. It is recommended that this be a combination of the ExecEnv.{i}.Name and an OSGi Framework local unique value. The unique value for an OSGi framework should be the Bundle Location.

 Alias

A non-volatile handle used to reference this instance.

 Name

The name should be unique across all Bundles instances contained within its associated DeploymentUnit. As the Deployment Unit and the Execution Unit are the same the value must be the Bundle Symbolic Name.

 ExecEnvLabel

The name must be unique across all Bundles contained within a specific OSGi Framework. This must therefore be the Bundle Id.

 AutoStart

If true and the proper start level is met, then this Bundle will be automatically started by the device after its OSGi Framework's start level is met. If false this Bundle must not be started after launch until it is explicitly commanded to do so.

An OSGi bundle is persistently started or transiently started. It is not possible to change this state without affecting the active state of the bundle. Therefore, if the AutoStart is set to true, the bundle must be started persistently, even if it is already started. This will record the persistent start state. If the AutoStart is set to false, the bundle must be stopped. Therefore, in an OSGi Framework setting the AutoStart flag to true has the side effect that the bundle is started if it was not active; setting it to false will stop the bundle.

 RunLevel

Determines when this Bundle will be started. If AutoStart is true and the CurrentRunLevel is greater than or equal to this RunLevel, then this ExecutionUnit must be started, if run levels are enabled. This maps directly to the Bundles start level.

 Status

Indicates the status of this ExecutionUnit. Enumeration of:

  • Idle - This Bundle is in an Idle state and not running. This maps to the Bundle INSTALLED or Bundle RESOLVED state.

  • Starting - This Bundle is in the process of starting and should transition to the Active state. This maps to the STARTING state in OSGi. In an OSGi Framework, lazily activated bundles can remain in the STARTING state for a long time.

  • Active - This instance is currently running. This maps to the Bundle ACTIVE state.

  • Stopping - This instance is in the process of stopping and should transition to the Idle state.

 RequestedState

Indicates the state transition that the ACS is requesting for this Bundle. Enumeration of:

  • Idle - If this Bundle is currently in STARTING or ACTIVE state then the CPE must attempt to stop the Bundle; otherwise this requested state is ignored.

  • Active - If this Bundle is currently in the INSTALLED or RESOLVED state the management agent must attempt to start the Bundle. If this ExecutionUnit is in the STOPPING state the request is rejected and a fault raised. Otherwise this requested state is ignored.

If this Bundle is disabled and an attempt is made to alter this value, then a CWMP Fault must be generated. The value of this parameter is not part of the device configuration and is always an empty string when read. Bundles must be started transiently when the AutoStart is false, otherwise persistently.

 ExecutionFaultCode

If while running or transitioning between states this Bundle raises an Exception then this parameter embodies the problem. Enumeration of:

  • NoFault - No fault, default value.

  • FailureOnStart - Threw an exception when started.

  • FailureOnAutoStart - Failed to be started by the framework, this must be intercepted by the management agent because this is a Framework Error event.

  • FailureOnStop - Raised an exception while stopping

  • FailureWhileActive - Raised when a bundle cannot be restarted after a background operation of the Framework, for example refreshing.

  • DependencyFailure - Failed to resolve

  • UnStartable - Cannot be raised in OSGi since this is the same error as FailureOnStart.

For fault codes not included in this list, the vendor can include vendor-specific values, which must use the format defined in Section 3.3 of [6] TR-106a4 Data Model Template for TR-069-Enabled Devices.

 ExecutionFaultMessage

If while running or transitioning between states this Bundle identifies a fault this parameter provides a more detailed explanation of the problem enumerated in the ExecutionFaultCode.

If ExecutionFaultCode has the value of NoFault then the value of this parameter must be an empty string and ignored. This message must be the message value of the exception thrown by the Bundle.

 Vendor

Vendor of this Bundle. The value of the Bundle-Vendor manifest header

 Description

Textual description of this Bundle. The value of the Bundle-Description manifest header

 Version

Version of the Bundle. The value of the getVersion() method.

 VendorLogList

Empty string.

 VendorConfigList

Empty string.

 DiskSpaceInUse

Implementation defined

 MemoryInUse

Implementation defined

 References

Empty String

 AssociatedProcessList

Empty String as an OSGi bundle reuses the process of the VM.

 SupportedDataModelList

Comma-separated list of strings. Each list item must be the path name of a row in the DeviceInfo.SupportedDataModel table. If the referenced object is deleted, the corresponding item must be removed from the list. Represents the CWMP-DT schema instances that have been introduced to this device because of the existence of this ExecutionUnit. In OSGi this is implementation defined.

 ExecutionEnvRef

The path to the OSGi Framework that hosts this bundle in the ExecEnv table.

Device.SoftwareModules.

 ExecutionUnit.{i}.Extensions.

This object proposes a general location for vendor extensions specific to this Execution Unit, which allows multiple Execution Units to expose parameters without the concern of conflicting parameter names. This part is not used in OSGi.


155.3 References

[2]RFC 4122 A Universally Unique IDentifier (UUID) URN Namespacehttp://tools.ietf.org/html/rfc4122

[6]TR-106a4 Data Model Template for TR-069-Enabled Deviceshttp://www.broadband-forum.org/technical/download/TR-106_Amendment-4.pdf