Run Test - Custom Test Applications in the Programming Sequence

For Cyclone FX, Cyclone FX MultiChannel

As part of the production programming process, certain Cyclone programmers have the ability to program and run a series of custom test applications in the target processor before final programming is allowed to occur. These custom test applications, written by the end user, indicate to the Cyclone through the debug interface whether the test application was successful or not and also optionally return generated data to the Cyclone for use later in the programming process. If any of the test applications fail, programming does not continue. If all the test applications pass, the final application is programmed into the target and can optionally include any data generated by the test applications. This "Run Test" process is shown here:

Example uses of the Run Test feature during programming:

• Verify that the target hardware works as intended before programming
• Add information from the Cyclone, such as a scanned barcode or current date and time to the final programmed data
• Uniquely fingerprint each target based upon its Unique ID using any algorithm. This fingerprint could be later verified or read by the final application in the field.
• Precisely calibrate an RTC crystal using an External Timer/Counter
• Fetch Data from user input on the Cyclone Screen and add to the final programming data
• Add information from inputs on the target processor to the final programming data, such as:
• Data could be read from external devices on the PCB such as recording the serial number of external flash memories (to prevent them from being changed for instance)
• Data could be read from communications interfaces connected to the target processor. For instance, if the target being programmed had a network connection, data could be read from a local PC or an internet server and added to the data to be programmed.

Run Test Availability

The Run Test advanced control/automation feature is a standard feature on Cyclone FX programmers. It is not available on Cyclone LC models. The user should be sure to install the latest Cyclone installation software and firmware to use the most up-to-date version of the Run Test Feature, as well as the Run Test API files PEtest.c and PEtest.h for including into test applications.

"Run Test" Applications

Run Test applications are written by the user in any development environment which can generate a valid application for the processor being programmed. The test application could be a special version of the final application which conditionally has included test code, or the test application could just as easily be a completely different code base. The test application links in the Run Test API code which allows the run test application to communicate to the Cyclone during the test process. While each test application must in the end report back a success/fail result to the Cyclone, it can also query the Cyclone for information and interact with the user through the Cyclone hardware.

As part of each test application that is programmed and run, the test application can optionally return "named" blocks of run test data (rtData) which are saved in the Cyclone until the entire programming process is complete. These rtData blocks may be programmed with any subsequent test application or during final application programming.

Adding Run Tests to the Cyclone Programming Script

The Image Creation utility, which generates stand-alone programming images, has a script creation wizard which specifies the steps to be executed during target programming.

Here is what a simple, and yet common, programming script without Run Test looks like:

Here is what a simple programming script with Run Test looks like:

The RT command (Run Test) executes the application currently programmed into the flash. The application establishes a connection to the Cyclone through the debug bus, optionally interacts with the Cyclone, optionally saves named blocks of data (rtData) to the Cyclone, and will report success/failure to the Cyclone. A failure immediately terminates the programming script. The PF command (program feature) can be used to program any named rtData blocks back into the device at any time. rtData blocks are discarded once the programming script/image completes.

Run Test API Calls

In order to implement the test applications as part of the programming process, PEmicro provides a Run Test API C and header file. These are linked into the test application and allow the application to communicate to the Cyclone through the debug bus. The API calls let the user display, retrieve, and save a variety of information on the Cyclone.

A selection of the Run Test API Calls:

void runtest_initialize_programmer_connection(void);

Initiate the connection to the Cyclone programmer across the debug connection. This is expected to be called somewhere near the start of the main() function in the test application. If the Cyclone doesn't receive a connection request from the Run Test application, then it will error after a timeout. Once this routine returns, all other calls may be used until the test application is stopped by the runtest_stop_test_and_return_result() call.

void runtest_stop_test_and_return_result(unsigned long pe_test_result);

Stops the test application from running and sends back the test application result to the Cyclone as a pass/fail with error codes. The Cyclone will move on to the next programming step if the result was successful. A zero result denotes success and non-zero means failure.

unsigned char runtest_send_rtdata_block_to_programmer(void *dataptr, unsigned long number_of_bytes, char *data_feature_description);

Sends a block of data ("rtData") to the Cyclone, with a specific name to reference it, for later use by the Cyclone. This data can be reprogrammed by the Cyclone into the device using the PF Program Feature command when programming in the final application (or other test applications).

void runtest_get_date_time(pe_date_struct *pe_date_ptr);

void runtest_get_UTC_date_time(pe_date_struct *pe_date_ptr);

Allows the test application to retrieve either the local or the UTC date and time from the Cyclone. The Cyclone will fill out the data structure pointed to by the pe_date_ptr.

unsigned char runtest_display_message_dialog(char *dialog_text, char *button_one_text, char *button_two_text, char *button_three_text);

Allows the test application to pop up a message box with three buttons on the Cyclone display or on the PC. All strings are null terminated. If the button text for each button is not blank, then the button will be visible. This is a way to either notify the operator to do something at some point in the test or to ask them a question. Once a button is selected, it will send back the button number from the Cyclone to the running test application in the target. If no button is selected, it will send back a 0 for no data.

unsigned char runtest_display_input_query(const char *message_string, char *string_input_by_user, unsigned char max_string_length);

Pops up a message box on the Cyclone screen prompting the user for a response. This default response on the Cyclone screen for editing is specified by the string_input_by_user string. If the user enters a new string, the data in the string_input_by_user string will be overwritten. The image below shows an example of this prompt on the Cyclone touch screen.

unsigned char runtest_write_string_to_log_file(char *string_to_append_to_logfile);

Send a text string back to the Cyclone for display/logging.

void runtest_request_power_measurement(unsigned long *V_measured, unsigned long *I_measured);

Reads the target voltage and current usage as measured from the Cyclone. The voltage is in mV and the current is in uA.

Example Programming Images With Run Test

PEmicro has provided several examples, including application codes and programming scripts, in the blog article Cyclone Incorporates Automated Run Test Prior to Final Application Programming