SDK Upgrade Manifest (.slcu)

The SDK upgrade manifest file has the .slcu extension. It describes transformations to be performed on projects to make them compatible with a later version of the SDK.

An upgrade manifest consists of an object with a single top-level property upgrade. This property contains an array, where each item corresponds to a single upgrade transformation from one SDK version to another. The target SDK version is given by the sdk property, while the source SDK version is implicit, and will vary depending on whether the previous SDK or any intermediate SDK required any upgrade rules to be defined.

Component upgrade

The "component" property contains a list of component upgrades. A declarative upgrade has the format

Property	Required	Type	Description
trigger	Yes	string	Rule is triggered if component with this ID is present in the project
description	Yes	string	Description of the upgrade rule, to be shown to the user
remove	No	list[string]	List of components to remove if rule is triggered. Typically includes the trigger component.
add	No	list[string]	List of components to add if rule is triggered.

A scripted upgrade has the format

Property	Required	Type	Description
script	Yes	string	Path to the upgrade script relative to the upgrade manifest file
description	Yes	string	Description of the upgrade rule, to be shown to the user

Configuration upgrade

The "configuration" property contains a list of configuration upgrades. A declarative upgrade has the format

Property	Required	Type	Description
name	Yes	string	Configuration option to replace
replacement	Yes	string	New configuration option name
value	No	map[string,string]	Map of replacement options where the key is the old configuration value and the value is the new configuration value

A scripted upgrade has the format

Property	Required	Type	Description
script	Yes	string	Path to the upgrade script relative to the upgraded manifest file

Example

upgrade:
  # Upgrade to SDK 3.0.1
  - sdk:
      id: gecko_sdk
      version: "3.0.1"
    component:
      # Example declarative rule to perform simple component replacement
      - trigger: component_a
        description: >
          Component A has been separated into Component X and Component Y.
        remove:
          - component_a
        add:
          - component_x
          - component_y
      # Example scripted rule to perform advanced transformation, e.g. inspecting config
      - script: upgrade_component_b.lua
        description: >
          Component B has been overhauled by doing X, Y and Z.
    configuration:
      # Example declarative rule to perform simple config rename, with optional value remapping
      - name: C_FOO
        replacement: D_FOO
        value:
          C_FOO_ONE: D_FOO_ONE
          C_FOO_TWO: D_FOO_TWO
      # Example scripted rule to perform advanced config change
      - script: upgrade_config_c.lua
  # Upgrade to SDK 3.1.0
  - sdk:
      id: gecko_sdk
      version: "3.1.0"
    component:
      - trigger: component_x
        description: >
          Component X has been renamed Component F.
        remove:
          - component_x
        add:
          - component_f
    configuration:
      - name: X_BAR
        replacement: F_BAR
      - script: upgrade_config_x.lua

Upgrade Scripts

Scripted upgrades are performed by calling Lua scripts implementing component upgrades, configuration upgrades, or both. A Python binding is also supported for backwards compatibility for SDKs only, SDK Extensions must use Lua.

Namespaces

Global (SLC)

The SLC namespace provides functions to work on the project that is being upgraded. It has the following interface:

Method	Arguments	Return Type	Description
component	id (string) ID of component	Component	Returns a component object representing the component.
config	id (string) - ID of configuration option	Configurable	Returns a Configurable object representing the configuration, or nil if not defined.
component_selected	id (string) ID of component	bool	Returns true if the given component is selected in the project. Implementations should also allow is_selected as an alias for consistency with the Validation API.
is_provided	id (string) Name of provide	bool	Returns true if the given feature is provided in the project.

Component

The component object represents a component from the SDK. It has the following interface:

Member	Type	Description
id	string	The ID of the component
label	string	The display name of the component
instances	list[string]	List of selected instances in the active project if the component is instantiable.
is_instantiable	bool	True if the given component is instantiable.

Configurable

Member	Type	Description
id	string	Returns the name of the configuration option, i.e. <id> from #define <id> if the option is a CMSIS annotated configuration macro
value	String	Returns the current value of the configuration option

Component Upgrade Script

The component upgrade script is a Lua script. It returns a table of change actions to perform on the project.

A project change action is a table with the following data:

Key	Type	Mandatory	Description
component	string	Yes	ID of the component whose state should be modified in the project.
action	string	Yes	One of "add" or "remove", to add or remove the component from the project.
instance	list[string]	No	List of instance names to modify. If component is instantiable and this is not given for a "remove" action, all instances will be removed.

Example

local changeset = {}

if slc.is_selected('foo') then
  -- Replace foo with bar
  table.insert(changeset, {
    ['component'] = 'foo',
    ['action'] = 'remove',
  })
  table.insert(changeset, {
    ['component'] = 'bar',
    ['action'] = 'add',
  })
end

if slc.config('FOO_OPTION').value == '42' then
  -- Add the 'one' and 'two' instances of baz if FOO_OPTION is 42
  table.insert(changeset, {
    ['component'] = 'baz',
    ['instance'] = {'one', 'two'},
    ['action'] = 'add'
  })
end

if slc.is_selected('quux') and slc.component('quux').instances['cake'] then
  -- Remove the 'cake' instance of quux, leaving other instances alone
  table.insert(changeset, {
    ['component'] = 'quux',
    ['instance'] = {'cake'},
    ['action'] = 'remove'
  })
end

return changeset

Configuration Upgrade Script

The configuration upgrade script implements a function def configuration_upgrade(project), where project is an instance of Project representing the project being upgraded. The function returns a list of change actions to perform on the project.

A configuration change action is a map with the following data, containing keys from either A or B:

Key	Type	Mandatory	Description
option	string	Always	Configuration option to modify
action	string	A	Value of "remove" to remove the configuration option from the project
value	string	B	Set the value of the configuration option to this.

Example

local changeset = {}

local old_config = slc.config('FOO_OPTION')

if (old_config ~= nil) then
  -- FOO_OPTION had a non-default value
  table.insert(changeset, {
    ['option'] = 'FOO_OPTION',
    ['action'] = 'remove'
  })
  table.insert(changeset, {
    ['option'] = 'BAR_OPTION',
    ['value'] = tostring(tonumber(old_config.value) * 3)
  })
else 
  if slc.is_selected('foo') then
    -- The 'foo' component is present, but had a default value for FOO_OPTION
    -- The new 'bar' defaults deviate from the foo defaults, so we need to explicitly set them
    table.insert(changeset, {
      ['option'] = 'BAR_OPTION',
      ['value'] = '62'
    })
  end
end

return changeset