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.