X-Git-Url: https://git.lttng.org/?p=lttng-tools.git;a=blobdiff_plain;f=include%2Flttng%2Fchannel.h;fp=include%2Flttng%2Fchannel.h;h=a6a6f04fcb185cec5b412ea31401897aef84634b;hp=3d175b8a4b7312fcc94349a740d2cc81831b486a;hb=048f01efd5931e364cc777d47c284c3f7d7d6ed6;hpb=78f5b22de60c114c5c83410015a08bdd212edc0b diff --git a/include/lttng/channel.h b/include/lttng/channel.h index 3d175b8a4..a6a6f04fc 100644 --- a/include/lttng/channel.h +++ b/include/lttng/channel.h @@ -24,18 +24,139 @@ extern "C" { * The structures should be initialized to zero before use. */ #define LTTNG_CHANNEL_ATTR_PADDING1 LTTNG_SYMBOL_NAME_LEN + 12 + +/*! +@brief + Attributes of a \link #lttng_channel channel summary\endlink. + +@ingroup api_channel + +The lttng_channel::attr member is an instance of such a structure. + +lttng_channel_set_default_attr() sets the members of such a structure +to their default values given a specific \lt_obj_domain summary. + +\anchor api-channel-valid-attr-struct A \em valid #lttng_channel_attr +structure satisfies the following constraints: + + + + + + +
Member + Constraints +
lttng_channel_attr::overwrite + 0, 1, or -1 +
lttng_channel_attr::subbuf_size + + - Greater than 0 + - Power of two +
lttng_channel_attr::num_subbuf + + - Greater than 0 + - Power of two +
+*/ struct lttng_channel_attr { + /*! + @brief + \ref api-channel-er-loss-mode "Event record loss mode". + + One of: + +
+
0 +
+ The \ref api-channel-er-loss-mode "event record loss mode" + of the channel is + \ref api-channel-discard-mode "discard". + +
1 +
+ The event record loss mode of the channel is + \ref api-channel-overwrite-mode "overwrite". + +
-1 +
+ The event record loss mode of the channel is the default + value of its \lt_obj_session: + +
+
\ref api-session-snapshot-mode "Snapshot mode" +
Overwrite mode + +
Other modes +
Discard mode +
+
+ */ int overwrite; /* -1: session default, 1: overwrite, 0: discard */ + + /*! + @brief + \ref api-channel-sub-buf-size-count "Sub-buffer size" + (bytes). + */ uint64_t subbuf_size; /* bytes, power of 2 */ + + /*! + @brief + \ref api-channel-sub-buf-size-count "Sub-buffer count". + */ uint64_t num_subbuf; /* power of 2 */ + + /*! + @brief + \ref api-channel-switch-timer "Switch timer period" (µs), + if applicable. + + Only available if the \lt_obj_session which + owns this channel is \em not in + \ref api-session-live-mode "live mode". + */ unsigned int switch_timer_interval; /* usec */ + + /// \ref api-channel-read-timer "Read timer period" (µs). unsigned int read_timer_interval; /* usec */ + + /// Output type (Linux kernel channel). enum lttng_event_output output; /* splice, mmap */ + /* LTTng 2.1 padding limit */ + + /*! + @brief + \ref api-channel-max-trace-file-size-count "Maximum trace file size" + (bytes), or 0 for unlimited. + */ uint64_t tracefile_size; /* bytes */ + + /*! + @brief + \ref api-channel-max-trace-file-size-count "Maximum trace file count", + or 0 for unlimited. + */ uint64_t tracefile_count; /* number of tracefiles */ + /* LTTng 2.3 padding limit */ + + /*! + @brief + \ref api-channel-live-timer "Live timer period" (µs), if + applicable. + + You may \em not set this member: use the + \lt_p{live_timer_period} parameter of + lttng_session_descriptor_live_network_create() when you create + the descriptor of a \ref api-session-live-mode "live" recording + session to contain the channel to create. + + Only available if the \lt_obj_session which + owns this channel is in \ref api-session-live-mode "live mode". + */ unsigned int live_timer_interval; /* usec */ + /* LTTng 2.7 padding limit */ uint32_t align_to_64; union { @@ -52,88 +173,508 @@ struct lttng_channel_attr { * The structures should be initialized to zero before use. */ #define LTTNG_CHANNEL_PADDING1 16 + +/*! +@brief + \lt_obj_c_channel summary. + +@ingroup api_channel + +The purpose of such a structure is to provide information about a +channel itself, but not about its \lt_obj_rers +(use lttng_list_events() for this). + +lttng_list_channels() sets a pointer to an array of all the +channel summaries of a given \lt_obj_session and \lt_obj_domain. + +Most properties are part of the lttng_channel::attr member, but the +following ones have their own dedicated accessors: + +
+
\ref api-channel-monitor-timer "Monitor timer" period +
+ - lttng_channel_get_monitor_timer_interval() + - lttng_channel_set_monitor_timer_interval() + +
\ref api-channel-blocking-timeout "Blocking timeout" +
+ - lttng_channel_get_blocking_timeout() + - lttng_channel_set_blocking_timeout() +
+ +Create a channel summary with lttng_channel_create(). + +Destroy a channel summary with lttng_channel_destroy(). +*/ struct lttng_channel { + /// Name. char name[LTTNG_SYMBOL_NAME_LEN]; + + /*! + @brief + 1 if this \lt_obj_channel is enabled, or 0 otherwise. + + @sa lttng_enable_channel() -- + Creates or enables a channel. + @sa lttng_disable_channel() -- + Disables a channel. + */ uint32_t enabled; + + /// Other properties. struct lttng_channel_attr attr; char padding[LTTNG_CHANNEL_PADDING1]; }; -/* - */ +/*! +@brief + Creates and returns a \lt_obj_channel summary, + setting the members of its lttng_channel::attr member to default + values according to the \lt_obj_domain summary \lt_p{domain}. + +@ingroup api_channel + +This function internally calls + +@code +lttng_channel_set_default_attr(domain, &channel->attr); +@endcode + +where \c channel is the returned channel summary. + +After you create a channel summary with this function, you can modify +its \ref api-channel-channel-props "properties" and call +lttng_enable_channel() to create and enable a channel. + +@param[in] domain + Tracing domain summary to consider to set the members of the + lttng_channel::attr member of the returned structure to default + values. + +@returns + @parblock + New channel summary. + + Destroy the returned channel summary with lttng_channel_destroy(). + @endparblock + +@lt_pre_not_null{domain} + +@sa lttng_channel_destroy() -- + Destroys a channel summary. +*/ LTTNG_EXPORT extern struct lttng_channel *lttng_channel_create(struct lttng_domain *domain); -/* - */ +/*! +@brief + Destroys the \lt_obj_channel summary \lt_p{channel}. + +@ingroup api_channel + +@note + This function doesn't destroy the \lt_obj_channel + which \lt_p{channel} summarizes: the only way to destroy a channel + is to \link lttng_destroy_session_ext() destroy its recording + session\endlink. + +@param[in] channel + @parblock + Channel summary to destroy. + + May be \c NULL. + @endparblock +*/ LTTNG_EXPORT extern void lttng_channel_destroy(struct lttng_channel *channel); -/* - * List the channel(s) of a session. - * - * The handle CAN NOT be NULL. - * - * Return the size (number of entries) of the "lttng_channel" array. Caller - * must free channels. On error, a negative LTTng error code is returned. - */ +/*! +@brief + Sets \lt_p{*channels} to the summaries of the + \lt_obj_channels of the recording session handle \lt_p{handle}. + +@ingroup api_session + +@param[in] handle + Recording session handle which contains the name of the recording + session and the summary of the \lt_obj_domain which own the channels + of which to get the summaries. +@param[out] channels + @parblock + On success, this function sets \lt_p{*channels} to + the summaries of the channels. + + Free \lt_p{*channels} with free(). + @endparblock + +@returns + The number of items in \lt_p{*channels} on success, or a \em + negative #lttng_error_code enumerator otherwise. + +@lt_pre_conn +@lt_pre_not_null{handle} +@lt_pre_valid_c_str{handle->session_name} +@lt_pre_sess_exists{handle->session_name} +@pre + \lt_p{handle->domain} is valid as per the documentation of + #lttng_domain. +@lt_pre_not_null{channels} +*/ LTTNG_EXPORT extern int lttng_list_channels(struct lttng_handle *handle, struct lttng_channel **channels); -/* - * Create or enable a channel. - * - * The chan and handle params can not be NULL. - * - * Return 0 on success else a negative LTTng error code. - */ +/*! +@brief + Creates or enables a \lt_obj_channel summarized by \lt_p{channel} + within the recording session handle \lt_p{handle}. + +@ingroup api_channel + +This function, depending on \lt_p{channel->name}: + +
+
+ \lt_p{channel->name} names an existing + channel within the \lt_obj_session and + \lt_obj_domain of \lt_p{handle} +
+ Enables the existing channel. + + In this case, this function only uses \lt_p{channel->name}, ignoring + all the other properties of \lt_p{channel}. + +
Otherwise +
+ Creates and enables a new channel, considering all the properties of + \lt_p{channel}. +
+ +@param[in] handle + Recording session handle which contains the name of the + recording session and the summary of the \lt_obj_domain which own + the channel to create or enable. +@param[in] channel + Summary of the channel to create or enable. + +@returns + 0 on success, or a \em negative #lttng_error_code enumerator + otherwise. + +@lt_pre_conn +@lt_pre_not_null{handle} +@lt_pre_valid_c_str{handle->session_name} +@lt_pre_sess_exists{handle->session_name} +@pre + \lt_p{handle->domain} is valid as per the documentation of + #lttng_domain. +@lt_pre_not_null{channel} +@pre + If this function must create a new channel, then + \lt_p{channel->attr} is \ref api-channel-valid-attr-struct "valid". +@pre + If this function must create a new channel, then + \lt_p{handle->session_name} names a + \lt_obj_session which never became + \link lttng_session::enabled active\endlink (started) since its + creation. +@pre + If this function must create a new channel, then + all the existing channels of \lt_p{handle} have the same + \ref api-channel-buf-scheme "buffering scheme". + +@sa lttng_disable_channel() -- + Disables a channel. +*/ LTTNG_EXPORT extern int lttng_enable_channel(struct lttng_handle *handle, - struct lttng_channel *chan); + struct lttng_channel *channel); -/* - * Disable channel. - * - * Name and handle CAN NOT be NULL. - * - * Return 0 on success else a negative LTTng error code. - */ -LTTNG_EXPORT extern int lttng_disable_channel(struct lttng_handle *handle, const char *name); +/*! +@brief + Disables the \lt_obj_channel named \lt_p{channel_name} within the + recording session handle \lt_p{handle}. -/* - * Set the default channel attributes for a specific domain and an allocated - * lttng_channel_attr pointer. - * - * If one or both arguments are NULL, nothing happens. - */ +@ingroup api_channel + +@param[in] handle + Recording session handle which contains the name of the + recording session and the summary of the \lt_obj_domain which own + the channel to disable. +@param[in] channel_name + Name of the channel to disable within \lt_p{handle}. + +@returns + 0 on success, or a \em negative #lttng_error_code enumerator + otherwise. + +@lt_pre_conn +@lt_pre_not_null{handle} +@lt_pre_valid_c_str{handle->session_name} +@lt_pre_sess_exists{handle->session_name} +@pre + \lt_p{handle->domain} is valid as per the documentation of + #lttng_domain. +@lt_pre_not_null{channel_name} +@pre + \lt_p{channel_name} names an existing channel within the recording + session and tracing domain of \lt_p{handle}. + +@sa lttng_enable_channel() -- + Creates or enables a channel. +*/ +LTTNG_EXPORT extern int lttng_disable_channel(struct lttng_handle *handle, + const char *channel_name); + +/*! +@brief + Sets the members of \lt_p{attr} to their default values considering + the \lt_obj_domain summary \lt_p{domain}. + +@ingroup api_channel + +Use this function on an lttng_channel::attr member. + +@param[in] domain + Tracing domain summary to consider to set the members of \lt_p{attr} + to their default values. +@param[in] attr + Structure of which to set the members to their default values. + +@lt_pre_not_null{domain} +@lt_pre_not_null{attr} +*/ LTTNG_EXPORT extern void lttng_channel_set_default_attr(struct lttng_domain *domain, struct lttng_channel_attr *attr); -/* - * Get the discarded event count of a specific LTTng channel. - * - * Returns 0 on success, or a negative LTTng error code on error. - */ -LTTNG_EXPORT extern int lttng_channel_get_discarded_event_count(struct lttng_channel *chan, - uint64_t *discarded_events); +/*! +@brief + Sets \lt_p{*count} to the number of discarded event + records of the \lt_obj_channel summarized by \lt_p{channel}. -/* - * Get the lost packet count of a specific LTTng channel. - * - * Returns 0 on success, or a negative LTTng error code on error. - */ -LTTNG_EXPORT extern int lttng_channel_get_lost_packet_count(struct lttng_channel *chan, - uint64_t *lost_packets); +@ingroup api_channel + +In \ref api-channel-discard-mode "discard mode", LTTng discards an event +record when there's no sub-buffer left to write it. + +lttng_list_channels() sets a pointer to an array of all the +channel summaries of a given \lt_obj_session and \lt_obj_domain. + +@param[in] channel + Summary of the channel of which to get the number of discarded + event records. +@param[out] count + On success, this function sets \lt_p{*count} to + the number of discarded event records of the channel summarized + by \lt_p{channel}. + +@returns + 0 on success, or a \em negative #lttng_error_code enumerator + otherwise. + +@lt_pre_not_null{channel} +@pre + You obtained \lt_p{channel} with lttng_list_channels(). +@pre + The lttng_channel_attr::overwrite member of \lt_p{channel->attr} + is 0. +@lt_pre_not_null{count} + +@sa lttng_channel_get_lost_packet_count() -- + Returns the number of discarded packets (sub-buffers) of a channel. +*/ +LTTNG_EXPORT extern int lttng_channel_get_discarded_event_count(struct lttng_channel *channel, + uint64_t *count); + +/*! +@brief + Sets \lt_p{*count} to the number of discarded packets (sub-buffers) + of the \lt_obj_channel summarized by \lt_p{channel}. + +@ingroup api_channel + +In \ref api-channel-overwrite-mode "overwrite mode", LTTng discards a +whole sub-buffer when there's no sub-buffer left to record an event. + +lttng_list_channels() sets a pointer to an array of all the +channel summaries of a given \lt_obj_session and \lt_obj_domain. + +@param[in] channel + Summary of the channel of which to get the number of discarded + packets. +@param[out] count + On success, this function sets \lt_p{*count} to + the number of discarded packets of the channel summarized + by \lt_p{channel}. + +@returns + 0 on success, or a \em negative #lttng_error_code enumerator + otherwise. + +@lt_pre_not_null{channel} +@pre + You obtained \lt_p{channel} with lttng_list_channels(). +@pre + The lttng_channel_attr::overwrite member of \lt_p{channel->attr} + is 1. +@lt_pre_not_null{count} + +@sa lttng_channel_get_discarded_event_count() -- + Returns the number of discarded event records of a channel. +*/ +LTTNG_EXPORT extern int lttng_channel_get_lost_packet_count(struct lttng_channel *channel, + uint64_t *count); + +/*! +@brief + Sets \lt_p{period} to the + \ref api-channel-monitor-timer "monitor timer" period (µs) + property of the \lt_obj_channel summary \lt_p{channel}. + +@ingroup api_channel + +@param[in] channel + Summary of the channel of which to get the monitor timer period. +@param[out] period + On success, this function sets \lt_p{*period} to + the monitor timer period (µs) property of \lt_p{channel}. + +@returns + 0 on success, or a \em negative #lttng_error_code enumerator + otherwise. + +@lt_pre_not_null{channel} +@lt_pre_not_null{period} + +@sa lttng_channel_set_monitor_timer_interval() -- + Sets the monitor timer period property of a channel summary. +*/ +LTTNG_EXPORT extern int lttng_channel_get_monitor_timer_interval(struct lttng_channel *channel, + uint64_t *period); + +/*! +@brief + Sets the \ref api-channel-monitor-timer "monitor timer" period + property of the channel summary \lt_p{channel} to + \lt_p{period} Âµs. + +@ingroup api_channel + +@param[in] channel + Channel summary of which to set the monitor timer period + to \lt_p{period} Âµs. +@param[in] period + Monitor timer period property to set. + +@returns + 0 on success, or a \em negative #lttng_error_code enumerator + otherwise. + +@lt_pre_not_null{channel} +@pre + \lt_p{period} â‰¥ 1 + +@sa lttng_channel_get_monitor_timer_interval() -- + Returns the monitor timer period property of a channel summary. +*/ +LTTNG_EXPORT extern int lttng_channel_set_monitor_timer_interval(struct lttng_channel *channel, + uint64_t period); + +/*! +@brief + Sets \lt_p{timeout} to the + \ref api-channel-blocking-timeout "blocking timeout" + property of the \lt_obj_channel summary \lt_p{channel}. + +@ingroup api_channel + +This property only applies to \link #LTTNG_DOMAIN_UST user space\endlink +channels. + +@param[in] channel + Summary of the channel of which to get the blocking timeout. +@param[out] timeout + @parblock + On success, this function sets \lt_p{*timeout} to + one of: + +
+
-1 +
+ The blocking timeout of \lt_p{channel} is infinite. + +
0 +
+ Blocking is disabled for \lt_p{channel}. + +
Otherwise +
+ The blocking timeout of \lt_p{channel} is + \lt_p{*timeout} Âµs. +
+ @endparblock + +@returns + 0 on success, or a \em negative #lttng_error_code enumerator + otherwise. + +@lt_pre_not_null{channel} +@pre + The \lt_obj_domain type of \lt_p{channel} is #LTTNG_DOMAIN_UST. +@lt_pre_not_null{timeout} + +@sa lttng_channel_set_blocking_timeout() -- + Sets the blocking timeout property of a channel summary. +*/ +LTTNG_EXPORT extern int lttng_channel_get_blocking_timeout(struct lttng_channel *channel, + int64_t *timeout); + +/*! +@brief + Sets the \ref api-channel-blocking-timeout "blocking timeout" + property of the channel summary \lt_p{channel} to + \lt_p{timeout}. + +@ingroup api_channel + +This property only applies to \link #LTTNG_DOMAIN_UST user space\endlink +channels. + +@param[in] channel + Channel summary of which to set the blocking timeout + to \lt_p{timeout}. +@param[in] timeout + @parblock + One of: + +
+
-1 +
+ The blocking timeout of \lt_p{channel} is infinite. + +
0 +
+ Blocking is disabled for \lt_p{channel}. -LTTNG_EXPORT extern int lttng_channel_get_monitor_timer_interval(struct lttng_channel *chan, - uint64_t *monitor_timer_interval); +
Otherwise +
+ The blocking timeout of \lt_p{channel} is + \lt_p{timeout} Âµs. +
+ @endparblock -LTTNG_EXPORT extern int lttng_channel_set_monitor_timer_interval(struct lttng_channel *chan, - uint64_t monitor_timer_interval); +@returns + 0 on success, or a \em negative #lttng_error_code enumerator + otherwise. -LTTNG_EXPORT extern int lttng_channel_get_blocking_timeout(struct lttng_channel *chan, - int64_t *blocking_timeout); +@lt_pre_not_null{channel} +@pre + The \lt_obj_domain type of \lt_p{channel} is #LTTNG_DOMAIN_UST. +@pre + \lt_p{timeout} â‰¥ -1 -LTTNG_EXPORT extern int lttng_channel_set_blocking_timeout(struct lttng_channel *chan, - int64_t blocking_timeout); +@sa lttng_channel_get_blocking_timeout() -- + Returns the blocking timeout property of a channel summary. +*/ +LTTNG_EXPORT extern int lttng_channel_set_blocking_timeout(struct lttng_channel *channel, + int64_t timeout); #ifdef __cplusplus }