Skip to content

SAP Image Compiler (Scripted Programming & Image Creation)

For Cyclone LC, Cyclone FX, Cyclone MultiChannel

PEmicro’s Cyclone SAP image compiler (CSAP) is an essential component in the image creation process. It is designed to work in tandem with the Cyclone Image Creation Utility by running in the background, but it can also be called directly by the user. The CSAP image compiler typically takes either a .CFG file that was generated by the Image Creation Utility, or a SAPOBJ file, and uses it to locate and combine all of the components that will be included in the specific programming image that is being created. For more about why the user would choose to use one vs. the other, please refer to CFG Files Vs. SAPOBJ Files.

However, the user can also use a command line to submit a CFG file and various Command-Line Parameters directly to the image compiler. This allows users to write scripts that can automate the image creation/re-creation process.

In order for the user to do this, they will need to know what Command-Line Parameters are available, how they are used, and what items can/must be included in a CFG file. This includes Programming Commands and Configuration Commands. There is also a specific Command-Line Parameter that allows the user to easily substitute values inside a specific CFG file. This can enable a single CFG file to be used to create different programming images.

CFG Files Vs. SAPOBJ Files

Users often save a configuration file (.CFG) so they can later regenerate a new image from the same configuration and reference files. However, if any of the files have changed or been lost, such as the binary file or serial file, it is no longer possible to recreate the programming image with exactly the same data. The Cyclone Image Creation Utility addresses this by adding the ability to build a SAP object file (.SAPOBJ).

By checking the ‘Build to SAPOBJ only’ checkbox in the Image Creation Utility, a non-executable SAPOBJ object will be created that organizes everything needed for the programming image, including the programming script, programming settings, algorithm, power and communications settings, binary file - all in one place. Since all of the original information is saved into one file, if the user wants to start another production run and have the exact same programming data as a previous production, they can simply use the SAPOBJ to create an identical image. This eliminates potential issues if any of these original files are moved, deleted, or overwritten. They can load the desired SAPOBJ file, run the Deployment Manager utility, add the desired restrictions and encryption, and deploy a programming image from it.

Read more in the blog article The Magic of SAPOBJ.

Launching From the Command Line

The image compiler can be launched from the command line to create a programming image. Below is an example command line, along with descriptions of its various components.

Command-Line Example

Below is an example of using the command line to launch CSAP for ARM Cortex devices. The command line specifies where to locate the .CFG file and other necessary information.

csapacmpz.exe ! -INPUTCFG="C:\MyWorkspace\MyProject\KL25Z128_script.cfg" -DEPLOYSAPFILE="C:\MyWorkspace\MyProject\KL25Z128_image.sap" -DEPLOYDESCRIPTION="Test_KL25Z128"

Most command-line parameters can be used with any device, but some are specific to certain architectures or device types.

CSAP Executable

The user must first specify the particular CSAP executable that is compatible with their device. See the area of the example in green, which is specifically for ARM devices:

csapacmpz.exe ! -INPUTCFG="C:\MyWorkspace\MyProject\KL25Z128_script.cfg" -DEPLOYSAPFILE="C:\MyWorkspace\MyProject\KL25Z128_image.sap" -DEPLOYDESCRIPTION="Test_KL25Z128"

Below is a list of which executable corresponds to which architecture/device type.

Target Architecture / Executable Name

  • ARM-based devices (all manufacturers) : CSAPACMPZ.exe

  • MAC71XX, MAC72XX: CSAPARMZ.exe

  • HC(S)12(X): CSAPBDM12Z.exe

  • ColdFire V1: CSAPBDMCFV1Z.exe

  • ColdFire V2, V3, V4: CSAPBDMCFZ.exe

  • MPC5xx/8xx: CSAPBDMPPCZ.exe

  • DSC: CSAPDSCZ.exe

  • HCS08: CSAPHCS08Z.exe

  • HC08: CSAPMON08Z.exe

  • MPC55XX-57XX: CSAPPPCNEXUSZ.exe

  • RS08: CSAPRS08Z.exe

  • S12Z: CSAPS12ZZ.exe

  • STM8: CSAPWIZ01.exe

  • Renesas: CSAPWIZ00.exe

  • Infineon TriCore: CSAPTRICORE.exe

Filename and Additional Command-Line Parameters

After specifying the executable shown above, the user may also include one or more additional command-line parameters. The area of the example in violet shows an example of these other parameters in the command line.

csapacmpz.exe ! -INPUTCFG="C:\MyWorkspace\MyProject\KL25Z128_script.cfg" -DEPLOYSAPFILE="C:\MyWorkspace\MyProject\KL25Z128_image.sap" -DEPLOYDESCRIPTION="Test_KL25Z128"

List of Valid Command-Line Parameters

Note

​If there are white spaces inside a parameter, the parameter should be specified with double quotes “”. The command-line parameter identifier is case-insensitive.

Here is the listing of valid parameters:

[?]
Use the '?' character option to cause the utility to wait and display the result of configuration in the image compiler window. If the user does not use a batch file to test error level, this provides a method to display the configuration result. This option should be the FIRST command-line option.

[hideapp]
This will cause the CSAP executable to NOT display a visual presence while running, with the exception of appearing on the taskbar. (32-bit applications only)

[/logfile logfilename]
This option opens a logfile of the name "logfilename" which will cause any information which is written to the status window to also be written to this file. The "logfilename" should be a full path name such as c:\mydir\mysubdir\mylog.log.

[paramn=s]
A command- line parameter which can modify the executing script by replacing special tags (/PARAMn). Can be used to replace any part of the script including programming commands, filenames, and parameters. Valid values of n are 0..9. s is a string which will replace any occurrence of /PARAMn in the script file. See Using Command Line Parameters Inside a .CFG File for more information and examples.

Input Parameters

One of the following two parameters is required to select the input source:

[-inputcfg=”script filename with full path”]
Specify a script file to be used as input

[-inputsapobj=”SAPOBJ filename with full path”]
Specify a SAPOBJ file as input to create an image

Output Parameters

One of the following three parameters is required to select the output type:

[-deploytocloud]
Deploy an image directly to PEcloud.

[-deployimagefile=”filename”]
Replaces deploysapfile and deployjobfile.

[-deployimagetype=type]
type = STANDALONE for normal images. or = CLOUDCONNECTED for cloud-connected local images.

  • If -deploytocloud exists, it should be the only one of the above parameters used; for example:

    -deployimagefile="filename" -deployimagetype=standalone
    or -deployimagefile="filename" -deployimagetype=cloudconnected
    or -deploytocloud

  • If -deploytocloud is not present, then -deployimagetype must be used instead.

  • If -deployimagetype is missing for generating an image, the error code will be $50F, which has description "Error missing command line parameter for deploy image type DEPLOYIMAGETYPE= "

[-outputsapobj=”SAPOBJ filename with full path”]
Output a SAPOBJ to the specified path

Name / Description Parameter

Set a description/name for the programming image:

[-deploydescription=”description for image”]
Sets text as the description for an image. This becomes the Name for a cloud-connected image.

ImageKey File Parameter

Specifies a PE ImageKey file for encryption:

[-peimagekeyfile=”peimagekey file name with full path”]
Specifies a PE ImageKey file

Programming Restriction Parameters

The following parameters can be used to add restrictions to programming:

[-restrictdatefrom=mm/dd/yyyy]
Add restriction start date to an image

[-restrictdateto=mm/dd/yyyy]
Add restriction end date to an image

[-restrictmaxprograms=n] Restrict maximum number of programs to positive integer n.

[-restrictmaxattempts=n] Restrict maximum number of programming attempts to positive integer n.

Cloud Function Parameters

The following parameters can be used with the cloud:

[-job_vf_id=virtual factory id number]
Associates the PEcloud-tracked image with the specified Virtual Factory. PEcloud-tracked images include images distributed through PEcloud and images connected to PEcloud for execution control and result tracking.

[-forcenewjob]
Forces the previous PEcloud-tracked image with the same name in the same Virtual Factory to be disabled in the PEcloud Virtual Factory before the new image is created. Otherwise, image creation will fail if another image of the same name is distributed or tracked by the same Virtual Factory.

[-cloudcredentials=”file name for cloud credentials with full path”]
Specifies path to cloud credentials

Usage Examples

To use a script file to generate a SAPOBJ file:

-inputcfg="C:\PEMicro\cyclone\imageCreation\ImageCreationSupportFiles\cyclone2.cfg" -outputsapobj="test obj.sapobj"

To use an existing SAPOBJ file to generate a programming image:

-inputsapobj=testobj.sapobj -DEPLOYDESCRIPTION="This is a test" -deploysapfile=C:\PEMicro\cyclone\imageCreation\ImageCreationSupportFiles\test1.esap -peimagekeyfile=C:\PEMicro\cyclone\workspace\huajun_test3.peimagekey

To use a script file to generate a programming image:

-inputcfg="C:\PEMicro\cyclone\imageCreation\ImageCreationSupportFiles\cyclone2.cfg" -DEPLOYDESCRIPTION="This is a test" -deploysapfile=C:\PEMicro\cyclone\imageCreation\ImageCreationSupportFiles\test1.esap -peimagekeyfile=C:\PEMicro\cyclone\workspace\huajun_test3.peimagekey

Use an existing SAPOBJ file to generate a cloud-connected image directly:

/LOGFILE "C:\PEMicro\cyclone\imageCreation\ImageCreationSupportFiles\cyclone2.deploylog" -INPUTSAPOBJ="C:\PEMicro\cyclone\imageCreation\ImageCreationSupportFiles\cyclone2.sapobj" -DEPLOYOPTIONS="C:\PEMicro\cyclone\imageCreation\ImageCreationSupportFiles\cyclone2.deployoptions" -RESTRICTMAXPROGRAMS=1000 -RESTRICTMAXATTEMPTS=1000 -RESTRICTDATEFROM=05/30/2023 -RESTRICTDATETO=05/30/2024 -PEIMAGEKEYFILE="C:\PEMicro\cyclone\workspace\factory1.peimagekey" -JOB_VF_ID=30 -DEPLOYDESCRIPTION="Test_KE02Z64M4_EN_PM_VC_1000" -DEPLOYTOCLOUD -CLOUDCREDENTIALS="C:\PEMicro\cyclone\workspace\pecloud_api_PEmicro_Kevin_P_pemicro_com_2023_04_29_15_22_59.credentials"

Configuration (.CFG) File Contents

A Configuration (.CFG) file includes programming commands and the location of the binary files and programming algorithm to be used during programming. It may also include configuration commands and references to utilities that augment the programming process, such as serialization utilities or barcode-scanner setup information.

Note

​CSAP only supports serial files in JSON format.

Because the CFG file is essential to the process of creating a programming image, the command-line used to call CSAP must always use the '[-inputcfg=””]' parameter to specify a .CFG file. This file will instruct the image compiler which components will be used to create the eventual SAPOBJ and where to find them, among other things. On the other hand, when creating an image, a .CFG file is not necessarily required as input.

Sample .CFG File

A .CFG file is a plain ASCII file that includes one command per line. It will always include two main types of commands: Configuration Commands and Programming Commands. It can also include a certain type of command-line parameter that can serve as a placeholder for some of the script contents.

Below is a sample .CFG for NXP’s Kinetis KL25Z128 device. Lines in the file that begin with semicolons are comment lines.

The first several lines are comments that describe some of the attributes of the programming setup. The next several lines, which begin with a colon, are Configuration Commands that are read before programming. The final several lines are the Programming Commands that will be executed during the programming process.

; Automatically generated configuration file

; Silicon Manufacturer is NXP

; Silicon Architecture is ARM Based (Kinetis, LPC, etc.)

;

:ALLOWOUTOFRANGE 1

:DEVICE NXP_K7x_K70FN1M0M15

:USESWD 1

:DEBUGFREQUENCY 5560

:SAPGUIVERSION 352E3737

:PROVIDEPOWER

:POWERVOLTAGE 3.0

:POWERDOWNDELAY 250

:POWERUPDELAY 250

:KEEPPOWERON 0

:CUSTOMTRIMREF 31250.00

:NEWIMAGE

:DESCRIBEIMAGE Test_K70

CM C:\PEMicro\cyclone\supportfiles\supportFiles_ARM\NXP\K7x\freescale_k70fn1m0m15_1x32x256k_pflash.arp

CQ

QO C:\test\nxp\armcortex\mk_x_32_pflash_dflash_m5_05A0_1FFF.s19

EN ;Erase if not Blank

PM ;Program Module

VC ;Verify Checksum

Configuration Commands

Configuration Commands are commands that will be executed at startup, before the programming process. You can see configuration commands used inside a sample .CFG file above in Sample .CFG File. They listed are in the middle of the file. They always begin with a colon.

A listing of valid Configuration Commands and their formats is included below.

Target Power Related Configuration Commands

:PROVIDEPOWER n

Processors: All (EXCEPT MON08)

Determines whether the Cyclone should provide power to the target. (This is the same as legacy option :USEPRORELAYS n).

Note

​Not all hardware interfaces support this command. Valid values of n are:

0 : Cyclone does NOT provide power to target. (default)

1 : Enable Cyclone to provide power to target.

:POWERVOLTAGE n.n

Processors: All

Use this command if the Cyclone is providing/switching power to the target, otherwise omit this command. Specifies the target voltage as a real number. Acceptable range is from 1.6V - 5.0V.

Note

If an image is generated (using the current version the ICU) with separate settings for Cyclone and Cyclone MultiChannel, the Cyclone MultiChannel programmer will use the specific settings and ignore this one.

:POWERVOLTAGE 3.3 Specifies target voltage as 3.3V

:KEEPPOWERON n

Processors: All

Determines whether power provided to the target should be turned off when the application terminates. NOTE: Not all hardware interfaces support this command. Valid values of n are:

0 : Turn power off upon exit (default)

1 : Keep power on upon exit

:POWERDOWNDELAY n

Processors: All

Amount of time to delay when the power to the target is turned off for the target’s power supply to drop to below 0.1v. n is the time in milliseconds.

:POWERUPDELAY n

Processors: All

Amount of time to delay when the power to the target is turned on OR the target is reset, and before the software attempts to talk to the target. This time can be a combination of power on time and reset time (especially if a reset driver is used). n is the time in milliseconds.

:CUSTOMTRIMREF nnnnnnnn.nn

Processors: All

Desired internal reference clock frequency for the “PT; Program Trim” command. This frequency overrides the default internal reference clock frequency. Valid values for “nnnnnnnn.nn” depend on the particular device being programmed. Please refer to the electrical specifications of your device for valid internal reference frequency clock range.

Where:

nnnnnnnn.nn : Frequency in Hertz with two decimal places

Information Processing Configuration Commands

:CLEARSTATUS n

Processors: All

Specifies the amount of time after programming, in milliseconds, before the Success indicator (LED) will be turned off.

:DESCRIBEIMAGE string

Processors: All

string This is a string that describes the programming image. Will overwrite the command-line parameter “imagecontent” if both are present in the .CFG file.

Example:

:DESCRIBEIMAGE KL25Z128 TEST IMAGE

:ALLOWOUTOFRANGE n

Processors: All

Sets whether programming will continue when data is out of range.

:ALLOWOUTOFRANGE 1 Allows programming to continue when some data is out of range (addresses not in module). Out of range data is ignored.

:ALLOWOUTOFRANGE 0 Requires all programming data to be in range of the module. Out of range data causes an error on image creation.

Image Launch Settings Configuration Commands

:BARFILE barfile

Processors: All

Specifies that a .BAR file will be used during programming (programming initiated by bar code scanner).

barfile Indicates the path and filename of the .bar file.

Example:

:BARFILE C:\PEMicro\cyclone\imageCreation\barcodeTest.bar

:DEVICE string

Processors: ARM, DSC, MAC7xxx, TriCore

For ARM and TriCore devices, this is a mandatory parameter that specifies the device. It is required because the debug protocol changes between manufacturers and sometimes also between families or devices.

Where:

string: represents the device and follows the “VENDOR_FAMILY_DEVICE” format.

For ARM and TriCore devices, the easiest way to obtain the device string is from the Device Selection dialog in the Cyclone Image Configuration Utility software. In the PEMICRO Connection Manager, click “Select New Device” to open the Device Selection dialog. Expand the device tree to find your device, then right-click and select “Copy Device String to Clipboard.”

:DEBUGFREQUENCY n

Processors: ARM, ColdFire, PPC, MAC7xxx, TriCore

Specifies the communications frequency with the target device.

n Frequency in Kilohertz.

:USESWD n

Processors: ARM

Allows the user to specify SWD (single wire debug) mode instead of JTAG mode.

0 : Specifies that JTAG mode will be used during communications (default).

1 : Specifies that SWD (single wire debug) mode will be used during communications.

:JTAGTAPNUM n

Processors: ARM

The JTAG Tap Number is the index of the target device in the daisy chain. The first device connected to TDI is index 0, the next is index 1, and so on. The index of the last device connected to the TDO of the debugger is the total number of devices in the chain minus 1.

Note

This command is mandatory for JTAG daisy chain configurations. It is also important to specify JTAG communications using the :USESWD 0 command/value.

n : Specifies the index number of a device in the daisy chain.

For more information read this blog article on how to program or debug with a daisy chain setup.

:JTAGPREIR n

Processors: ARM

Every JTAG device has an IR register that is a certain width in bits. In the daisy chain the number of Pre-IR bits is the sum of all of the IR registers between your device and the TDO pin.

Note

This command is mandatory for JTAG daisy chain configurations. It is also important to specify JTAG communications using the :USESWD 0 command/value.

n : Specifies the total length of IR registers following the target device. The first device in the daisy chain is index 0.

For more information read this blog article on how to program or debug with a daisy chain setup

:RSTLOWPOSTSAP

Processors: All

Drives the RESET signal LOW before and after programming operations.

:DRIVEBKGDLOW n

Processors: S08, S12, CFV1, S12Z Note: Not RS08.

By default, the BKGD signal is driven low before and after programming operations are complete.

0 : Do NOT drive BGND low before and after programming operations.

non-zero or missing Drive BGND signal low before and after programming operations.

Example:

:DRIVEBKGDLOW 0 Does NOT drive the BKGD signal LOW after operations are complete.

:RSTLOWPOSTSAP

Processors: All

Drives the RESET signal LOW before and after SAP operations.

:USEPSTSIGNALS n

Processors: ColdFire

Specifies whether to use PST signals during debug.

0 : Do not use PST signals.

1 : Use PST signals.

:RSTLOWPOSTSAP

Processors: All

Drives the RESET signal LOW before and after SAP operations.

:DEBUGFREQUENCY n

Processors: ARM, ColdFire, PPC, MAC7xxx, DSC, PPCNexus

Specifies the communications frequency with the target device.

n : Frequency in Kilohertz.

:UNCENSOR n

Processors: PPCNexus, TriCore

This parameter should be used if 64-bit and 256-bit censorship passwords are needed to bypass security.

Note

​The ASCII version of the password must have each long word separated by a dash.

n : Password represented as a hexadecimal value, with no symbols or spaces

:RSTLOWPOSTSAP

Processors: All

Drives the RESET signal LOW before and after SAP operations.

:DEVICE string

Processors: ARM, DSC, MAC7xxx, TriCore

Describes the device being programmed.

string : Describes the device being programmed.

:RSTLOWPOSTSAP

Processors: DSC, STM8

Drives the RESET signal LOW before and after SAP operations.

:DEVICE string

Processors: ARM, DSC, MAC7xxx, TriCore

For ARM and TriCore devices, this is a mandatory parameter that specifies the device. It is required because the debug protocol changes between manufacturers and sometimes also between families or devices.

Where:

string : represents the device and follows the “VENDOR_FAMILY_DEVICE” format.

For ARM and TriCore devices, the easiest way to obtain the device string is from the Device Selection dialog in the Cyclone Image Configuration Utility software. In the PEMICRO Connection Manager, click “Select New Device” to open the Device Selection dialog. Expand the device tree to find your device, then right-click and select “Copy Device String to Clipboard.”

:DEBUGFREQUENCY n

Processors: ARM, ColdFire, PPC, MAC7xxx, DSC, PPCNexus, TriCore

Specifies the communications frequency with the target device.

n : Frequency in Kilohertz.

:RSTLOWPOSTSAP

Processors: All

Drives the RESET signal LOW before and after SAP operations.

:UNCENSOR n

Processors: PPCNexus, TriCore

This parameter should be used if 64-bit and 256-bit censorship passwords are needed to bypass security.

Note

​The ASCII version of the password must have each long word separated by a dash.

n : Password represented as a hexadecimal value, with no symbols or spaces

When using MON08 devices, the user must specify :POWERVOLTAGE and :POWERUPDELAY & :POWERDOWNDELAY.

:DEVICECLOCK n

For Class 5, 6, 7, and 8 devices. Controls whether the Cyclone should drive a clock to the target or whether the PEmicro interface should tristate its clock output. Valid values of n are:

0 : Clock driven by Cyclone. Must use :OUTPUTCLOCK to specify.

1 : Target self-clocked, Cyclone clock output disabled

:OUTPUTCLOCK n

Specifies the clock when :DEVICECLOCK is set to 0 (driven by Cyclone). Valid values of n are:

0 : 4.9152 MHz

1 : 9.8304 MHz

:CLOCKDIVIDER n

For Class 5, 6, 7, and 8 devices. Often one of the port pins of the target processor controls the ratio of the BUS clock to the External clock. Valid values of n are:

0 : Divide by 2 (usually and if applicable)

1 : Divide by 4 (usually and if applicable)

:BAUD n

Sets the baud rate to n. Serial port connection only If :BAUD is specified, include :FORCEPASS followed by :SECURITYCODE.

:FORCEPASS

Specifies that security should be passed on startup of the software instead of waiting for an EM (Erase Module) command. The :SECURITY code command must also be provided.

:SECURITYCODE hh hh hh hh hh hh hh hh

Specifies the 8 bytes of security code to use at startup which correspond to the addresses $FFF6-$FFFD of the target HC08 device. The parameter for this is a string containing 8 bytes of data in HEX separated by white spaces.

:DEVICETYPE string

Specifies the target device family. As an example, the device type for a 68HC908KX8 would be KX. The allowed device type values are:

AB,AP,AS,AT,AZ,BD,EY,GP,GR,GR4/8,GT,GZ,JB12,JB16, JB1/8,JG,JK,JL,JR,JW,KX,LB,LD, LJ,LK,LT,LV,MR4/8,MR16/32,QB,QC,QL,QT,QY,RF,RK,SR

:ARCHTYPE n

Processors: STM8

Specifies the STM8 family via the numeral n, where n indicates the following:

161 = STM8S/STM8A
162 = STM8L101X
163 = STM8L15X
164 = STM8L16X
165 = STM8AF
166 = STM8AL

:COMMSMODE 0

Processors: STM8

Indicates that communications speed should be controlled automatically.

:FORCEPASS

Processors: STM8

If this command is present, read-out protection will be ignored, i.e. the target will be unsecured and the programming process will continue.

If this command is missing, read-out protection will NOT be ignored. If the device is protected the programming process will not proceed.

:RSTLOWPOSTSAP

Processors: All

Drives the RESET signal LOW before and after SAP operations.

Be Aware

These require a Cyclone model (potentially with adapter) that supports Renesas processors.

:ARCHTYPE n

Processors: Renesas

Specifies the Renesas family via the numeral n, where n indicates the following:

177 = R8C
178 = H8 or HS8/Tiny
179 = M16C
180 = M16C/80
181 = M32C
182 = RL78
183 = RX
184 = RX63T
185 = RH850

:FORCEPASS

Processors: Renesas

If this command is present, read-out protection will be ignored, i.e. the target will be unsecured and the programming process will continue.

If this command is missing, read-out protection will NOT be ignored. If the device is protected the programming process will not proceed.

:RSTLOWPOSTSAP

Processors: All

Drives the RESET signal LOW before and after SAP operations.

Programming Commands

Programming Commands are the commands that will be executed during the programming process. These are the main commands that will manipulate and verify data on your device. A list of programming commands and their formats is included below.

See Sample .CFG File to view programming commands within a CFG file. The example programming commands are at the bottom of the file.

Note

​The command parameter formats starting_addr, ending_addr, base_addr, and byte, word are hexadecimal by default.

BM Blank check module.

BR starting_addr ending_addr Blank check range.

CM Choose module (algorithm) file. Note: Certain modules may require a base address to be specified

CQ Clears queue of object files to be programmed (see QO command)

CU either

EB starting_addr ending_addr Erase byte range.

EW starting_addr ending_addr Erase word range.

EM Erase module.

EN Blank check and erase

GO Starts device running. Can be used as final command if you want the device to run for testing. Should be immediately preceded by an 'RE' command.

PB starting_addr byte ... byte Program bytes.

PF feature_ID starting_addr Program feature data. feature_ID must be: datestr, datetimestr, barcodestr, or runtestdata.

PW starting_addr word ... word Program words.

PM Program module.

PT [address] Program trim (Devices with trim only. Address is only necessary for devices that have no dedicated non-volatile trim register)

RE Reset chip.

QO path Specify binary data file (S19/Elf/Hex). path indicates file path to the binary. Path is added to a queue of object files to be programmed. See also: CQ command.

VC Verify the programmed device using a checksum

VM starting_addr ending_addr Verify module.

VR starting_addr ending_addr Verify range.

VV type Verify module CRC. Type is CRC8 or CRC16.

DE timeinms - Delays "timeinms" milliseconds

Using Command Line Parameters Inside a .CFG File

The user may wish to make their .CFG files more versatile by inserting one or more placeholders into the script, and then specifying the values for those placeholders later, on the command line, when calling the CSAP executable that will reference that script.

The command-line parameter /PARAMn=s can be used to insert text into a .CFG file. It can replace any part of the script including programming commands, filenames, and parameters. n is a numeral from 0..9, which allows you to use multiple versions of this command line parameter in a .CFG file. s represents a string which will replace any occurrence of /PARAMn in the script file.

As an example, the following section of a .CFG script features three instances of /PARAMn=s: /PARAM1, /PARAM2, and /PARAM3: 

RE ;Reset the MCU

CM /PARAM1 ;Choose Flash Module

EM ;Erase the module

BM ;Blank Check the module

CQ ; Clear Queue of object files to be programmed

QO /PARAM2 ;Specify the S19 to use, it is added to the Queue of Object Files

PM ;Program the module with the S19

/PARAM3 ;Verify the module again
When the user calls the CSAP executable that will reference this CFG file they will need to specify the values of these parameters on the command line. See the example below, where the first of these parameters is used to specify a programming algorithm (.SRP), the second an .S19 file, and the third a programming command (VM). 
CSAPACMPZ

/PARAM1=C:\PEMICRO\Freescale_MK40X256_PFlash_DFlash.ARP

“/PARAM2=C:\PEMICRO\EXAMPLE FILES\TEST.S19"

/PARAM3=VM

Note

​Notice that /PARAM2 is enclosed in double quotation marks. This is because the parameter has a space in its value (Example Files). The surrounding double quotation marks are required in this situation, in order to indicate to Windows that it is a single parameter.

The complete example command line would be as below (note that this is one continuous line; no line breaks): 

C:\PROJECT\CSAPACMPZ -INPUTCFG=”C:\PROJECT\GENERIC.CFG “/PARAM1=C:\PEMICRO\Freescale_MK40X256_PFlash_DFlash.ARP “/PARAM2=C:\PEMICRO\EXAMPLE FILES\TEST.S19” /PARAM3=VM

Sample Batch File

Here is an example of how to call a command-line programmer and test its error code return in a simple batch file. Sample batch files are given for Windows 10/11.

Windows 10/11

C:\PEMicro\CYCLONE\IMAGECREATION\IMAGECREATIONSUPPORTFILES\CSAPACMPZ.EXE -INPUTCFG=”C:\PROJECT\ENGINE.CFG”

PORT=USB1

if errorlevel 1 goto bad

goto good

:bad

ECHO BAD BAD BAD BAD BAD BAD BAD BAD

:good

ECHO done

Note

​Path names of files that are relative to the CSAP executable can also be used.

CSAP Error Returns

An Error code is returned by the image compiler so that a script file or an application launching the image compiler can check for it. The error codes used are:

0 - Program completed with no errors.
1 - Canceled by user.
2 - Error reading S record file.
3 - Verify error.
4 - Verify canceled by user.
5 - S record file is not selected.
6 - Starting address is not in module.
7 - Ending address is not in module or is less than starting address.
8 - Unable to open file for uploading.
9 - File write error during upload.
10 - Upload canceled by user.
11 - Error opening algorithm file.
12 - Error reading algorithm file.
13 - Device did not initialize.
14 - Error loading .PCP file.
15 - Error enabling module just selected.
16 - Specified S record file not found.
17 - Insufficient buffer space specified by .PCP to hold a file S-record.
18 - Error during programming.
19 - Start address does not point into module.
20 - Error during last byte programming.
21 - Programming address no longer in module.
22 - Start address is not on an aligned word boundary.
23 - Error during last word programming.
24 - Module could not be erased.
25 - Module word not erased.
26 - Selected algorithm file does not implement byte checking.
27 - Module byte not erased.
28 - Word erase starting address must be even.
29 - Word erase ending address must be even.
30 - User parameter is not in the range.
31 - Error during algorithm-specified function.
32 - Specified port is not available or error opening port.
33 - Command is inactive for this .PCP file.
34 - Cannot enter background mode. Check connections.
35 - Not able to access processor. Try a software reset.
36 - Invalid algorithm file.
37 - Not able to access processor RAM. Try a software reset.
38 - Initialization canceled by user.
39 - Error converting hexadecimal command number.
40 - Configuration file not specified and file prog.cfg does not exist.
41 - Algorithm file does not exist.
42 - Error in io_delay number on command line.
43 - Invalid command line parameter.
44 - Error specifying decimal delay in milliseconds.
47 - Error in script file.
49 - Cable not detected.
50 - S-Record file does not contain valid data.
51 - Checksum Verification failure - S-record data does not match MCU memory.
52 - Sorting must be enabled to verify flash checksum.
53 - S-Records not all in range of module. (see "v" command line parameter).
54 - Error detected in settings on command line for port/interface.
58 - Device requires a power cycle.
60 - Error calculating device CRC value.
61 - Error - Device CRC does not match value given.
70 - Error - CSAP is already running.
71 - Error - Must specify both the INTERFACE and PORT on the command line.
72 – The selected target processor is not supported by the current hardware interface.