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