Packet format communications between instrumentation clients
and instrumentation endpoints
const UIAPacket_BROADCAST |
 |
Used to denote a broadcast message
#define UIAPacket_BROADCAST (UInt16)0xFFFE
DETAILS
The broadcast address is always 0xFFFE.
const UIAPacket_HOST |
 |
The address of the host
#define UIAPacket_HOST (UInt16)0xFFFF
DETAILS
The host address is always 0xFFFF.
enum UIAPacket_HdrType |
 |
Enumeration of the various types of packet
headers
typedef enum UIAPacket_HdrType {
UIAPacket_HdrType_InvalidData,
// reserved for future use
UIAPacket_HdrType_MsgWithPID,
// message with Process ID field (for multi-process O/Ses)
UIAPacket_HdrType_EventPktWithCRC,
// event packet with CRC of applciation name (for multi-process O/Ses)
UIAPacket_HdrType_MinEventPkt,
// small footprint event packet used by ti.uia.loggers.LoggerMin
UIAPacket_HdrType_Reserved4,
// reserved for future use
UIAPacket_HdrType_Reserved5,
// reserved for future use
UIAPacket_HdrType_Reserved6,
// reserved for future use
UIAPacket_HdrType_Reserved7,
// reserved for future use
UIAPacket_HdrType_ChannelizedData,
// Channelized data stream
UIAPacket_HdrType_Msg,
// Message (4 words header, 1 word footer)
UIAPacket_HdrType_EventPkt,
// Event rec. containing multiple events:
(4 word hdr, 1 word footer)
UIAPacket_HdrType_CPUTrace,
// CPU Trace ETB data
(4 word hdr, 1 word footer)
UIAPacket_HdrType_STMTrace,
// STM Trace ETB data
(4 word hdr, 1 word footer)
UIAPacket_HdrType_MemoryBuffer,
// Memory Buffer data
UIAPacket_HdrType_USER2,
// User defined header type 2
UIAPacket_HdrType_USER3
// User defined header type 3
} UIAPacket_HdrType;
DETAILS
Stored in a 4 bit bitfield (b31-b28) of the first word in the
packet.
The HdrType_InvalidData denotes that following data is invalid.
This can used to pad to the end of a buffer. Only the first word
of the header is filled in. The length includes the header field.
enum UIAPacket_MsgType |
 |
Message Types
typedef enum UIAPacket_MsgType {
UIAPacket_MsgType_ACK,
// Reply acknowledging receipt of CMD or DATA packet
UIAPacket_MsgType_CMD,
// Command packets
UIAPacket_MsgType_RESULT,
// Result reply
UIAPacket_MsgType_PARTIALRESULT,
// Partial result reply
UIAPacket_MsgType_NOTIFY,
// Notify messaage (equiv. to the EVENT packet in TCF)
UIAPacket_MsgType_FLOWCTRL,
// Flow control packet
UIAPacket_MsgType_DATA,
// Data packet (used for streaming data to host)
UIAPacket_MsgType_RESERVED7,
UIAPacket_MsgType_RESERVED8,
UIAPacket_MsgType_RESERVED9,
UIAPacket_MsgType_RESERVED10,
UIAPacket_MsgType_RESERVED11,
UIAPacket_MsgType_RESERVED12,
UIAPacket_MsgType_RESERVED13,
UIAPacket_MsgType_NACK_BAD_DATA,
// Negative Acknowledge due to bad data
UIAPacket_MsgType_NACK_WITH_ERROR_CODE
// Negative Acknowledge -
error code in msg body
} UIAPacket_MsgType;
DETAILS
Enumeration of the various types of packets.
Stored in a 4 bit bitfield.
MsgType_ACK:
Each packet of type CMD or DATA is immediately acknowledged by
sending either an ACK reply (if the packet can be processed),
a RESULT or PARTIALRESULT reply (if requested data can be provided
immediately) or a NACK reply (if the packet cannot be processed).
The Service that receives the command is responsible for sending
the ACK or NACK. If the requested service is not available, the
Endpoint is responsible for sending the NACK packet.
MsgType_CMD:
CMD packets are typically sent from the host to the target.
The receiving endpoint routes the command to the service
identified in the Service Id field.
MsgType_RESULT:
RESULT replies are sent along with any requested data.
If the Service cannot reply with the requested data immediately,
it should return with an ACK packet and send a RESULT packet
that echoes the header info of the original command.
MsgType_PARTIALRESULT:
PARTIALRESULT replies are sent along with any requested data when the
requested action can only be partly fulfilled. Examples are when the
service is reporting on some ongoing operation or has been requested
to periodically poll some data value.
MsgType_EVENT:
EVENT packets are sent to all interested parties in order to notify them
about state changes. They can, for example, be used to report an error
that has occurred which may impact the ability of the target to continue
operating normally.
MsgType_FLOWCTRL
FLOWCTRL packets are provided for TCF compliance. They are used to avoid
flooding of communication links. In response, endpoints can either
increase or decrease rate of packets sent, although this is only loosely
defined. TCF services are not directly concerned with flow control.
The data passed with FLOWCTRL packets reports the traffic congestion level
as an integer between -100 and 100, where 0 = "optimal load"
MsgType_DATA
DATA packets are used for sending event log data and other streams of data.
Details about how this will be used are being worked out to ensure alignment
with BIOS RTA Log Servers.
MsgType_NACK_BAD_DATA:
Negative Acknowledge due to bad data. Sent in response to a command that
had invalid data in the body of the packet. The original data is echoed
in the NACK response.
MsgType_NACK_WITH_ERROR_CODE
Negative Acknowledge with Error Code. Sent along with an error code in
the first word of the body of the reply that describes the error that was
encountered
enum UIAPacket_NACKErrorCode |
 |
Message Negative Acknowledge Error Codes
typedef enum UIAPacket_NACKErrorCode {
UIAPacket_NACKErrorCode_NO_REASON_SPECIFIED,
// Use this when none of the
defined NACK error codes are
appropriate
UIAPacket_NACKErrorCode_SERVICE_NOT_SUPPORTED,
// A module that handles the
requested Service Id could
not be found
UIAPacket_NACKErrorCode_CMD_NOT_SUPPORTED,
// The service does not support the
specified Command Id
UIAPacket_NACKErrorCode_QUEUE_FULL,
// Cmd couldn't be passed on to dest. end
point due to a queue full condition
UIAPacket_NACKErrorCode_BAD_ENDPOINT_ADDRESS,
// The destination end point
address does not exists
UIAPacket_NACKErrorCode_BAD_MESSAGE_LENGTH
// packet lenght > endpoint max.
msg length or not what is
required to service the cmd
} UIAPacket_NACKErrorCode;
DETAILS
Stored in the first 32b word of the data body of the packet
in Network Byte Order
enum UIAPacket_PayloadEndian |
 |
Enumeration of payload endianness
typedef enum UIAPacket_PayloadEndian {
UIAPacket_PayloadEndian_LITTLE,
UIAPacket_PayloadEndian_BIG
} UIAPacket_PayloadEndian;
struct UIAPacket_Footer |
 |
Packet Footer
typedef struct UIAPacket_Footer {
Int32 word1;
// 16 MSBs contain msg length in Bytes,
16 LSBs contain 0x7777
} UIAPacket_Footer;
DETAILS
The packet footer is always in network byte order
i.e. big-endian byte ordering
struct UIAPacket_Hdr |
 |
UIAPacket Header
typedef struct UIAPacket_Hdr {
Bits32 word1;
Bits32 word2;
Bits32 word3;
Bits32 word4;
} UIAPacket_Hdr;
DETAILS
The following is a breakdown of the packet header based on type packet.
The packet header is always sent in network byte (big endian) order.
The top 4 leftmost bits of word1 denote what type of packet this is:
HdrType_Msg or HdrType_EventPkt. The contents of the packet depends on
this type.
HdrType_Msg word1
3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0
1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
|---------------------------------------------------------------|
|H H H H|E|L L L L L L L L L L L|T T T T|S S S S S S S S S S S S|
|---------------------------------------------------------------|
H = HdrType (4-bits)
E = Payload endian (1-bit)
L = Message Length (11-bits)
T = Message Type (4-bits)
S = Service Id (12-bits)
HdrType_Msg word2
3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0
1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
|---------------------------------------------------------------|
|S S S S S S S S S S S S S S S S|C C C C C C C C C C C C C C C C|
|---------------------------------------------------------------|
S = Sequence Number (16-bits)
C = Command Id (16-bits)
HdrType_Msg word3
3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0
1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
|---------------------------------------------------------------|
|T T T T T T T T T T T T T T T T T T T T T T T T T T T T T T T T|
|---------------------------------------------------------------|
T - Tag (32-bits)
HdrType_Msg word4
3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0
1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
|---------------------------------------------------------------|
|D D D D D D D D D D D D D D D D|S S S S S S S S S S S S S S S S|
|---------------------------------------------------------------|
D - Destination Address (16-bits)
S - Source Address (16-bits)
HdrType_EventPkt word1
3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0
1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
|---------------------------------------------------------------|
|H H H H|E|L L L L L L L L L L L L L L L L L L L L L L L L L L L|
|---------------------------------------------------------------|
H = HdrType (4-bits)
E = Payload endian (1-bit)
L = Packet Length (27-bits)
HdrType_EventPkt word2
3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0
1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
|---------------------------------------------------------------|
|S S S S S S S S S S S S S S S S|E E E E E E E E E E E E E E|P P|
|---------------------------------------------------------------|
S = Packet Sequence Number (16-bits)
E = Event Sequence Number for first event in the packet (14-bits)
P = Priority: Normal=0, High > 0 (2-bits)
HdrType_EventPkt word3
3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0
1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
|---------------------------------------------------------------|
|D I I I I I I I I I I I I I I I M M M M M M M M M M M M M M M M|
|---------------------------------------------------------------|
D - wasLoggerDynamicallyCreated (1-bit: 0 = statically created,
1 = dynamically created)
I - Logger Instance ID (15-bits)
M - Logger Module ID (16-bits)
HdrType_EventPkt word4
3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0
1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
|---------------------------------------------------------------|
|D D D D D D D D D D D D D D D D|S S S S S S S S S S S S S S S S|
|---------------------------------------------------------------|
D - Destination Address (16-bits)
S - Source Address (16-bits)
For HdrType_EventPktWithCRC
word 5 holds the 16b CRC of the application name (0 for RTOSes such as SysBIOS)
3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0
1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
|---------------------------------------------------------------|
|R R R R R R R R R R R R R R R|C C C C C C C C C C C C C C C C C|
|---------------------------------------------------------------|
C = CRC16 of the application name (0 if only one process) (32-bits)
R = Reserved (set to 0)
For memory constrained systems, ti.uia.loggers.LoggerMin uses the
following 2 word Event Packet header format, with HdrType =
HdrType_MinEventPkt :
3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0
1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
|---------------------------------------------------------------|
|H H H H|E|D D D D D|R R R R R R|L L L L L L L L L L L L L L L L|
|---------------------------------------------------------------|
H = HdrType (4-bits)
E = Payload endian (1-bit)
D = Sender Adrs / Device ID (5 bits – DNUM)
R = Reserved (set to 0)
L = packet Length (16-bits)
HdrType_MinEventPkt word2
3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0
1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
|---------------------------------------------------------------|
|S S S S S S S S S S S S S S S S|E E E E E E E E E E E E E E|P P|
|---------------------------------------------------------------|
S = Packet Sequence Number (16-bits)
E = Event Sequence Number for first event in the packet (14-bits)
P = Priority: Normal=0, High > 0 (2-bits)
config UIAPacket_maxPktLengthInBytes // module-wide |
 |
maximum number of bytes a packet can contain
extern const Int UIAPacket_maxPktLengthInBytes;
DETAILS
used to limit the amount of memory needed by the
packet factories in order to handle a new packet
UIAPacket_getCmdId() // module-wide |
 |
gets the packet type from the packet header
ARGUMENTS
(Hdr* msgHdr) pointer to the packet header
DETAILS
Message header is always layed out as big endian (network order).
This macro is designed to work on both little endian and
big endian targets, since 32b long words are consistently
handled for both endianness - it is only when converting
from bytes to longs that bit orders get swapped.
#ifdef xdc_target__bigEndian can be used if necessary.
UIAPacket_getDestAdrs() // module-wide |
 |
gets the packet destination address from the packet header
ARGUMENTS
(Hdr* msgHdr) pointer to the packet header
DETAILS
Message header is always layed out as big endian (network order).
This macro is designed to work on both little endian and
big endian targets, since 32b long words are consistently
handled for both endianness - it is only when converting
from bytes to longs that bit orders get swapped.
#ifdef xdc_target__bigEndian can be used if necessary.
Example1 :
Void example1(UIAPacket_Object *obj){
Int16 destAdrs = UIAPacket_getDestAdrs(&obj->hdr);
...
}
Example2 :
Void example2(UIAPacket_Hdr *pHdr){
Int16 destAdrs = UIAPacket_getDestAdrs(pHdr);
...
}
UIAPacket_getEventLength() // module-wide |
 |
Gets the packet length (in bytes) from the packet header
ARGUMENTS
(Hdr* msgHdr) pointer to the packet header
DETAILS
Includes the packet header
UIAPacket_getFooter() // module-wide |
 |
returns the integer to use as the packet footer
ARGUMENTS
(Hdr* pHdr) pointer to the packet header
UIAPacket_getHdrType() // module-wide |
 |
gets the packet header type from the packet header
ARGUMENTS
(Hdr* msgHdr) pointer to the packet header
DETAILS
Message header is always layed out as big endian (network order).
This macro is designed to work on both little endian and
big endian targets, since 32b long words are consistently
handled for both endianness - it is only when converting
from bytes to longs that bit orders get swapped.
#ifdef xdc_target__bigEndian can be used if necessary.
UIAPacket_getLength() // module-wide |
 |
Gets the packet length (in bytes) from the packet header
ARGUMENTS
(Hdr* msgHdr) pointer to the packet header
DETAILS
Includes the packet header
UIAPacket_getLoggerInstanceId() // module-wide |
 |
gets the logger instance ID from the event packet header
ARGUMENTS
(Hdr* msgHdr) pointer to the packet header
DETAILS
Message header is always layed out as big endian (network order).
This macro is designed to work on both little endian and
big endian targets, since 32b long words are consistently
handled for both endianness - it is only when converting
from bytes to longs that bit orders get swapped.
#ifdef xdc_target__bigEndian can be used if necessary.
UIAPacket_getLoggerModuleId() // module-wide |
 |
gets the logger ID from the event packet header
ARGUMENTS
(Hdr* msgHdr) pointer to the packet header
DETAILS
Message header is always layed out as big endian (network order).
This macro is designed to work on both little endian and
big endian targets, since 32b long words are consistently
handled for both endianness - it is only when converting
from bytes to longs that bit orders get swapped.
#ifdef xdc_target__bigEndian can be used if necessary.
UIAPacket_getMsgLength() // module-wide |
 |
gets the packet length (in bytes) from the packet header
ARGUMENTS
(Hdr* msgHdr) pointer to the packet header
DETAILS
Message header is always layed out as big endian (network order).
This macro is designed to work on both little endian and
big endian targets, since 32b long words are consistently
handled for both endianness - it is only when converting
from bytes to longs that bit orders get swapped.
#ifdef xdc_target__bigEndian can be used if necessary.
UIAPacket_getMsgType() // module-wide |
 |
gets the packet type from the packet header
ARGUMENTS
(Hdr* pHdr) pointer to the packet header
DETAILS
Message header is always layed out as big endian (network order).
This macro is designed to work on both little endian and
big endian targets, since 32b long words are consistently
handled for both endianness - it is only when converting
from bytes to longs that bit orders get swapped.
#ifdef xdc_target__bigEndian can be used if necessary.
UIAPacket_getPayloadEndianness() // module-wide |
 |
gets the payload endianness bit from the packet header
macro Bits32 UIAPacket_getPayloadEndianness(
UIAPacket_Hdr *
pHdr);
ARGUMENTS
(Hdr* msgHdr) pointer to the packet header
DETAILS
Message header is always layed out as big endian (network order).
This macro is designed to work on both little endian and
big endian targets, since 32b long words are consistently
handled for both endianness - it is only when converting
from bytes to longs that bit orders get swapped.
#ifdef xdc_target__bigEndian can be used if necessary.
UIAPacket_getSenderAdrs() // module-wide |
 |
gets the packet sender address from the packet header
ARGUMENTS
(Hdr* msgHdr) pointer to the packet header
DETAILS
Message header is always layed out as big endian (network order).
This macro is designed to work on both little endian and
big endian targets, since 32b long words are consistently
handled for both endianness - it is only when converting
from bytes to longs that bit orders get swapped.
#ifdef xdc_target__bigEndian can be used if necessary.
UIAPacket_getSequenceCount() // module-wide |
 |
gets the sequence count from the packet header
ARGUMENTS
(Hdr* msgHdr) pointer to the packet header
DETAILS
Message header is always layed out as big endian (network order).
This macro is designed to work on both little endian and
big endian targets, since 32b long words are consistently
handled for both endianness - it is only when converting
from bytes to longs that bit orders get swapped.
#ifdef xdc_target__bigEndian can be used if necessary.
UIAPacket_getServiceId() // module-wide |
 |
gets the packet type from the packet header
ARGUMENTS
(Hdr* msgHdr) pointer to the packet header
DETAILS
Message header is always layed out as big endian (network order).
This macro is designed to work on both little endian and
big endian targets, since 32b long words are consistently
handled for both endianness - it is only when converting
from bytes to longs that bit orders get swapped.
#ifdef xdc_target__bigEndian can be used if necessary.
UIAPacket_getTag() // module-wide |
 |
gets the 32b tag field from the packet header
ARGUMENTS
(Hdr* msgHdr) pointer to the packet header
UIAPacket_initEventRecHdr() // module-wide |
 |
initializes all bitfields in the message header
ARGUMENTS
(Hdr* msgHdr) pointer to the packet header
endianness
endianness of the payload
eventLength
the number of Bytes in the packet, including
the header and footer
seqCount
the sequence number for the packet
priority
the logger's priority
moduleId
the logger's module Id
instanceId
the logger's instanceId
destAdrs
the destination address
senderAdrs
the sender address
UIAPacket_initMinEventRecHdr() // module-wide |
 |
initializes all bitfields in the minimum event packet header,
setting the length, sequence count and last timestamp fields to 0
ARGUMENTS
(Hdr* pPktHdr) pointer to the packet header
endianness
endianness of the payload
loggerInstanceId
the logger's instanceId
senderAdrs
the sender address (i.e. DNUM / endpoint ID for the CPU core)
UIAPacket_initMsgHdr() // module-wide |
 |
initializes all bitfields in the message header
ARGUMENTS
(Hdr* msgHdr) pointer to the packet header
endianness
endianness of the payload
msgType
the packet type
msgLength
the number of Bytes in the packet, including the
header and footer
serviceId
the service Id
seqCount
the sequence number for the packet
cmdId
the command Id
tag
the tag value to store in the header
destAdrs
the destination address
senderAdrs
the sender address
UIAPacket_setCmdId() // module-wide |
 |
sets the command Id in the packet header
macro Void UIAPacket_setCmdId(
UIAPacket_Hdr *
pHdr,
UInt16 cmdId);
ARGUMENTS
(Hdr* msgHdr) pointer to the packet header
cmdId
the new command Id
DETAILS
Message header is always layed out as big endian (network order).
This macro is designed to work on both little endian and
big endian targets, since 32b long words are consistently
handled for both endianness - it is only when converting
from bytes to longs that bit orders get swapped.
#ifdef xdc_target__bigEndian can be used if necessary.
UIAPacket_setDestAdrs() // module-wide |
 |
sets the packet destination address in the packet header
macro Void UIAPacket_setDestAdrs(
UIAPacket_Hdr *
pHdr,
UInt16 destAdrs);
ARGUMENTS
(Hdr* msgHdr) pointer to the packet header
destAdrs
the new destination address
DETAILS
The destination address identifies which endpoint (i.e. which
CPU or process) the packet should be sent to.
0 is used to broadcast the packet.
1 is used for point-to-point connections.
Replies to a packet always use the sender address in the
originating packet as the destination address.
Destination addresses other than the above can be determined
via a discovery process.
Message header is always layed out as big endian (network order).
This macro is designed to work on both little endian and
big endian targets, since 32b long words are consistently
handled for both endianness - it is only when converting
from bytes to longs that bit orders get swapped.
#ifdef xdc_target__bigEndian can be used if necessary.
UIAPacket_setEventLength() // module-wide |
 |
Sets the packet length (in bytes) from the packet header
macro Void UIAPacket_setEventLength(
UIAPacket_Hdr *
pHdr,
Bits32 pktLength);
ARGUMENTS
(Hdr* msgHdr) pointer to the packet header
pktLength
the new packet length
DETAILS
Includes the packet header
UIAPacket_setEventLengthFast() // module-wide |
 |
Sets the packet length (in bytes) from the packet header
by just writing the length, instead of reading the old
value, setting the length, and writing it back
macro Void UIAPacket_setEventLengthFast(
UIAPacket_Hdr *
pHdr,
Bits32 pktLength);
ARGUMENTS
(Hdr* msgHdr) pointer to the packet header
pktLength
the new packet length
DETAILS
Includes the packet header
UIAPacket_setHdrType() // module-wide |
 |
sets the header type in the packet header
ARGUMENTS
(Hdr* msgHdr) pointer to the packet header
HdrType hdrType
the new header type
DETAILS
Message header is always layed out as big endian (network order).
This macro is designed to work on both little endian and
big endian targets, since 32b long words are consistently
handled for both endianness - it is only when converting
from bytes to longs that bit orders get swapped.
#ifdef xdc_target__bigEndian can be used if necessary.
UIAPacket_setInvalidHdr() // module-wide |
 |
Used to set the header type as invalid
macro Void UIAPacket_setInvalidHdr(
UIAPacket_Hdr *
pHdr,
UInt32 eventLength);
ARGUMENTS
(Hdr* pHdr) pointer to the packet header
eventLength
the number of Bytes in the packet of memory
that is invalid (including the first word of the 32-bit hdr)
UIAPacket_setLoggerInstanceId() // module-wide |
 |
sets the sequence count in the packet header
macro Void UIAPacket_setLoggerInstanceId(
UIAPacket_Hdr *
pHdr,
Bits16 loggerInstanceId);
ARGUMENTS
(Hdr* msgHdr) pointer to the packet header
seqCount
the new packet sequence count
DETAILS
Message header is always layed out as big endian (network order).
This macro is designed to work on both little endian and
big endian targets, since 32b long words are consistently
handled for both endianness - it is only when converting
from bytes to longs that bit orders get swapped.
#ifdef xdc_target__bigEndian can be used if necessary.
UIAPacket_setLoggerModuleId() // module-wide |
 |
sets the module ID in the event packet header
macro Void UIAPacket_setLoggerModuleId(
UIAPacket_Hdr *
pHdr,
Bits16 loggerModuleId);
ARGUMENTS
(Hdr* msgHdr) pointer to the packet header
loggerModuleId
the moduleID of the logger that logged the events
DETAILS
Message header is always layed out as big endian (network order).
This macro is designed to work on both little endian and
big endian targets, since 32b long words are consistently
handled for both endianness - it is only when converting
from bytes to longs that bit orders get swapped.
#ifdef xdc_target__bigEndian can be used if necessary.
UIAPacket_setMinEventPacketLength() // module-wide |
 |
Set UIA packet length of the completed packet
macro Void UIAPacket_setMinEventPacketLength(
UIAPacket_Hdr *
pHdr,
Bits32 pktLength,
UInt16 loggerInstanceId,
UInt16 senderAdrs);
ARGUMENTS
(Hdr* msgHdr) pointer to the packet header
pktLength
the new packet length
loggerInstanceId
the logger's instanceId
senderAdrs
the sender address (i.e. DNUM or endpoint ID, 0 if only 1 CPU per device)
UIAPacket_setMinEventPacketSequenceCount() // module-wide |
 |
stores the current event sequence number and
12 msbs of last timestamp in the packet header
macro Void UIAPacket_setMinEventPacketSequenceCount(
UIAPacket_Hdr *
pHdr,
Bits16 pktSeqCount,
Bits16 eventSeqCount);
ARGUMENTS
(Hdr* pHdr) pointer to the packet header
pktSeqCount
the new packet sequence count
eventSeqCount
the event sequence count for the first event in the packet
DETAILS
Message header is always layed out as big endian (network order).
This macro is designed to work on both little endian and
big endian targets, since 32b long words are consistently
handled for both endianness - it is only when converting
from bytes to longs that bit orders get swapped.
#ifdef xdc_target__bigEndian can be used if necessary.
UIAPacket_setMsgLength() // module-wide |
 |
sets the packet length (in bytes) from the packet header
macro Void UIAPacket_setMsgLength(
UIAPacket_Hdr *
pHdr,
UInt16 pktLength);
ARGUMENTS
(Hdr* msgHdr) pointer to the packet header
pktLength
the new packet length
DETAILS
Message header is always layed out as big endian (network order).
This macro is designed to work on both little endian and
big endian targets, since 32b long words are consistently
handled for both endianness - it is only when converting
from bytes to longs that bit orders get swapped.
#ifdef xdc_target__bigEndian can be used if necessary.
UIAPacket_setMsgType() // module-wide |
 |
sets the packet type in the packet header
ARGUMENTS
(Hdr* msgHdr) pointer to the packet header
msgType
the new packet type
DETAILS
Message header is always layed out as big endian (network order).
This macro is designed to work on both little endian and
big endian targets, since 32b long words are consistently
handled for both endianness - it is only when converting
from bytes to longs that bit orders get swapped.
#ifdef xdc_target__bigEndian can be used if necessary.
UIAPacket_setPayloadEndianness() // module-wide |
 |
sets the payload endianness bit from the packet header
ARGUMENTS
(Hdr* msgHdr) pointer to the packet header
(Hdr* msgHdr) Endianness of the payload
DETAILS
Message header is always layed out as big endian (network order).
This macro is designed to work on both little endian and
big endian targets, since 32b long words are consistently
handled for both endianness - it is only when converting
from bytes to longs that bit orders get swapped.
#ifdef xdc_target__bigEndian can be used if necessary.
UIAPacket_setSenderAdrs() // module-wide |
 |
sets the packet sender address in the packet header
macro Void UIAPacket_setSenderAdrs(
UIAPacket_Hdr *
pHdr,
UInt16 senderAdrs);
ARGUMENTS
(Hdr* msgHdr) pointer to the packet header
senderAdrs
the new destination address
DETAILS
The sender address identifies which endpoint (i.e. which
CPU or process) the packet is coming from
1 is used by default.
Sender addresses other than 1 can be set via configuration
(e.g. to identify which CPU core a packet originated from).
Message header is always layed out as big endian (network order).
This macro is designed to work on both little endian and
big endian targets, since 32b long words are consistently
handled for both endianness - it is only when converting
from bytes to longs that bit orders get swapped.
#ifdef xdc_target__bigEndian can be used if necessary.
UIAPacket_setSequenceCount() // module-wide |
 |
sets the packet sequence count in the packet header
macro Void UIAPacket_setSequenceCount(
UIAPacket_Hdr *
pHdr,
Bits16 seqCount);
ARGUMENTS
(Hdr* msgHdr) pointer to the packet header
seqCount
the new packet sequence count
DETAILS
Message header is always layed out as big endian (network order).
This macro is designed to work on both little endian and
big endian targets, since 32b long words are consistently
handled for both endianness - it is only when converting
from bytes to longs that bit orders get swapped.
#ifdef xdc_target__bigEndian can be used if necessary.
UIAPacket_setSequenceCountFast() // module-wide |
 |
Sets the packet sequence count in the packet header
by directly writing the word, and not reading it first
macro Void UIAPacket_setSequenceCountFast(
UIAPacket_Hdr *
pHdr,
Bits16 seqCount);
ARGUMENTS
(Hdr* msgHdr) pointer to the packet header
seqCount
the new packet sequence count
DETAILS
Message header is always layed out as big endian (network order).
This macro is designed to work on both little endian and
big endian targets, since 32b long words are consistently
handled for both endianness - it is only when converting
from bytes to longs that bit orders get swapped.
#ifdef xdc_target__bigEndian can be used if necessary.
UIAPacket_setSequenceCounts() // module-wide |
 |
sets the packet sequence count and the event sequence count for the first
event in the packet header
macro Void UIAPacket_setSequenceCounts(
UIAPacket_Hdr *
pHdr,
Bits16 pktSeqCount,
Bits16 eventSeqCount);
ARGUMENTS
(Hdr* pHdr) pointer to the packet header
pktSeqCount
the new packet sequence count
eventSeqCount
the event sequence count for the first event in the packet
DETAILS
Message header is always layed out as big endian (network order).
This macro is designed to work on both little endian and
big endian targets, since 32b long words are consistently
handled for both endianness - it is only when converting
from bytes to longs that bit orders get swapped.
#ifdef xdc_target__bigEndian can be used if necessary.
UIAPacket_setServiceId() // module-wide |
 |
sets the packet type in the packet header
macro Void UIAPacket_setServiceId(
UIAPacket_Hdr *
pHdr,
UInt16 serviceId);
ARGUMENTS
(Hdr* msgHdr) pointer to the packet header
serviceId
the new service Id
DETAILS
Message header is always layed out as big endian (network order).
This macro is designed to work on both little endian and
big endian targets, since 32b long words are consistently
handled for both endianness - it is only when converting
from bytes to longs that bit orders get swapped.
#ifdef xdc_target__bigEndian can be used if necessary.
UIAPacket_setTag() // module-wide |
 |
sets the 32b tag field in the packet header
macro Void UIAPacket_setTag(
UIAPacket_Hdr *
pHdr,
Bits32 tagValue);
ARGUMENTS
(Hdr* msgHdr) pointer to the packet header
tagValue
the tag value to store in the header
UIAPacket_swizzle() // module-wide |
 |
returns the value in big endian format
macro Bits32 UIAPacket_swizzle(Bits32 value);
UIAPacket_swizzle16() // module-wide |
 |
returns the value in big endian format
macro Bits16 UIAPacket_swizzle16(Bits16 value);
Module-Wide Built-Ins |
 |
// Get this module's unique id
Bool UIAPacket_Module_startupDone();
// Test if this module has completed startup
// The heap from which this module allocates memory
Bool UIAPacket_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 UIAPacket_Module_getMask();
// Returns the diagnostics mask for this module
Void UIAPacket_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
const UIAPacket.BROADCAST |
 |
Used to denote a broadcast message
const UIAPacket.BROADCAST = 0xFFFE;
DETAILS
The broadcast address is always 0xFFFE.
C SYNOPSIS
const UIAPacket.HOST |
 |
The address of the host
const UIAPacket.HOST = 0xFFFF;
DETAILS
The host address is always 0xFFFF.
C SYNOPSIS
enum UIAPacket.HdrType |
 |
Enumeration of the various types of packet
headers
values of type UIAPacket.HdrType
const UIAPacket.HdrType_InvalidData;
// reserved for future use
const UIAPacket.HdrType_MsgWithPID;
// message with Process ID field (for multi-process O/Ses)
const UIAPacket.HdrType_EventPktWithCRC;
// event packet with CRC of applciation name (for multi-process O/Ses)
const UIAPacket.HdrType_MinEventPkt;
// small footprint event packet used by ti.uia.loggers.LoggerMin
const UIAPacket.HdrType_Reserved4;
// reserved for future use
const UIAPacket.HdrType_Reserved5;
// reserved for future use
const UIAPacket.HdrType_Reserved6;
// reserved for future use
const UIAPacket.HdrType_Reserved7;
// reserved for future use
const UIAPacket.HdrType_ChannelizedData;
// Channelized data stream
const UIAPacket.HdrType_Msg;
// Message (4 words header, 1 word footer)
const UIAPacket.HdrType_EventPkt;
// Event rec. containing multiple events:
(4 word hdr, 1 word footer)
const UIAPacket.HdrType_CPUTrace;
// CPU Trace ETB data
(4 word hdr, 1 word footer)
const UIAPacket.HdrType_STMTrace;
// STM Trace ETB data
(4 word hdr, 1 word footer)
const UIAPacket.HdrType_MemoryBuffer;
// Memory Buffer data
const UIAPacket.HdrType_USER2;
// User defined header type 2
const UIAPacket.HdrType_USER3;
// User defined header type 3
DETAILS
Stored in a 4 bit bitfield (b31-b28) of the first word in the
packet.
The HdrType_InvalidData denotes that following data is invalid.
This can used to pad to the end of a buffer. Only the first word
of the header is filled in. The length includes the header field.
C SYNOPSIS
enum UIAPacket.MsgType |
 |
Message Types
values of type UIAPacket.MsgType
const UIAPacket.MsgType_ACK;
// Reply acknowledging receipt of CMD or DATA packet
const UIAPacket.MsgType_CMD;
// Command packets
const UIAPacket.MsgType_RESULT;
// Result reply
const UIAPacket.MsgType_PARTIALRESULT;
// Partial result reply
const UIAPacket.MsgType_NOTIFY;
// Notify messaage (equiv. to the EVENT packet in TCF)
const UIAPacket.MsgType_FLOWCTRL;
// Flow control packet
const UIAPacket.MsgType_DATA;
// Data packet (used for streaming data to host)
const UIAPacket.MsgType_RESERVED7;
const UIAPacket.MsgType_RESERVED8;
const UIAPacket.MsgType_RESERVED9;
const UIAPacket.MsgType_RESERVED10;
const UIAPacket.MsgType_RESERVED11;
const UIAPacket.MsgType_RESERVED12;
const UIAPacket.MsgType_RESERVED13;
const UIAPacket.MsgType_NACK_BAD_DATA;
// Negative Acknowledge due to bad data
const UIAPacket.MsgType_NACK_WITH_ERROR_CODE;
// Negative Acknowledge -
error code in msg body
DETAILS
Enumeration of the various types of packets.
Stored in a 4 bit bitfield.
MsgType_ACK:
Each packet of type CMD or DATA is immediately acknowledged by
sending either an ACK reply (if the packet can be processed),
a RESULT or PARTIALRESULT reply (if requested data can be provided
immediately) or a NACK reply (if the packet cannot be processed).
The Service that receives the command is responsible for sending
the ACK or NACK. If the requested service is not available, the
Endpoint is responsible for sending the NACK packet.
MsgType_CMD:
CMD packets are typically sent from the host to the target.
The receiving endpoint routes the command to the service
identified in the Service Id field.
MsgType_RESULT:
RESULT replies are sent along with any requested data.
If the Service cannot reply with the requested data immediately,
it should return with an ACK packet and send a RESULT packet
that echoes the header info of the original command.
MsgType_PARTIALRESULT:
PARTIALRESULT replies are sent along with any requested data when the
requested action can only be partly fulfilled. Examples are when the
service is reporting on some ongoing operation or has been requested
to periodically poll some data value.
MsgType_EVENT:
EVENT packets are sent to all interested parties in order to notify them
about state changes. They can, for example, be used to report an error
that has occurred which may impact the ability of the target to continue
operating normally.
MsgType_FLOWCTRL
FLOWCTRL packets are provided for TCF compliance. They are used to avoid
flooding of communication links. In response, endpoints can either
increase or decrease rate of packets sent, although this is only loosely
defined. TCF services are not directly concerned with flow control.
The data passed with FLOWCTRL packets reports the traffic congestion level
as an integer between -100 and 100, where 0 = "optimal load"
MsgType_DATA
DATA packets are used for sending event log data and other streams of data.
Details about how this will be used are being worked out to ensure alignment
with BIOS RTA Log Servers.
MsgType_NACK_BAD_DATA:
Negative Acknowledge due to bad data. Sent in response to a command that
had invalid data in the body of the packet. The original data is echoed
in the NACK response.
MsgType_NACK_WITH_ERROR_CODE
Negative Acknowledge with Error Code. Sent along with an error code in
the first word of the body of the reply that describes the error that was
encountered
C SYNOPSIS
enum UIAPacket.NACKErrorCode |
 |
Message Negative Acknowledge Error Codes
values of type UIAPacket.NACKErrorCode
const UIAPacket.NACKErrorCode_NO_REASON_SPECIFIED;
// Use this when none of the
defined NACK error codes are
appropriate
const UIAPacket.NACKErrorCode_SERVICE_NOT_SUPPORTED;
// A module that handles the
requested Service Id could
not be found
const UIAPacket.NACKErrorCode_CMD_NOT_SUPPORTED;
// The service does not support the
specified Command Id
const UIAPacket.NACKErrorCode_QUEUE_FULL;
// Cmd couldn't be passed on to dest. end
point due to a queue full condition
const UIAPacket.NACKErrorCode_BAD_ENDPOINT_ADDRESS;
// The destination end point
address does not exists
const UIAPacket.NACKErrorCode_BAD_MESSAGE_LENGTH;
// packet lenght > endpoint max.
msg length or not what is
required to service the cmd
DETAILS
Stored in the first 32b word of the data body of the packet
in Network Byte Order
C SYNOPSIS
enum UIAPacket.PayloadEndian |
 |
Enumeration of payload endianness
values of type UIAPacket.PayloadEndian
const UIAPacket.PayloadEndian_LITTLE;
const UIAPacket.PayloadEndian_BIG;
C SYNOPSIS
struct UIAPacket.Footer |
 |
Packet Footer
var obj = new UIAPacket.Footer;
obj.word1 = Int32 ...
// 16 MSBs contain msg length in Bytes,
16 LSBs contain 0x7777
DETAILS
The packet footer is always in network byte order
i.e. big-endian byte ordering
C SYNOPSIS
struct UIAPacket.Hdr |
 |
UIAPacket Header
var obj = new UIAPacket.Hdr;
obj.word1 = Bits32 ...
obj.word2 = Bits32 ...
obj.word3 = Bits32 ...
obj.word4 = Bits32 ...
DETAILS
The following is a breakdown of the packet header based on type packet.
The packet header is always sent in network byte (big endian) order.
The top 4 leftmost bits of word1 denote what type of packet this is:
HdrType_Msg or HdrType_EventPkt. The contents of the packet depends on
this type.
HdrType_Msg word1
3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0
1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
|---------------------------------------------------------------|
|H H H H|E|L L L L L L L L L L L|T T T T|S S S S S S S S S S S S|
|---------------------------------------------------------------|
H = HdrType (4-bits)
E = Payload endian (1-bit)
L = Message Length (11-bits)
T = Message Type (4-bits)
S = Service Id (12-bits)
HdrType_Msg word2
3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0
1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
|---------------------------------------------------------------|
|S S S S S S S S S S S S S S S S|C C C C C C C C C C C C C C C C|
|---------------------------------------------------------------|
S = Sequence Number (16-bits)
C = Command Id (16-bits)
HdrType_Msg word3
3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0
1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
|---------------------------------------------------------------|
|T T T T T T T T T T T T T T T T T T T T T T T T T T T T T T T T|
|---------------------------------------------------------------|
T - Tag (32-bits)
HdrType_Msg word4
3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0
1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
|---------------------------------------------------------------|
|D D D D D D D D D D D D D D D D|S S S S S S S S S S S S S S S S|
|---------------------------------------------------------------|
D - Destination Address (16-bits)
S - Source Address (16-bits)
HdrType_EventPkt word1
3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0
1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
|---------------------------------------------------------------|
|H H H H|E|L L L L L L L L L L L L L L L L L L L L L L L L L L L|
|---------------------------------------------------------------|
H = HdrType (4-bits)
E = Payload endian (1-bit)
L = Packet Length (27-bits)
HdrType_EventPkt word2
3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0
1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
|---------------------------------------------------------------|
|S S S S S S S S S S S S S S S S|E E E E E E E E E E E E E E|P P|
|---------------------------------------------------------------|
S = Packet Sequence Number (16-bits)
E = Event Sequence Number for first event in the packet (14-bits)
P = Priority: Normal=0, High > 0 (2-bits)
HdrType_EventPkt word3
3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0
1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
|---------------------------------------------------------------|
|D I I I I I I I I I I I I I I I M M M M M M M M M M M M M M M M|
|---------------------------------------------------------------|
D - wasLoggerDynamicallyCreated (1-bit: 0 = statically created,
1 = dynamically created)
I - Logger Instance ID (15-bits)
M - Logger Module ID (16-bits)
HdrType_EventPkt word4
3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0
1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
|---------------------------------------------------------------|
|D D D D D D D D D D D D D D D D|S S S S S S S S S S S S S S S S|
|---------------------------------------------------------------|
D - Destination Address (16-bits)
S - Source Address (16-bits)
For HdrType_EventPktWithCRC
word 5 holds the 16b CRC of the application name (0 for RTOSes such as SysBIOS)
3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0
1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
|---------------------------------------------------------------|
|R R R R R R R R R R R R R R R|C C C C C C C C C C C C C C C C C|
|---------------------------------------------------------------|
C = CRC16 of the application name (0 if only one process) (32-bits)
R = Reserved (set to 0)
For memory constrained systems, ti.uia.loggers.LoggerMin uses the
following 2 word Event Packet header format, with HdrType =
HdrType_MinEventPkt :
3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0
1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
|---------------------------------------------------------------|
|H H H H|E|D D D D D|R R R R R R|L L L L L L L L L L L L L L L L|
|---------------------------------------------------------------|
H = HdrType (4-bits)
E = Payload endian (1-bit)
D = Sender Adrs / Device ID (5 bits – DNUM)
R = Reserved (set to 0)
L = packet Length (16-bits)
HdrType_MinEventPkt word2
3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0
1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
|---------------------------------------------------------------|
|S S S S S S S S S S S S S S S S|E E E E E E E E E E E E E E|P P|
|---------------------------------------------------------------|
S = Packet Sequence Number (16-bits)
E = Event Sequence Number for first event in the packet (14-bits)
P = Priority: Normal=0, High > 0 (2-bits)
C SYNOPSIS
config UIAPacket.maxPktLengthInBytes // module-wide |
 |
maximum number of bytes a packet can contain
UIAPacket.maxPktLengthInBytes = Int 128;
DETAILS
used to limit the amount of memory needed by the
packet factories in order to handle a new packet
C SYNOPSIS
metaonly config UIAPacket.common$ // module-wide |
 |
Common module configuration parameters
DETAILS
All modules have this configuration parameter. Its name
contains the '$' character to ensure it does not conflict with
configuration parameters declared by the module. This allows
new configuration parameters to be added in the future without
any chance of breaking existing modules.