Component Validation

The validation_helper key is used in .slcc and .slcp files to register scripts that are executed whenever the project is generated. Scripts can be written in Lua and must have the .lua extension.

In a Lua validation script, the validation code is placed in global scope. The slc namespace has an API to observe different aspects of the project's state, while the validation namespace is used to emit warnings and errors. Additionally, the script may make use of libraries registered using the validation_library key in .slcc files. The library is available as a namespace named <name>, where <name> is defined by the .slcc file registering the library.

All validation helpers registered by components present in the resolved project are run whenever the project is generated. GUI tools may also run validation functions whenever configuration options are modified using the GUI tool. CLI tools may also expose an entry point to validate a generated project.

Example

local stack_size = slc.config('OS_CFG_STK_SIZE_MIN')
local min_size = stack_calculator.min_stack_size()

if not stack_calculator.ensure_stack_size(stack_size.value) then
  validation.warning('Small Stack Size'
                     validation.target_for_defines({stack_size.id})
                     'Stack size must be larger than or equal to ' .. min_size  .. ', was' .. stack_size.value,
                     validation.quickfix({min_size}, nil, nil)
                     )
end

using the library

local lib = {}

local _min_stack_size = 128

function lib.min_stack_size()
  return tostring(_min_stack_size)
end

function lib.ensure_stack_size(size)
  return tonumber(size) >= _min_stack_size
end

return lib

Validation API

The validation helper script uses methods on the slc namespace to inspect the state of the project and emit warnings and errors using the validation namespace.

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 feature	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

Validation

The Validation namespace provides functions to return warnings and errors for the configuration state of the project.

Method	Arguments	Return Type	Description
quickfix	suggested_values (list[string]) Suggested value(s) to fix the problem. other_variables (optional table[string, list[string]]) Suggested values for other configuration options. define_name (optional string) The configuration option to apply the suggested values to	QuickFix	Creates a quickfix object for the given define_name. Used to propose a change to the configuration state of the project to make it valid. If used in a warning or error context, the define_name can be omitted, as it is inferred from the context.
target_for_defines	defines (list[string]) List of configuration options to apply Problem Marker to	Target	Creates a Problem Marker Target to associate a warning or error with a configuration option.
target_for_pintool_requirements	requirements (list[string]) List of Pin Tool requirements to apply Problem Marker to	Target	Creates a Problem Marker Target to associate a warning or error to a Pin Tool requirement.
target_for_project		Target	Creates a Problem Marker Target to associate a warning or error with the project itself. Typically used when the problem is too complex to associate with individual configuration options.
warning	problem (string) Summary of the problem target (Target) Problem Marker Target for the warning message description (optional string) Description of the problem quickfix (optional QuickFix) Proposed fix for the problem		Presents a warning to the user about a problem with the current configuration.
error	problem (string) Summary of the problem target (Target) Problem Marker Target for the error message description (optional string) Description of the problem quickfix (optional QuickFix) Proposed fix for the problem		Presents an error to the user about a problem with the current configuration.