src/common/mi-lttng.h

   1 /*
   2  * Copyright (C) 2014 - Jonathan Rajotte <jonathan.r.julien@gmail.com>
   3  *                    - Olivier Cotte <olivier.cotte@polymtl.ca>
   4  *
   5  * This program is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License, version 2 only, as
   7  * published by the Free Software Foundation.
   8  *
   9  * This program is distributed in the hope that it will be useful, but WITHOUT
  10  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  11  * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
  12  * more details.
  13  *
  14  * You should have received a copy of the GNU General Public License along with
  15  * this program; if not, write to the Free Software Foundation, Inc., 51
  16  * Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  17  */
  18
  19 #ifndef _MI_LTTNG_H
  20 #define _MI_LTTNG_H
  21
  22 #include <stdint.h>
  23
  24 #include <common/error.h>
  25 #include <common/macros.h>
  26 #include <common/config/config.h>
  27 #include <lttng/lttng.h>
  28
  29 /* Instance of a machine interface writer. */
  30 struct mi_writer {
  31         struct config_writer *writer;
  32         enum lttng_mi_output_type type;
  33 };
  34
  35 /*
  36  * Version information for the machine interface.
  37  */
  38 struct mi_lttng_version {
  39         char version[NAME_MAX]; /* Version number of package */
  40         uint32_t version_major; /* LTTng-Tools major version number */
  41         uint32_t version_minor; /* LTTng-Tools minor version number */
  42         uint32_t version_patchlevel; /* LTTng-Tools patchlevel version number */
  43         char version_commit[NAME_MAX]; /* Commit hash of the current version */
  44         char version_name[NAME_MAX];
  45         char package_url[NAME_MAX]; /* Define to the home page for this package. */
  46 };
  47
  48 /* Strings related to command */
  49 const char * const mi_lttng_element_command;
  50 const char * const mi_lttng_element_command_version;
  51 const char * const mi_lttng_element_command_list;
  52 const char * const mi_lttng_element_command_name;
  53 const char * const mi_lttng_element_command_output;
  54
  55 /* Strings related to command: version */
  56 const char * const mi_lttng_element_version;
  57 const char * const mi_lttng_element_version_str;
  58 const char * const mi_lttng_element_version_web;
  59 const char * const mi_lttng_element_version_major;
  60 const char * const mi_lttng_element_version_minor;
  61 const char * const mi_lttng_element_version_license;
  62 const char * const mi_lttng_element_version_commit;
  63 const char * const mi_lttng_element_version_patch_level;
  64 const char * const mi_lttng_element_version_description;
  65
  66 /* String related to a lttng_event_field */
  67 const char * const mi_lttng_element_event_field;
  68 const char * const mi_lttng_element_event_fields;
  69
  70 /* Strings related to pid */
  71 const char * const mi_lttng_element_pids;
  72 const char * const mi_lttng_element_pid;
  73 const char * const mi_lttng_element_pid_id;
  74
  75 /* General element of mi_lttng */
  76 const char * const mi_lttng_element_type_other;
  77 const char * const mi_lttng_element_type_integer;
  78 const char * const mi_lttng_element_type_enum;
  79 const char * const mi_lttng_element_type_float;
  80 const char * const mi_lttng_element_type_string;
  81 const char * const mi_lttng_element_nowrite;
  82
  83 /* String related to loglevel */
  84 const char * const mi_lttng_loglevel_str_alert;
  85 const char * const mi_lttng_loglevel_str_crit;
  86 const char * const mi_lttng_loglevel_str_debug;
  87 const char * const mi_lttng_loglevel_str_debug_function;
  88 const char * const mi_lttng_loglevel_str_debug_line;
  89 const char * const mi_lttng_loglevel_str_debug_module;
  90 const char * const mi_lttng_loglevel_str_debug_process;
  91 const char * const mi_lttng_loglevel_str_debug_program;
  92 const char * const mi_lttng_loglevel_str_debug_system;
  93 const char * const mi_lttng_loglevel_str_debug_unit;
  94 const char * const mi_lttng_loglevel_str_emerg;
  95 const char * const mi_lttng_loglevel_str_err;
  96 const char * const mi_lttng_loglevel_str_info;
  97 const char * const mi_lttng_loglevel_str_notice;
  98 const char * const mi_lttng_loglevel_str_unknown;
  99 const char * const mi_lttng_loglevel_str_warning;
 100
 101 const char * const mi_lttng_loglevel_type_all;
 102 const char * const mi_lttng_loglevel_type_range;
 103 const char * const mi_lttng_loglevel_type_single;
 104 const char * const mi_lttng_loglevel_type_unknown;
 105
 106 /* Utility string function  */
 107 const char *mi_lttng_loglevel_string(int value);
 108 const char *mi_lttng_logleveltype_string(enum lttng_loglevel_type value);
 109 const char *mi_lttng_eventfieldtype_string(enum lttng_event_field_type value);
 110 const char *mi_lttng_domaintype_string(enum lttng_domain_type value);
 111 const char *mi_lttng_buffertype_string(enum lttng_buffer_type value);
 112
 113 /*
 114  * Create an instance of a machine interface writer.
 115  *
 116  * fd_output File to which the XML content must be written. The file will be
 117  * closed once the mi_writer has been destroyed.
 118  *
 119  * Returns an instance of a machine interface writer on success, NULL on
 120  * error.
 121  */
 122 struct mi_writer *mi_lttng_writer_create(int fd_output, int mi_output_type);
 123
 124 /*
 125  * Destroy an instance of a machine interface writer.
 126  *
 127  * writer An instance of a machine interface writer.
 128  *
 129  * Returns zero if the XML document could be closed cleanly. Negative values
 130  * indicate an error.
 131  */
 132 int mi_lttng_writer_destroy(struct mi_writer *writer);
 133
 134 /*
 135  * Open a command tag and add it's name node.
 136  *
 137  * writer An instance of a machine interface writer.
 138  * command The command name.
 139  *
 140  * Returns zero if the XML document could be closed cleanly.
 141  * Negative values indicate an error.
 142  */
 143 int mi_lttng_writer_command_open(struct mi_writer *writer, const char *command);
 144
 145 /*
 146  * Close a command tag.
 147  *
 148  * writer An instance of a machine interface writer.
 149  *
 150  * Returns zero if the XML document could be closed cleanly.
 151  * Negative values indicate an error.
 152  */
 153 int mi_lttng_writer_command_close(struct mi_writer *writer);
 154
 155 /*
 156  * Open an element tag.
 157  *
 158  * writer An instance of a machine interface writer.
 159  * element_name Element tag name.
 160  *
 161  * Returns zero if the XML document could be closed cleanly.
 162  * Negative values indicate an error.
 163  */
 164 int mi_lttng_writer_open_element(struct mi_writer *writer,
 165                 const char *element_name);
 166
 167 /*
 168  * Close the current element tag.
 169  *
 170  * writer An instance of a machine interface writer.
 171  *
 172  * Returns zero if the XML document could be closed cleanly.
 173  * Negative values indicate an error.
 174  */
 175 int mi_lttng_writer_close_element(struct mi_writer *writer);
 176
 177 /*
 178  * Close multiple element.
 179  *
 180  * writer An instance of a machine interface writer.
 181  * nb_element Number of elements.
 182  *
 183  * Returns zero if the XML document could be closed cleanly.
 184  * Negative values indicate an error.
 185  */
 186 int mi_lttng_close_multi_element(struct mi_writer *writer,
 187                 unsigned int nb_element);
 188
 189 /*
 190  * Write an element of type unsigned int.
 191  *
 192  * writer An instance of a machine interface writer.
 193  * element_name Element name.
 194  * value Unsigned int value of the element
 195  *
 196  * Returns zero if the element's value could be written.
 197  * Negative values indicate an error.
 198  */
 199 int mi_lttng_writer_write_element_unsigned_int(struct mi_writer *writer,
 200                 const char *element_name, uint64_t value);
 201
 202 /*
 203  * Write an element of type signed int.
 204  *
 205  * writer An instance of a machine interface writer.
 206  * element_name Element name.
 207  * value Signed int value of the element.
 208  *
 209  * Returns zero if the element's value could be written.
 210  * Negative values indicate an error.
 211  */
 212 int mi_lttng_writer_write_element_signed_int(struct mi_writer *writer,
 213                 const char *element_name, int64_t value);
 214
 215 /*
 216  * Write an element of type boolean.
 217  *
 218  * writer An instance of a machine interface writer.
 219  * element_name Element name.
 220  * value Boolean value of the element.
 221  *
 222  * Returns zero if the element's value could be written.
 223  * Negative values indicate an error.
 224  */
 225 int mi_lttng_writer_write_element_bool(struct mi_writer *writer,
 226                 const char *element_name, int value);
 227
 228 /*
 229  * Write an element of type string.
 230  *
 231  * writer An instance of a machine interface writer.
 232  * element_name Element name.
 233  * value String value of the element.
 234  *
 235  * Returns zero if the element's value could be written.
 236  * Negative values indicate an error.
 237  */
 238 int mi_lttng_writer_write_element_string(struct mi_writer *writer,
 239                 const char *element_name, const char *value);
 240
 241 /*
 242  * Machine interface of struct version.
 243  *
 244  * writer An instance of a machine interface writer.
 245  * version Version struct.
 246  * lttng_description String value of the version description.
 247  * lttng_license String value of the version license.
 248  *
 249  * Returns zero if the element's value could be written.
 250  * Negative values indicate an error.
 251  */
 252 int mi_lttng_version(struct mi_writer *writer, struct mi_lttng_version *version,
 253                 const char *lttng_description, const char *lttng_license);
 254
 255 /*
 256  * Machine interface: open a sessions element.
 257  *
 258  * writer An instance of a machine interface writer.
 259  *
 260  * Returns zero if the element's value could be written.
 261  * Negative values indicate an error.
 262  */
 263 int mi_lttng_sessions_open(struct mi_writer *writer);
 264
 265 /*
 266  * Machine interface of struct session.
 267  *
 268  * writer An instance of a machine interface writer.
 269  * session An instance of a session.
 270  * is_open Defines whether or not the session element shall be closed.
 271  *         This should be used carefully and the client
 272  *         must close the session element.
 273  *         Use case: nested addtionnal information on a session
 274  *                  ex: domain,channel event.
 275  *
 276  * Returns zero if the element's value could be written.
 277  * Negative values indicate an error.
 278  */
 279 int mi_lttng_session(struct mi_writer *writer,
 280                 struct lttng_session *session, int is_open);
 281
 282 /*
 283  * Machine interface: open a domains element.
 284  *
 285  * writer An instance of a machine interface writer.
 286  *
 287  * Returns zero if the element's value could be written.
 288  * Negative values indicate an error.
 289  */
 290 int mi_lttng_domains_open(struct mi_writer *writer);
 291
 292 /*
 293  * Machine interface of struct domain.
 294  *
 295  * writer An instance of a machine interface writer.
 296  * domain An instance of a domain.
 297  *
 298  * is_open Defines whether or not the session element shall be closed.
 299  *         This should be used carefully and the client
 300  *         must close the domain element.
 301  *         Use case: nested addition information on a domain
 302  *                  ex: channel event.
 303  *
 304  * Returns zero if the element's value could be written.
 305  * Negative values indicate an error.
 306  */
 307 int mi_lttng_domain(struct mi_writer *writer,
 308                 struct lttng_domain *domain, int is_open);
 309
 310 /*
 311  * Machine interface: open a channels element.
 312  *
 313  * writer An instance of a machine interface writer.
 314  *
 315  * Returns zero if the element's value could be written.
 316  * Negative values indicate an error.
 317  */
 318 int mi_lttng_channels_open(struct mi_writer *writer);
 319
 320 /*
 321  * Machine interface of struct channel.
 322  *
 323  * writer An instance of a machine interface writer.
 324  * channel An instance of a channel.
 325  *
 326  * is_open Defines whether or not the session element shall be closed.
 327  *         This should be used carefully and the client
 328  *         must close the channel element.
 329  *         Use case: nested addition information on a channel.
 330  *                  ex: channel event.
 331  *
 332  * Returns zero if the element's value could be written.
 333  * Negative values indicate an error.
 334  */
 335 int mi_lttng_channel(struct mi_writer *writer,
 336                 struct lttng_channel *channel, int is_open);
 337
 338 /*
 339  * Machine interface of struct channel_attr.
 340  *
 341  * writer An instance of a machine interface writer.
 342  * attr An instance of a channel_attr struct.
 343  *
 344  * Returns zero if the element's value could be written.
 345  * Negative values indicate an error.
 346  */
 347 int mi_lttng_channel_attr(struct mi_writer *writer,
 348                 struct lttng_channel_attr *attr);
 349
 350 /*
 351 * Machine interface for event common attributes.
 352 *
 353 * writer An instance of a mi writer.
 354 * event single trace event.
 355 *
 356 * The common attribute are:
 357 * - mi event element
 358 * - event name
 359 * - event type
 360 * - enabled tag
 361 * - event filter
 362 *
 363 * Returns zero if the element's value could be written.
 364 * Negative values indicate an error.
 365 */
 366 int mi_lttng_event_common_attributes(struct mi_writer *writer,
 367                 struct lttng_event *event);
 368
 369 /*
 370  * Machine interface for kernel tracepoint event with a loglevel.
 371  *
 372  * writer An instance of a mi writer.
 373  * event single trace event.
 374  *
 375  * Returns zero if the element's value could be written.
 376  * Negative values indicate an error.
 377  */
 378 int mi_lttng_event_tracepoint_loglevel(struct mi_writer *writer,
 379                 struct lttng_event *event);
 380
 381 /*
 382  * Machine interface for kernel tracepoint event with no loglevel.
 383  *
 384  * writer An instance of a mi writer.
 385  * event single trace event.
 386  *
 387  * Returns zero if the element's value could be written.
 388  * Negative values indicate an error.
 389  */
 390 int mi_lttng_event_tracepoint_no_loglevel(struct mi_writer *writer,
 391                 struct lttng_event *event);
 392
 393 /*
 394  * Machine interface for kernel function and probe event.
 395  *
 396  * writer An instance of a mi writer.
 397  * event single trace event.
 398  *
 399  * Returns zero if the element's value could be written.
 400  * Negative values indicate an error.
 401  */
 402 int mi_lttng_event_function_probe(struct mi_writer *writer,
 403                 struct lttng_event *event);
 404
 405 /*
 406  * Machine interface for kernel function entry event.
 407  *
 408  * writer An instance of a mi writer.
 409  * event single trace event.
 410  *
 411  * Returns zero if the element's value could be written.
 412  * Negative values indicate an error.
 413  */
 414 int mi_lttng_event_function_entry(struct mi_writer *writer,
 415                 struct lttng_event *event);
 416
 417 /*
 418  * Machine interface: open an events element.
 419  *
 420  * writer An instance of a machine interface writer.
 421  *
 422  * Returns zero if the element's value could be written.
 423  * Negative values indicate an error.
 424  */
 425 int mi_lttng_events_open(struct mi_writer *writer);
 426
 427 /*
 428  * Machine interface for printing an event.
 429  * The trace event type currently supported are:
 430  *  TRACEPOINT,
 431  *  PROBE,
 432  *  FUNCTION,
 433  *  FUNCTION_ENTRY,
 434  *  SYSCALL
 435  *
 436  * writer An instance of a mi writer.
 437  * event single trace event.
 438  * is_open Defines whether or not the session element shall be closed.
 439  *         This should be used carefully and the client
 440  *         must close the event element.
 441  *         Use case: nested additional information
 442  *
 443  * Returns zero if the element's value could be written.
 444  * Negative values indicate an error.
 445  */
 446 int mi_lttng_event(struct mi_writer *writer, struct lttng_event *event,
 447                 int is_open);
 448
 449 /*
 450  * Machine interface for struct lttng_event_field.
 451  *
 452  * writer An instance of a mi writer.
 453  * field An event_field instance.
 454  *
 455  * Returns zero if the element's value could be written.
 456  * Negative values indicate an error.
 457  */
 458 int mi_lttng_event_field(struct mi_writer *writer,
 459                 struct lttng_event_field *field);
 460
 461 /*
 462  * Machine interface: open a event_fields element.
 463  *
 464  * writer An instance of a machine interface writer.
 465  *
 466  * Returns zero if the element's value could be written.
 467  * Negative values indicate an error.
 468  */
 469 int mi_lttng_event_fields_open(struct mi_writer *writer);
 470
 471 /*
 472  * Machine interface: open a PIDs element.
 473  *
 474  * writer An instance of a machine interface writer.
 475  *
 476  * Returns zero if the element's value could be written.
 477  * Negative values indicate an error.
 478  */
 479 int mi_lttng_pids_open(struct mi_writer *writer);
 480
 481 /*
 482  * Machine interface of a PID.
 483  *
 484  * writer An instance of a machine interface writer.
 485  * pid A PID.
 486  *
 487  * is_open Defines whether or not the session element shall be closed.
 488  *         This should be used carefully and the client
 489  *         must close the pid element.
 490  *         Use case: nested addition information on a domain
 491  *                  ex: channel event.
 492  *
 493  * Returns zero if the element's value could be written.
 494  * Negative values indicate an error.
 495  */
 496 int mi_lttng_pid(struct mi_writer *writer, pid_t pid , const char *cmdline,
 497                 int is_open);
 498
 499 #endif /* _MI_LTTNG_H */