UM0541 STMICROELECTRONICS | Alldatasheet
Document overview
- Manufacturer or author: Provided By ALLDATASHEET.COM(FREE DATASHEET DOWNLOAD SITE)
- PDF pages: 19
Technical content
Datasheet sections
- 1 Architecture
- 1.1 DCP monitor
- 1.1.1 DCP protocol
- 1.2 Communication mechanism
- 1.2.1 Introduction
- 1.2.2 Transmission
- 1.2.3 Reception
- 1.2.4 ACK management
- 1.2.5 Resend management
- 1.2.6 CRC management
- 2 Using DCP monitor
- 2.1 Defining behavior
- 2.1.1 Autonomously
- 2.1.2 Polling
- 2.2 Configuring DCP
- 2.2.1 Communication API configuration
- 2.2.2 ACK management
- 2.2.3 DCP version
- 2.2.4 Communication error management
- 2.3 Initializing the monitor
- 2.4 Writing the callback
- 2.4.1 Sample
- 3 DCP-Application Programm ing Interface
- 3.1 Introduction
- 3.2 API reference
- 3.2.1 DCP_register
- 3.2.2 DCP_RegisterErrorHandler
- 3.2.3 DCP_SendFrame
- 3.2.4 DCP_Callback
- 3.2.5 DCErrorManagement
- 3.2.6 DCP_Init()
CPU commander is a user-friendly tool to perform data logging or to control and to monitor software applications running on MCU targets such as EVA boards, customer modules or application boards. Using CPU commander and its collection of visual instruments makes it possible to quickly build control panels for a large number of application fields. The user can connect CPU commander to a target device using different communication systems. If the user connects CPU commander to the target device via RS232, CPU commander uses a specific protocol called DCP that is described in Section 1.1.1: DCP protocol. In this case, a software called DCP monitor must be present on the target side to establish the communication between CPU commander and the target. This document provides a complete guideline to porting and to configure the DCP monitor in a target device project. Chapter 1: Architecture gives a brief description of the architecture and the DCP protocol. Chapter 2: Using DCP monitor describes how to use the DCP monitor and provides details on its configuration and initialization. Chapter 3: DCP- Application Programming Interface describes the API of the DCP monitor. Requirements CPU commander (PCs) has been designed to work with Windows 2000 and Windows XP platforms and with no particular hardware requirements. However, in order to connect your PC to the target, either a UART port or a USB port and an ST COMBox kit (driver and board) must be installed in your PC.
1 Architecture
1.1 DCP monitor
- DCP .c - contains all functions of the DCP monitor
- DCP .h - header file used to configure the DCP monitor
- DCPPort_xxx.c - contains all functions specific for the target
- DCPPort_xxx.h - header file for DCPPort_xxx.c All these files have to be included in the target side project to implement the DCP monitor.
1.1.1 DCP protocol
DCP protocol is used by CPU commander during a UART communication. Figure 1 describes the format of a DCP frame. Figure 1. Serial communication frame format bits long and identifies the frame. Command ID (Command Identifier): is the identifier of the frame and is 32 bits long. SYS (System) flag: when it is set, the frame is a system frame. ACK (Acknowledge) flag: when it is set, the receiver must send an acknowledge frame. bytes) present in the current frame. Data: it contains from 0 up to 255 bytes of data. CRC: if CRC flag is set the last filed contains the CRC value. It is 16 bits long.
1.2 Communication mechanism
1.2.1 Introduction
This section describes the transmission mechanism and the reception mechanism between CPU commander and a target device.
1.2.2 Transmission
To send data, the sender must build a DCP frame and insert information in each field. The sender has to perform these steps: 1. Insert the CommandID. 2. Set the correct flags for the func tionality requested (SYS, ACK, CRC). 3. Insert the Length of the bytes of the data. 4. Insert the data. 5. Calculate the CRC if the CRC flag is set an d insert the value at the end of the frame. 6. Call the function SendFrame(frame).
1.2.3 Reception
The reception is interrupt implemented. Using UART communication, the receiver receives one byte at a time, so the number of the byte received depends from the properties of each frame. If the acknowledge management is activated, the first seven bytes (FrameID, CommandID, Flags, Length) are mandatory. If the acknowledge management is not activated the first six bytes are always present (CommandID, Flags, Length). After the reception of the Length, it is possible to know how many bytes of data the receiver has to receive. After the receiver has received all data, it waits for CRC flag if the CRC flag is set, otherwise the reception is complete. When the frame is complete, the receiver can pass the frame to the DCP protocol for the parsing calling DCP_ProcessFrame() function. If the frame is a system (SYS) frame, DCP protocol executes the task programmed for the specific SYS. If the frame is an acknowledge frame (ACK), the protocol checks if the FrameID of the frame received corresponds to the expected FrameID. If the FrameID does not match, an error occurs. If the CommandID of the frame is a user CommandID, the management of this frame is passed to the CallBack function managed by the user. In fact, the user has to insert the managed frame into the Callback function with a CommandID which is specific to the application.
1.2.4 ACK management
If the application uses acknowledge management, each frame will contain a FrameID field that identifies the associated frame. The FrameID is a counter that is increased for each frame sent. When the frame is sent, the sender waits for the reception of the corresponding acknowledge frame and it remains blocked in the DCP_WaitACK function. When the receiver receives a data frame, it checks for the CRC (only if activated), builds and sends the acknowledge frame by calling the DCP_SendACK function. Following the task executed by DCP_SendACK function:
- The function inserts the FrameID of the frame received into the FrameID of the acknowledge frame. Next, it inserts the value DCC_FACK into the CommandID field if the CRC calculation is correct otherwise it inserts the value DCC_CRC_ERR. At the end of the frame it inserts the value zero into flags and length fields.
- The last step is to call the function DCP_WriteFrame to send the frame. At this time the sender receives the acknowledge frame and it checks if the FrameID received is the same as the FrameID attended. If it is true, the receiver checking for the CommandID of the ACK. The CommandID can be DCC_FACK and in this case the ACK is correct, otherwise it can be DCC_CRC_ERR and an error occurs. If the ACK is lost, a timeout occurs and an error is generated. This timeout can be set during configuration phase ( it can be different depending on the type of communication system and the power of the target’s processor). For each error generated, the receiver sends an error frame to the sender.
1.2.5 Resend management
This feature is enabled if the acknowledge mechanism is present. It allows to resend a frame if the sender does not receive any acknowledge frame. If the DCP_WaitACK ends because a timeout has occurred, the sender can resend the frame up to the SendFrameTries maximum number of times.
1.2.6 CRC management
If the CRC management is enabled, either the sender or the receiver has to execute a specific task to manage the CRC. When the sender has the frame ready to send, calculates the CRC using the function ComputeCRC(). Following the algorithm used to calculate the CRC:
- If the frame has an odd number of bytes, the sender adds a byte equal to zero until the frame has an even number of bytes.
- The sender executes an XOR operation between all 8-bit long words of the frame.
- The sender adds the 16-bit long value inside the CRC field. At this time the frame is ready to be sent. When the receiver receives the frame, it calculates the CRC using the same function. Only when this value is calculated does the receiver compare the CRC received with the CRC calculated. If the values are the same it means that the receiver has received the frame correctly otherwise an error occurs. If the acknowledge mechanism is activated, the ACK frame contains the CRC error.
2 Using DCP monitor
2.1 Defining behavior
DCP monitor can work in two ways:
- Polling
- Autonomously This means that the user can query information from an external tool (usually CPU commander) or the application can send the information by itself.
2.1.1 Autonomously
In order to communicate with this mode, the user can call whenever needed within the code the DCP_SendFrame function. For parsing, the user should customize and register the DCP_Callback function. Within this function all the necessary processing should be done. Parsing of the received user command.
2.1.2 Polling
In order to work with this mode, no specifications are needed. The external tool instructs the target to read or write data using the DCC_READ and DCC_WRITE commands. In this case there is no need of coding for the user. The only operation required is to initialize the DCP by calling the DCP_Init function. Note: About endianness: the protocol works with big endianness. This means that all information sent must be converted to big endian and all the information received must be converted to the endianness of the receiving platform.
2.2 Configuring DCP
2.2.1 Communication API configuration
COM_API defines which communication API is used.
2.2.2 ACK management
ACK management can be enabled with ACK_MANAGEMENT_SEND. ACK management on Rx can be enabled with ACK_MANAGEMENT_WAIT, specifying the timeout for waiting in ms with ACK_MANAGEMENT_TIMEOUT. If the sender is waiting for an ACK and it receives a frame, it simply processes the frame and still remains waiting for the ACK.
2.2.3 DCP version
The version of the protocol is specified by DCP_VERSION.
2.2.4 Communication error management
Resend of not acknowledge frames can be activated by RESEND_ON_ERROR. In this case, MAX_SEND_TRIES specifies the number of tries and MAX_WAIT_LOOPS the time for acknowledgement waiting.
2.3 Initializing the monitor
To initialize the DCP monitor, the user has to call the DCP_Init function that initialize the used target communication interface. The user also has to call the following functions:
- DCP_Register (DCCallback): DCCallback is a pointer to callback that processes received frames.
- DCP_RegisterErrorHandler (DCErrorHandler): DCErrorHandler is a pointer to function that processes errors.
2.4 Writing the callback
This function must be implemented by the user in application code. It contains the management of the frame with specifics CommandID for the application. In fact, the user has to associate some specific task to a specific CommandID.
2.4.1 Sample
UINT32 DCCallback(UINT32 pFrame) FRAME frame = {0}; // Handle DCP messages switch(((FRAME*)pFrame)->CommandID) case IDC_LED // Switch on/off the LED SetPort(LED_PORT, frame.Param32) break; case IDC_GET_FIRMWARE_VERSION: // Initializes reply frame framex.CommandID = IDC_FIRMWARE_VERSION; frames.length = 1; framex.Data[0] = FIRMWARE_VERSION; DCP_SendFrame(&frame); break; default: break; return DCN_SUCCESS;
UM0541 DCP-Application Programming Interface
3 DCP-Application Programming Interface
3.1 Introduction
This section describes the API (Application Programming Interface) for the DCP protocol. Following a list of the functions implemented to realize the communication using DCP protocol:
- DCP_Register
- DCP_RegisterErrorHandler
- DCP_SendFrame
- DCCallback
- DCErrorManagement
3.2 API reference
3.2.1 DCP_register
UINT32 DCP_register( PFN_DCB2 pfnDCB ). Arguments pfnDCB [in] a pointer to callback that processes received frames. Returns This function returns DCN_SUCCESS on successful completion, DCN_BAD_PARAMETER if pfnDCB is NULL.
Description
The function DCP_register is used by the user application to register the callback function defined by the user.
3.2.2 DCP_RegisterErrorHandler
UINT32 DCP_RegisterErrorHandler( PFN_DEH pfnDEH ). Arguments pfnDEH [in] a pointer to function that processes errors. Returns This function returns DCN_SUCCESS on successful completion, DCN_BAD_PARAMETER if pfnDEH is NULL.
DCP-Application Programming Interface UM0541 The function DCP_RegisterErrorHandler is used by the user application to register the error handler function defined by the user.
3.2.3 DCP_SendFrame
UINT32 DCP_SendFrame( UINT8 u8Channel, LPFRAME pFrame ). Arguments u8Channel[in] number of the channel; pFrame [in] pointer to the frame to send. Returns This function returns DCN_SUCCESS on success, DCN_BAD_PARAMETER on bad parameter, DCN_ERROR otherwise This function is used to send a frame and to wait for the acknowledge frame if the acknowledgement mechanism is enabled. If the timeout occurred, the function sends the frame again up to a maximum number of times defined by user.
3.2.4 DCP_Callback
UINT32 DCCallback( LPFRAME pFrame ). Arguments pFrame[in], a pointer to the received frame. Returns This function returns DCN_SUCCESS if the frame has been handled, DCN_NOT_IMPLEMENTED if has not been handled, DCN_ERROR on error. This function is implemented by the user and contains the management of the used defined frame.
UM0541 DCP-Application Programming Interface
3.2.5 DCErrorManagement
UINT32 DCErrorManagement( UINT32 ErrCode ). Arguments ErrCode[in], a code that describes the type of error. Returns This function returns DCN_SUCCESS if the error has been handled, DCN_NOT_IMPLEMENTED if has not been handled, DCN_ERROR on error. This function is implemented by the user and contains the management of the error occurred.
3.2.6 DCP_Init()
UINT32 DCP_Init( void ). Arguments Void. Returns This function returns DCN_SUCCESS on success and DCN_MUTEX_ERR on error in mutex's creation. Initializes all peripherals for DCP . Create semaphores for synchronization.
DCP-Application Programming Interface UM0541
3.3 Data structures and constants
#define TRACE OutputDebugString Trace1 To show debug messages #define TRACE1(a, b) char sz[256]=""; wsprintf(sz, (a), (b)); OutputDebugString(sz); Trace2 To show debug messages #define TRACE2(a, b, c) char sz[256]=""; wsprintf(sz, (a), (b), (c)); OutputDebugString(sz);
3.3.1 Type definition
Tag_frame Structure that contains the frame section Typedef struct tagFRAME UITN8 FrameID; UINT32 CommandID; BITFIELD SYS : 1; BITFIELD CRC : 1; BITFIELD rsvd: 1; BITFIELD ACK: 1; BITFIELD rsvd: 4; UITN8 lENGTH; UITN8 Data[]; } FRAME; LPframe Pointer to a frame structure typedef FRAME* LPFRAME;
3.3.2 Configuration constants
The following #define in DCP .h can be used to configure protocol behavior. The following #define in DCPPort_x.h can be used to configure protocol behavior. Table 1. Constants in DCP.h Table 2. Constants in DCPPort_x.h
3.3.3 Command reference
Table 3. Preprocessor definitions WIN32 Includes this block of code if compiling for Windows. __CC_ARM Includes this block of code if compiling for ARM. __ppc Includes this block of code if compiling for PPC. Table 4. Command reference
3.3.4 Return codes
The following codes are returned by DCP functions. Table 5. Return codes
Software end-user agreement UM0541 Appendix A Software end-user agreement End-user license agreement Y ou (“you”) should carefully read the following terms and conditions before using this software (the “software”) which is licensed by STMicroelectronics nv (“ST”) to its customers for their use only as set forth below. Acceptance If Y ou agree with and accept the terms and conditions of this agreement it shall become a legally binding agreement between Y ou and ST and Y ou may proceed to install, copy and use the software in accordance with the terms and conditions of the agreement. Rejection and right to a refund If Y ou do not agree with or do not wish to be bound by the terms and conditions of this agreement Y ou may NOT install, copy or use the software. License ST hereby grants to Y ou, subject to the terms and conditions of this agreement, a non- exclusive, non-transferable, worldwide license, without the right to sub-license, to use the software to develop software applications for ST microcontroller product only. Y ou are not permitted to lease, rent, distribute or sublicense the software or to use the software in a timesharing arrangement or in any unauthorized manner. Restrictions on use of the software The software is delivered free of charge by electronically means. Y ou are allowed to copy the software in its initial form to be installed on as many computers as needed. Y ou shall only use the software on a single computer connected to a single monitor at any one time. Limited warranty ST warrants to Y ou that the software will perform substantially in accordance with the accompanying documentation. ST's total liability and your exclusive remedy for breach of the limited warranty given above shall be limited to ST, it is ST's sole option, using reasonable efforts to correct material, documents, reproduce defects in the software. Except as provided above ST expressly disclaims all other representations, warranties, conditions or other terms, express or implied, including without limitation the implied warranties of non infringement, satisfactory quality, and fitness for a particular purpose. Limitation of liability To the maximum extent permitted by applicable law, in no event shall ST be liable for any indirect, special, incidental or consequential damages (including loss of profits) arising out of the use or inability to use the software whether based on a claim under contract, tort or other legal theory, even if ST was advised of the possibility of such damages.
UM0541 Software end-user agreement ST does not seek to limit or exclude liability for death or personal injury arising from ST's negligence and because some jurisdictions do not permit the exclusion or limitation of liability for consequential or incidental damages the above limitation relating to liability for consequential damages may not apply to Y ou. Third party rights Software provided under this agreement may contain or be derived from portions of materials provided by a third party under license to ST. The third party disclaims all warranties express or implied with respect to the use of such materials in connection with the software, including (without limitation) any warranties of satisfactory quality or fitness for a particular purpose. Software provided under this agreement may contain or be derived from portions of materials provided by a third party under license to ST. The third party may enforce any of the provisions of this agreement to the extent such third party materials are effected. Additionally, any limitation of liabilities described in this agreement also applies to any third- party supplier of materials supplied to Y ou. ST and its third party supplier limitations of liabilities are not cumulative. Such third party is an intended beneficiary of this section. Term and termination This agreement shall remain in force until terminated by Y ou or by ST. Without prejudice to any of its other rights if Y ou are in breach of any of the terms and conditions of this agreement then this agreement will terminate immediately. Upon such termination Y ou agree to destroy the software and documentation together with all copies in any form. Y ou may terminate this agreement at any time by destroying the software and documentation together with all copies in any form. General This agreement is governed by the law of France. This is the only agreement between Y ou and ST relating to the software and it may only be modified by written agreement between Y ou and ST. This agreement may not be modified by purchase orders, advertising or other representation by any person. If any clause in this agreement is held by a court of law to be illegal or unenforceable the remaining provisions of the agreement shall not be affected thereby. The failure by ST to enforce any of the provisions of this agreement, unless waived in writing, shall not constitute a waiver of ST's rights to enforce such provision or any other provision of the agreement in the future. Use, copying or disclosure by the US Government is subject to the restrictions set out in subparagraph (c)(1)(ii) of the Rights in technical data and computer software clause at DFARS 252.227-7013 or subparagraphs (c)(1) and (2) of the Commercial Computer Y ou agree that Y ou will not export or re-export the software to any country, person or entity or end user subject to U.S.A. export restrictions, or other countries’ export restrictions.
4 Revision history
Table 6. Document revision history 24-Sep-2013 2 Updated Disclaimer.