VueMetrix Firmware Uploader

Size: px

Start display at page:

Download "VueMetrix Firmware Uploader"

Noreen Pitts
5 years ago
Views:

1 VueMetrix Firmware Uploader Release 1.0 Date of this document: August The Firmware Uploader is a set of C language programming tools that uploads a new version of firmware into any VueMetrix controller. It is distributed in source code form so that it can be compiled by the end user and linked with a user-written program. Use of this source code is restricted to approved users. It is copyrighted 2010 by VueMetrix, Inc., and it may not be modified or given to a third party without permission. 1 Description There are two files in the distribution: 1. a header file fwup.h 2. a C source file fwup.cpp We can provide a Windows DLL built from this source, but the firmware uploader is mainly intended to be compiled into another application. To that end it is written in a plain C style. All variables are of either char or int type. RAM data requirement is less than 100 bytes. 1.1 The upload protocol Some general familiarity with the steps of the upload protocol may be helpful, although the details are handled by fwup. This information is provided to facilitate troubleshooting and understanding of the requirements. 1. Uploader sends a message to the controller uf, which tells it that a firmware download is beginning. After that message you MUST complete the firmware transfer in its entirety before the controller is functional again. 2. The uploader verifies that the controller is in a state to receive program data. 3. The uploader instructs the controller to delete its existing firmware. This clears space in the controller's flash memory for the new program. 4. The uploader transfers the new firmware in blocks of no more than 16 bytes. Each block has a one-byte prefix, a two-byte address, and an appended checksum. The maximum total block length is 20, although some blocks may be smaller. 5. If steps 2-4 proceed without error, the uploader instructs the controller to run the new firmware. Error recovery is discussed in section 4. 2 API

2 The API consists of three typedefs and a single function: typedef const char* F_PCC_PCCIIPI(const char*,int,int,int*); typedef const char* F_PCC_IPIPI(int,int*,int*); typedef void F_V_III(int,int,int); int load_complete(f_pcc_pcciipi *f0,f_pcc_ipipi *f1,f_v_iii *f2); f0 is a pointer to a transport function, which relays serial messages to the controller. See section 3.1. f1 is a pointer to a data function, which returns one block of the firmware program. See section 3.2. f2 is a pointer to a callback function, which allows the calling program to track the progress of the upload. See section 3.3. When load_complete function is called it will perform the complete upload procedure. It returns 1 on success and 0 on failure. In the event of success the new firmware is installed and executing. The function takes three arguments, each of which is a non-null function pointer. The following sections explain them in more detail. Given those three functions, which must be provided by the user, load_complete calls them in the proper sequence to perform the entire upload procedure. As explained below and illustrated in Section 5, the user will typically not need to write a data function. 2.1 Processor type VueMetrix products use two different microprocessors, and the upload procedures differ slightly. The macro PROCESSOR_TYPE allows fwup to handle these differences. It defaults to zero if not previously defined; certain products require its value to be 1. #define PROCESSOR_TYPE 0 for these products (this is the default so this statement can be omitted): DPSS HCT HCV MV HV MC #define PROCESSOR_TYPE 1 for these products: LV TEC 3 User-supplied functions 3.1 The transport function

3 The transport function is responsible for sending a string of characters to the controller and returning the controller's reply. It must have a prototype as follows (assuming the name is f_transport). const char* f_transport(const char *p,int outlen,int inlen,int *perror); The arguments are: p a pointer to an array containing the bytes to be transmitted. outlen - The number of bytes in p. This will not exceed 20. inlen - The number of characters expected in reply from the controller. This will not exceed 20. An integer error code is returned through this pointer. If the message was sent and a reply was received without error, set the error value to 0. The VueMetrix software does not parse this error other than to determine if it is zero or not. A non-zero value indicates an error, in which case the upload process will be stopped. There is one case where an error does not abort the upload; this is noted in section 4. The returned value is a pointer to a buffer containing the controller's reply. The buffer size does not need to exceed 20 bytes. The contents of the buffer will not be modified by the VueMetrix program. All RS-232 firmware transfers on our standard products require baud, 1 stop bit, no parity, no flow control Timeout It is important that f_transport return when there is no reply from the controller. This timeout interval needs to be 2 seconds in the case of PROCESSOR_TYPE 0 and 5 seconds for PROCESSOR_TYPE 1. Most of the replies will occur much faster than this, but the exception is step 3 in the procedure (which erases the previous firmware from microprocessor's flash memory). See section 1.1. Another exceptional case is when a previous upload failed. See section Data function The data function provides a pointer to one block of the program. Its prototype is (assuming the name is get_block): const char* get_block(int block_no,int* plength,int* perror) The arguments are: block_no the number of the program block to return plength on return should point to the length of the block. If block_no is greater than the total length of the program, this must be zero. That indicates the end of the program. perror on a valid return should point to zero, or any non-zero value to indicate an error. If plength is zero because block_no is too large, do not set perror to a nonzero value; that is a not an error but a normal condition indicating the end of the program.

4 The function should return a pointer to a buffer containing the requested block of program bytes. In the standard distribution this function is already provided and only needs to be compiled. See section Callback function This is provided for convenience, allowing the calling program to display a progress bar or other indication that the upload is in fact proceeding. No specific action is required here; the callback function could simply be a stub that does nothing. The prototype is (assuming the function is named c_callback): void c_callback(int status,int error,int blocks_complete); The arguments are: status an integer code indicating the state of the upload. Its possible values are as follows (these are declared in fwup.h) STATUS_FAULT 0 An error has occurred. The second argument will contain the error code. STATUS_INVOKED_LOADER 1 The first step in the protocol in section 1.1 has been completed. STATUS_VERIFIED_LOADER 2 The second step in the protocol in section 1.1 has been completed. STATUS_ERASED_PROGRAM 3 The third step in the protocol in section 1.1 has been completed. The actual upload of the program's bytes will begin. STATUS_UPLOADED_BLOCK 4 One block of the program data has been successfully transferred. The third argument will contain an integer indicating the number of blocks transferred so far. STATUS_UPLOAD_COMPLETE 5 All blocks of the program have been successfully transferred. STATUS_RUN_PROGRAM 6 The new program is running. The upload process is complete. If the first argument is zero the second argument contains an error code. Possible values are: NO_ERROR 0 ERROR_INVOKING_LOADER 1 The controller did not respond to the uf command. This is not necessarily fatal; see section 5. INCORRECT_LOADER_ACKNOWLEDGMENT 2 The controller responded but indicated a fatal fault occurred. The upload process will stop. The third argument to c_callback

5 contains the error code returned from f_transport. LOADER_DID_NOT_ACKNOWLEDGE 3 There was no response from the controller when one was expected. DATA_FUNCTION_ERROR 4 The function that returns a program block reported an error. The third argument to c_callback contains the error code returned from get_block. UPLOAD_ERROR 5 The upload process was aborted when error 3 or 4 occurred. The upload process is aborted. If the first argument is 4 (uploaded block) the third argument will be the total number of blocks transferred so far. If the first argument is 0 see the table above for possible values of the third argument. 4 Recovery from a fault One the controller is placed in loader mode, it remains in that state until the final step (run) in the upload process. Therefore when a fault occurs, the controller remains in a state where it is ready to receive a program upload. All that is required is to restart the uploading process from the beginning. Normally the upload process begins with the controller in its standard operating mode. When the command uf is sent, the controller acknowledges by responding OK and switches to its loader mode. In loader mode all communication is in binary, not ASCII. Therefore a controller in the loader mode will not be able to understand and parse uf. A timeout will occur. The fwup.cpp program will ignore such an error at this point and proceed to the next step, since the controller is already in its loader mode. The upload process will proceed and conclude normally. It is important that the user-provided transport function does not terminate the upload process because of a timeout. That would defeat this fault recovery logic, which is designed to bypass a fault occurring at this point. 5 Providing a get_block function Examples cannot be provided for the transport and callback functions, since those are dependent on the runtime environment. VueMetrix provides the get_block function in a C-compilable format, along with the firmware bytes to be uploaded. This is how a new version of firmware is distributed. It looks like this: /* C compilable VueMetrix Firmware lv6.vmfs */ struct block {

6 }; char length; char bytes[20]; struct block the_program[] = { {20, {10,28,138,117,221,117,115,234,205,117,117,113,205,117,117,225,205,117,117,232,}}, // omitted: 4062 blocks of program data {12,{103,135,111,71,71,71,71,117,117,28,117,230,}}, }; #define N_BLOCKS 4064 const char* get_block(int block_no,int* plength,int* perror) { if (block_no >= N_BLOCKS) { *perror = 0; *plength = 0; return 0; } *perror = 0; *plength = the_program[block_no].length; return the_program[block_no].bytes; } This code can simply be attached to the program with an #include directive, or compiled and linked in some other convenient way.

MicroBlaze TFTP Server User Guide

MicroBlaze TFTP Server User Guide Lorne Applebaum appleba@eecg.utoronto.ca August 25, 2004 1 Preamble This document describes the intended method of use for the MicroBlaze TFTP Server. For detailed information regarding how the server