Using the µVision Socket Interface: UVSOCK Messaging

| Using the µVision Socket Interface Application Note 198 Control and monitor µVision via the built-in TCP/IP interface

- Main Page
- Usage and Description
- Reference

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
UVSOCK Messaging

UVSOCK uses messages to establish the communication between the Client and uVision. Messages are sent and received back-to-back on the socket interface. Usually, the Client triggers the communication cycle. As such we can define the following message types:

- Request/Response Message - triggered by the Client expecting a response from uVision
- Asynchronous Message - sent at any time by uVision to the Client and not in response to a request

The general form of the message is explained in General Message Format. The general form of the status code messages is explained Status Codes. UVSOCK Data Types are designed for easy implementation.

# General Message Format

A variable length message transfers data between the Client and uVision. Each message consists of the:

- Header (32-byte long), describing the message payload. For uVision ==> Client messages, the header contains timing information for the target.
- Payload itself, which is variable in format and length, dependent on the information in the header.

The following general rules apply while working with UVSOCK:

- Multiple TCP connections are possible simultaneously and get defined with #define UVSC_MAX_CLIENTS.
- Reserved data fields in structures must be written as 0 and ignored when reading.
- Non-relevant data fields in requests must be written as 0.

UV_MESSAGE describes the general message format

Data | Type | Width (Bytes) | Description
--- | --- | --- | ---
Header | UV_HEADER | 32 | Header with the command
Data | various | SOCK_NDATA (32768) | Payload with data depending on the command

UV_HEADER describes the message header format

Data | Type | Width (Bytes) | Description
--- | --- | --- | ---
Total Length | unsigned integer | 4 (32 bits) | Total packet length in bytes
Command | unsigned integer | 4 (32 bits) | Command code; (listed in UV_OPERATION)
Command Length | unsigned integer | 4 (32 bits) | Length of command code dependent data
Cycle Count | unsigned integer | 8 (64 bits) | Number of MCU cycles since program execution started (from uVision ==> Client only)
Timestamp | floating point | 8 (64 bits) | Time in seconds since program execution started (from uVision ==> Client only)
Reserved | Reserved | 4 (32 bits) | Reserved. Send 0.

# Request/Response Message

This section describes messages that can be sent from the Client to uVision. Each message from the Client is replayed by a response message from uVision.

Several messages have the same format, except for the command code contained in the request header. The payload of the response message contains the:

- Request command, and
- Either a success indication (with variable response data),
- Or an error indication, with an error string.

Any reserved portion of a message should be sent as zero (0).

UV_CMD_RESPONSE describes the header and payload of the request/response message

Data | Type | Width (Bytes) | Description
--- | --- | --- | ---
Header | UV_HEADER | 32 | Header with UV_CMD_RESPONSE command code
Command Executed | unsigned integer | 4 (32 bits) | Command to which this is a response (see table UVSOCK Command Set)
Status | unsigned integer | 4 (32 bits) | Status Codes indicating if the executed command was successful or not
Response | various | <= SOCK_NDATA-8 | Possible data returned in response to the executed command

All command codes are listed in UV_OPERATION.

The following table lists the command set and the message ordering:

UVSOCK Command Set
Request (Client ==> uVision) | Expected Response (uVision ==> Client) | Description
--- | --- | ---
UV_GEN_GET_VERSION | UV_CMD_RESPONSE [UV_GEN_GET_VERSION] | Retrieve the version of the UV Socket interface
UV_GEN_UI_UNLOCK | UV_CMD_RESPONSE [UV_GEN_UI_UNLOCK] | Enable message boxes / user input to uVision
UV_GEN_UI_LOCK | UV_CMD_RESPONSE [UV_GEN_UI_LOCK] | Disable message boxes / user input to uVision
UV_GEN_HIDE | UV_CMD_RESPONSE [UV_GEN_HIDE] | Completely hide the uVision window
UV_GEN_SHOW | UV_CMD_RESPONSE [UV_GEN_SHOW] | Show the uVision window
UV_GEN_RESTORE | UV_CMD_RESPONSE [UV_GEN_RESTORE] | Restore the uVision window
UV_GEN_MINIMIZE | UV_CMD_RESPONSE [UV_GEN_MINIMIZE] | Minimise the uVision window
UV_GEN_MAXIMIZE | UV_CMD_RESPONSE [UV_GEN_MAXIMIZE] | Maximise the uVision window
UV_GEN_EXIT | UV_CMD_RESPONSE [UV_GEN_EXIT] | Close uVision
UV_GEN_GET_EXTVERSION | UV_CMD_RESPONSE [UV_GEN_GET_EXTVERSION] | Get extended version information, including the uVision and UVSOCK versions (in ASCII)
UV_PRJ_LOAD | UV_CMD_RESPONSE [UV_PRJ_LOAD] | Open a project
UV_PRJ_CLOSE | UV_CMD_RESPONSE [UV_PRJ_CLOSE] | Close a project
UV_PRJ_ADD_GROUP | UV_CMD_RESPONSE [UV_PRJ_ADD_GROUP] | Add a group to a project
UV_PRJ_DEL_GROUP | UV_CMD_RESPONSE [UV_PRJ_DEL_GROUP] | Remove a group from a project
UV_PRJ_ADD_FILE | UV_CMD_RESPONSE [UV_PRJ_ADD_FILE] | Add a file to a project group
UV_PRJ_DEL_FILE | UV_CMD_RESPONSE [UV_PRJ_DEL_FILE] | Remove a file from a project group
UV_PRJ_BUILD | UV_CMD_RESPONSE [UV_PRJ_BUILD] UV_PRJ_BUILD_OUTPUT UV_PRJ_BUILD_COMPLETE UV_PRJ_BUILD_CANCEL | Build the currently active project
UV_PRJ_REBUILD | UV_CMD_RESPONSE [UV_PRJ_REBUILD] UV_PRJ_BUILD_OUTPUT UV_PRJ_BUILD_COMPLETE UV_PRJ_BUILD_CANCEL | Clean and build the currently active project
UV_PRJ_CLEAN | UV_CMD_RESPONSE [UV_PRJ_CLEAN] | Clean the currently active project
UV_PRJ_BUILD_CANCEL | UV_CMD_RESPONSE [UV_PRJ_BUILD_CANCEL] | Stop a build that is currently in operation
UV_PRJ_FLASH_DOWNLOAD | UV_CMD_RESPONSE [UV_PRJ_FLASH_DOWNLOAD] UV_ASYNC_MSG [UV_PRJ_FLASH_DOWNLOAD] | Downloads the current project executable to target Flash
UV_PRJ_SET_TARGET | UV_CMD_RESPONSE [UV_PRJ_SET_TARGET] | Set the project debug mode to simulator or target
UV_PRJ_GET_OPTITEM | UV_CMD_RESPONSE [UV_PRJ_GET_OPTITEM] | Get a file or project group option (such as preprocessor defines)
UV_PRJ_SET_OPTITEM | UV_CMD_RESPONSE [UV_PRJ_SET_OPTITEM] | Set a file or project group option (such as preprocessor defines)
UV_PRJ_ENUM_GROUPS | UV_CMD_RESPONSE [UV_PRJ_ENUM_GROUPS] UV_PRJ_ENUM_GROUPS_START UV_PRJ_ENUM_GROUPS_ENU (Group 1) ... UV_PRJ_ENUM_GROUPS_ENU (Group n) UV_PRJ_ENUM_GROUPS_END | Enumerate the project groups present in a project
UV_PRJ_ENUM_FILES | UV_CMD_RESPONSE [UV_PRJ_ENUM_FILES] UV_PRJ_ENUM_FILES_START UV_PRJ_ENUM_FILES_ENU (File 1) ... UV_PRJ_ENUM_FILES_ENU (File n) UV_PRJ_ENUM_FILES_END | Enumerate the files present in a project group in the project
UV_PRJ_CMD_PROGRESS | UV_CMD_RESPONSE [UV_PRJ_CMD_PROGRESS] | Gets information on the progress of a FLASH download
UV_PRJ_ACTIVE_FILES | UV_CMD_RESPONSE [UV_PRJ_ACTIVE_FILES] | Gets the number of active files. This is the total number of files that will be built if a UV_PRJ_REBUILD command was issued
UV_DBG_ENTER | UV_CMD_RESPONSE [UV_DBG_ENTER] UV_ASYNC_MSG [UV_DBG_ENTER] | Start the debugger
UV_DBG_EXIT | UV_CMD_RESPONSE [UV_DBG_EXIT] UV_ASYNC_MSG [UV_DBG_EXIT] | Stop the debugger
UV_DBG_START_EXECUTION | UV_CMD_RESPONSE [UV_DBG_START_EXECUTION] UV_ASYNC_MSG [UV_DBG_START_EXECUTION] | Start execution of the target
UV_DBG_STOP_EXECUTION | UV_CMD_RESPONSE [UV_DBG_STOP_EXECUTION] UV_ASYNC_MSG [UV_DBG_STOP_EXECUTION] | Stop execution of the target
UV_DBG_STATUS | UV_CMD_RESPONSE [UV_DBG_STATUS] | Check to see if the debugger is executing
UV_DBG_RESET | UV_CMD_RESPONSE [UV_DBG_RESET] UV_ASYNC_MSG [UV_DBG_RESET] | Reset the target / simulator
UV_DBG_STEP_HLL | UV_CMD_RESPONSE [UV_DBG_STEP_HLL] UV_ASYNC_MSG [UV_DBG_START_EXECUTION] UV_ASYNC_MSG [UV_DBG_STOP_EXECUTION] | Step one high level code line
UV_DBG_STEP_INTO | UV_CMD_RESPONSE [UV_DBG_STEP_INTO] UV_ASYNC_MSG [UV_DBG_START_EXECUTION] UV_ASYNC_MSG [UV_DBG_STOP_EXECUTION] | Step one processor instruction
UV_DBG_STEP_INSTRUCTION | UV_CMD_RESPONSE [UV_DBG_STEP_INSTRUCTION] UV_ASYNC_MSG [UV_DBG_START_EXECUTION] UV_ASYNC_MSG [UV_DBG_STOP_EXECUTION] | Step into the current function
UV_DBG_STEP_OUT | UV_CMD_RESPONSE [UV_DBG_STEP_OUT] UV_ASYNC_MSG [UV_DBG_START_EXECUTION] UV_ASYNC_MSG [UV_DBG_STOP_EXECUTION] | Step out of the current function
UV_DBG_CALC_EXPRESSION | UV_CMD_RESPONSE [UV_DBG_CALC_EXPRESSION] | Calculate an expression
UV_DBG_MEM_READ | UV_CMD_RESPONSE [UV_DBG_MEM_READ] | Read a chunk of memory
UV_DBG_MEM_WRITE | UV_CMD_RESPONSE [UV_DBG_MEM_WRITE] | Write a chunk of memory
UV_DBG_TIME_INFO | UV_CMD_RESPONSE [UV_DBG_TIME_INFO] | Get cycle time information from the target
UV_DBG_SET_CALLBACK | UV_CMD_RESPONSE [UV_DBG_SET_CALLBACK] UV_DBG_CALLBACK | Set a callback for a time in the future in MCU cycles
UV_DBG_VTR_GET | UV_CMD_RESPONSE [UV_DBG_VTR_GET] | Get the value of a VTR
UV_DBG_VTR_SET | UV_CMD_RESPONSE [UV_DBG_VTR_SET] | Set the value of a VTR
UV_DBG_SERIAL_GET | UV_CMD_RESPONSE [UV_DBG_SERIAL_GET] | Get buffered serial output from the target
UV_DBG_SERIAL_PUT | UV_CMD_RESPONSE [UV_DBG_SERIAL_PUT] | Pass in serial terminal information to the target
UV_DBG_VERIFY_CODE | UV_CMD_RESPONSE [UV_DBG_VERIFY_CODE] | Verify code in flash against built executable
UV_DBG_CREATE_BP | UV_CMD_RESPONSE [UV_DBG_CREATE_BP] UV_ASYNC_MSG [UV_DBG_CHANGE_BP (UV_STATUS_BP_CREATED)] | Create a breakpoint
UV_DBG_ENUMERATE_BP | UV_CMD_RESPONSE [UV_DBG_ENUMERATE_BP] UV_ASYNC_MSG UV_ASYNC_MSG (BP 1) ... UV_ASYNC_MSG (BP n) UV_ASYNC_MSG | Enumerate the currently defined breakpoints
UV_DBG_CHANGE_BP | UV_CMD_RESPONSE [UV_DBG_CHANGE_BP] UV_ASYNC_MSG [UV_DBG_CHANGE_BP (x)] | Enable, disable or delete a breakpoint

# Asynchronous Message

Asynchronous messages are sent from uVision ==> Client, but not in response to a request.

Most asynchronous messages have the same format as the response message (UV_CMD_RESPONSE), except for the command code UV_ASYNC_MSG, and use the standard message with a sub-command code that is already defined for a Request/Response Message. An example of this is UV_DBG_START_EXECUTION. The command can be sent as a request for uVision to start execution, or as an asynchronous messsage to indicate that uVision has started execution.

A few asynchronous messages have no corresponding Request/Response Message, and the command is sent with the message header UV_HEADER. An example of this is UV_RTA_MESSAGE, which can be sent at any time by uVision and is never in response to a request.

UV_ASYNC_MSG (standard type) describes the header and payload of the asynchronous message

Data | Type | Width (Bytes) | Description
--- | --- | --- | ---
Header | UV_HEADER | 32 | Header with UV_ASYNC_MSG command code
Command Executed | unsigned integer | 4 (32 bits) | Command code that corresponds to the asynchronous operation
Status | unsigned integer | 4 (32 bits) | Status Codes indicating if the executed command was successful or not
Response | various | <= SOCK_NDATA-8 | Possible data returned in response to the executed command

All message codes are listed in UV_OPERATION.

The following table lists the UVSOCK asynchronous messages:

Message (uVision ==> Client) | Description
--- | ---
UV_ASYNC_MSG | Generic asyncronous response to a command from the client ( see table UVSOCK Command Set)
UV_PRJ_BUILD_COMPLETE | A build has completed
UV_PRJ_BUILD_OUTPUT | A line of build output
UV_DBG_CALLBACK | The callback timeout has expired
UV_DBG_BP_ENUM_START | Start of enumeration (no breakpoint info)
UV_DBG_BP_ENUMERATED | Zero, one or more Responses with breakpoint info (BKRSP)
UV_DBG_BP_ENUM_END | End of enumeration (no breakpoint info)
UV_PRJ_ENUM_GROUPS_START | Start of group enumeration
UV_PRJ_ENUM_GROUPS_ENU | Zero, one or more Responses with group name (SSTR)
UV_PRJ_ENUM_GROUPS_END | End of group enumeration
UV_PRJ_ENUM_FILES_START | Start of files enumeration
UV_PRJ_ENUM_FILES_ENU | Zero, one or more Responses with file name (SSTR)
UV_PRJ_ENUM_FILES_END | End of files enumeration
UV_RTA_MESSAGE | A Real-Time Agent protocol message encapsulated in a UVSOCK message
UV_RTA_INCOMPATIBLE | Sent when the RTA version in target is incompatible with uVision

# Status Codes

Status codes are returned in UV_CMD_RESPONSE and UV_ASYNC_MSG messages from uVision ==> Client. They represent the result of the operation and relate to the UVSOCK command code in the message.

In the case of UV_STATUS_SUCCESS, the Response data in the message will be formatted dependent on the Command Executed. The formats are detailed in the section corresponding to the command.

Other codes than UV_STATUS_SUCCESS identify an error. Then, the Response data in the message will be formatted as follows:

Data | Type | Width (Bytes) | Description
--- | --- | --- | ---
Reserved | Reserved | 4 (32 bits) | Reserved
Reserved | Reserved | 4 (32 bits) | Reserved
Error String Length | unsigned integer | 4 (32 bits) | Length of error string (including terminator) in bytes (maximum length of (SOCK_NDATA - 20) bytes)
Error String | NULL terminated string | Data Length | Error description

The enumeration UV_STATUS lists all codes.

Note
  Functions return the status codes listed in UVSC_STATUS.