1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
32
33 34 35
36 package ti.uia.runtime;
37
38 import ti.uia.runtime.IUIATransfer;
39
40 /*!
41 * ======== UIAPacket ========
42 * Packet format communications between instrumentation clients
43 * and instrumentation endpoints
44 */
45 @CustomHeader
46 module UIAPacket {
47
48 /*!
49 * ======== Hdr ========
50 * UIAPacket Header
51 *
52 * The following is a breakdown of the packet header based on type packet.
53 *
54 * The packet header is always sent in network byte (big endian) order.
55 *
56 * The top 4 leftmost bits of word1 denote what type of packet this is:
57 * HdrType_Msg or HdrType_EventPkt. The contents of the packet depends on
58 * this type.
59 *
60 * @p(code)
61 *
62 * HdrType_Msg word1
63 * 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
64 * 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
65 * |---------------------------------------------------------------|
66 * |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|
67 * |---------------------------------------------------------------|
68 *
69 * H = HdrType (4-bits)
70 * E = Payload endian (1-bit)
71 * L = Message Length (11-bits)
72 * T = Message Type (4-bits)
73 * S = Service Id (12-bits)
74 *
75 * HdrType_Msg word2
76 * 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
77 * 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
78 * |---------------------------------------------------------------|
79 * |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|
80 * |---------------------------------------------------------------|
81 *
82 * S = Sequence Number (16-bits)
83 * C = Command Id (16-bits)
84 *
85 * HdrType_Msg word3
86 * 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
87 * 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
88 * |---------------------------------------------------------------|
89 * |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|
90 * |---------------------------------------------------------------|
91 *
92 * T - Tag (32-bits)
93 *
94 * HdrType_Msg word4
95 * 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
96 * 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
97 * |---------------------------------------------------------------|
98 * |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|
99 * |---------------------------------------------------------------|
100 *
101 * D - Destination Address (16-bits)
102 * S - Source Address (16-bits)
103 *
104 * @p(code)
105 *
106 * HdrType_EventPkt word1
107 * 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
108 * 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
109 * |---------------------------------------------------------------|
110 * |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|
111 * |---------------------------------------------------------------|
112 *
113 * H = HdrType (4-bits)
114 * E = Payload endian (1-bit)
115 * L = Packet Length (27-bits)
116 *
117 * HdrType_EventPkt word2
118 * 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
119 * 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
120 * |---------------------------------------------------------------|
121 * |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|
122 * |---------------------------------------------------------------|
123 *
124 * S = Packet Sequence Number (16-bits)
125 * E = Event Sequence Number for first event in the packet (14-bits)
126 * P = Priority: Normal=0, High > 0 (2-bits)
127 *
128 * HdrType_EventPkt word3
129 * 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
130 * 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
131 * |---------------------------------------------------------------|
132 * |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|
133 * |---------------------------------------------------------------|
134 *
135 * D - wasLoggerDynamicallyCreated (1-bit: 0 = statically created,
136 * 1 = dynamically created )
137 * I - Logger Instance ID (15-bits)
138 * M - Logger Module ID (16-bits)
139 *
140 * HdrType_EventPkt word4
141 * 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
142 * 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
143 * |---------------------------------------------------------------|
144 * |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|
145 * |---------------------------------------------------------------|
146 *
147 * D - Destination Address (16-bits)
148 * S - Source Address (16-bits)
149 *
150 * @p(code)
151 *
152 * For HdrType_EventPktWithCRC
153 * word 5 holds the 16b CRC of the application name (0 for RTOSes such as SysBIOS)
154 * 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
155 * 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
156 * |---------------------------------------------------------------|
157 * |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|
158 * |---------------------------------------------------------------|
159 * C = CRC16 of the application name (0 if only one process) (32-bits)
160 * R = Reserved (set to 0)
161 *
162 * @p(code)
163 *
164 * For memory constrained systems, ti.uia.loggers.LoggerMin uses the
165 * following 2 word Event Packet header format, with HdrType =
166 * HdrType_MinEventPkt :
167 *
168 * 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
169 * 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
170 * |---------------------------------------------------------------|
171 * |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|
172 * |---------------------------------------------------------------|
173 *
174 * H = HdrType (4-bits)
175 * E = Payload endian (1-bit)
176 * D = Sender Adrs / Device ID (5 bits – DNUM)
177 * R = Reserved (set to 0)
178 * L = packet Length (16-bits)
179 *
180 * HdrType_MinEventPkt word2
181 * 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
182 * 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
183 * |---------------------------------------------------------------|
184 * |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|
185 * |---------------------------------------------------------------|
186 *
187 * S = Packet Sequence Number (16-bits)
188 * E = Event Sequence Number for first event in the packet (14-bits)
189 * P = Priority: Normal=0, High > 0 (2-bits)
190 */
191 struct Hdr {
192 Bits32 word1;
193 Bits32 word2;
194 Bits32 word3;
195 Bits32 word4;
196 };
197
198 /*!
199 * ======== HdrType ========
200 * Enumeration of the various types of packet
201 * headers.
202 *
203 * Stored in a 4 bit bitfield (b31-b28) of the first word in the
204 * packet.
205 *
206 * The HdrType_InvalidData denotes that following data is invalid.
207 * This can used to pad to the end of a buffer. Only the first word
208 * of the header is filled in. The length includes the header field.
209 *
210 */
211 enum HdrType {
212 HdrType_InvalidData = 0, /*! reserved for future use */
213 HdrType_MsgWithPID = 1, /*! message with Process ID field (for multi-process O/Ses) */
214 HdrType_EventPktWithCRC = 2, /*! event packet with CRC of applciation name (for multi-process O/Ses) */
215 HdrType_MinEventPkt = 3, /*! small footprint event packet used by ti.uia.loggers.LoggerMin */
216 HdrType_Reserved4 = 4, /*! reserved for future use */
217 HdrType_Reserved5 = 5, /*! reserved for future use */
218 HdrType_Reserved6 = 6, /*! reserved for future use */
219 HdrType_Reserved7 = 7, /*! reserved for future use */
220 HdrType_ChannelizedData = 8, /*! Channelized data stream */
221 HdrType_Msg = 9, /*! Message (4 words header, 1 word footer) */
222 HdrType_EventPkt = 10, /*! Event rec. containing multiple events:
223 (4 word hdr, 1 word footer) */
224 HdrType_CPUTrace = 11, /*! CPU Trace ETB data
225 (4 word hdr, 1 word footer) */
226 HdrType_STMTrace = 12, /*! STM Trace ETB data
227 (4 word hdr, 1 word footer) */
228 HdrType_MemoryBuffer = 13, /*! Memory Buffer data */
229 HdrType_USER2 = 14, /*! User defined header type 2 */
230 HdrType_USER3 = 15 /*! User defined header type 3 */
231 };
232
233
234 /*!
235 * ======== PayloadEndian ========
236 * Enumeration of payload endianness
237 */
238 enum PayloadEndian {
239 PayloadEndian_LITTLE = 0,
240 PayloadEndian_BIG = 1
241 };
242
243 /*!
244 * ======== Footer ========
245 * Packet Footer
246 *
247 * The packet footer is always in network byte order
248 * i.e. big-endian byte ordering
249 */
250 struct Footer
251 {
252 Int32 word1; /*! 16 MSBs contain msg length in Bytes,
253 16 LSBs contain 0x7777 */
254 }
255
256 /*!
257 * ======== MsgType ========
258 * Message Types
259 *
260 * Enumeration of the various types of packets.
261 * Stored in a 4 bit bitfield.
262 *
263 * MsgType_ACK:
264 * Each packet of type CMD or DATA is immediately acknowledged by
265 * sending either an ACK reply (if the packet can be processed),
266 * a RESULT or PARTIALRESULT reply (if requested data can be provided
267 * immediately) or a NACK reply (if the packet cannot be processed).
268 * The Service that receives the command is responsible for sending
269 * the ACK or NACK. If the requested service is not available, the
270 * Endpoint is responsible for sending the NACK packet.
271 *
272 * MsgType_CMD:
273 * CMD packets are typically sent from the host to the target.
274 * The receiving endpoint routes the command to the service
275 * identified in the Service Id field.
276 *
277 * MsgType_RESULT:
278 * RESULT replies are sent along with any requested data.
279 * If the Service cannot reply with the requested data immediately,
280 * it should return with an ACK packet and send a RESULT packet
281 * that echoes the header info of the original command.
282 *
283 * MsgType_PARTIALRESULT:
284 * PARTIALRESULT replies are sent along with any requested data when the
285 * requested action can only be partly fulfilled. Examples are when the
286 * service is reporting on some ongoing operation or has been requested
287 * to periodically poll some data value.
288 *
289 * MsgType_EVENT:
290 * EVENT packets are sent to all interested parties in order to notify them
291 * about state changes. They can, for example, be used to report an error
292 * that has occurred which may impact the ability of the target to continue
293 * operating normally.
294 *
295 * MsgType_FLOWCTRL
296 * FLOWCTRL packets are provided for TCF compliance. They are used to avoid
297 * flooding of communication links. In response, endpoints can either
298 * increase or decrease rate of packets sent, although this is only loosely
299 * defined. TCF services are not directly concerned with flow control.
300 * The data passed with FLOWCTRL packets reports the traffic congestion level
301 * as an integer between -100 and 100, where 0 = "optimal load"
302 *
303 * MsgType_DATA
304 * DATA packets are used for sending event log data and other streams of data.
305 * Details about how this will be used are being worked out to ensure alignment
306 * with BIOS RTA Log Servers.
307 *
308 * MsgType_NACK_BAD_DATA:
309 * Negative Acknowledge due to bad data. Sent in response to a command that
310 * had invalid data in the body of the packet. The original data is echoed
311 * in the NACK response.
312 *
313 * MsgType_NACK_WITH_ERROR_CODE
314 * Negative Acknowledge with Error Code. Sent along with an error code in
315 * the first word of the body of the reply that describes the error that was
316 * encountered
317 */
318 enum MsgType {
319 MsgType_ACK=0, /*! Reply acknowledging receipt of CMD or DATA packet */
320 MsgType_CMD=1, /*! Command packets */
321 MsgType_RESULT=2, /*! Result reply */
322 MsgType_PARTIALRESULT=3, /*! Partial result reply */
323 MsgType_NOTIFY=4, /*! Notify messaage (equiv. to the EVENT packet in TCF) */
324 MsgType_FLOWCTRL=5, /*! Flow control packet */
325 MsgType_DATA=6, /*! Data packet (used for streaming data to host) */
326 MsgType_RESERVED7,
327 MsgType_RESERVED8,
328 MsgType_RESERVED9,
329 MsgType_RESERVED10,
330 MsgType_RESERVED11,
331 MsgType_RESERVED12,
332 MsgType_RESERVED13,
333 MsgType_NACK_BAD_DATA=14, /*! Negative Acknowledge due to bad data */
334 MsgType_NACK_WITH_ERROR_CODE=15 /*! Negative Acknowledge -
335 error code in msg body */
336 };
337
338 /*!
339 * ======== NACKErrorCode ========
340 * Message Negative Acknowledge Error Codes
341 *
342 * Stored in the first 32b word of the data body of the packet
343 * in Network Byte Order
344 */
345 enum NACKErrorCode {
346 NACKErrorCode_NO_REASON_SPECIFIED=0, /*! Use this when none of the
347 defined NACK error codes are
348 appropriate */
349 NACKErrorCode_SERVICE_NOT_SUPPORTED=1, /*! A module that handles the
350 requested Service Id could
351 not be found */
352 NACKErrorCode_CMD_NOT_SUPPORTED=2, /*! The service does not support the
353 specified Command Id */
354 NACKErrorCode_QUEUE_FULL=3, /*! Cmd couldn't be passed on to dest. end
355 point due to a queue full condition */
356 NACKErrorCode_BAD_ENDPOINT_ADDRESS=4, /*! The destination end point
357 address does not exists */
358 NACKErrorCode_BAD_MESSAGE_LENGTH=5 /*! packet lenght > endpoint max.
359 msg length or not what is
360 required to service the cmd */
361 };
362
363 /*!
364 * ======== HOST ========
365 * The address of the host
366 *
367 * The host address is always 0xFFFF.
368 */
369 const UInt16 HOST = 0xFFFF;
370
371 /*!
372 * ======== BROADCAST ========
373 * Used to denote a broadcast message
374 *
375 * The broadcast address is always 0xFFFE.
376 */
377 const UInt16 BROADCAST = 0xFFFE;
378
379 /*!
380 * ========= maxPktLengthInBytes =========
381 * maximum number of bytes a packet can contain
382 *
383 * used to limit the amount of memory needed by the
384 * packet factories in order to handle a new packet
385 */
386 config Int maxPktLengthInBytes = 128;
387
388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403
404
405 /*!
406 * ======== swizzle ========
407 * returns the value in big endian format
408 */
409 @Macro Bits32 swizzle(Bits32 value);
410
411 /*!
412 * ======== swizzle ========
413 * returns the value in big endian format
414 */
415 @Macro Bits16 swizzle16(Bits16 value);
416
417 /*!
418 * ======== getHdrType ========
419 * gets the packet header type from the packet header
420 *
421 * Message header is always layed out as big endian (network order).
422 * This macro is designed to work on both little endian and
423 * big endian targets, since 32b long words are consistently
424 * handled for both endianness - it is only when converting
425 * from bytes to longs that bit orders get swapped.
426 * #ifdef xdc_target__bigEndian can be used if necessary.
427 *
428 * @param(Hdr* msgHdr) pointer to the packet header
429 */
430 @Macro HdrType getHdrType(Hdr *pHdr);
431
432 /*!
433 * ======== setHdrType ========
434 * sets the header type in the packet header
435 *
436 * Message header is always layed out as big endian (network order).
437 * This macro is designed to work on both little endian and
438 * big endian targets, since 32b long words are consistently
439 * handled for both endianness - it is only when converting
440 * from bytes to longs that bit orders get swapped.
441 * #ifdef xdc_target__bigEndian can be used if necessary.
442 *
443 * @param(Hdr* msgHdr) pointer to the packet header
444 * @param(HdrType hdrType) the new header type
445 */
446 @Macro Void setHdrType(Hdr *pHdr, HdrType hdrType);
447
448 /*!
449 * ======== getPayloadEndianness ========
450 * gets the payload endianness bit from the packet header
451 *
452 * Message header is always layed out as big endian (network order).
453 * This macro is designed to work on both little endian and
454 * big endian targets, since 32b long words are consistently
455 * handled for both endianness - it is only when converting
456 * from bytes to longs that bit orders get swapped.
457 * #ifdef xdc_target__bigEndian can be used if necessary.
458 *
459 * @param(Hdr* msgHdr) pointer to the packet header
460 */
461 @Macro Bits32 getPayloadEndianness(Hdr *pHdr);
462
463 /*!
464 * ======== setPayloadEndianness ========
465 * sets the payload endianness bit from the packet header
466 *
467 * Message header is always layed out as big endian (network order).
468 * This macro is designed to work on both little endian and
469 * big endian targets, since 32b long words are consistently
470 * handled for both endianness - it is only when converting
471 * from bytes to longs that bit orders get swapped.
472 * #ifdef xdc_target__bigEndian can be used if necessary.
473 *
474 * @param(Hdr* msgHdr) pointer to the packet header
475 * @param(Hdr* msgHdr) Endianness of the payload
476 */
477 @Macro Bits32 setPayloadEndianness(Hdr *pHdr, PayloadEndian endianess);
478
479 /*!
480 * ======== getMsgLength ========
481 * gets the packet length (in bytes) from the packet header
482 *
483 * Message header is always layed out as big endian (network order).
484 * This macro is designed to work on both little endian and
485 * big endian targets, since 32b long words are consistently
486 * handled for both endianness - it is only when converting
487 * from bytes to longs that bit orders get swapped.
488 * #ifdef xdc_target__bigEndian can be used if necessary.
489 *
490 * @param(Hdr* msgHdr) pointer to the packet header
491 */
492 @Macro Int32 getMsgLength(Hdr *pHdr);
493
494 /*!
495 * ======== setMsgLength ========
496 * sets the packet length (in bytes) from the packet header
497 *
498 * Message header is always layed out as big endian (network order).
499 * This macro is designed to work on both little endian and
500 * big endian targets, since 32b long words are consistently
501 * handled for both endianness - it is only when converting
502 * from bytes to longs that bit orders get swapped.
503 * #ifdef xdc_target__bigEndian can be used if necessary.
504 *
505 * @param(Hdr* msgHdr) pointer to the packet header
506 * @param(pktLength) the new packet length
507 *
508 */
509 @Macro Void setMsgLength(Hdr *pHdr, UInt16 pktLength);
510
511 /*!
512 * ======== getEventLength ========
513 * Gets the packet length (in bytes) from the packet header
514 *
515 * Includes the packet header
516 *
517 * @param(Hdr* msgHdr) pointer to the packet header
518 */
519 @Macro Int32 getEventLength(Hdr *pHdr);
520
521 /*!
522 * ======== setEventLength ========
523 * Sets the packet length (in bytes) from the packet header
524 *
525 * Includes the packet header
526 *
527 * @param(Hdr* msgHdr) pointer to the packet header
528 * @param(pktLength) the new packet length
529 *
530 */
531 @Macro Void setEventLength(Hdr *pHdr, Bits32 pktLength);
532
533 /*!
534 * ======== setEventLengthFast ========
535 * Sets the packet length (in bytes) from the packet header
536 * by just writing the length, instead of reading the old
537 * value, setting the length, and writing it back.
538 *
539 * Includes the packet header
540 *
541 * @param(Hdr* msgHdr) pointer to the packet header
542 * @param(pktLength) the new packet length
543 *
544 */
545 @Macro Void setEventLengthFast(Hdr *pHdr, Bits32 pktLength);
546
547 /*!
548 * ======== setMinEventPacketLength ========
549 * Set UIA packet length of the completed packet
550 *
551 * @param(Hdr* msgHdr) pointer to the packet header
552 * @param(pktLength) the new packet length
553 * @param(loggerInstanceId) the logger's instanceId
554 * @param(senderAdrs) the sender address (i.e. DNUM or endpoint ID, 0 if only 1 CPU per device)
555 */
556 @Macro Void setMinEventPacketLength(Hdr *pHdr, Bits32 pktLength,
557 UInt16 loggerInstanceId,
558 UInt16 senderAdrs);
559 /*!
560 * ======== getLength ========
561 * Gets the packet length (in bytes) from the packet header
562 *
563 * Includes the packet header
564 *
565 * @param(Hdr* msgHdr) pointer to the packet header
566 */
567 Int32 getLength(Hdr *pHdr);
568
569 /*!
570 * ======== getSequenceCount ========
571 * gets the sequence count from the packet header
572 *
573 * Message header is always layed out as big endian (network order).
574 * This macro is designed to work on both little endian and
575 * big endian targets, since 32b long words are consistently
576 * handled for both endianness - it is only when converting
577 * from bytes to longs that bit orders get swapped.
578 * #ifdef xdc_target__bigEndian can be used if necessary.
579 *
580 * @param(Hdr* msgHdr) pointer to the packet header
581 */
582 @Macro UInt16 getSequenceCount(Hdr *pHdr);
583
584 /*!
585 * ======== setSequenceCount ========
586 * sets the packet sequence count in the packet header
587 *
588 * Message header is always layed out as big endian (network order).
589 * This macro is designed to work on both little endian and
590 * big endian targets, since 32b long words are consistently
591 * handled for both endianness - it is only when converting
592 * from bytes to longs that bit orders get swapped.
593 * #ifdef xdc_target__bigEndian can be used if necessary.
594 *
595 * @param(Hdr* msgHdr) pointer to the packet header
596 * @param(seqCount) the new packet sequence count
597 */
598 @Macro Void setSequenceCount(Hdr *pHdr, Bits16 seqCount);
599
600 /*!
601 * ======== setSequenceCountFast ========
602 * Sets the packet sequence count in the packet header
603 * by directly writing the word, and not reading it first.
604 *
605 * Message header is always layed out as big endian (network order).
606 * This macro is designed to work on both little endian and
607 * big endian targets, since 32b long words are consistently
608 * handled for both endianness - it is only when converting
609 * from bytes to longs that bit orders get swapped.
610 * #ifdef xdc_target__bigEndian can be used if necessary.
611 *
612 * @param(Hdr* msgHdr) pointer to the packet header
613 * @param(seqCount) the new packet sequence count
614 */
615 @Macro Void setSequenceCountFast(Hdr *pHdr, Bits16 seqCount);
616
617 /*!
618 * ======== setSequenceCounts ========
619 * sets the packet sequence count and the event sequence count for the first
620 * event in the packet header
621 *
622 * Message header is always layed out as big endian (network order).
623 * This macro is designed to work on both little endian and
624 * big endian targets, since 32b long words are consistently
625 * handled for both endianness - it is only when converting
626 * from bytes to longs that bit orders get swapped.
627 * #ifdef xdc_target__bigEndian can be used if necessary.
628 *
629 * @param(Hdr* pHdr) pointer to the packet header
630 * @param(pktSeqCount) the new packet sequence count
631 * @param(eventSeqCount) the event sequence count for the first event in the packet
632 */
633 @Macro Void setSequenceCounts(Hdr *pHdr, Bits16 pktSeqCount, Bits16 eventSeqCount );
634
635 /*!
636 * ======== setMinEventPacketSequenceCountFast ========
637 * stores the current event sequence number and
638 * 12 msbs of last timestamp in the packet header
639 *
640 * Message header is always layed out as big endian (network order).
641 * This macro is designed to work on both little endian and
642 * big endian targets, since 32b long words are consistently
643 * handled for both endianness - it is only when converting
644 * from bytes to longs that bit orders get swapped.
645 * #ifdef xdc_target__bigEndian can be used if necessary.
646 *
647 * @param(Hdr* pHdr) pointer to the packet header
648 * @param(pktSeqCount) the new packet sequence count
649 * @param(eventSeqCount) the event sequence count for the first event in the packet
650 */
651 @Macro Void setMinEventPacketSequenceCount(Hdr *pHdr, Bits16 pktSeqCount, Bits16 eventSeqCount);
652
653 /*! @_nodoc
654 * ======== getLoggerPriority ========
655 * gets the logger priority field from the event packet header
656 *
657 * Message header is always layed out as big endian (network order).
658 * This macro is designed to work on both little endian and
659 * big endian targets, since 32b long words are consistently
660 * handled for both endianness - it is only when converting
661 * from bytes to longs that bit orders get swapped.
662 * #ifdef xdc_target__bigEndian can be used if necessary.
663 *
664 * @param(Hdr* msgHdr) pointer to the packet header
665 * @a(return) the priority of the logger that logged the events
666 * @see IUIATransfer#Priority
667 */
668 @Macro IUIATransfer.Priority getLoggerPriority(Hdr *pHdr);
669
670 /*! @_nodoc
671 * ======== setLoggerPriority ========
672 * sets the logger priority field in the event packet header
673 *
674 * Message header is always layed out as big endian (network order).
675 * This macro is designed to work on both little endian and
676 * big endian targets, since 32b long words are consistently
677 * handled for both endianness - it is only when converting
678 * from bytes to longs that bit orders get swapped.
679 * #ifdef xdc_target__bigEndian can be used if necessary.
680 *
681 * @param(Hdr* msgHdr) pointer to the packet header
682 * @param(priority) the logger priority ( @see IUIATransfer#Priority )
683 */
684 @Macro Void setLoggerPriority(Hdr *pHdr, IUIATransfer.Priority priority);
685 /*!
686 * ======== getLoggerModuleId ========
687 * gets the logger ID from the event packet header
688 *
689 * Message header is always layed out as big endian (network order).
690 * This macro is designed to work on both little endian and
691 * big endian targets, since 32b long words are consistently
692 * handled for both endianness - it is only when converting
693 * from bytes to longs that bit orders get swapped.
694 * #ifdef xdc_target__bigEndian can be used if necessary.
695 *
696 * @param(Hdr* msgHdr) pointer to the packet header
697 */
698 @Macro Bits16 getLoggerModuleId(Hdr *pHdr);
699
700 /*!
701 * ======== setLoggerModuleId ========
702 * sets the module ID in the event packet header
703 *
704 * Message header is always layed out as big endian (network order).
705 * This macro is designed to work on both little endian and
706 * big endian targets, since 32b long words are consistently
707 * handled for both endianness - it is only when converting
708 * from bytes to longs that bit orders get swapped.
709 * #ifdef xdc_target__bigEndian can be used if necessary.
710 *
711 * @param(Hdr* msgHdr) pointer to the packet header
712 * @param(loggerModuleId) the moduleID of the logger that logged the events
713 */
714 @Macro Void setLoggerModuleId(Hdr *pHdr, Bits16 loggerModuleId);
715
716 /*!
717 * ======== getLoggerInstanceId ========
718 * gets the logger instance ID from the event packet header
719 *
720 * Message header is always layed out as big endian (network order).
721 * This macro is designed to work on both little endian and
722 * big endian targets, since 32b long words are consistently
723 * handled for both endianness - it is only when converting
724 * from bytes to longs that bit orders get swapped.
725 * #ifdef xdc_target__bigEndian can be used if necessary.
726 *
727 * @param(Hdr* msgHdr) pointer to the packet header
728 */
729 @Macro Bits16 getLoggerInstanceId(Hdr *pHdr);
730
731 /*!
732 * ======== setLoggerInstanceId ========
733 * sets the sequence count in the packet header
734 *
735 * Message header is always layed out as big endian (network order).
736 * This macro is designed to work on both little endian and
737 * big endian targets, since 32b long words are consistently
738 * handled for both endianness - it is only when converting
739 * from bytes to longs that bit orders get swapped.
740 * #ifdef xdc_target__bigEndian can be used if necessary.
741 *
742 * @param(Hdr* msgHdr) pointer to the packet header
743 * @param(seqCount) the new packet sequence count
744 */
745 @Macro Void setLoggerInstanceId(Hdr *pHdr, Bits16 loggerInstanceId);
746
747 /*!
748 * ======== getMsgType ========
749 * gets the packet type from the packet header
750 *
751 * Message header is always layed out as big endian (network order).
752 * This macro is designed to work on both little endian and
753 * big endian targets, since 32b long words are consistently
754 * handled for both endianness - it is only when converting
755 * from bytes to longs that bit orders get swapped.
756 * #ifdef xdc_target__bigEndian can be used if necessary.
757 *
758 * @param(Hdr* pHdr) pointer to the packet header
759 */
760 @Macro MsgType getMsgType(Hdr *pHdr);
761
762 /*!
763 * ======== setMsgType ========
764 * sets the packet type in the packet header
765 *
766 * Message header is always layed out as big endian (network order).
767 * This macro is designed to work on both little endian and
768 * big endian targets, since 32b long words are consistently
769 * handled for both endianness - it is only when converting
770 * from bytes to longs that bit orders get swapped.
771 * #ifdef xdc_target__bigEndian can be used if necessary.
772 *
773 * @param(Hdr* msgHdr) pointer to the packet header
774 * @param(msgType) the new packet type
775 */
776 @Macro Void setMsgType(Hdr *pHdr, MsgType msgType);
777
778 /*!
779 * ======== getCmdId ========
780 * gets the packet type from the packet header
781 *
782 * Message header is always layed out as big endian (network order).
783 * This macro is designed to work on both little endian and
784 * big endian targets, since 32b long words are consistently
785 * handled for both endianness - it is only when converting
786 * from bytes to longs that bit orders get swapped.
787 * #ifdef xdc_target__bigEndian can be used if necessary.
788 *
789 * @param(Hdr* msgHdr) pointer to the packet header
790 */
791 @Macro UInt16 getCmdId(Hdr *pHdr);
792
793 /*!
794 * ======== setCmdId ========
795 * sets the command Id in the packet header
796 *
797 * Message header is always layed out as big endian (network order).
798 * This macro is designed to work on both little endian and
799 * big endian targets, since 32b long words are consistently
800 * handled for both endianness - it is only when converting
801 * from bytes to longs that bit orders get swapped.
802 * #ifdef xdc_target__bigEndian can be used if necessary.
803 *
804 * @param(Hdr* msgHdr) pointer to the packet header
805 * @param(cmdId) the new command Id
806 */
807 @Macro Void setCmdId(Hdr *pHdr, UInt16 cmdId);
808
809 /*!
810 * ======== getServiceId ========
811 * gets the packet type from the packet header
812 *
813 * Message header is always layed out as big endian (network order).
814 * This macro is designed to work on both little endian and
815 * big endian targets, since 32b long words are consistently
816 * handled for both endianness - it is only when converting
817 * from bytes to longs that bit orders get swapped.
818 * #ifdef xdc_target__bigEndian can be used if necessary.
819 *
820 * @param(Hdr* msgHdr) pointer to the packet header
821 */
822 @Macro UInt16 getServiceId(Hdr *pHdr);
823 /*!
824 * ======== setServiceId ========
825 * sets the packet type in the packet header
826 *
827 * Message header is always layed out as big endian (network order).
828 * This macro is designed to work on both little endian and
829 * big endian targets, since 32b long words are consistently
830 * handled for both endianness - it is only when converting
831 * from bytes to longs that bit orders get swapped.
832 * #ifdef xdc_target__bigEndian can be used if necessary.
833 *
834 * @param(Hdr* msgHdr) pointer to the packet header
835 * @param(serviceId) the new service Id
836 */
837 @Macro Void setServiceId(Hdr *pHdr, UInt16 serviceId);
838
839 /*!
840 * ======== getTag =========
841 * gets the 32b tag field from the packet header
842 *
843 * @param(Hdr* msgHdr) pointer to the packet header
844 */
845 @Macro Bits32 getTag(Hdr *pHdr);
846
847 /*!
848 * ======== setTag =========
849 * sets the 32b tag field in the packet header
850 *
851 * @param(Hdr* msgHdr) pointer to the packet header
852 * @param(tagValue) the tag value to store in the header
853 */
854 @Macro Void setTag(Hdr *pHdr, Bits32 tagValue);
855
856 /*!
857 * ======== getDestAdrs ========
858 * gets the packet destination address from the packet header
859 *
860 * Message header is always layed out as big endian (network order).
861 * This macro is designed to work on both little endian and
862 * big endian targets, since 32b long words are consistently
863 * handled for both endianness - it is only when converting
864 * from bytes to longs that bit orders get swapped.
865 * #ifdef xdc_target__bigEndian can be used if necessary.
866 *
867 * Example1 :
868 * Void example1(UIAPacket_Object *obj){
869 * Int16 destAdrs = UIAPacket_getDestAdrs(&obj->hdr);
870 * ...
871 * }
872 * Example2 :
873 * Void example2(UIAPacket_Hdr *pHdr){
874 * Int16 destAdrs = UIAPacket_getDestAdrs(pHdr);
875 * ...
876 * }
877 *
878 * @param(Hdr* msgHdr) pointer to the packet header
879 */
880 @Macro UInt16 getDestAdrs(Hdr *pHdr);
881
882 /*!
883 * ======== setDestAdrs ========
884 * sets the packet destination address in the packet header
885 *
886 * The destination address identifies which endpoint (i.e. which
887 * CPU or process) the packet should be sent to.
888 * 0 is used to broadcast the packet.
889 * 1 is used for point-to-point connections.
890 * Replies to a packet always use the sender address in the
891 * originating packet as the destination address.
892 * Destination addresses other than the above can be determined
893 * via a discovery process.
894 *
895 * Message header is always layed out as big endian (network order).
896 * This macro is designed to work on both little endian and
897 * big endian targets, since 32b long words are consistently
898 * handled for both endianness - it is only when converting
899 * from bytes to longs that bit orders get swapped.
900 * #ifdef xdc_target__bigEndian can be used if necessary.
901 *
902 * @param(Hdr* msgHdr) pointer to the packet header
903 * @param(destAdrs) the new destination address
904 */
905 @Macro Void setDestAdrs(Hdr *pHdr, UInt16 destAdrs);
906
907 /*!
908 * ======== getSenderAdrs ========
909 * gets the packet sender address from the packet header
910 *
911 * Message header is always layed out as big endian (network order).
912 * This macro is designed to work on both little endian and
913 * big endian targets, since 32b long words are consistently
914 * handled for both endianness - it is only when converting
915 * from bytes to longs that bit orders get swapped.
916 * #ifdef xdc_target__bigEndian can be used if necessary.
917 *
918 * @param(Hdr* msgHdr) pointer to the packet header
919 */
920 @Macro UInt16 getSenderAdrs(Hdr *pHdr);
921
922 /*!
923 * ======== setSenderAdrs ========
924 * sets the packet sender address in the packet header
925 *
926 * The sender address identifies which endpoint (i.e. which
927 * CPU or process) the packet is coming from
928 * 1 is used by default.
929 * Sender addresses other than 1 can be set via configuration
930 * (e.g. to identify which CPU core a packet originated from).
931 *
932 * Message header is always layed out as big endian (network order).
933 * This macro is designed to work on both little endian and
934 * big endian targets, since 32b long words are consistently
935 * handled for both endianness - it is only when converting
936 * from bytes to longs that bit orders get swapped.
937 * #ifdef xdc_target__bigEndian can be used if necessary.
938 *
939 * @param(Hdr* msgHdr) pointer to the packet header
940 * @param(senderAdrs) the new destination address
941 */
942 @Macro Void setSenderAdrs(Hdr *pHdr, UInt16 senderAdrs);
943
944 /*!
945 * ======== initMsgHdr ========
946 * initializes all bitfields in the message header
947 *
948 * @param(Hdr* msgHdr) pointer to the packet header
949 * @param(endianness) endianness of the payload
950 * @param(msgType) the packet type
951 * @param(msgLength) the number of Bytes in the packet, including the
952 * header and footer
953 * @param(serviceId) the service Id
954 * @param(seqCount) the sequence number for the packet
955 * @param(cmdId) the command Id
956 * @param(tag) the tag value to store in the header
957 * @param(destAdrs) the destination address
958 * @param(senderAdrs) the sender address
959 */
960 @Macro Void initMsgHdr(Hdr *pHdr, PayloadEndian endianness,
961 MsgType msgType, UInt16 msgLength,
962 UInt16 serviceId, UInt16 seqCount,
963 UInt16 cmdId, UInt32 tag,
964 UInt16 destAdrs, UInt16 senderAdrs);
965
966 /*!
967 * ======== initEventRecHdr ========
968 * initializes all bitfields in the message header
969 *
970 * @param(Hdr* msgHdr) pointer to the packet header
971 * @param(endianness) endianness of the payload
972 * @param(eventLength) the number of Bytes in the packet, including
973 * the header and footer
974 * @param(seqCount) the sequence number for the packet
975 * @param(priority) the logger's priority
976 * @param(moduleId) the logger's module Id
977 * @param(instanceId) the logger's instanceId
978 * @param(destAdrs) the destination address
979 * @param(senderAdrs) the sender address
980 */
981 @Macro Void initEventRecHdr(Hdr *pHdr, PayloadEndian endianness,
982 UInt32 eventLength, UInt16 seqCount,
983 IUIATransfer.Priority priority, UInt16 moduleId,
984 UInt16 instanceId, UInt16 destAdrs,
985 UInt16 senderAdrs);
986
987 /*!
988 * ======== initMinEventRecHdr ========
989 * initializes all bitfields in the minimum event packet header,
990 * setting the length, sequence count and last timestamp fields to 0
991 *
992 * @param(Hdr* pPktHdr) pointer to the packet header
993 * @param(endianness) endianness of the payload
994 * @param(loggerInstanceId) the logger's instanceId
995 * @param(senderAdrs) the sender address (i.e. DNUM / endpoint ID for the CPU core)
996 */
997 @Macro Void initMinEventRecHdr(Hdr *pHdr, PayloadEndian endianness,
998 UInt16 loggerInstanceId,
999 UInt16 senderAdrs);
1000 /*!
1001 * ======== getFooter ========
1002 * returns the integer to use as the packet footer
1003 *
1004 * @param(Hdr* pHdr) pointer to the packet header
1005 */
1006 @Macro Int32 getFooter(Hdr *pHdr);
1007
1008 /*!
1009 * ======== setInvalidHdr ========
1010 * Used to set the header type as invalid
1011 *
1012 * @param(Hdr* pHdr) pointer to the packet header
1013 * @param(eventLength) the number of Bytes in the packet of memory
1014 * that is invalid (including the first word of the 32-bit hdr)
1015 */
1016 @Macro Void setInvalidHdr(Hdr *pHdr, UInt32 eventLength);
1017 }