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