+/*!
+@defgroup api-tir-pkt Packet
+@ingroup api-tir
+
+@brief
+ Trace packet.
+
+A <strong><em>packet</em></strong> is a conceptual container of
+\bt_p_ev within a \bt_stream.
+
+Some trace formats group events together within packets. This is the
+case, for example, of the
+<a href="https://diamon.org/ctf/">Common Trace Format</a>.
+
+Because a packet could contain millions of events, there are no actual
+links from a packet to its events. However, there are links from a
+packet's events to it (see bt_event_borrow_packet() and
+bt_event_borrow_packet_const()).
+
+A packet can contain a context \bt_field which is data associated to
+all the events of the packet.
+
+A packet is a \ref api-tir "trace IR" data object.
+
+A packet conceptually belongs to a \bt_stream. Borrow the stream of a
+packet with bt_packet_borrow_stream() and
+bt_packet_borrow_stream_const().
+
+Before you create a packet for a given stream, the stream's class must
+\ref api-tir-stream-cls-prop-supports-pkt "support packets".
+
+Create a packet with bt_packet_create(). You can then use this packet to
+create a \bt_pb_msg and a \bt_pe_msg.
+
+A packet is a \ref api-fund-shared-object "shared object": get a
+new reference with bt_packet_get_ref() and put an existing
+reference with bt_packet_put_ref().
+
+Some library functions \ref api-fund-freezing "freeze" packets on
+success. The documentation of those functions indicate this
+postcondition.
+
+The type of a packet is #bt_packet.
+
+<h1>Property</h1>
+
+A packet has the following property:
+
+<dl>
+ <dt>\anchor api-tir-pkt-prop-ctx Context field</dt>
+ <dd>
+ Packet's context \bt_field.
+
+ The context of a packet contains data associated to all its
+ events.
+
+ The \ref api-tir-fc "class" of a packet's context field is set
+ at the packet's \bt_stream_cls level. See
+ bt_stream_class_set_packet_context_field_class()
+ bt_stream_class_borrow_packet_context_field_class(),
+ and bt_stream_class_borrow_packet_context_field_class_const()
+
+ Use bt_packet_borrow_context_field() and
+ bt_packet_borrow_context_field_const().
+ </dd>
+</dl>
+*/
+
+/*! @{ */
+
+/*!
+@name Type
+@{
+
+@typedef struct bt_packet bt_packet;
+
+@brief
+ Packet.
+
+@}
+*/
+
+/*!
+@name Creation
+@{
+*/
+
+/*!
+@brief
+ Creates a packet for the \bt_stream \bt_p{stream}.
+
+@attention
+ @parblock
+ Only use this function if
+
+ @code
+ bt_stream_class_supports_packets(bt_stream_borrow_class_const(stream))
+ @endcode
+
+ returns #BT_TRUE.
+ @endparblock
+
+On success, the returned packet has the following property value:
+
+<table>
+ <tr>
+ <th>Property
+ <th>Value
+ <tr>
+ <td>\ref api-tir-pkt-prop-ctx "Context field"
+ <td>
+ Unset instance of the
+ \ref api-tir-stream-cls-prop-pc-fc "packet context field class" of
+ the \ref api-tir-stream-cls "class" of \bt_p{stream}.
+</table>
+
+@param[in] stream
+ Stream for which to create the packet.
+
+@returns
+ New packet reference, or \c NULL on memory error.
+
+@pre
+ <code>bt_stream_class_supports_packets(bt_stream_borrow_class_const(stream))</code>
+ returns #BT_TRUE.
+*/