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