src/plugins/ctf/common/msg-iter/msg-iter.hpp

   1 /*
   2  * SPDX-License-Identifier: MIT
   3  *
   4  * Copyright (c) 2015-2016 EfficiOS Inc. and Linux Foundation
   5  * Copyright (c) 2015-2016 Philippe Proulx <pproulx@efficios.com>
   6  *
   7  * Babeltrace - CTF message iterator
   8  */
   9
  10 #ifndef CTF_MSG_ITER_H
  11 #define CTF_MSG_ITER_H
  12
  13 #include <stdbool.h>
  14 #include <stdint.h>
  15 #include <stdio.h>
  16 #include <stddef.h>
  17 #include <babeltrace2/babeltrace.h>
  18 #include "common/macros.h"
  19
  20 #include "../metadata/ctf-meta.hpp"
  21
  22 /**
  23  * @file ctf-msg-iter.h
  24  *
  25  * CTF message iterator
  26  *
  27  * This is a common internal API used by CTF source plugins. It allows
  28  * one to get messages from a user-provided medium.
  29  */
  30
  31 /**
  32  * Medium operations status codes.  These use the same values as
  33  * libbabeltrace2.
  34  */
  35 enum ctf_msg_iter_medium_status {
  36         /**
  37          * End of file.
  38          *
  39          * The medium function called by the message iterator
  40          * function reached the end of the file.
  41          */
  42         CTF_MSG_ITER_MEDIUM_STATUS_EOF = 1,
  43
  44         /**
  45          * There is no data available right now, try again later.
  46          */
  47         CTF_MSG_ITER_MEDIUM_STATUS_AGAIN = 11,
  48
  49         /** General error. */
  50         CTF_MSG_ITER_MEDIUM_STATUS_ERROR = -1,
  51
  52         /** Memory error. */
  53         CTF_MSG_ITER_MEDIUM_STATUS_MEMORY_ERROR = -12,
  54
  55         /** Everything okay. */
  56         CTF_MSG_ITER_MEDIUM_STATUS_OK = 0,
  57 };
  58
  59 /**
  60  * CTF message iterator API status code.
  61  */
  62 enum ctf_msg_iter_status {
  63         /**
  64          * End of file.
  65          *
  66          * The medium function called by the message iterator
  67          * function reached the end of the file.
  68          */
  69         CTF_MSG_ITER_STATUS_EOF = CTF_MSG_ITER_MEDIUM_STATUS_EOF,
  70
  71         /**
  72          * There is no data available right now, try again later.
  73          *
  74          * Some condition resulted in the
  75          * ctf_msg_iter_medium_ops::request_bytes() user function not
  76          * having access to any data now. You should retry calling the
  77          * last called message iterator function once the situation
  78          * is resolved.
  79          */
  80         CTF_MSG_ITER_STATUS_AGAIN = CTF_MSG_ITER_MEDIUM_STATUS_AGAIN,
  81
  82         /** General error. */
  83         CTF_MSG_ITER_STATUS_ERROR = CTF_MSG_ITER_MEDIUM_STATUS_ERROR,
  84
  85         /** Memory error. */
  86         CTF_MSG_ITER_STATUS_MEMORY_ERROR  = CTF_MSG_ITER_MEDIUM_STATUS_MEMORY_ERROR,
  87
  88         /** Everything okay. */
  89         CTF_MSG_ITER_STATUS_OK = CTF_MSG_ITER_MEDIUM_STATUS_OK,
  90 };
  91
  92 /**
  93  * Medium operations.
  94  *
  95  * Those user functions are called by the message iterator
  96  * functions to request medium actions.
  97  */
  98 struct ctf_msg_iter_medium_ops {
  99         /**
 100          * Returns the next byte buffer to be used by the binary file
 101          * reader to deserialize binary data.
 102          *
 103          * This function \em must be defined.
 104          *
 105          * The purpose of this function is to return a buffer of bytes
 106          * to the message iterator, of a maximum of \p request_sz
 107          * bytes. If this function cannot return a buffer of at least
 108          * \p request_sz bytes, it may return a smaller buffer. In
 109          * either cases, \p buffer_sz must be set to the returned buffer
 110          * size (in bytes).
 111          *
 112          * The returned buffer's ownership remains the medium, in that
 113          * it won't be freed by the message iterator functions. The
 114          * returned buffer won't be modified by the message
 115          * iterator functions either.
 116          *
 117          * When this function is called for the first time for a given
 118          * file, the offset within the file is considered to be 0. The
 119          * next times this function is called, the returned buffer's
 120          * byte offset within the complete file must be the previous
 121          * offset plus the last returned value of \p buffer_sz by this
 122          * medium.
 123          *
 124          * This function must return one of the following statuses:
 125          *
 126          *   - <b>#CTF_MSG_ITER_MEDIUM_STATUS_OK</b>: Everything
 127          *     is okay, i.e. \p buffer_sz is set to a positive value
 128          *     reflecting the number of available bytes in the buffer
 129          *     starting at the address written in \p buffer_addr.
 130          *   - <b>#CTF_MSG_ITER_MEDIUM_STATUS_AGAIN</b>: No data is
 131          *     available right now. In this case, the message
 132          *     iterator function called by the user returns
 133          *     #CTF_MSG_ITER_STATUS_AGAIN, and it is the user's
 134          *     responsibility to make sure enough data becomes available
 135          *     before calling the \em same message iterator
 136          *     function again to continue the decoding process.
 137          *   - <b>#CTF_MSG_ITER_MEDIUM_STATUS_EOF</b>: The end of
 138          *     the file was reached, and no more data will ever be
 139          *     available for this file. In this case, the message
 140          *     iterator function called by the user returns
 141          *     #CTF_MSG_ITER_STATUS_EOF. This must \em not be
 142          *     returned when returning at least one byte of data to the
 143          *     caller, i.e. this must be returned when there's
 144          *     absolutely nothing left; should the request size be
 145          *     larger than what's left in the file, this function must
 146          *     return what's left, setting \p buffer_sz to the number of
 147          *     remaining bytes, and return
 148          *     #CTF_MSG_ITER_MEDIUM_STATUS_EOF on the \em following
 149          *     call.
 150          *   - <b>#CTF_MSG_ITER_MEDIUM_STATUS_ERROR</b>: A fatal
 151          *     error occurred during this operation. In this case, the
 152          *     message iterator function called by the user returns
 153          *     #CTF_MSG_ITER_STATUS_ERROR.
 154          *
 155          * If #CTF_MSG_ITER_MEDIUM_STATUS_OK is not returned, the
 156          * values of \p buffer_sz and \p buffer_addr are \em ignored by
 157          * the caller.
 158          *
 159          * @param request_sz    Requested buffer size (bytes)
 160          * @param buffer_addr   Returned buffer address
 161          * @param buffer_sz     Returned buffer's size (bytes)
 162          * @param data          User data
 163          * @returns             Status code (see description above)
 164          */
 165         enum ctf_msg_iter_medium_status (* request_bytes)(size_t request_sz,
 166                         uint8_t **buffer_addr, size_t *buffer_sz, void *data);
 167
 168         /**
 169          * Repositions the underlying stream's position.
 170          *
 171          * This *optional* method repositions the underlying stream
 172          * to a given absolute position in the medium.
 173          *
 174          * @param offset        Offset to use for the given directive
 175          * @param data          User data
 176          * @returns             One of #ctf_msg_iter_medium_status values
 177          */
 178         enum ctf_msg_iter_medium_status (* seek)(off_t offset, void *data);
 179
 180         /**
 181          * Called when the message iterator wishes to inform the medium that it
 182          * is about to start a new packet.
 183          *
 184          * After the iterator has called switch_packet, the following call to
 185          * request_bytes must return the content at the start of the next
 186          * packet.       */
 187         enum ctf_msg_iter_medium_status (* switch_packet)(void *data);
 188
 189         /**
 190          * Returns a stream instance (weak reference) for the given
 191          * stream class.
 192          *
 193          * This is called after a packet header is read, and the
 194          * corresponding stream class is found by the message
 195          * iterator.
 196          *
 197          * @param stream_class  Stream class of the stream to get
 198          * @param stream_id     Stream (instance) ID of the stream
 199          *                      to get (-1ULL if not available)
 200          * @param data          User data
 201          * @returns             Stream instance (weak reference) or
 202          *                      \c NULL on error
 203          */
 204         bt_stream * (* borrow_stream)(bt_stream_class *stream_class,
 205                         int64_t stream_id, void *data);
 206 };
 207
 208 /** CTF message iterator. */
 209 struct ctf_msg_iter;
 210
 211 /**
 212  * Creates a CTF message iterator.
 213  *
 214  * Upon successful completion, the reference count of \p trace is
 215  * incremented.
 216  *
 217  * @param trace                 Trace to read
 218  * @param max_request_sz        Maximum buffer size, in bytes, to
 219  *                              request to
 220  *                              ctf_msg_iter_medium_ops::request_bytes()
 221  *                              at a time
 222  * @param medops                Medium operations
 223  * @param medops_data           User data (passed to medium operations)
 224  * @returns                     New CTF message iterator on
 225  *                              success, or \c NULL on error
 226  */
 227 BT_HIDDEN
 228 struct ctf_msg_iter *ctf_msg_iter_create(
 229                 struct ctf_trace_class *tc,
 230                 size_t max_request_sz,
 231                 struct ctf_msg_iter_medium_ops medops,
 232                 void *medops_data,
 233                 bt_logging_level log_level,
 234                 bt_self_component *self_comp,
 235                 bt_self_message_iterator *self_msg_iter);
 236
 237 /**
 238  * Destroys a CTF message iterator, freeing all internal resources.
 239  *
 240  * The registered trace's reference count is decremented.
 241  *
 242  * @param msg_iter              CTF message iterator
 243  */
 244 BT_HIDDEN
 245 void ctf_msg_iter_destroy(struct ctf_msg_iter *msg_iter);
 246
 247 /**
 248  * Returns the next message from a CTF message iterator.
 249  *
 250  * Upon successful completion, #CTF_MSG_ITER_STATUS_OK is
 251  * returned, and the next message is written to \p msg.
 252  * In this case, the caller is responsible for calling
 253  * bt_message_put() on the returned message.
 254  *
 255  * If this function returns #CTF_MSG_ITER_STATUS_AGAIN, the caller
 256  * should make sure that data becomes available to its medium, and
 257  * call this function again, until another status is returned.
 258  *
 259  * @param msg_iter              CTF message iterator
 260  * @param message               Returned message if the function's
 261  *                              return value is #CTF_MSG_ITER_STATUS_OK
 262  * @returns                     One of #ctf_msg_iter_status values
 263  */
 264 BT_HIDDEN
 265 enum ctf_msg_iter_status ctf_msg_iter_get_next_message(
 266                 struct ctf_msg_iter *msg_it,
 267                 const bt_message **message);
 268
 269 struct ctf_msg_iter_packet_properties {
 270         int64_t exp_packet_total_size;
 271         int64_t exp_packet_content_size;
 272         uint64_t stream_class_id;
 273         int64_t data_stream_id;
 274
 275         struct {
 276                 uint64_t discarded_events;
 277                 uint64_t packets;
 278                 uint64_t beginning_clock;
 279                 uint64_t end_clock;
 280         } snapshots;
 281 };
 282
 283 BT_HIDDEN
 284 enum ctf_msg_iter_status ctf_msg_iter_get_packet_properties(
 285                 struct ctf_msg_iter *msg_it,
 286                 struct ctf_msg_iter_packet_properties *props);
 287
 288 BT_HIDDEN
 289 enum ctf_msg_iter_status ctf_msg_iter_curr_packet_first_event_clock_snapshot(
 290                 struct ctf_msg_iter *msg_it, uint64_t *first_event_cs);
 291
 292 BT_HIDDEN
 293 enum ctf_msg_iter_status ctf_msg_iter_curr_packet_last_event_clock_snapshot(
 294                 struct ctf_msg_iter *msg_it, uint64_t *last_event_cs);
 295
 296 BT_HIDDEN
 297 enum ctf_msg_iter_status ctf_msg_iter_seek(
 298                 struct ctf_msg_iter *msg_it, off_t offset);
 299
 300 /*
 301  * Resets the iterator so that the next requested medium bytes are
 302  * assumed to be the first bytes of a new stream. Depending on
 303  * ctf_msg_iter_set_emit_stream_beginning_message(), the first message
 304  * which this iterator emits after calling ctf_msg_iter_reset() is of
 305  * type `CTF_MESSAGE_TYPE_STREAM_BEGINNING`.
 306  */
 307 BT_HIDDEN
 308 void ctf_msg_iter_reset(struct ctf_msg_iter *msg_it);
 309
 310 /*
 311  * Like ctf_msg_iter_reset(), but preserves stream-dependent state.
 312  */
 313 BT_HIDDEN
 314 void ctf_msg_iter_reset_for_next_stream_file(struct ctf_msg_iter *msg_it);
 315
 316 BT_HIDDEN
 317 void ctf_msg_iter_set_dry_run(struct ctf_msg_iter *msg_it,
 318                 bool val);
 319
 320 static inline
 321 const char *ctf_msg_iter_medium_status_string(
 322                 enum ctf_msg_iter_medium_status status)
 323 {
 324         switch (status) {
 325         case CTF_MSG_ITER_MEDIUM_STATUS_EOF:
 326                 return "EOF";
 327         case CTF_MSG_ITER_MEDIUM_STATUS_AGAIN:
 328                 return "AGAIN";
 329         case CTF_MSG_ITER_MEDIUM_STATUS_ERROR:
 330                 return "ERROR";
 331         case CTF_MSG_ITER_MEDIUM_STATUS_MEMORY_ERROR:
 332                 return "MEMORY_ERROR";
 333         case CTF_MSG_ITER_MEDIUM_STATUS_OK:
 334                 return "OK";
 335         }
 336
 337         bt_common_abort();
 338 }
 339
 340 static inline
 341 const char *ctf_msg_iter_status_string(
 342                 enum ctf_msg_iter_status status)
 343 {
 344         switch (status) {
 345         case CTF_MSG_ITER_STATUS_EOF:
 346                 return "EOF";
 347         case CTF_MSG_ITER_STATUS_AGAIN:
 348                 return "AGAIN";
 349         case CTF_MSG_ITER_STATUS_ERROR:
 350                 return "ERROR";
 351         case CTF_MSG_ITER_STATUS_MEMORY_ERROR:
 352                 return "MEMORY_ERROR";
 353         case CTF_MSG_ITER_STATUS_OK:
 354                 return "OK";
 355         }
 356
 357         bt_common_abort();
 358 }
 359
 360 #endif /* CTF_MSG_ITER_H */