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