ARRIS Enterprises, Inc. Confidential Information

IIP Attributes

Each IIP has a number of attributes:

Name - The name of the IIP.
Content version - The version of the IIP's content (such as binaries, application, boot loader).
Architecture - The hardware architecture the IIP is intended for.
Version - The build version of the IIP.
Branch - The branch which the IIP was built on.
Date - The date when the IIP was built.
Time - The time when the IIP was built.
Dependencies - Specifies what other IIPs are required for this IIP to work.
Description - An XML file describing the IIP and its parameters.
Installation scripts - One or more scripts used to install the IIP in a boot image at buildtime.
Data - Files used by the installation script(s).

Name

All IIP names shall follow the following structure:

<product or vendor>-<type>[-<what>]

Additionally, you will find the version and architecture as a part of the IIP file name. For information on that see the IIP Naming chapter.

Product or vendor

If an IIP is created by ARRIS, you will see the word kreatv here, i.e. the name of the software stack. Put vendor, middleware or company name here if the IIP is not created by ARRIS. This part may consist of lower-case letters and numbers only.

Type

The <type> part may only consist of lower-case letters and numbers.

kreatv-app-xyz - Holds a C++ application running on top of TOI/C++.
kreatv-common-xyz - Typically contains files (typically a library) used by several binaries packaged in different IIPs. These IIPs would be of DependencyOnly type and is not part of boot image configuration file.
kreatv-finalize-xyz - See Finalizers chapter of IIP building page.
kreatv-font-xyz - Includes one or several fonts.
kreatv-hal - Holds KreaTV Hardware Abstraction Layer related stuff.
kreatv-localportal-xyz - Holds an HTML or SVG application running in a browser on top of TOI/JS.
kreatv-option-xyz - Adding/enabling/disabling configuring functionality is done using option IIPs. Examples are AAC audio, adaptive video mode and DLNA.
kreatv-platform - The default core KreaTV platform services are packaged in this IIP.
kreatv-tool-xyz - Low-level system tools used in deployment and tools used during development. Examples are logging, process logging, command line SQLite program.

What

The <what> part may consist of lower-case letters, numbers and "-".

Examples

kreatv-app-webkit: Webkit browser application.
kreatv-option-usb: USB support as an option.

Content version

The version of the IIP's content (such as application, binaries, boot loader).

Content version attribute is specified with iip_build option --content_version.

Version

The build version can have the following formats:

General KreaTV release version format: <major>.<minor>[.<flavor>][.<candidate>]
You will see this version if release is built upon a general KreaTV release. <major> and <minor> are rather self explanatory. The <flavor> is a string describing the flavor of this major.minor release. It may be the name of a release. <candidate> lists a release candidate number.

Development drop version format: <branch>.<revision>
A development drop IIP may have this version format. Specified is software branch name and KreaTV repository revision.

Custom format:Version format can be the result of an agreement with a customer or partner.

Examples

4.3: Release 4.3.
4.3.turtle.5: Release candidate 5 of 4.3 with flavor turtle.
trunk.205123: Revision 205123 of branch trunk.
Meatball.1.2: Customer release Meatball with version 1.2.

Version attribute is specified with iip_build option --version.

Branch

The build branch is a string containing the name of the branch from which the IIP is built. It is used for debug purposes only.

Branch attribute is specified with iip_build option --branch.

Date

The build date is a string. It is used for debug purposes only. The format of the string is:

YYYYMMDD (%Y%m%d in Linux date command format)

Date attribute is specified with iip_build option --date.

Time

The build time is a string. It is used for debug purposes only. The format of the string is:

hhmmss (%H%M%S in Linux date command format)

Time attribute is specified with iip_build option --time.

Architecture

The architecture specifies which KreaTV STBs the IIP is intended for.

Architecture consists of:

Toolchain
Device

Each architecture field specifies the target of the IIP even more. For instance, if the architecture string is empty, then the IIP can be used on any KreaTV STB hardware or software. Example of such an IIP would be one containing only configuration files.

Toolchain and device are further explained in the architecture section.

Architecture is specified with iip_build options --toolchain and --device.

Dependencies

Sometimes the content of one IIP requires that a different IIP is also installed. In this case, we say that the IIP depends upon another IIP. This dependency information is used when building boot images. At build time, when installing an IIP to a boot image, the build_boot_image script will make sure that all the IIPs this current IIP depends upon are also installed.

Since the IIPs which are depended upon are added automatically, they do not have to be explicitly mentioned in the configuration. The order of installing the IIPs is set by the assigned dependency type. Depended-upon IIPs using the default dependency type (rootdisk) are installed before the IIP that depends on them.

Dependency types
Type	Description
rootdisk	A rootdisk dependency sets up the correct environment for the IIP. That means the depended-upon IIP is installed before the IIP at buildtime.
finalize	A finalize dependency can be specified in order to install a finalizer IIP after all other IIPs at build time. No guarantees are given that the finalizers are installed in a specific order, only that they are installed after all normal IIPs at buildtime.

The build_boot_image command makes sure that the IIPs are installed in the correct order if the dependencies are correct. All dependency types are by default fulfilled when building a boot image. Note that circular dependencies are strictly forbidden: they will cause the KreaTV IP-STB to fail.

Dependencies are specified with iip_build option --depends.

Description

The description of an IIP is XML file with a textual description of the purpose of the IIP and also a definition of all available parameters to the IIP. All possible IIP parameters must be documented (unless AllowAnyParameters is specified).

XML elements in an IIP description file
Element	Valid values	Required	Description
Description	Any string (possibly containing escaped HTML text)	Yes	Description of the IIP.
Deprecated	Any string (possibly containing escaped HTML text)	No	Specifies whether this IIP is deprecated. This will trigger a warning when building a boot image.
Parameter	See the table below	No	An optional parameter to the IIP.
DependencyOnly		No	Prevents the IIP from appearing in the boot image configuration file. The presence of this element is meaningful for IIPs that do not make sense to use on their own, but only in some larger context. Examples: An IIP which installs a (non-plugin) shared object. In this case, any IIP which installs a binary which links against the shared object will depend on said IIP. An IIP which provides documentation for some feature. In this case, the IIP providing the feature will depend on the IIP documenting the feature. Notes: If DependencyOnly is present, the IIP can only be configured if it inherits parameters from some other IIP (using the Inherit element). DependencyOnly and Explicit are mutually exclusive.
Explicit		No	Add this element to indicate that this IIP must be included in the boot image configuration file if needed in a boot image. Other IIPs may still depend on an Explicit IIP. Including such an IIP in the build without including the Explicit IIP in the boot image config leads to a boot image build error. This element encourages the boot image builder to read the documentation of the Explicit IIP to understand how it shall be configured. Explicit and DependencyOnly are mutually exclusive.
AllowAnyParameters		No	Add this element to indicate that any parameters can be specified for the IIP. If not present (i.e. by default), only parameters described in the Parameter elements are allowed for this IIP. Usage of AllowAnyParameters is not recommended since less consistency checks will be performed.
Inherit		No	Add this element to specify the name of an IIP from which this IIP inherits parameters during build of a boot image. See the How to solve changing graphics stack example on when you would want to do this. The name must be specified using the "iip" attribute.

Element Valid values Required Description

Name String Yes Name of the parameter.

Description Any string (possibly containing escaped HTML text) Yes Description of the IIP.

Repeat Once | Multiple No The number of times the parameter can be repeated.

BoolType,
EnumType,
FileType,
IntType,
StringType

The data type of the parameter. The boot image build framework will validate parameter values based on type before passing them to an IIP installation script. The type is specified by using one of the available type elements listed below.

StringType

The default type. It is used if no type element is specified. No value validation is done. It will be up to the IIP installation script to make sure the parameter value is correct.


<StringType/>

The meaning of specific values can be documented by adding a Description element for each value. The value descriptions will be listed in IIP documentation together with the parameter description.


<StringType>
  <Description value="none">something</Description>
</StringType>

BoolType

Either 'true' or 'false' will be passed to the IIP installation script. Values such as 'True', '1' and 'yes' will be converted to 'true' before passing them. Values such as 'False', '0' and 'no' will be converted to 'false' before passing them.


<BoolType/>

The meaning of specific values can be documented by adding a Description element for each value. The value descriptions will be listed in IIP documentation together with the parameter description.


<BoolType>
  <Description value="true">something 1</Description>
  <Description value="false">something 2</Description>
</BoolType>

EnumType

The value must be within a predefined set of valid values. The set of values is defined using one of more Enum elements added as child elements to the EnumType element.


<EnumType>
  <Enum value="red"/>
  <Enum value="blue">
    <Description>blue color</Description>
  </Enum>
</EnumType>

IntType

The value must be an integer.


<IntType/>

Optionally, a value range can be specified. The value range can be a lower bound, a higher bound or both at the same time (by including/excluding attributes).


<IntType low="0" high="10"/>

The meaning of specific values can be documented by adding a Description element for each value. The value descriptions will be listed in IIP documentation together with the parameter description.


<IntType low="-1">
  <Description value="-1">something</Description>
</IntType>

FileType

The value is a file path. The validation will make sure the file exists and with read access. The path can be either absolute or relative. A relative path is relative to the location of the boot image config in which the path is used to set the parameter.

A relative path will be converted to an absolute path before it is passed to the IIP installation script.


<FileType/>

Default String No Default value of the parameter. If present, a parameter with this value will be sent to the install script unless the parameter is explicitly specified in the boot image configuration.

Example Any string (possibly containing escaped HTML text) No Example use of the parameter.

Deprecated

Any string (possibly containing escaped HTML text)

Specifies that the parameter as a whole is deprecated, or that a specific parameter value is deprecated. Optionally, an alias can be specified, in which case the installation script will receive the alias instead of the deprecated parameter (value). The element content is used as a complementary text in the generated documentation of the parameter, but can be left empty.

The element has two optional attributes. The table below lists examples on how these variables are used.

Example	Description
`-`	The parameter as a whole is deprecated, i.e. deprecated regardless of its value.
`alias="otherparam=somevalue"`	The parameter is deprecated. The alias `otherparam=somevalue` will replace the deprecated parameter. The value of the deprecated parameter, if it exists, is not reused.
`alias="otherparam"`	The parameter is deprecated. The alias `otherparam` has no explicit value stated. The alias replacing the deprecated parameter will be `otherparam=<X>` where `<X>` is the value of the deprecated parameter. The alias attribute cannot contain an equal sign (`=`) because that would render the previous behaviour.
`value="deprvalue1"`	The parameter value `deprvalue1` is deprecated.
`value="deprvalue2" alias="param=bettervalue"`	The parameter value `deprvalue2` is deprecated. The alias `param=bettervalue` will be replacing the assignment of the deprecated parameter for that value.

It is possible to include other XML files with a special @include comment syntax (see the example below).

Example


<IipInterface>
  <Description>
    Description goes here. <![CDATA[<b>Note</b>: If you want to
    include HTML markup in any of the Description or Example fields, you must
    quote it, preferably using the
    <a href="http://en.wikipedia.org/wiki/CDATA">CDATA</a> construction.]]>
  </Description>
  <!-- The IIP is deprecated. When building a boot image, the specified warning
       will be triggered. -->
  <Deprecated>Please use kreatv-xxx instead.</Deprecated>
  <Inherit iip="kreatv-app-portal"/>
  <Parameter>
    <Name>paramname</Name>
    <Description>
      Parameter description goes here.
    </Description>
    <Repeat>Once</Repeat>
    <StringType/>
    <Default>somedefaultvalue</Default>
    <Example>paramname=thefileorvalueorwhateveryouwant</Example>
    <!-- The parameter is deprecated. -->
    <Deprecated>Some description</Deprecated>

    <!-- The parameter is deprecated. If specified (with any or no value),
         otherparam=somevalue will be used instead. -->
    <Deprecated alias="otherparam=somevalue"/>

    <!-- paramname=deprvalue1 is deprecated. -->
    <Deprecated value="deprvalue1"/>

    <!-- paramname=deprvalue2 is deprecated. If specified,
         paramname=bettervalue will be used instead. -->
    <Deprecated value="deprvalue2" alias="paramname=bettervalue"/>
  </Parameter>
  <DependencyOnly/>
  <AllowAnyParameters/>
  <!-- @include /path/to/included/file -->
</IipInterface>

Description data is built into the IIP with iip_build option --description.

Installation

Each IIP can contain one or more installation scripts used to install the IIP under different circumstances. The different types of installation scripts included in an IIP define its possible usage.

Installation types
Type	Description
buildtime	Used to install an IIP into a rootdisk at build time (i.e. when building the rootdisk/boot image). The build_boot_image script, which combines IIPs into a rootdisk and a boot image, allows parameters to be sent to the installation script. These parameters can e.g. be used to install different parts of the IIP or to configure the installed parts.
kit	Used to install an IIP into a KreaTV SDK. This type is only used internally at ARRIS.

You can write your own scripts if preferred. There are a number of predefined installation scripts available for the most common tasks of IIP installation:

Buildtime installation scripts

IIP buildtime installation scripts.
Name	Parameters	Description
copy_data_to_rootdisk	-	Used for simple IIPs that only need to copy some files into the rootdisk. Copies the data to the rootdisk. This means that the data needs to have the same directory structure as the rootdisk.
install_app_in_rootdisk	`start \| prop(<name>)=<value> \| prop(<name>)-`	Used for application registration packages. Copies the data to the rootdisk. Registers the application in the Application Service. The prop(<name>)- parameters are used to remove default property values. Note that any values you set using prop(<name>)=<value> will also be removed. If extra installation is needed, it is possible to add a script named extra/install to the data directory. Parameters not handled by install_app_in_rootdisk will be passed on to the extra installation script. More information regarding the parameters can be found in the table below.

These are the parameters that can be given to the install-app-in-rootdisk script:

install-app-in-rootdisk script parameters
Parameter	Description
`start`
`prop(<name>)=<value>`	The `prop(<name>)=<value>` parameters can be used to set/add properties in the application property file supplied to the Application Service. Note that any default value for a property (in the property file included in the registration package) will be replaced when using this parameter.
`prop(<name>)-`	The prop(<name>)- parameters are used to remove default property values. Note that any values you set using prop(<name>)=<value> will also be removed.

Installation scripts are built into the IIP with iip_build option --install.

Data

The data is a number of files which the installation script can use to install the IIP in a rootdisk. It can copy the files, use them as data source or as extra scripts to apply on the rootdisk.

The layout of the data depends on its intended usage:

All files shall be copied into a rootdisk

In this case it is easiest to use the same layout in the data dir as in the rootdisk. You can then use the copy_data_to_rootdisk installation script which will copy the data into the rootdisk at build time.

Only some files shall be copied to the rootdisk

In some cases it it easier to make an IIP installing only some of its files depending on the IIP parameters used. A typical example is the kreatv-font-file IIP which installs one or more font files.

In this case you can use any layout of the data directory that you desire and let the installation script install it in the correct place in the rootdisk. You must write your own installation script to make this work.

Only modify the rootdisk

Some IIPs only modify the rootdisk. A typical example is the kreatv-tool-logging IIP which creates a file in the /etc directory based on the parameters given to the IIP.

In this case it is not necessary to have a data directory (it would be empty) so don't create one.

Data directory is specified with iip_build option --data_dir.