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