include/babeltrace/ctf-ir/packet.h

   1 #ifndef BABELTRACE_CTF_IR_PACKET_H
   2 #define BABELTRACE_CTF_IR_PACKET_H
   3
   4 /*
   5  * BabelTrace - CTF IR: Stream packet
   6  *
   7  * Copyright 2016 Philippe Proulx <pproulx@efficios.com>
   8  *
   9  * Permission is hereby granted, free of charge, to any person obtaining a copy
  10  * of this software and associated documentation files (the "Software"), to deal
  11  * in the Software without restriction, including without limitation the rights
  12  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  13  * copies of the Software, and to permit persons to whom the Software is
  14  * furnished to do so, subject to the following conditions:
  15  *
  16  * The above copyright notice and this permission notice shall be included in
  17  * all copies or substantial portions of the Software.
  18  *
  19  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  20  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  21  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  22  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  23  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  24  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  25  * SOFTWARE.
  26  *
  27  * The Common Trace Format (CTF) Specification is available at
  28  * http://www.efficios.com/ctf
  29  */
  30
  31 #include <stdint.h>
  32
  33 /* For bt_get() */
  34 #include <babeltrace/ref.h>
  35
  36 /* For bt_bool */
  37 #include <babeltrace/types.h>
  38
  39 #ifdef __cplusplus
  40 extern "C" {
  41 #endif
  42
  43 /**
  44 @defgroup ctfirpacket CTF IR packet
  45 @ingroup ctfir
  46 @brief CTF IR packet.
  47
  48 @code
  49 #include <babeltrace/ctf-ir/packet.h>
  50 @endcode
  51
  52 A CTF IR <strong><em>packet</em></strong> is a container of packet
  53 fields, that is, of the <strong>trace packet header</strong> and
  54 <strong>stream packet context</strong> fields.
  55
  56 As a reminder, here's the structure of a CTF packet:
  57
  58 @imgpacketstructure
  59
  60 You can create a CTF IR packet \em from a
  61 \link ctfirstream CTF IR stream\endlink with bt_packet_create(). The
  62 stream you use to create a packet object becomes its parent.
  63
  64 When you set the trace packet header and stream packet context fields of
  65 a packet with resp. bt_packet_set_header() and
  66 bt_packet_set_context(), their field type \em must be equivalent to
  67 the field types returned by resp. bt_trace_get_packet_header_type()
  68 and bt_stream_class_get_packet_context_type() for its parent trace
  69 class and stream class.
  70
  71 You can attach a packet object to a \link ctfirevent CTF IR
  72 event\endlink object with bt_event_set_packet().
  73
  74 As with any Babeltrace object, CTF IR packet objects have
  75 <a href="https://en.wikipedia.org/wiki/Reference_counting">reference
  76 counts</a>. See \ref refs to learn more about the reference counting
  77 management of Babeltrace objects.
  78
  79 bt_notification_event_create() \em freezes its event parameter on
  80 success, which in turns freezes the event's associated packet object.
  81 This is the only way that a CTF IR packet object can be frozen.
  82 You cannot modify a frozen packet: it is considered immutable,
  83 except for \link refs reference counting\endlink.
  84
  85 @sa ctfirstream
  86 @sa ctfirstreamclass
  87 @sa ctfirtraceclass
  88
  89 @file
  90 @brief CTF IR packet type and functions.
  91 @sa ctfirpacket
  92
  93 @addtogroup ctfirpacket
  94 @{
  95 */
  96
  97 /**
  98 @struct bt_packet
  99 @brief A CTF IR packet.
 100 @sa ctfirpacket
 101 */
 102 struct bt_packet;
 103 struct bt_packet_header_field;
 104 struct bt_packet_context_field;
 105 struct bt_stream;
 106 struct bt_clock_value;
 107 struct bt_clock_class;
 108
 109 enum bt_packet_previous_packet_availability {
 110         BT_PACKET_PREVIOUS_PACKET_AVAILABILITY_ERROR = -1,
 111         BT_PACKET_PREVIOUS_PACKET_AVAILABILITY_AVAILABLE,
 112         BT_PACKET_PREVIOUS_PACKET_AVAILABILITY_NOT_AVAILABLE,
 113         BT_PACKET_PREVIOUS_PACKET_AVAILABILITY_NONE,
 114 };
 115
 116 enum bt_packet_property_availability {
 117         BT_PACKET_PROPERTY_AVAILABILITY_ERROR = -1,
 118         BT_PACKET_PROPERTY_AVAILABILITY_AVAILABLE,
 119         BT_PACKET_PROPERTY_AVAILABILITY_NOT_AVAILABLE,
 120 };
 121
 122 /**
 123 @name Creation and parent access functions
 124 @{
 125 */
 126
 127 /**
 128 @brief  Creates a default CTF IR packet with \p stream as its parent
 129         CTF IR stream.
 130
 131 On success, the packet object's trace packet header and stream packet
 132 context fields are not set. You can set them with resp.
 133 bt_packet_set_header() and bt_packet_set_context().
 134
 135 @param[in] stream       Parent CTF IR stream of the packet to create.
 136 @returns                Created packet, or \c NULL on error.
 137
 138 @prenotnull{stream}
 139 @postsuccessrefcountret1
 140 */
 141 extern struct bt_packet *bt_packet_create(struct bt_stream *stream,
 142                 enum bt_packet_previous_packet_availability previous_packet_availability,
 143                 struct bt_packet *previous_packet);
 144
 145 extern struct bt_stream *bt_packet_borrow_stream(struct bt_packet *packet);
 146
 147 /**
 148 @brief  Returns the parent CTF IR stream of the CTF IR packet \p packet.
 149
 150 This function returns a reference to the stream which was used to create
 151 the packet object in the first place with bt_packet_create().
 152
 153 @param[in] packet       Packet of which to get the parent stream.
 154 @returns                Parent stream of \p packet, or \c NULL on error.
 155
 156 @prenotnull{packet}
 157 @postrefcountsame{packet}
 158 @postsuccessrefcountretinc
 159 */
 160 static inline
 161 struct bt_stream *bt_packet_get_stream(
 162                 struct bt_packet *packet)
 163 {
 164         return bt_get(bt_packet_borrow_stream(packet));
 165 }
 166
 167 /** @} */
 168
 169 /**
 170 @name Contained fields functions
 171 @{
 172 */
 173
 174 extern
 175 struct bt_field *bt_packet_borrow_header(struct bt_packet *packet);
 176
 177 extern
 178 int bt_packet_move_header(struct bt_packet *packet,
 179                 struct bt_packet_header_field *header);
 180
 181 extern
 182 struct bt_field *bt_packet_borrow_context(struct bt_packet *packet);
 183
 184 extern
 185 int bt_packet_move_context(struct bt_packet *packet,
 186                 struct bt_packet_context_field *context);
 187
 188 /** @} */
 189
 190 extern
 191 enum bt_packet_property_availability
 192 bt_packet_borrow_default_beginning_clock_value(struct bt_packet *packet,
 193                 struct bt_clock_value **clock_value);
 194
 195 extern
 196 enum bt_packet_property_availability
 197 bt_packet_borrow_default_end_clock_value(struct bt_packet *packet,
 198                 struct bt_clock_value **clock_value);
 199
 200 extern
 201 enum bt_packet_previous_packet_availability
 202 bt_packet_get_previous_packet_availability(struct bt_packet *packet);
 203
 204 extern
 205 enum bt_packet_property_availability
 206 bt_packet_borrow_previous_packet_default_end_clock_value(
 207                 struct bt_packet *packet, struct bt_clock_value **clock_value);
 208
 209 extern
 210 enum bt_packet_property_availability bt_packet_get_discarded_event_counter(
 211                 struct bt_packet *packet, uint64_t *counter);
 212
 213 extern
 214 enum bt_packet_property_availability bt_packet_get_sequence_number(
 215                 struct bt_packet *packet, uint64_t *sequence_number);
 216
 217 extern
 218 enum bt_packet_property_availability bt_packet_get_discarded_event_count(
 219                 struct bt_packet *packet, uint64_t *count);
 220
 221 extern
 222 enum bt_packet_property_availability bt_packet_get_discarded_packet_count(
 223                 struct bt_packet *packet, uint64_t *count);
 224
 225 /** @} */
 226
 227 #ifdef __cplusplus
 228 }
 229 #endif
 230
 231 #endif /* BABELTRACE_CTF_IR_PACKET_H */