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_name;
  51 const char * const mi_lttng_element_command_version;
  52 const char * const mi_lttng_element_command_list;
  53 const char * const mi_lttng_element_command_save;
  54 const char * const mi_lttng_element_command_load;
  55 const char * const mi_lttng_element_command_stop;
  56 const char * const mi_lttng_element_command_start;
  57 const char * const mi_lttng_element_command_create;
  58 const char * const mi_lttng_element_command_destroy;
  59 const char * const mi_lttng_element_command_calibrate;
  60 const char * const mi_lttng_element_command_add_context;
  61 const char * const mi_lttng_element_command_enable_channels;
  62 const char * const mi_lttng_element_command_output;
  63 const char * const mi_lttng_element_command_success;
  64
  65 /* Strings related to version command */
  66 const char * const mi_lttng_element_version;
  67 const char * const mi_lttng_element_version_str;
  68 const char * const mi_lttng_element_version_web;
  69 const char * const mi_lttng_element_version_major;
  70 const char * const mi_lttng_element_version_minor;
  71 const char * const mi_lttng_element_version_license;
  72 const char * const mi_lttng_element_version_commit;
  73 const char * const mi_lttng_element_version_patch_level;
  74 const char * const mi_lttng_element_version_description;
  75
  76 /* String related to a lttng_event_field */
  77 const char * const mi_lttng_element_event_field;
  78 const char * const mi_lttng_element_event_fields;
  79
  80 /* String related to lttng_event_context */
  81 const char * const mi_lttng_context_type_perf_counter;
  82 const char * const mi_lttng_context_type_perf_cpu_counter;
  83 const char * const mi_lttng_context_type_perf_thread_counter;
  84
  85 /* String related to lttng_event_perf_counter_ctx */
  86 const char * const mi_lttng_element_perf_counter_context;
  87
  88 /* Strings related to pid */
  89 const char * const mi_lttng_element_pids;
  90 const char * const mi_lttng_element_pid;
  91 const char * const mi_lttng_element_pid_id;
  92
  93 /* Strings related to save command */
  94 const char * const mi_lttng_element_save;
  95
  96 /* Strings related to load command */
  97 const char * const mi_lttng_element_load;
  98
  99 /* General element of mi_lttng */
 100 const char * const mi_lttng_element_type_other;
 101 const char * const mi_lttng_element_type_integer;
 102 const char * const mi_lttng_element_type_enum;
 103 const char * const mi_lttng_element_type_float;
 104 const char * const mi_lttng_element_type_string;
 105 const char * const mi_lttng_element_nowrite;
 106 const char * const mi_lttng_element_success;
 107
 108 /* String related to loglevel */
 109 const char * const mi_lttng_loglevel_str_alert;
 110 const char * const mi_lttng_loglevel_str_crit;
 111 const char * const mi_lttng_loglevel_str_debug;
 112 const char * const mi_lttng_loglevel_str_debug_function;
 113 const char * const mi_lttng_loglevel_str_debug_line;
 114 const char * const mi_lttng_loglevel_str_debug_module;
 115 const char * const mi_lttng_loglevel_str_debug_process;
 116 const char * const mi_lttng_loglevel_str_debug_program;
 117 const char * const mi_lttng_loglevel_str_debug_system;
 118 const char * const mi_lttng_loglevel_str_debug_unit;
 119 const char * const mi_lttng_loglevel_str_emerg;
 120 const char * const mi_lttng_loglevel_str_err;
 121 const char * const mi_lttng_loglevel_str_info;
 122 const char * const mi_lttng_loglevel_str_notice;
 123 const char * const mi_lttng_loglevel_str_unknown;
 124 const char * const mi_lttng_loglevel_str_warning;
 125
 126 /* String related to loglevel type */
 127 const char * const mi_lttng_loglevel_type_all;
 128 const char * const mi_lttng_loglevel_type_range;
 129 const char * const mi_lttng_loglevel_type_single;
 130 const char * const mi_lttng_loglevel_type_unknown;
 131
 132 /* Sting related to lttng_calibrate */
 133 const char * const mi_lttng_element_calibrate;
 134 const char * const mi_lttng_element_calibrate_function;
 135
 136 /* Utility string function  */
 137 const char *mi_lttng_loglevel_string(int value);
 138 const char *mi_lttng_logleveltype_string(enum lttng_loglevel_type value);
 139 const char *mi_lttng_eventfieldtype_string(enum lttng_event_field_type value);
 140 const char *mi_lttng_domaintype_string(enum lttng_domain_type value);
 141 const char *mi_lttng_buffertype_string(enum lttng_buffer_type value);
 142 const char *mi_lttng_calibratetype_string(enum lttng_calibrate_type val);
 143
 144 /*
 145  * Create an instance of a machine interface writer.
 146  *
 147  * fd_output File to which the XML content must be written. The file will be
 148  * closed once the mi_writer has been destroyed.
 149  *
 150  * Returns an instance of a machine interface writer on success, NULL on
 151  * error.
 152  */
 153 struct mi_writer *mi_lttng_writer_create(int fd_output, int mi_output_type);
 154
 155 /*
 156  * Destroy an instance of a machine interface writer.
 157  *
 158  * writer An instance of a machine interface writer.
 159  *
 160  * Returns zero if the XML document could be closed cleanly. Negative values
 161  * indicate an error.
 162  */
 163 int mi_lttng_writer_destroy(struct mi_writer *writer);
 164
 165 /*
 166  * Open a command tag and add it's name node.
 167  *
 168  * writer An instance of a machine interface writer.
 169  * command The command name.
 170  *
 171  * Returns zero if the XML document could be closed cleanly.
 172  * Negative values indicate an error.
 173  */
 174 int mi_lttng_writer_command_open(struct mi_writer *writer, const char *command);
 175
 176 /*
 177  * Close a command tag.
 178  *
 179  * writer An instance of a machine interface writer.
 180  *
 181  * Returns zero if the XML document could be closed cleanly.
 182  * Negative values indicate an error.
 183  */
 184 int mi_lttng_writer_command_close(struct mi_writer *writer);
 185
 186 /*
 187  * Open an element tag.
 188  *
 189  * writer An instance of a machine interface writer.
 190  * element_name Element tag name.
 191  *
 192  * Returns zero if the XML document could be closed cleanly.
 193  * Negative values indicate an error.
 194  */
 195 int mi_lttng_writer_open_element(struct mi_writer *writer,
 196                 const char *element_name);
 197
 198 /*
 199  * Close the current element tag.
 200  *
 201  * writer An instance of a machine interface writer.
 202  *
 203  * Returns zero if the XML document could be closed cleanly.
 204  * Negative values indicate an error.
 205  */
 206 int mi_lttng_writer_close_element(struct mi_writer *writer);
 207
 208 /*
 209  * Close multiple element.
 210  *
 211  * writer An instance of a machine interface writer.
 212  * nb_element Number of elements.
 213  *
 214  * Returns zero if the XML document could be closed cleanly.
 215  * Negative values indicate an error.
 216  */
 217 int mi_lttng_close_multi_element(struct mi_writer *writer,
 218                 unsigned int nb_element);
 219
 220 /*
 221  * Write an element of type unsigned int.
 222  *
 223  * writer An instance of a machine interface writer.
 224  * element_name Element name.
 225  * value Unsigned int value of the element
 226  *
 227  * Returns zero if the element's value could be written.
 228  * Negative values indicate an error.
 229  */
 230 int mi_lttng_writer_write_element_unsigned_int(struct mi_writer *writer,
 231                 const char *element_name, uint64_t value);
 232
 233 /*
 234  * Write an element of type signed int.
 235  *
 236  * writer An instance of a machine interface writer.
 237  * element_name Element name.
 238  * value Signed int value of the element.
 239  *
 240  * Returns zero if the element's value could be written.
 241  * Negative values indicate an error.
 242  */
 243 int mi_lttng_writer_write_element_signed_int(struct mi_writer *writer,
 244                 const char *element_name, int64_t value);
 245
 246 /*
 247  * Write an element of type boolean.
 248  *
 249  * writer An instance of a machine interface writer.
 250  * element_name Element name.
 251  * value Boolean value of the element.
 252  *
 253  * Returns zero if the element's value could be written.
 254  * Negative values indicate an error.
 255  */
 256 int mi_lttng_writer_write_element_bool(struct mi_writer *writer,
 257                 const char *element_name, int value);
 258
 259 /*
 260  * Write an element of type string.
 261  *
 262  * writer An instance of a machine interface writer.
 263  * element_name Element name.
 264  * value String value of the element.
 265  *
 266  * Returns zero if the element's value could be written.
 267  * Negative values indicate an error.
 268  */
 269 int mi_lttng_writer_write_element_string(struct mi_writer *writer,
 270                 const char *element_name, const char *value);
 271
 272 /*
 273  * Machine interface of struct version.
 274  *
 275  * writer An instance of a machine interface writer.
 276  * version Version struct.
 277  * lttng_description String value of the version description.
 278  * lttng_license String value of the version license.
 279  *
 280  * Returns zero if the element's value could be written.
 281  * Negative values indicate an error.
 282  */
 283 int mi_lttng_version(struct mi_writer *writer, struct mi_lttng_version *version,
 284                 const char *lttng_description, const char *lttng_license);
 285
 286 /*
 287  * Machine interface: open a sessions element.
 288  *
 289  * writer An instance of a machine interface writer.
 290  *
 291  * Returns zero if the element's value could be written.
 292  * Negative values indicate an error.
 293  */
 294 int mi_lttng_sessions_open(struct mi_writer *writer);
 295
 296 /*
 297  * Machine interface of struct session.
 298  *
 299  * writer An instance of a machine interface writer.
 300  * session An instance of a session.
 301  * is_open Defines whether or not the session element shall be closed.
 302  *         This should be used carefully and the client
 303  *         must close the session element.
 304  *         Use case: nested addtionnal information on a session
 305  *                  ex: domain,channel event.
 306  *
 307  * Returns zero if the element's value could be written.
 308  * Negative values indicate an error.
 309  */
 310 int mi_lttng_session(struct mi_writer *writer,
 311                 struct lttng_session *session, int is_open);
 312
 313 /*
 314  * Machine interface: open a domains element.
 315  *
 316  * writer An instance of a machine interface writer.
 317  *
 318  * Returns zero if the element's value could be written.
 319  * Negative values indicate an error.
 320  */
 321 int mi_lttng_domains_open(struct mi_writer *writer);
 322
 323 /*
 324  * Machine interface of struct domain.
 325  *
 326  * writer An instance of a machine interface writer.
 327  * domain An instance of a domain.
 328  *
 329  * is_open Defines whether or not the session element shall be closed.
 330  *         This should be used carefully and the client
 331  *         must close the domain element.
 332  *         Use case: nested addition information on a domain
 333  *                  ex: channel event.
 334  *
 335  * Returns zero if the element's value could be written.
 336  * Negative values indicate an error.
 337  */
 338 int mi_lttng_domain(struct mi_writer *writer,
 339                 struct lttng_domain *domain, int is_open);
 340
 341 /*
 342  * Machine interface: open a channels element.
 343  *
 344  * writer An instance of a machine interface writer.
 345  *
 346  * Returns zero if the element's value could be written.
 347  * Negative values indicate an error.
 348  */
 349 int mi_lttng_channels_open(struct mi_writer *writer);
 350
 351 /*
 352  * Machine interface of struct channel.
 353  *
 354  * writer An instance of a machine interface writer.
 355  * channel An instance of a channel.
 356  *
 357  * is_open Defines whether or not the session element shall be closed.
 358  *         This should be used carefully and the client
 359  *         must close the channel element.
 360  *         Use case: nested addition information on a channel.
 361  *                  ex: channel event.
 362  *
 363  * Returns zero if the element's value could be written.
 364  * Negative values indicate an error.
 365  */
 366 int mi_lttng_channel(struct mi_writer *writer,
 367                 struct lttng_channel *channel, int is_open);
 368
 369 /*
 370  * Machine interface of struct channel_attr.
 371  *
 372  * writer An instance of a machine interface writer.
 373  * attr An instance of a channel_attr struct.
 374  *
 375  * Returns zero if the element's value could be written.
 376  * Negative values indicate an error.
 377  */
 378 int mi_lttng_channel_attr(struct mi_writer *writer,
 379                 struct lttng_channel_attr *attr);
 380
 381 /*
 382 * Machine interface for event common attributes.
 383 *
 384 * writer An instance of a mi writer.
 385 * event single trace event.
 386 *
 387 * The common attribute are:
 388 * - mi event element
 389 * - event name
 390 * - event type
 391 * - enabled tag
 392 * - event filter
 393 *
 394 * Returns zero if the element's value could be written.
 395 * Negative values indicate an error.
 396 */
 397 int mi_lttng_event_common_attributes(struct mi_writer *writer,
 398                 struct lttng_event *event);
 399
 400 /*
 401  * Machine interface for kernel tracepoint event with a loglevel.
 402  *
 403  * writer An instance of a mi writer.
 404  * event single trace event.
 405  *
 406  * Returns zero if the element's value could be written.
 407  * Negative values indicate an error.
 408  */
 409 int mi_lttng_event_tracepoint_loglevel(struct mi_writer *writer,
 410                 struct lttng_event *event);
 411
 412 /*
 413  * Machine interface for kernel tracepoint event with no loglevel.
 414  *
 415  * writer An instance of a mi writer.
 416  * event single trace event.
 417  *
 418  * Returns zero if the element's value could be written.
 419  * Negative values indicate an error.
 420  */
 421 int mi_lttng_event_tracepoint_no_loglevel(struct mi_writer *writer,
 422                 struct lttng_event *event);
 423
 424 /*
 425  * Machine interface for kernel function and probe event.
 426  *
 427  * writer An instance of a mi writer.
 428  * event single trace event.
 429  *
 430  * Returns zero if the element's value could be written.
 431  * Negative values indicate an error.
 432  */
 433 int mi_lttng_event_function_probe(struct mi_writer *writer,
 434                 struct lttng_event *event);
 435
 436 /*
 437  * Machine interface for kernel function entry event.
 438  *
 439  * writer An instance of a mi writer.
 440  * event single trace event.
 441  *
 442  * Returns zero if the element's value could be written.
 443  * Negative values indicate an error.
 444  */
 445 int mi_lttng_event_function_entry(struct mi_writer *writer,
 446                 struct lttng_event *event);
 447
 448 /*
 449  * Machine interface: open an events element.
 450  *
 451  * writer An instance of a machine interface writer.
 452  *
 453  * Returns zero if the element's value could be written.
 454  * Negative values indicate an error.
 455  */
 456 int mi_lttng_events_open(struct mi_writer *writer);
 457
 458 /*
 459  * Machine interface for printing an event.
 460  * The trace event type currently supported are:
 461  *  TRACEPOINT,
 462  *  PROBE,
 463  *  FUNCTION,
 464  *  FUNCTION_ENTRY,
 465  *  SYSCALL
 466  *
 467  * writer An instance of a mi writer.
 468  * event single trace event.
 469  * is_open Defines whether or not the session element shall be closed.
 470  *         This should be used carefully and the client
 471  *         must close the event element.
 472  *         Use case: nested additional information
 473  *
 474  * Returns zero if the element's value could be written.
 475  * Negative values indicate an error.
 476  */
 477 int mi_lttng_event(struct mi_writer *writer, struct lttng_event *event,
 478                 int is_open);
 479
 480 /*
 481  * Machine interface for struct lttng_event_field.
 482  *
 483  * writer An instance of a mi writer.
 484  * field An event_field instance.
 485  *
 486  * Returns zero if the element's value could be written.
 487  * Negative values indicate an error.
 488  */
 489 int mi_lttng_event_field(struct mi_writer *writer,
 490                 struct lttng_event_field *field);
 491
 492 /*
 493  * Machine interface: open a event_fields element.
 494  *
 495  * writer An instance of a machine interface writer.
 496  *
 497  * Returns zero if the element could be written.
 498  * Negative values indicate an error.
 499  */
 500 int mi_lttng_event_fields_open(struct mi_writer *writer);
 501
 502 /*
 503  * Machine interface: open a PIDs element.
 504  *
 505  * writer An instance of a machine interface writer.
 506  *
 507  * Returns zero if the element's value could be written.
 508  * Negative values indicate an error.
 509  */
 510 int mi_lttng_pids_open(struct mi_writer *writer);
 511
 512 /*
 513  * Machine interface of a PID.
 514  *
 515  * writer An instance of a machine interface writer.
 516  * pid A PID.
 517  *
 518  * is_open Defines whether or not the session element shall be closed.
 519  *         This should be used carefully and the client
 520  *         must close the pid element.
 521  *         Use case: nested addition information on a domain
 522  *                  ex: channel event.
 523  *
 524  * Returns zero if the element's value could be written.
 525  * Negative values indicate an error.
 526  */
 527 int mi_lttng_pid(struct mi_writer *writer, pid_t pid , const char *cmdline,
 528                 int is_open);
 529
 530 /*
 531  * Machine interface for struct lttng_calibrate.
 532  *
 533  * writer An instance of a machine interface writer.
 534  *
 535  * calibrate A lttng_calibrate instance.
 536  *
 537  * Returns zero if the element's value could be written.
 538  * Negative values indicate an error.
 539  */
 540 int mi_lttng_calibrate(struct mi_writer *writer,
 541                 struct lttng_calibrate *calibrate);
 542
 543 /*
 544  * Machine interface of a context.
 545  *
 546  * writer An instance of a machine interface writer
 547  *
 548  * context An instance of a lttng_event_context
 549  *
 550  * is_open Define if we close the context element
 551  *         This should be used carefully and the client
 552  *         need to close the context element.
 553  *         0-> False
 554  *         1-> True
 555  * Returns zero if the element's value could be written.
 556  * Negative values indicate an error.
 557  */
 558 int mi_lttng_context(struct mi_writer *writer,
 559                 struct lttng_event_context *context, int is_open);
 560
 561 /*
 562  * Machine interface of a perf_counter_context.
 563  *
 564  * writer An instance of a machine interface writer
 565  *
 566  * contest An instance of a lttng_event_perf_counter_ctx
 567  *
 568  * Returns zero if the element's value could be written.
 569  * Negative values indicate an error.
 570  */
 571 int mi_lttng_perf_counter_context(struct mi_writer *writer,
 572                 struct lttng_event_perf_counter_ctx  *perf_context);
 573
 574 #endif /* _MI_LTTNG_H */