:orphan: .. index:: pair: group; MI measurement-specific declarations .. _doxid-group__te__tools__te__mi__log__meas: MI measurement-specific declarations ==================================== .. toctree:: :hidden: enum_te_mi_graph_axis.rst enum_te_mi_meas_aggr.rst enum_te_mi_meas_multiplier.rst enum_te_mi_meas_type.rst enum_te_mi_meas_view_type.rst struct_te_mi_meas.rst Overview ~~~~~~~~ .. ref-code-block:: cpp :class: doxyrest-overview-code-block // typedefs typedef enum :ref:`te_mi_meas_aggr` :ref:`te_mi_meas_aggr`; typedef enum :ref:`te_mi_meas_type` :ref:`te_mi_meas_type`; typedef enum :ref:`te_mi_meas_multiplier` :ref:`te_mi_meas_multiplier`; typedef struct :ref:`te_mi_meas` :ref:`te_mi_meas`; typedef void enum :ref:`te_mi_meas_view_type` :ref:`te_mi_meas_view_type`; typedef enum :ref:`te_mi_graph_axis` :ref:`te_mi_graph_axis`; // enums enum :ref:`te_mi_graph_axis`; enum :ref:`te_mi_meas_aggr`; enum :ref:`te_mi_meas_multiplier`; enum :ref:`te_mi_meas_type`; enum :ref:`te_mi_meas_view_type`; // structs struct :ref:`te_mi_meas`; // global functions :ref:`te_errno` :ref:`te_mi_logger_meas_create`(const char* tool, :ref:`te_mi_logger`** logger); :ref:`te_errno` :ref:`te_mi_log_meas`(const char* tool, const :ref:`te_mi_meas`* measurements, const :ref:`te_mi_log_kvpair`* keys, const :ref:`te_mi_log_kvpair`* comments); void :ref:`te_mi_logger_add_meas`(:ref:`te_mi_logger`* logger, :ref:`te_errno`* retval, :ref:`te_mi_meas_type` type, const char* name, :ref:`te_mi_meas_aggr` aggr, double val, :ref:`te_mi_meas_multiplier` multiplier); void :ref:`te_mi_logger_add_meas_obj`(:ref:`te_mi_logger`* logger, :ref:`te_errno`* retval, const :ref:`te_mi_meas`* meas); void :ref:`te_mi_logger_add_meas_vec`(:ref:`te_mi_logger`* logger, :ref:`te_errno`* retval, const :ref:`te_mi_meas`* measurements); void :ref:`te_mi_logger_add_meas_key`(:ref:`te_mi_logger`* logger, :ref:`te_errno`* retval, const char* key, const char* value_fmt, ...); void :ref:`te_mi_logger_add_meas_view`(:ref:`te_mi_logger`* logger, :ref:`te_errno`* retval, :ref:`te_mi_meas_view_type` type, const char* name, const char* title); void :ref:`te_mi_logger_meas_graph_axis_add`(:ref:`te_mi_logger`* logger, :ref:`te_errno`* retval, :ref:`te_mi_meas_view_type` view_type, const char* view_name, :ref:`te_mi_graph_axis` axis, :ref:`te_mi_meas_type` meas_type, const char* meas_name); static void :ref:`te_mi_logger_meas_graph_axis_add_name`(:ref:`te_mi_logger`* logger, :ref:`te_errno`* retval, :ref:`te_mi_meas_view_type` view_type, const char* view_name, :ref:`te_mi_graph_axis` axis, const char* meas_name); static void :ref:`te_mi_logger_meas_graph_axis_add_type`(:ref:`te_mi_logger`* logger, :ref:`te_errno`* retval, :ref:`te_mi_meas_view_type` view_type, const char* view_name, :ref:`te_mi_graph_axis` axis, :ref:`te_mi_meas_type` meas_type); void :ref:`te_mi_logger_meas_point_add`(:ref:`te_mi_logger`* logger, :ref:`te_errno`* retval, const char* view_name, :ref:`te_mi_meas_type` meas_type, const char* meas_name, :ref:`te_mi_meas_aggr` meas_aggr); // macros #define :ref:`TE_MI_GRAPH_AUTO_SEQNO` #define :ref:`TE_MI_MEAS`(_type, _name, _aggr, _val, _multiplier) #define :ref:`TE_MI_MEAS_KEYS`(...) #define :ref:`TE_MI_MEAS_V`(...) .. _details-group__te__tools__te__mi__log__meas: Detailed Documentation ~~~~~~~~~~~~~~~~~~~~~~ Typedefs -------- .. index:: pair: typedef; te_mi_meas_aggr .. _doxid-group__te__tools__te__mi__log__meas_1ga11926a8c37bbdecbcbb03921986c13cc: .. ref-code-block:: cpp :class: doxyrest-title-code-block typedef enum :ref:`te_mi_meas_aggr` te_mi_meas_aggr Type of a measurement aggregation. The units of the measurement are defined by measurement type, unless different units are specified by aggregation explicilty. First enum element must have value ``0``. .. index:: pair: typedef; te_mi_meas_type .. _doxid-group__te__tools__te__mi__log__meas_1ga6cdf668cfc9ee23165fa3c7944a196b1: .. ref-code-block:: cpp :class: doxyrest-title-code-block typedef enum :ref:`te_mi_meas_type` te_mi_meas_type Type of a measurement. First enum element must have value ``0``. .. index:: pair: typedef; te_mi_meas_multiplier .. _doxid-group__te__tools__te__mi__log__meas_1ga702921d3a153eea3d05d5e20d2876ad3: .. ref-code-block:: cpp :class: doxyrest-title-code-block typedef enum :ref:`te_mi_meas_multiplier` te_mi_meas_multiplier Scale of a measurement result. The measurement value should be multiplied by this to get value in base units. First enum element must have value ``0``. .. index:: pair: typedef; te_mi_meas .. _doxid-group__te__tools__te__mi__log__meas_1gabff7f3c2e8cf2e760aaefbc59831ce33: .. ref-code-block:: cpp :class: doxyrest-title-code-block typedef struct :ref:`te_mi_meas` te_mi_meas Measurement. Base units of a measurement are defined by measurement type and measurement aggregation. .. index:: pair: typedef; te_mi_meas_view_type .. _doxid-group__te__tools__te__mi__log__meas_1ga99c8088f6ef5361be48b9a8dcb766f29: .. ref-code-block:: cpp :class: doxyrest-title-code-block typedef void enum :ref:`te_mi_meas_view_type` te_mi_meas_view_type Types of MI measurement views .. index:: pair: typedef; te_mi_graph_axis .. _doxid-group__te__tools__te__mi__log__meas_1gaa7f1eb337fed27a9d3732fd6db4c6f41: .. ref-code-block:: cpp :class: doxyrest-title-code-block typedef enum :ref:`te_mi_graph_axis` te_mi_graph_axis Types of MI measurement view axis Global Functions ---------------- .. index:: pair: function; te_mi_logger_meas_create .. _doxid-group__te__tools__te__mi__log__meas_1ga418b9a0987844352f9fd1cb55d34d8d3: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` te_mi_logger_meas_create(const char* tool, :ref:`te_mi_logger`** logger) Create a MI measurements logger entity. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - tool - Tool that was used for gathering measurements. * - logger - Created logger .. rubric:: Returns: Status code .. index:: pair: function; te_mi_log_meas .. _doxid-group__te__tools__te__mi__log__meas_1ga7d404fc02fa0c60e9235b27372c497ba: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` te_mi_log_meas(const char* tool, const :ref:`te_mi_meas`* measurements, const :ref:`te_mi_log_kvpair`* keys, const :ref:`te_mi_log_kvpair`* comments) Log MI measurements in one call. Logging steps: * create a logger; * add ``measurements``, ``keys`` and ``comments`` to the logger; * log the MI data; * destroy the logger; usage example: .. ref-code-block:: cpp :ref:`te_mi_log_meas `("mytool", :ref:`TE_MI_MEAS_V `(:ref:`TE_MI_MEAS `(PPS, "pps", :ref:`MIN `, 42.4, PLAIN), :ref:`TE_MI_MEAS `(PPS, "pps", MEAN, 300, PLAIN), :ref:`TE_MI_MEAS `(PPS, "pps", CV, 10, PLAIN), :ref:`TE_MI_MEAS `(PPS, "pps", :ref:`MAX `, 5.4, KILO), :ref:`TE_MI_MEAS `(TEMP, "mem", SINGLE, 42.4, PLAIN), :ref:`TE_MI_MEAS `(LATENCY, "low", MEAN, 54, MICRO)), :ref:`TE_MI_MEAS_KEYS `({"key", "value"}), :ref:`TE_MI_COMMENTS `({"comment", "comment_value"})); .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - tool - Tool that was used for gathering measurements. * - measurements - Measurements vector. The last element must have type ``TE_MI_MEAS_END``. * - keys - Measurement keys vector. The last element must have key ``NULL``. May be ``NULL`` to not add any keys. * - comments - Comments vector. The last element must have key ``NULL``. May be ``NULL`` to not add any comments. .. rubric:: Returns: Status code .. index:: pair: function; te_mi_logger_add_meas .. _doxid-group__te__tools__te__mi__log__meas_1ga1f6699bdac8edd62fabf16967c0493ce: .. ref-code-block:: cpp :class: doxyrest-title-code-block void te_mi_logger_add_meas(:ref:`te_mi_logger`* logger, :ref:`te_errno`* retval, :ref:`te_mi_meas_type` type, const char* name, :ref:`te_mi_meas_aggr` aggr, double val, :ref:`te_mi_meas_multiplier` multiplier) Add a measurement result to a MI logger. Results are aggregated by ``type`` - ``name`` pair. Multiple results with the the same ``type`` - ``name`` pair are allowed. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - logger - MI logger * - retval - Return code. If ``NULL`` is passed, ``logger`` is not ``NULL`` and error occures, error flag is stored in ``logger``, which will fail the next :ref:`te_mi_logger_flush() `. * - type - The type of the measurement result * - name - The name of the measurement result used to identify measurements in logs, may be ``NULL`` * - aggr - Aggregation type of the measurement * - val - Value of the measurement * - multiplier - Scale of the measurement value .. index:: pair: function; te_mi_logger_add_meas_obj .. _doxid-group__te__tools__te__mi__log__meas_1ga5945868fe967edbfd1766d03d2cdbc9e: .. ref-code-block:: cpp :class: doxyrest-title-code-block void te_mi_logger_add_meas_obj(:ref:`te_mi_logger`* logger, :ref:`te_errno`* retval, const :ref:`te_mi_meas`* meas) Variation of te_mi_logger_add_result() function that accepts measurement as a struct. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - logger - MI logger * - retval - Return code. If ``NULL`` is passed, ``logger`` is not ``NULL`` and error occures, error flag is stored in ``logger``, which will fail the next :ref:`te_mi_logger_flush() `. * - meas - Measurement .. rubric:: Returns: Status code .. index:: pair: function; te_mi_logger_add_meas_vec .. _doxid-group__te__tools__te__mi__log__meas_1ga975d30734ee75f2de6b27fe308a48a47: .. ref-code-block:: cpp :class: doxyrest-title-code-block void te_mi_logger_add_meas_vec(:ref:`te_mi_logger`* logger, :ref:`te_errno`* retval, const :ref:`te_mi_meas`* measurements) Add an vector of measurements to a MI logger. Insertion stops on the first error (the rest of the measurements are not added and the successful insertions persist in logger). .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - logger - MI logger * - retval - Return code. If ``NULL`` is passed, ``logger`` is not ``NULL`` and error occures, error flag is stored in ``logger``, which will fail the next :ref:`te_mi_logger_flush() `. * - measurements - Measurements vector. The last element must have type ``TE_MI_MEAS_END``. .. rubric:: Returns: Status code .. index:: pair: function; te_mi_logger_add_meas_key .. _doxid-group__te__tools__te__mi__log__meas_1gab71406642f97a09c442d1c5bd6ebd924: .. ref-code-block:: cpp :class: doxyrest-title-code-block void te_mi_logger_add_meas_key(:ref:`te_mi_logger`* logger, :ref:`te_errno`* retval, const char* key, const char* value_fmt, ...) Add a measurement key to a MI logger. Measurement key is a key-value pair that represents extra measurement information. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - logger - MI logger. * - retval - Return code. If ``NULL`` is passed, ``logger`` is not ``NULL`` and error occurs, error flag is stored in ``logger``, which will fail the next :ref:`te_mi_logger_flush() `. * - key - Measurement key * - value_fmt - Format string for the value of the measurement key * - ... - Format string arguments .. index:: pair: function; te_mi_logger_add_meas_view .. _doxid-group__te__tools__te__mi__log__meas_1gaa530663750bbe89ae321a419963c3661: .. ref-code-block:: cpp :class: doxyrest-title-code-block void te_mi_logger_add_meas_view(:ref:`te_mi_logger`* logger, :ref:`te_errno`* retval, :ref:`te_mi_meas_view_type` type, const char* name, const char* title) Add a view for MI measurement. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - logger - MI logger * - retval - Return code. If ``NULL`` is passed, ``logger`` is not ``NULL`` and error occures, error flag is stored in ``logger``, which will fail the next :ref:`te_mi_logger_flush() `. * - type - View type. * - name - View name (must be unique for a given type; used for identifying a view when calling other functions of this API). * - title - View title (may be an empty string; used as a title when displaying a graph). .. index:: pair: function; te_mi_logger_meas_graph_axis_add .. _doxid-group__te__tools__te__mi__log__meas_1gab6e0065b327d0c2305280bccaaf6b286: .. ref-code-block:: cpp :class: doxyrest-title-code-block void te_mi_logger_meas_graph_axis_add(:ref:`te_mi_logger`* logger, :ref:`te_errno`* retval, :ref:`te_mi_meas_view_type` view_type, const char* view_name, :ref:`te_mi_graph_axis` axis, :ref:`te_mi_meas_type` meas_type, const char* meas_name) Add a measurement to a graph axis. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - logger - MI logger. * - retval - Return code. If ``NULL`` is passed, ``logger`` is not ``NULL`` and error occurs, error flag is stored in ``logger``, which will fail the next :ref:`te_mi_logger_flush() `. * - view_type - View type. * - view_name - Name of the graph view. * - axis - Graph axis. For X axis only a single measurement may (and must) be specified - or a special ``TE_MI_GRAPH_AUTO_SEQNO`` keyword must be used as described below. Measurements specified for Y axis will each be drawn as a separate line. All measurements must have the same number of values as the measurement specified for X axis. If no measurement is specified for Y axis, it behaves as if all measurements are assigned to it except the one assigned to X axis. * - meas_type - Measurement type. Using ``TE_MI_MEAS_END`` means that no type is specified; in that case measurement name must be unique (i.e. used only for a single type). Also ``TE_MI_MEAS_END`` can be used for ``TE_MI_GRAPH_AUTO_SEQNO`` (see ``meas_name``). * - meas_name - Name of the measurement. May be empty or ``NULL`` if ``meas_type`` is specified, in which case there should be the single parameter of a given type. For X axis ``TE_MI_GRAPH_AUTO_SEQNO`` can be used instead of a measurement name. In that case sequence number in array of values will be used as X-coordinate on a graph. .. index:: pair: function; te_mi_logger_meas_graph_axis_add_name .. _doxid-group__te__tools__te__mi__log__meas_1ga4a91d14a41c364b182cced5d1c2cd218: .. ref-code-block:: cpp :class: doxyrest-title-code-block static void te_mi_logger_meas_graph_axis_add_name(:ref:`te_mi_logger`* logger, :ref:`te_errno`* retval, :ref:`te_mi_meas_view_type` view_type, const char* view_name, :ref:`te_mi_graph_axis` axis, const char* meas_name) Wrapper for :ref:`te_mi_logger_meas_graph_axis_add() ` which accepts only measurement name (which must be unique among all measurements of different types). .. index:: pair: function; te_mi_logger_meas_graph_axis_add_type .. _doxid-group__te__tools__te__mi__log__meas_1gac112333292be601d7d48891dfc20f2b2: .. ref-code-block:: cpp :class: doxyrest-title-code-block static void te_mi_logger_meas_graph_axis_add_type(:ref:`te_mi_logger`* logger, :ref:`te_errno`* retval, :ref:`te_mi_meas_view_type` view_type, const char* view_name, :ref:`te_mi_graph_axis` axis, :ref:`te_mi_meas_type` meas_type) Wrapper for :ref:`te_mi_logger_meas_graph_axis_add() ` which accepts only measurement type (there must be a single parameter with NULL name for a given type in such case). .. index:: pair: function; te_mi_logger_meas_point_add .. _doxid-group__te__tools__te__mi__log__meas_1gaa910e6fbaee45e2e7105c40c0e33e0c7: .. ref-code-block:: cpp :class: doxyrest-title-code-block void te_mi_logger_meas_point_add(:ref:`te_mi_logger`* logger, :ref:`te_errno`* retval, const char* view_name, :ref:`te_mi_meas_type` meas_type, const char* meas_name, :ref:`te_mi_meas_aggr` meas_aggr) Add a point view representing MI measurement by a single point (mean, maximum value, etc). This view can be used for performance history graphs showing such 'points' taken from multiple logs on a single graph. Example: .. ref-code-block:: cpp te_mi_logger *logger; CHECK_RC(te_mi_logger_meas_create("mytool", &logger)); te_mi_logger_add_meas(logger, NULL, TE_MI_MEAS_LATENCY, "MeasName", TE_MI_MEAS_AGGR_MEAN, 10, TE_MI_MEAS_MULTIPLIER_NANO); te_mi_logger_add_meas_view(logger, NULL, TE_MI_MEAS_VIEW_POINT, "ViewName", "ViewTitile"); te_mi_logger_meas_point_add(logger, NULL, "ViewName", TE_MI_MEAS_LATENCY, "MeasName", TE_MI_MEAS_AGGR_MEAN); te_mi_logger_destroy(logger); .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - logger - MI logger. * - retval - Return code. If ``NULL`` is passed, ``logger`` is not ``NULL`` and error occurs, error flag is stored in ``logger``, which will fail the next :ref:`te_mi_logger_flush() `. * - view_name - Name of the point view. * - meas_type - Measurement type. Using ``TE_MI_MEAS_END`` means that no type is specified; in that case measurement name must be unique (i.e. used only for a single type). * - meas_name - Name of the measurement. May be empty or ``NULL`` if ``meas_type`` is specified, in which case there should be the single parameter of a given type. * - meas_aggr - Type of a measurement aggregation. Using ``TE_MI_MEAS_AGGR_SF_UNPECIFIED`` means that aggr is not specified, in that case the measurement that is descibed by ``meas_name`` and ``meas_type`` must contain only one value. Macros ------ .. index:: pair: define; TE_MI_GRAPH_AUTO_SEQNO .. _doxid-group__te__tools__te__mi__log__meas_1ga6a7635b6753b89a3dfa40d7f4762b77d: .. ref-code-block:: cpp :class: doxyrest-title-code-block #define TE_MI_GRAPH_AUTO_SEQNO Special name meaning that sequence number should be used instead of values of some measurement on a given graph axis. .. index:: pair: define; TE_MI_MEAS .. _doxid-group__te__tools__te__mi__log__meas_1ga7059903ce1f68fb106365a2268e28984: .. ref-code-block:: cpp :class: doxyrest-title-code-block #define TE_MI_MEAS(_type, _name, _aggr, _val, _multiplier) Convenience :ref:`te_mi_meas ` constructor .. index:: pair: define; TE_MI_MEAS_KEYS .. _doxid-group__te__tools__te__mi__log__meas_1ga97bc7147639912ca5c8c71f9aa678f62: .. ref-code-block:: cpp :class: doxyrest-title-code-block #define TE_MI_MEAS_KEYS(...) Convenience measurement key vector constructor for :ref:`te_mi_log_meas() ` .. index:: pair: define; TE_MI_MEAS_V .. _doxid-group__te__tools__te__mi__log__meas_1gad8c26377d38df61b10d2654ea51c3f74: .. ref-code-block:: cpp :class: doxyrest-title-code-block #define TE_MI_MEAS_V(...) Convenience :ref:`te_mi_meas ` vector constructor for :ref:`te_mi_log_meas() `