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