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