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