15.4.8 Tcl Interface

new_prog_data   -data_name <name>
                -import_file <path>
                [-keyset_file < keyset_name>]

• name - Programming data entry name.
• path - Libero design data file (JDC).
• keyset_name - Name of the keyset file. File name only. The file will be in the keyset directory as specified in the Application settings.

This command creates a new Programming Data entry from JDC (design data exported from Libero project). If keyset parameter is specified, HSM handles all the key management.

set_key -data_name <name> 
[-upk1 <upk1_value>] [-uek1 <uek1_value>] [-upk2 <upk2_value>] [-uek2
<uek2_value>] [-dpk <dpk_value>] [-uek3 <uek3_value>]

• name - Name of the Programming Data.
• uek*_value - New value for the selected encryption key.
• upk*_value - New value for the selected pass key.
• dpk_value - New value for the DPK.

This command overwrites key values imported from JDC with the ones specified in the command arguments.

remove_key   -data_name <name> 
             -key_names <ALL UPK1 UEK1 UPK2 UEK2 DPK> UEK3

• name - Name of the Programming Data.
• key_names - Names of the keys whose values to be reverted (can specify multiple values).

This command reverts the value of the specified encryption and/or pass key to the value imported from JDC. This command supports action opposite to set_key.

set_security_overwrite -data_name <name> -file <spm_file_path>

• name - Name of the Programming Data entry.
• spm_file_path - File path of the new SPM file.

This command overwrites design security settings imported from Libero through the new SPM file. This command is applicable to HSM and non-HSM flows. How the security policies and keys are overridden is explained below:

• Security policies: Always overwritten from the new SPM file (HSM and non-HSM flows)
• Security Keys (UPK1, UEK1, UPK2, UEK2, UEK3, and DPK)
  • Non-HSM flow:
    • If set_key is run before or after this command, then all keys specified in set_key are used. The keys that are not specified are taken from the new SPM file provided as argument.
    • If set_key is not run, then all security keys are taken from the new SPM file.
  • HSM flow:
    • Security keys are always taken from the keyset file.

remove_security_overwrite -data_name <name>

• name - Name of the Programming Data entry.

This command removes existing security overwrite settings. This command supports action opposite to set_security_overwrite.

set_new_keys_for_rotation -data_name <name> \
                          [-keyset_file <keyset_name>] \ 
                          [-upk1 <upk1_value>] \ 
                          [-uek1 <uek1_value>] \ 
                          [-upk2 <upk2_value>] \ 
                          [-uek2 <uek1_value>] \ 
                          [-dpk <dpk_value>] \ 
                          [-uek3 <uek3_value>]

• name - Name of the Programming Data.
• keyset_name - Name of the keyset file containing new key values.
• uek*_value - New value for the selected encryption key.
• upk*_value - New value for the selected pass key.
• dpk_value - New value for the DPK.

This command is used to specify the new key values that user wants to replace with an already programmed secured device as part of Key Rotation flow. For more information, see 15.4.7.3 HSM Flow and 15.4.7.4 Non-HSM Flow.

set_envm_update   -data_name <data> 
                  -client_name <client>
                  -file < file_path>
                  [-overwrite <YES | NO>]

• data - Programming data entry name.
• client - Name of the target eNVM client.
• file_path - File path of the client update data file.

This command creates a new client update entry in the specified Programming Data. If an update already exists for that client, the command will fail unless the optional -overwrite parameter is set to "yes". Data file size must not exceed the client size defined by the Libero project and imported via the JDC file. This command allows using all eNVM data file formats that Libero supports. For more information, see Libero SoC Design Flow User Guide . This command is available for the PolarFire® SoC device family.

remove_envm_update   -data_name< data > 
                     -client_name < client > 
                     -all <YES| NO>

• data - Programming data entry name.
• client - Name of the target eNVM client.
• all - Removes all clients. Default is "YES"

This command removes an entry that set_envm_update created. All client updates can be removed using "all" key set to "YES". A removed client update results in the client being reverted to the original eNVM data received in the JDC.

set_snvm_update   -data_name <data> 
                  -client_name <client> 
                  -file < file_path>
                  [-overwrite <YES | NO>]

• data - Programming data entry name.
• client - Name of the target sNVM client.
• file_pathc - File path to the client update data file.

This command creates a new client update entry in the specified Programming Data. If an update already exists for that client, the command will fail unless the optional -overwrite parameter is set to "YES". Data file size must not exceed the client size defined by the Libero project and imported via the JDC file. This command allows using all sNVM data file formats that Libero supports. For more information, see Libero SoC Design Flow User Guide .

The command is available for the PolarFire and PolarFire SoC device family.

init_bitstream   -data_name "design data name" \
        -bitstream_name "bitstream name" \
        -bitstream_type "TRUSTED_FACILITY | MASTER | UEK1 | UEK2 | UEK3 | KEY_ROTATION | DEBUG" \
        [-features "[ALL | FABRIC | ENVM | SNVM | SECURITY]+"] \
        [-use_protocol "AUTH_CODE | UNIQUE_KEY"] \
        [-unique_key_types "[UPK1 | UEK1 | UPK2 | UEK2 | UEK3 | DPK]+"] \
        [-envm_clients "[eNVM client selection]+"] \
        [-snvm_clients "[sNVM client selection]+"] \
        [-generate_coc "TRUE | FALSE"] \
        [-auth_keymode "DFK | KFPE | KFP | KUP | KUPE"] \
        [-enable_key_rotation "TRUE | FALSE"] \
        [-auto_inc_design_version] \
        [-first_keymode "UEK1 | UEK2 | UEK3"] \
        [-enable_passkey_export "TRUE | FALSE"]

• data_name - Name of the Programming Data entry.
• bitstream_name - Name of the bit stream being added (without path or extension).
• bitstream_type - Specifies bit stream type. The resulting bit stream will be generated according to the security policy specified in the Programming Data Security settings. Only one of the following bit stream types can be selected at a time:
  • TRUSTED_FACILITY - For the Non-HSM flow only. Programs selected bit stream components (Fabric, eNVM, or non-authenticated plain text sNVM clients) using KLK key mode.
  • ​Initiator - Programs security and any other selected components.
    • For the Non-HSM flow: Uses the KLK key mode to program security and other components. If security is programmed with UEK1/UEK2, then bit stream will also include plaintext UPK1/UPK2 respectively to enable erase and verify actions.
    • For the HSM flow: Uses DFK, KFP, KFPE, KUP, and KUPE key modes to program security and other components. In this case, all keys are encrypted by HSM.
      • UEK1 - Programs (updates) selected bit stream component(s) (Fabric/eNVM/sNVM) using UEK1 key mode. If the target component is update-protected, UPK1 will be used to unlock target component.
        • For the Non-HSM flow, generated bit stream uses plain text UPK1 value unlocking security.
        • For the HSM flow, the M-HSM performs security unlock using the encrypted value of UPK1.
      • UEK2 - Similar to UEK1, but uses UEK2 and UPK2 respectively.
      • UEK3 - Similar to UEK1, but uses UEK3. Supported for M2S060, M2GL060, M2S090, M2GL090, M2S150, and M2GL150 devices.
  • KEY_ROTATION - Specifies that bit stream will be used for updating user keys, see 15.4.7 Key Rotation section.
  • DEBUG - Initializes bit stream that can be used for debugging with tools like SmartDebug that require HSM support to unlock device debug features using One Time Passkey protocol protected by user encryption keys. This type of bit stream requires specification of the protocol (ONE_TIME_PASSCODE) in the current version and auth_keymode that can be UEK1 or UEK2 depending on security settings.
• features - Any combination of the features or ALL (default option) SECURITY is selected for programming.
  Important: Security is always programmed in the ​Initiator bit stream.
  • FABRIC - Selected for programming.
  • eNVM - Selected for programming. Supported for SmartFusion 2, IGLOO 2, and PolarFire SoC devices.
  • sNVM - Selected for programming. Supported for PolarFire and PolarFire SoC devices.
  • ALL - All features available in Design Data to be selected (default).
  Important: For PolarFire devices, Fabric and sNVM must be programmed all at once. Separate programming of sNVM disables Fabric.
• use_protocol - Allows selecting one of the following HSM security protocols:
  • AUTH_CODE - Securely sends Encryption Key (KIP) to the device using Authorization code. Use this option when all the user keys are project keys. This protocol supports INITIATOR bit stream flow and UEK1/UEK2/UEK3 update bit streams flow.
  • UNIQUE_KEY - Allows programming unique per-device keys in the ​Initiator flow. For the UEK1/UEK2/UEK3 update flow, this option can be used to generate per-device bit stream files (if DSN is known at the time of job or bit stream file generation) or to use per-device keys during programming jobs using the M-HSM.
• hsm_protocol_parameters -

  -unique_key_types <UEK1 UEK2 UPK1 UPK2 DPK UEK3>

  Parameter required for UNIQUE_KEY protocol. It specifies which of the user keys are per-device keys. Each per-device key is derived from a base key and Device Serial Number (DSN) during programming, which makes it device-specific.

  Important: UEK3 is supported for M2S060, M2GL060, M2S090, M2GL090, M2S150, and M2GL150 devices only.
• generate_coc - Parameter to setup the generation and export of Certificate of Conformance.

  This command allows the user to setup parameters for bit stream generation. Actual generation occurs upon job or bit stream file export. Bitstream generation is based on design information in the Programming Data entry, including all modifications such as eNVM update, security overwrites, and so on.

• auth_keymode - Specifies what key mode to use for Authorization component in INITIATOR bit stream HSM flow. This parameter is required for M2S060, M2GL060, M2S090, M2GL090, M2S150, M2GL150, and all PolarFire and PolarFire SoC devices and optional for the rest of SmartFusion 2 and IGLOO 2 devices. The following table shows the valid and default value of this parameter.
• enable_passkey_export - By default, the programming or the job file does not contain plain text UPK values. Use -enable_passkey_export to include plain text UPK values in the STAPL or the JOB file. Set to TRUE in the non-HSM flow to allow erase/verify operations, if security is programmed.
  Important: By default, UPKs are not staged to prevent security risks.

  Device	Valid Values
  PolarFire® and PolarFire SoC devices M2S060, M2GL060, M2S090, M2GL090, M2S150, M2GL150	KFP, KFPE, KUP, KUPE
  Other SmartFusion® 2 and IGLOO® 2 devices	DFK

• enable_key_rotation - Used to generate an ​initiator file, which allows updating user keys using Key Rotation flow. The UNIQUE_KEY protocol is not supported.
• auto_inc_design_version - Flag to automatically increase design version in each of the exported key rotation bit stream file. This parameter is set by default if Auto-Update flow is enabled in JDC.
• first_keymode - Denotes the key mode used to encrypt the first key rotation bit stream file (*_rotate_1_uks*). If user is aware that particular User Key Set is not compromised, then they can use it to securely start the key rotation flow.

The following is an example of bit stream settings for the SmartDebug tool.

init_bitstream -data_name {MyProgData} -bitstream_name {MyDebugBitstream} -bitstream_type {DEBUG} \
-features {ALL} -use_protocol {ONE_TIME_PASSCODE} -auth_keymode {UEK1}

export_bitstream_file   -data_name <name> 
                        -bitstream_name <bitstream_name>
                        -formats <format_selection>
                        -export_path <path > [-dsn <dsn_value>]

• name - Name of the programming data.
• bitstream_name - Name of the bit stream entry to be exported.
• format_selection - Any combination of the format types. File will be created for each selected type:
  • STAPL file (non-HSM and HSM update flow)
  • SPI file (non-HSM and HSM update flow)
  • DAT file (non-HSM and HSM update flow)
• path - Complete file path without any extension. Extensions are determined based on format parameters above.
• dsn - Device Serial Number (DSN) of the device for which to generate per-device UEK1/2/3-bit stream files.

This command generates and exports specified format bit stream file(s). The bit stream file is generated based on the information provided in the Programming Data entry.

add_hsmtask_to_job   -job_name <job>
                     -hsmtask_name <task> 
                     [-m_request_type {INTERNAL|EXTERNAL}]

• job - Name of the programming (or debug) job for which task is created.
• task - Name of the HSM Task. Must be unique within the job.
• m_request_type - Specifies how the M-HSM request is executed.
  • INTERNAL - This mode can only be specified if the same physical User HSM is used to generate and execute the programming job. In this case, the Job Manager will internally execute the request.
  • EXTERNAL - Default mode requires user to export the request, process it using FlashPro Express, and then import it back into the Job Manager project.

This command creates a new HSM Task for the specified programming job. The HSM task can contain one or more job tickets. This HSM task is then used to send a job request to the M-HSM and the job response received is imported into the HSM Task, which then enables HSM task export.

new_hsmtask_ticket   -job_name <job>
                     -hsmtask_name <task>
                     -ticket_name <ticket>
                     -device <device>
                     -actions <programming action | DEBUG>
                     -max_device <max>

• job - Name of the programming job which adds a new ticket.
• task - Name of the task within the Job.
• ticket - Name of the new ticket. Must be unique within the task.
• device - Name of the target device in the Job for the new ticket.
• action - Programming action for the ticket.
  • DEBUG: SmartDebug action for the ticket.
• max - Overbuild protection: max devices to use this ticket. Can be 'unlimited'.

This command creates a new job ticket for the HSM Task. The HSM task can have one or more job tickets for each device, but each job ticket is created per programming action. The overbuild protection parameter max_device is applicable to the protocols that are capable of controlling the number of authorized devices, such as the Authorization Code and Unique Key protocols.

hsmtask_m_request   -job_name <job> 
                    -hsmtask_name <task>
                    -request_file <path>

• job - Name of the programming job that contains target HSM Task.
• task - Name of the HSM task for which CM request is being generated.
• path - Full file name of the request container.

This command creates a job request that is required to perform a handshake protocol with the M-HSM (FlashPro Express or IHP). Once FlashPro Express has processed the request, it generates and exports a Job Reply that must be imported into the HSM Task on the Job Manager side. This handshake protocol guarantees one time use of the HSM Task on the FlashPro Express or IHP side (M-HSM), thus preventing job replication. This command is only applicable if the HSM task was created with the request set to EXTERNAL value (default). See add_hsm_task for details.

hsmtask_m_reply   -job_name <job> 
                  -hsmtask_name <task>
                  -reply_file <path>

• job - Name of the programming job that owns target HSM Task.
• task - Name of the task in the job.
• path - Full file name to the container with Job Response.

Import job reply by FlashPro Express or IHP (M-HSM). This command is only applicable if the HSM task was created with the request set to EXTERNAL value (default). See add_hsm_task for details. For more information, see the process_job_request FlashPro Express command documented in the Tcl Commands Reference Guide .

export_hsmtask   -job_name <job> 
                 -hsmtask_name <task>  
                 -location <path>
                 -name <file_name>

• job - Name of the programming job that contains task being exported.
• task - Name of the task in the job.
• path - Location of the export container.
• file_name - File name for the export container.

This command exports the HSM job for further execution by FlashPro Express or IHP. This can only be executed after importing job reply.

export_spi_directory   -golden_ver <value or SPI file> 
                       -golden_addr <hex value> 
                       -update_ver <value or SPI file> 
                       -update_addr <hex value> 
                       -file <file_name>

• golden_ver <value or SPI file> - Specifies Golden SPI Image design version. There are two ways to specify the value:
  • Decimal value less than 65536 (exclusive)
  • SPI file from which the design version is read.
• -golden_addr <hex value> - Specifies Golden SPI Image address where hex is 32-bit hexadecimal value with prefix 0x/0X.
• -update_ver <value or SPI file> - Specifies Update SPI Image design version. There are two ways to specify the value:
  • Decimal value less than 65536 (exclusive)
  • SPI file from which the design version is read.
• -update_addr <hex value> - Specifies Update SPI Image address where hex is a 32-bit hexadecimal value with prefix 0x/0X.
• -file <file> - Mandatory argument; specifies the file export location.

Supported Families

• SmartFusion 2
• IGLOO 2

export_spi_directory \
-golden_ver {D:\flashpro_files\m2s025_jb_spi_dir\designer\a1_MSS\export\a1_MSS.spi} \
-golden_addr {0xa} \
-file {D:\flashpro_files\jobmgr_project12\dev.spidir}

export_spi_directory \
-update_ver {456} \
-update_addr {0xdef} \
-file {D:\flashpro_files\jobmgr_project12\dev.spidir}

export_spi_directory \
-golden_ver {123} \
-golden_addr {0xabc} \
-update_ver {456} \
-update_addr {0xdef} \
-file {D:\flashpro_files\jobmgr_project12\dev.spidir}