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