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