fix Makefile for libbabeltrace-ctf

Signed-off-by: Julien Desfossez <jdesfossez@efficios.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

fix warnings

Signed-off-by: Julien Desfossez <jdesfossez@efficios.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

fix missing libbabeltrace-ctf for libctfcopytrace

Signed-off-by: Julien Desfossez <jdesfossez@efficios.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

fixes after rebase on eepp-jgalar/fixes-mar-7

Signed-off-by: Julien Desfossez <jdesfossez@efficios.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

Text: handle output file

Signed-off-by: Julien Desfossez <jdesfossez@efficios.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

text: escape control sequences characters

Signed-off-by: Julien Desfossez <jdesfossez@efficios.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

Support for --clock-offset and --clock-offset-ns

Signed-off-by: Julien Desfossez <jdesfossez@efficios.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

Text output identical with babeltrace 1

Various fixes to make sure the text output stays the same as babeltrace
1. Tested all -f and -n options combinations with no differences.

Signed-off-by: Julien Desfossez <jdesfossez@efficios.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

fix: missing equal sign when printing events without colors

Signed-off-by: Julien Desfossez <jdesfossez@efficios.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

debug-info filter plugin

This plugin can be inserted in the graph to add the debugging
informations to events that have the necessary context informations (see
the README for usage informations).

Compared to the previous implementation, this version does not only
output the debug informations to the text output, but it adds the
debug_info structure into the CTF events. That way, the plugins and
sinks after this one see the debug_info as part of the event contexts.

The default name of the structure added to the events is "debug_info",
but can be overridden. If this structure already exists in the event
context, it is not added again.

If a trace does not have the ip and vpid event contexts in its stream
class, the trace is copied without adding the "debug_info" structure.

Signed-off-by: Julien Desfossez <jdesfossez@efficios.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

Make bt_ctf_field_structure_set_field public

Signed-off-by: Julien Desfossez <jdesfossez@efficios.com>
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

cleanup error paths in trimmer, writer and ctfcopytrace

Signed-off-by: Julien Desfossez <jdesfossez@efficios.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

trimmer: Update the bounds of the trimmed packets

Update the timestamp_begin field of the first packet of each stream and
the timestamp_end field of the last packet to reflect the fact that the
packet content got truncated by the user. This is important for the
packet intersection feature afterwards. This requires that we create new
packets and copy the events to assign them to the new packets.

Signed-off-by: Julien Desfossez <jdesfossez@efficios.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

Fix graph facilities handling in writer component class

Commit 43e5ad310e9ea54e86dd3444e23c2d3c69827bc9 missed a few details to
make it work properly.

Signed-off-by: Julien Desfossez <jdesfossez@efficios.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

fix trimmer compiled library name

Signed-off-by: Julien Desfossez <jdesfossez@efficios.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

writer: create event classes lazily

Instead of copying all the event classes when we copy the stream
classes, we now create them only when needed. That way, we can use this
plugin in live where new events can get created after the trace has
already been opened.

Signed-off-by: Julien Desfossez <jdesfossez@efficios.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

libcopytrace: export ctf_copy_event_header

Signed-off-by: Julien Desfossez <jdesfossez@efficios.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

Override clock fields in copied traces

Some tracers like LTTng use a compression scheme on the timestamp field
to avoid writing the full 64-bit timestamp at every event. When the
trace is complete, the reader has all the information to understand this
compression, but if a trace is filtered or truncated, there might be
some state information missing.

Since we don't know in advance if a compression scheme is used in a
trace, we now force the copied traces to have a full 64-bit timestamp.

The user of this library can decide whether or not to override the type
of the clock fields.

Signed-off-by: Julien Desfossez <jdesfossez@efficios.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

Create a library to copy a CTF trace

Move all the code from the writer plugin to a standalone plugin library
so it can be used by other plugins.

Signed-off-by: Julien Desfossez <jdesfossez@efficios.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

Allow to set the size of an integer type

Add bt_ctf_field_type_integer_set_size to the API.

Signed-off-by: Julien Desfossez <jdesfossez@efficios.com>
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

Fix writer: leak of the event classes

We have to release the writer_event_class once it is added to the
writer_stream_class. This also highlighted a problem with the ownership
of the stream, stream_class and writer objects which is now fixed.

Signed-off-by: Julien Desfossez <jdesfossez@efficios.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

Fix writer: missing put ref to values and types

Signed-off-by: Julien Desfossez <jdesfossez@efficios.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

Fix writer: leak of the header fields

Signed-off-by: Julien Desfossez <jdesfossez@efficios.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

Rename converter/ -> cli/ (it's more than a converter now)

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

Event notification: pass CC priority map on creation

An event notification must have an associated clock class priority map
to indicate the ranks of its event's clock values.

As of this patch, a ctf.fs source component always set the priority of
all the parsed clock classes to 0.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

Remove Babeltrace 1 files and reorganize the tree

This is one of the patches that you won't easily forget.

This patch removes the remaining legacy files, moving them if we still
need them, and reorganizes the tree as such:

* formats/ is removed
* formats/ctf/ir/ is moved to lib/ctf-ir/
* formats/ctf/writer/ is moved to lib/ctf-writer/
* types/ is removed

Because some of the CTF IR and CTF writer objects are so coupled, both
components are in libbabeltrace now. The build system creates a symbolic
link from libbabeltrace-ctf (where CTF writer used to reside) to
libbabeltrace, so that `-lbabeltrace-ctf` still works for the current
users of CTF writer.

converter/babeltrace-log.c still exists, but it's not build as of this
patch because it uses the legacy API. We need to change this to use CTF
writer and add it to the Makefile again.

Some debug info files are gone because they also use the legacy API.
They are updated anyway as part of the upcoming debug info component
class.

The Python bindings are not covered by this patch: a subsequent patch
should fix them at once.

Some tests which used the legacy API are removed.

The legacy include files are removed, except for
include/babeltrace/ctf/event.h which could be included by CTF writer
users. The file simply includes all the CTF writer header files now.

The functions to serialize integer and floating point number fields
are moved to lib/ctf-writer/serialize.c where a light
`struct bt_ctf_stream_pos` exists along with a few helper functions
for this renamed legacy object. The serialization functions use BT 2
objects now so that the dependency on the legacy API can be dropped.

The serialization functions accept a native byte order parameter now.
When a field type has a "native" byte order, the real (passed) native
byte order must be used. This ensures that:

* CTF IR objects do not need to propagate the trace's native byte order
  to all the contained field types.

* Two references to the same field type which are part of two different
  trace objects can have a native byte order without causing byte order
  overwriting bugs.

The CTF IR code is simplified with this change. Also the
bt_ctf_trace_set_byte_order() function refuses the
BT_CTF_BYTE_ORDER_NATIVE byte order.

I also added internal inline functions to quickly access the parent
of some CTF IR object without getting a new reference:

* bt_ctf_event_borrow_event_class()
* bt_ctf_event_class_borrow_stream_class()
* bt_ctf_stream_class_borrow_trace()

Since the CTF parser test in formats/ctf/metadata/ was a legacy tool,
it's removed in this patch. It's not used anymore by test_ctf_writer
(only the converter runs to validate the generated trace).

Leaks are fixed in test_ctf_ir_ref and test_trace_listener.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

ctf.fs: bt_ctf_notif_iter_create(): assert() that all medops exist

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

trace.h: update API doc

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

tests: add clock class priority map tests

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

Add clock class priority map object

This new object is a simple map of clock classes to their priorities
against the other clock classes of the same map. See the header
file's documentation for more information (clock-class-priority-map.h).

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

ctf.fs: split streams, one per port

The ports are named `traceN-stream-STREAM`, where `N` is the index of
the trace (starts at 0) and `STREAM` is the base name of the stream
file.

The heap which used to be in this component class is expected to be
moved to the utils.muxer filter component class.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

Add user data for private port

A private port belongs to a private component, so it's okay to set
custom user data within a port. The user must make sure to release the
private user data whatever happens. The easiest solution is to make
a port's private data owned by the component's private data.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

Add graph topology tests

The new tests verify that the component methods and graph listeners are
called by the graph framework in reaction to specific events with the
expected parameters and in the expected order.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

Call a single "ports connected/disconnected" graph listener instead of two

It is reasonable to believe that a user implementing a
"ports connected" or "ports disconnected" graph listener wants both
the upstream and downstream ports, instead of getting called two times
with one and the other.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

Fix: call acting component's "port disconnected" method too

When a port is disconnected, call both upstream and downstream
components. It's okay to get notified as a component even if you
caused this notification.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

bt_graph_connect() -> bt_graph_connect_ports()

This is more explicit.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

Rename <babeltrace/component/...> -> <babeltrace/graph/...>

Also put all the graph-related header files directly in this directory,
not in subdirectories.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

Update notification iterator's "init" function signature

As per this project's standard way of calling methods, the self object
should always be the first parameter. In the cast of
bt_component_class_notification_iterator_init_method, we don't need to
explicitly pass the bt_private_component object since you can get it
from the notification iterator with
bt_private_notification_iterator_get_private_component().

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

Remove the need to implement the notification iterator's "get" method

The order of a notification iterator's "get" method is to return the
"current notification", set by the last "next" method call. Since all
source and filter plugins do the same in their "get" method, let's
remove the need to implement it at all.

The bt_notification_iterator_next() and
bt_notification_iterator_get_notification() public functions are still
available for the iterator's user, but the iterator object itself keeps
the current notification returned by the last "next" method call.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

"destroy" method -> "finalize" method

"Finalize" is more symmetric with "initialize" ("init"), and "destroy"
implies that the object is completely destroyed, which might not be the
case eventually.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

Accept port connection method: take other port as parameter

This can be useful, as we already have it at this point when calling the
method, to inspect the other port and its component.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

Visibility: split graph API into public and private interfaces

The goal here is to avoid that a component or a graph user calls methods
that do not logically apply to itself, but should according to the API's
intention. For example, a component should not be able to remove the
ports of another component, and a graph user should not be able to
create a notification iterator directly.

Therefore the existing bt_component, bt_port, bt_connection, and
bt_notification_iterator objects are considered "public": any user can
call their API.

The user-defined methods (callbacks) now accept private versions of
those objects:

* bt_private_component
* bt_private_port
* bt_private_connection
* bt_private_notification_iterator

This ensures that only the user which is called back with those private
objects can call specific, private methods, which start with the
`bt_private_` prefix.

For example, any user can get a sink component's input port by name with
bt_component_sink_get_input_port(). This function accepts a bt_component
object parameter and returns a bt_port object. However, only the called
back user can get its private version of the port with the equivalent
bt_private_component_sink_get_input_private_port(). This function
accepts a bt_private_component object parameter and returns a
bt_private_port object. The private port API has the
bt_private_port_remove_from_component() function: thus only the owner
component of a port can remove it from itself.

Each private API has a bt_OBJ_from_private_OBJ() function which
returns a _new reference_ to the equivalent public object of a private
object to be able to call public functions.

With all this, if a user calls a private function with a public object,
the compiler emits a warning similar to:

    warning: assignment from incompatible pointer type

With GCC and Clang, you can make this warning an error with:

    -Werror=incompatible-pointer-types

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

Add graph event listeners

With this patch you can add event listeners to a graph:

* Port added to a graph's component. Note that this is only called when
  the component belongs to a graph. It is not called for existing ports
  when the component becomes part of a graph (with bt_graph_connect()).
* Port removed from a graph's component.
* Graph component's port connected.
* Graph component's port disconnected.

All those listeners return `void` because they cannot "fail". In the
worst case they should just abort. Another way would be to set a flag
at some place and read it once you have called bt_graph_run() or
bt_graph_consume().

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

Allow a component to remove a port and any user to disconnect one

This patch allows a component to remove one of its own ports at anytime.
Removing a connected port has the side effect of also disconnecting it.
This patch also allows any user (graph's creator or component, for
example) to disconnect a component's port.

A component can remove one of its port with
bt_port_remove_from_component(). This function only needs the port
object because the removing component is its parent. Note that this
function does not check in any way that the removing component is the
parent of the port to remove from its parent, so any component or even
the graph's user could remove any component's port. This is prohibited
by the API's contract, but it's not enforced. It should be documented
accordingly.

You can disconnect a port with bt_port_disconnect(). When you call this
function, both upstream and downstream ports of the port's current
connection are disconnected, that is, they become available again for
bt_graph_connect().

When a port is disconnected with bt_port_remove_from_component(), the
parent component's of the connection's other port is called back ("port
disconnected" method) to notify it that one of its ports lost a
connection. Then the component is free to keep this port as an available
port, or to remove it too.

When a port is disconnected with bt_port_disconnect(), both
components are called back ("port disconnected method").

The existing iterators on a connection which is dropped (ports are
disconnected) are left as is: they still work.

The "new connection" optional method is renamed to "accept port
connection": this method can return
BT_COMPONENT_STATUS_REFUSE_PORT_CONNECTION to explicitly refuse the
new connection.

With this patch, only one connection per port is allowed. This
simplifies the model. One-to-many connections can be replaced with
a "tee" filter. Thus this patch removes the concept of a maximum number
of connections per port (it's always one).

With this patch, a component can add a new port at anytime, not just
during its initialization.

Also in this patch: the input and output ports are part of the
bt_component object. The public API is not changed. This avoids some
code duplication.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

Put Python plugin support in a separate shared object

This is to make the work of packagers easier for libbabeltrace not
to depend on libpython, even if you need Python plugin support.

With this patch, python.c's constructor tries to open the new Python
plugin provider shared object. If it fails, Python plugin support is
disabled, but shared object plugins can still be loaded.

The new BUILT_IN_PYTHON_PLUGIN_SUPPORT configure variable, if set to 1,
makes the build embed the Python plugin provider into libbabeltrace
(like before this patch).

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

Add `babeltrace convert` argument tests

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

CLI: add `run` command and make `convert` command use it

This patch adds the babeltrace(1) command `run` which is essentially the
same as the current `convert` command without the magic stuff (legacy
options and their interesting constraints), plus this:

* You can set the name of a component by prefixing the --source,
  --filter, or --sink option's argument with `NAME:`. You can escape
  `.`, `:`, and `\` with `\`. Example:

      --source=instance:ctf.fs --sink=my-text:text.text
      --filter='my\.name:my\.plugin.my\.comp\.cls'

  This is the equivalent of:

      --source=ctf.fs --name=instance --sink=text.text --name=my-text
      --filter='my\.plugin.my\.comp\.cls' --name my.name

  The --name option still exists: it sets the current name of the
  current component, so that, with this:

      --sink=a:b.c --name=salut --name=bonjour

  the effective name of this component is `bonjour`.

* You can use the new --key and --value options to add one string
  initialization parameter to the current component. The name of this
  parameter is given by the last --key option's argument, and its value
  by the --value option's argument. Examples:

      --source=ctf.fs --key=path --value ~/lttng-traces/...
      --key=path --source=ctf.fs --value ~/lttng-traces/...

  This is useful to not care about the specific escaping required by the
  --params option format for a string parameter, to use any parameter
  name, and to use shell expansion for the value (tilde expansion for
  example, as --path is not a `run` command's option).

The `convert` command is now a specialization of the `run` command,
specific to a _conversion graph_ (whereas the terminology for what you
build with the `run` command is a _processing graph_). The conversion
graph that the `convert` command builds always has the following
topology:

    sources -> utils.muxer -> [utils.trimmer] -> lttng-utils.debug-info -.
           .-------------------------------------------------------------'
           '-> [user filters] -> sinks

There's no more --connect option in the `convert` command. When you run
the `convert` command, it prepares the equivalent `run` command
arguments and invokes the latter directly. However if `-o ctf-metadata`
exists, a new "print CTF metadata" command configuration is created, and
if `-o lttng-live` exists with a URL missing a session name, a new
"print LTTng-live sessions" command configuration is created.

New `convert` options are:

--color=(always | auto | never)
    Adds the `color` initialization parameter set to the corresponding
    value to the implicit text.text sink component.

--no-debug-info
    Do not add an implicit lttng-utils.debug-info filter component to
    the filter chain. The lttng-utils.debug-info filter always exists
    otherwise.

--run-args
    Instead of invoking the `run` command, prints to the standard output
    the equivalent `run` command arguments, formatted for a shell. This
    means you can copy the whole output and use it as is to execute
    `babeltrace run` without escaping, so that the two following
    commands are equivalent:

        babeltrace convert [...]
        babeltrace run $(babeltrace convert --run-args [...])

    You can also use this trick to augment the conversion graph with the
    `run` command, for example:

        babeltrace run --base-params common-to-each-convert-comp=23
                       $(babeltrace convert --run-args /path/to/trace
                         --source=src:my.source [...])
                       --reset-base-params
                       --sink=special-sink:my.sink
                       --connect=src.some-port:special-sink

--run-args-0
    Like --run-args, but does not escape the individual arguments for a
    shell, and uses the null character as the argument delimiter. This
    is useful to get the list of equivalent raw arguments outside a
    shell (in a user program), or to use `xargs -0`.

--url=URL
    Set the `url` initialization parameter of the current user component
    to URL.

Lost `convert` options are:

* --base-params
* --connect
* --reset-base-params

Note that --clock-force-correlate sets the boolean `force-correlate`
initialization parameter of the implicit utils.muxer filter to true.

The necessary conditions to instantiate implicit components are now:

* Implicit ctf.fs source: any of:
  * Leftover argument and no --input-format
  * Leftover argument and --input-format=ctf
  * Leftover argument and --clock-offset
  * Leftover argument and --clock-offset-ns
  * Leftover argument and --stream-intersection

* Implicit ctf.lttng-live source: any of:
  * Leftover argument and --input-format=lttng-live

* Implicit utils.muxer filter: always exists

* Implicit utils.trimmer filter: any of:
  * --begin
  * --end
  * --timerange

* Implicit lttng-utils.debug-info filter:
  * No --no-debug-info

* Implicit utils.dummy sink:
  * --output-format=dummy

* Implicit text.text sink: any of:
  * No --output-format and no --sink
  * --output-format=text
  * --clock-cycles
  * --clock-date
  * --clock-gmt
  * --clock-seconds
  * --color
  * --fields
  * --names
  * --no-delta
  * --output

The default names of the implicit components, given by the `convert`
command, to be used by the `run` command, are:

* Implicit ctf.fs source: `ctf`
* Implicit ctf.lttng-live source: `lttng-live`
* Implicit utils.muxer filter: always exists `mux`
* Implicit utils.trimmer filter: `trim`
* Implicit lttng-utils.debug-info filter: `debug-info`
* Implicit utils.dummy sink: `dummy`
* Implicit text.text sink: `text`

If any name is already taken by an explicit user component (--source,
--filter, and --sink), the rule is to try `NAME-0`, then `NAME-1`, then
`NAME-2`, etc. The same rule applies to unnamed user components.
Implicit components are always automatically named after automatically
naming the unnamed user components.

This patch also adds the following:

* Connection cycle detection in babeltrace-cfg-connect.c.
* bt_common_string_until() which returns a substring from a given point
  to one of a set of terminating characters, possibly with escapable
  characters.
* bt_common_shell_quote() which quotes a string (if necessary) for a
  shell.
* bt_common_string_is_printable() which checks if a string contains
  only printable characters, including whitespaces.
* bt_common_parse_lttng_live_url() to parse a LTTng-live URL. This is
  needed in both the LTTng-live plugin itself and babeltrace-cfg.c to
  know if the command is a `run` command or a "print LTTng-live
  sessions" command.
* The --name, --source, --filter, --sink, and --connect arguments are
  checked with bt_common_string_is_printable().

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

Fix: missing reference release in field reset

A missing bt_put() on in reset_structure_field() will cause
the reset fields to be leaked. This function is used on fields
which are automatically managed by the writer such as
timestamp_begin, timestamp_end, packet_size, and content_size.

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

Fix: bt_connection_get_*_port() must take a reference on port

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

Fix: only remove newly added components on connection error

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

Fix: only add components to graph if they are not already present

bt_graph_connect() creates a connection and adds the components
on both ends of the connection to the graph. This fix ensures
that the components are not added a second time if multiple
connections involving the same components are established.

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

Fix: release the reference held by a child to its former parent

The bt_object class' bt_object_set_parent() increments the reference
count of the parent since the child now holds a reference to it.
This assumes that a child is externally visible when this call is
made (as is always the case currently).

The parent of a child can be changed in the future. In this case,
we want to ensure the reference it held to its former parent is
released.

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

babeltrace-cfg.c: do not allow duplicate -v option

Otherwise, `babeltrace -vvv list-plugins` passes and tries to open the
`list-plugins` directory with ctf.fs.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

babeltrace-cfg.c: add "Command line error" prefix to error messages

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

babeltrace-cfg.c: do not infer text.text sink with -v

Having the -v option passed to the `convert` command is not a
sufficient criterion to infer a text.text sink component, because -v
is also a general option which applies to the whole command. Without
this patch, you can't run this:

    babeltrace -v /path/to/trace -o my.sink

because the configurator sees both an implicit text.text sink (caused by
-v) and an explicit my.sink sink.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

babeltrace(1): add --filter option to create filter components

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

babeltrace(1): escape '.' in PLUGIN.COMPCLS arguments

Now you can have dots in your plugin or component class names:

    babeltrace --source 'hello\.world.my\.component\.class'

Also, escape `\` with `\\`.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

common.c: bt_common_colors_supported(): add a few supported terminal prefixes

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

Return component port counts by parameter

The rest of the API separates the return of success/error from
the return of the item count. This change makes the component
API consistent with the style used elsewhere.

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

Remove component prefix from graph, connection and port filenames

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

Add missing include in component-sink-internal.h

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

Build and run hard-coded component graph in babeltrace.c

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

Use graph facilities in dummy sink component class

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

Use graph facilities in text component class

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

Use graph facilities in trimmer component class

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

Use graph facilities in writer component class

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

Add missing forward declarations to component-class.h

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

Replace add_iterator methods by a single new_connection method

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

Implement the component graph interface

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

Hide bt_component_sink_consume

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

Hide filter iterator creation functions

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

Hide source iterator creation functions

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

Hide filter creation functions

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

Add ports to the source, filter and sink component interfaces

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

Add the component port interface

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

Text: print unknown enumeration mappings in red

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

Implement the component connection interface

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

Text: tone down the rainbow text color scheme

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

Rename "query info" to "query" everywhere, and "action" to "object"

A "query" here is a request for a specific named object using or not
parameters. This is analogous to a REST (HTTP) GET stateless request:

    GET /path/to/object?param1=value1&param2=value2

Also expect the `metadata-info` object in the ctf.fs query method
instead of the `get-metadata-info` action.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

text: mask some internal fields

Some fields from the stream packet context are not really useful to the
end user of the text output, so we mask them by default. They can be
displayed using the -v/--verbose flag. The masked fields are the same as
in previous version:
 - timestamp_begin
 - timestamp_end
 - events_discarded
 - content_size
 - packet_size
 - packet_seq_num

Signed-off-by: Julien Desfossez <jdesfossez@efficios.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

Add the verbose parameter to the legacy text options

Signed-off-by: Julien Desfossez <jdesfossez@efficios.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

babeltrace(1): support -o metadata legacy option

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

ctf.fs source: add `get-metadata-info` query info action

The `get-metadata-info` query info action of the ctf.fs source returns,
if successful, the (possibly decoded) metadata string and if the
metadata file is packetized or not. It only needs the `path` parameter
which is the trace directory path (non-recursive).

You can test it with the query-info command:

    babeltrace query-info --source ctf.fs get-metadata-info
                          -p 'path="/path/to/trace"'

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

babeltrace(1): print value with colors

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

babeltrace(1): add the query-info command

The new query-info command is the interface for the query info component
class API:

    babeltrace query-info --sink plugin.sink get-something
       --params meow=mix,zoom=18,consider-this=yes

The action is mandatory, as well as exactly one --source/--filter/--sink
option with the plugin and component class names to query info from. If
--params is not omitted, the query info method receives bt_value_null.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

babeltrace-cfg: put comp. class type within struct bt_config_component

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

bt2: test query info API

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

bt2: add support for the "query info" API

Any user-defined component class can now define a _query_info() static
method which accepts an action name and parameters (value object, or
None) and returns a bt2.create_value()-compatible object:

    class MySink(bt2.UserSinkComponent):
        def _consume(self):
            pass

        @staticmethod
        def _query_info(action, params):
            if action == 'get-stuff':
                return {
                    'stuff': get_stuff(),
                    'id': get_id()
                }
            elif action == 'get-thing':
                return the_thing()

This static method can raise any exception: the caller of
bt_component_class_query_info() gets NULL.

On the Python side, either with a user-defined component class or with
a component class wrapper:

    results = comp_class.query_info('get-stuff', {'name': 'wrerzvr'})

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

bt2: raise when bt2.create_plugin_from_name() finds nothing

Returning None from this function when there's no plugin is Pythonically
weird:

    plugin = bt2.create_plugin_from_name()
    print(plugin.name)

The execution should not reach print() here when the plugin is not
found.

Raise the new bt2.NoSuchPluginError exception instead.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

Add query info API tests

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

SO plugin API: add comp. class query info method macro and use it

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

Add bt_component_class_query_info() API

When you create a component class, you can set an optional "query info"
class method with bt_component_class_sink_set_query_info_method().

A "query info" class method is a method which accepts an action name
and custom parameters and returns custom results. It can be used for
component class-specific requests such as getting the beginning and end
timestamps of a trace, its total size, and other statistics. On some
real-time source component class, it can be used to get a list of
endpoints to which to connect.

You can use bt_component_class_query_info() to query a component class.
The action name and parameters are mandatory, although you can use
bt_value_null for the parameters.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

babeltrace(1): handle legacy -o dummy option

Legacy -o dummy option instantiates a utils.dummy sink component.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

Add utils.dummy component class, move plugins/trimmer to plugins/utils

This patch adds a plugins/utils directory where the utils plugin sources
are. plugins/trimmer is moved to this new directory because the trimmer
component class is part of the utils plugin.

Also in the utils plugin is the dummy sink component class. This sink
does absolutely nothing with its notifications. It is the equivalent of
the BT 1.x dummy format. At consume time, it gets one notification per
input notification iterator and returns
BT_NOTIFICATION_ITERATOR_STATUS_END when all the iterators are at the
end.

The legacy `-o dummy` option is not handled specifically in this commit.
You can use the dummy sink as usual:

    babeltrace /path/to/trace -o utils.dummy

The dummy component class ignores its initialization parameters.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

text plugin: add color support

This patch adds terminal color support to the text plugin.

The text component class accepts a new initialization parameter `color`
which you can set to one of the following strings:

never:
  Never output color codes.

auto:
  Output color codes if the standard output is connected to a
  color-capable terminal and if the file stream to use is the standard
  output.

always:
  Always output color codes. This is useful to print colors even if the
  standard output is not connected to a terminal, for example:

      babeltrace /path/to/trace -o text.text -p color=always | less -R

The semantic of this parameter is the same as ls(1)'s and grep(1)'s
--color option.

The chosen color scheme is open to debate. In an ideal world, it should
be configurable by the component parameters, or read $LS_COLORS.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

babeltrace(1): add --connect option and connection management

This patch adds the --connect option to connect component instances
by name (and optional port name):

    --connect SRC[SRCPORT]:DST[DSTPORT]

Example:

    babeltrace convert --source a.a --name A1 --source a.a --name A2
                       --sink b.b --name B
                       --connect A1.port:B
                       --connect A2.port:B.other-port

The code in babeltrace-cfg-connect.c validates that:

1. All the endpoint specified in connection arguments exist.

2. All connections are in the correct direction (source to filter,
   source to sink, filter to filter, filter to sink).

3. SRC and DST are not the same above.

4. All component instances are connected (no orphan component).

5. There's no duplicate connection.

There's a remaining validation to be done: ensure that there's no cycle
in the graph created by those connections.

If no --connect options are specified, babeltrace-cfg-connect.c connects
the component instances automatically:

1. It gives a unique name to unnamed component instances. The automatic
   name is TYPE-PLUGIN.COMPCLS.INDEX, where:

   TYPE:
     `source`, `filter`, or `sink`

   PLUGIN:
     Plugin name

   COMPCLS:
     Component class name

   INDEX:
     Automatic index to avoid collisions

2. It creates a multiplexer filter component configuration
   (`utils.mux`).

3. It connects the default ports of all the configured sources to the
   default port of this multiplexer filter.

4. It connects this multiplexer filter to the default ports of all the
   configured sinks.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

babeltrace convert: add --name option

The --name option sets the name of the current (latest) component
instance, e.g.:

    babeltrace convert --source=abc.xzy --name=my-component ...

This can be useful to locate specific instances in the conversion graph,
in particular in case of error.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

babeltrace(1): add help command

The new `help` command shows all the information of a specific plugin
or of a specific component class.

The syntax to get help for a specific plugin is:

    babeltrace help PLUGIN

and for a specific component class:

    babeltrace help (--source | --filter | --sink) PLUGIN.COMPCLS

The full help of the component class (bt_component_class_get_help())
is printed when available.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

babeltrace-cfg.c: improve error messages

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

Make babeltrace(1)'s CLI Git-like and implement the list-plugins command

This patch adds a command concept to the babeltrace(1) program, so that
the usage becomes:

    babeltrace [GENERAL OPTIONS] [COMMAND] [COMMAND OPTIONS]

The idea is to support multiple actions performed by the same program
without having to deal with a single command-line option parsing phase.

The default command is `convert`: it builds a trace conversion graph and
runs it. Therefore the current behaviour without a command name remains
the same.

The general command-line options, which can apply to all commands, are:

    -d, --debug        Enable debug mode
    -h  --help         Show general help and quit
        --help-legacy  Show Babeltrace 1.x legacy help and quit
    -v, --verbose      Enable verbose output
    -V, --version      Show version and quit

You can get the usage of a specific command with:

    babeltrace COMMAND --help

Because there is a default command, the parsing of the general options
is done manually to catch the first unknown option OR positional
argument. If an unknown option is found, all the arguments are given
back to the convert command. This is why the convert command also
parses --verbose, for example, because of this situation:

    babeltrace --debug --sink=my.sink --verbose

Here, the general options parsing stops at --sink because it's unknown,
and no explicit command name was found so far, so everything starting
with --debug is given to the convert command.

I also implemented the `list-plugins` command which lists plugins, their
component classes, and their properties:

    babeltrace list-plugins

You can still specify a plugin path or use the BABELTRACE_PLUGIN_PATH
environment variable with this command:

    babeltrace list-plugins --plugin-path=/path/to/other/plugins

I added color support in libbabeltrace-common and used it in the
`list-plugins` command. Color codes are only printed when color support
is detected, that is, when the standard output is connected to a
color-compatible terminal.

I also improved the way bt_value objects are printed with print_value()
in babeltrace.c to make it look more YAML-ish. This is easier on the
eyes.

This patch introduces a backward compatibility break in the very
specific scenario where an explicit command name is used and a directory
in the CWD exists with this name:

    babeltrace list-plugins

If `list-plugins` is a directory in the CWD, the legacy behaviour is to
recursively find CTF traces in it. With this patch, plugins are listed.
However a message is printed at the end of the command in this case:

    NOTE: The `list-plugins` command was executed. If you meant to
    convert a trace located in the local `list-plugins` directory,
    please use:

        babeltrace convert list-plugins [OPTIONS]

In other words, `babeltrace convert` (with 2.x) is a drop-in replacement
of `babeltrace` (with 1.x).

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>