lib: bt_packet_create(): accept previous packet to set properties

lib: bt_packet_create(): accept previous packet to set properties

This patch changes the signature of the bt_packet_create() function
from:

    struct bt_packet *bt_packet_create(struct bt_stream *stream);

to:

    struct bt_packet *bt_packet_create(struct bt_stream *stream,
        enum bt_packet_previous_packet_availability prev_packet_avail,
        struct bt_packet *prev_packet);

bt_packet_create() now accepts the previous packet in the same stream
and its availability to automatically set some properties on the created
packet which depend on the properties of the previous packets. Those
properties are:

* The number of discarded events, by the original tracer, between the
  previous packet's end time and the current packet's end time.
* The number of discarded packets, by the original tracer, between the
  previous packet's end time and the current packet's end time.

"Automatically" here means from the packet's context subfields.

The availability parameter's purpose is to provide a reason for a
missing previous packet:

* Not available (will be used after seeking when this is implemented).
* None (first packet of its data stream).

When the previous packet is passed, you must pass
`BT_PACKET_PREVIOUS_PACKET_AVAILABILITY_AVAILABLE`.

bt_packet_create() does not keep a reference to the passed previous
packet object: this would create a potentially huge reference chain.
Instead, the function keeps snapshots the needed previous packet's
properties.

bt_packet_create() does not automatically set the created packet's
properties right away: this is the purpose of the internal
bt_packet_set_properties() function. This is because you borrow and set
the packet context subfields after you create the packet, so the
automatic setting must happen at the same location the packet would be
frozen in developer mode. Thus bt_notification_event_create(),
bt_notification_packet_begin_create(), and
bt_notification_packet_end_create() call bt_packet_set_properties().

bt_packet_set_properties() sets, from the context subfields, when
available:

* Discarded event _counter_ (free running counter, not the difference)
  from `events_discarded`.
* Sequence number from `packet_seq_num`.
* Default beginning clock value from `timestamp_begin`.
* Default end clock value from `timestamp_end`.

Because bt_notification_event_create() calls bt_packet_set_properties(),
and we don't want to do all this work every time we call
bt_notification_event_create(), there's a "validation" flag for the
property cache. So we can call bt_packet_set_properties() and
eventually, when we're sure that the context field won't change until
the packet is recycled (reset), we call
bt_packet_invalidate_properties().

Each packet property can be available or not: each property getter
returns its availability and the function sets a user variable to the
property's value. The getters are:

    enum bt_packet_property_availability
    bt_packet_borrow_default_beginning_clock_value(struct bt_packet *packet,
        struct bt_clock_value **clock_value);

    enum bt_packet_property_availability
    bt_packet_borrow_default_end_clock_value(struct bt_packet *packet,
        struct bt_clock_value **clock_value);

    enum bt_packet_property_availability
    bt_packet_borrow_previous_packet_default_end_clock_value(
        struct bt_packet *packet, struct bt_clock_value **clock_value);

    enum bt_packet_property_availability
    bt_packet_get_discarded_event_counter(
        struct bt_packet *packet, uint64_t *counter);

    enum bt_packet_property_availability
    bt_packet_get_sequence_number(
        struct bt_packet *packet, uint64_t *sequence_number);

    enum bt_packet_property_availability
    bt_packet_get_discarded_event_count(
        struct bt_packet *packet, uint64_t *count);

    enum bt_packet_property_availability
    bt_packet_get_discarded_packet_count(
        struct bt_packet *packet, uint64_t *count);

Source plugins are updated to keep the previous packet's reference when
needed and call bt_packet_create() correctly.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>