[lttng-tools.git] / include / lttng / userspace-probe.h

/*
 * Copyright (C) 2017 Jérémie Galarneau <jeremie.galarneau@efficios.com>
 *
 * SPDX-License-Identifier: LGPL-2.1-only
 *
 */

#ifndef LTTNG_USERSPACE_PROBE_H
#define LTTNG_USERSPACE_PROBE_H

#include <lttng/lttng-export.h>

#ifdef __cplusplus
extern "C" {
#endif

/*
 * Userspace probe lookup methods specifies how the userspace probe location
 * specified by the user should be interpreted.
 */
struct lttng_userspace_probe_location_lookup_method;

enum lttng_userspace_probe_location_lookup_method_type {
	LTTNG_USERSPACE_PROBE_LOCATION_LOOKUP_METHOD_TYPE_UNKNOWN	    = -1,
	LTTNG_USERSPACE_PROBE_LOCATION_LOOKUP_METHOD_TYPE_FUNCTION_DEFAULT  = 0,
	LTTNG_USERSPACE_PROBE_LOCATION_LOOKUP_METHOD_TYPE_FUNCTION_ELF	    = 1,
	LTTNG_USERSPACE_PROBE_LOCATION_LOOKUP_METHOD_TYPE_TRACEPOINT_SDT    = 2,
};

/*
 * Get the type of a lookup method.
 */
LTTNG_EXPORT extern enum lttng_userspace_probe_location_lookup_method_type
lttng_userspace_probe_location_lookup_method_get_type(
		const struct lttng_userspace_probe_location_lookup_method *lookup_method);

/*
 * Destroy a lookup method.
 */
LTTNG_EXPORT extern void lttng_userspace_probe_location_lookup_method_destroy(
		struct lttng_userspace_probe_location_lookup_method *lookup_method);

/*
 * Create a tracepoint ELF function lookup method struct.
 * Return NULL on failure.
 */
LTTNG_EXPORT extern struct lttng_userspace_probe_location_lookup_method *
lttng_userspace_probe_location_lookup_method_function_elf_create(void);

/*
 * Create a tracepoint SDT tracepoint lookup method struct.
 * Return NULL on failure.
 */
LTTNG_EXPORT extern struct lttng_userspace_probe_location_lookup_method *
lttng_userspace_probe_location_lookup_method_tracepoint_sdt_create(void);


/*
 * Contains all the information needed to compute the instrumentation point in
 * the binary. It is used in conjonction with a lookup method.
 */
struct lttng_userspace_probe_location;

enum lttng_userspace_probe_location_status {
	LTTNG_USERSPACE_PROBE_LOCATION_STATUS_OK 	= 0,
	/* Invalid parameters provided. */
	LTTNG_USERSPACE_PROBE_LOCATION_STATUS_INVALID 	= -1,
};

enum lttng_userspace_probe_location_type {
	LTTNG_USERSPACE_PROBE_LOCATION_TYPE_UNKNOWN	= -1,
	/* Function. */
	LTTNG_USERSPACE_PROBE_LOCATION_TYPE_FUNCTION	= 0,
	/* SDT probe's callsites. */
	LTTNG_USERSPACE_PROBE_LOCATION_TYPE_TRACEPOINT	= 1,
};

/*
 * Get the type of the userspace probe location.
 */
LTTNG_EXPORT extern enum lttng_userspace_probe_location_type
lttng_userspace_probe_location_get_type(
		const struct lttng_userspace_probe_location *location);

/*
 * Destroy the userspace probe location.
 */
LTTNG_EXPORT extern void lttng_userspace_probe_location_destroy(
		struct lttng_userspace_probe_location *location);


enum lttng_userspace_probe_location_function_instrumentation_type {
	LTTNG_USERSPACE_PROBE_LOCATION_FUNCTION_INSTRUMENTATION_TYPE_UNKNOWN = -1,
	/* Only instrument the function's entry. */
	LTTNG_USERSPACE_PROBE_LOCATION_FUNCTION_INSTRUMENTATION_TYPE_ENTRY = 0,
};

/*
 * Create a probe location of the function type.
 * Receives the target binary file path and function to instrument.
 * On failure, NULL is returned.
 *
 * The ownership of the lookup method is transferred to the created probe
 * location.
 */
LTTNG_EXPORT extern struct lttng_userspace_probe_location *
lttng_userspace_probe_location_function_create(const char *binary_path,
		const char *function_name,
		struct lttng_userspace_probe_location_lookup_method *lookup_method);

/*
 * Get the target binary path of the probe location of the function type.
 */
LTTNG_EXPORT extern const char *lttng_userspace_probe_location_function_get_binary_path(
		const struct lttng_userspace_probe_location *location);

/*
 * Get the target function type of the probe location of the function type.
 */
LTTNG_EXPORT extern const char *lttng_userspace_probe_location_function_get_function_name(
		const struct lttng_userspace_probe_location *location);

/*
 * Get the FD to the target binary file to the probe location of the function
 * type. The FD is only valid for the duration of the lifetime of `location`.
 */
LTTNG_EXPORT extern int lttng_userspace_probe_location_function_get_binary_fd(
		const struct lttng_userspace_probe_location *location);

/*
 * Get the instrumentation type of the function probe location.
 */
LTTNG_EXPORT extern enum lttng_userspace_probe_location_function_instrumentation_type
lttng_userspace_probe_location_function_get_instrumentation_type(
		const struct lttng_userspace_probe_location *location);

/*
 * Get the instrumentation type of the function probe location.
 * Defaults to
 * LTTNG_USERSPACE_PROBE_LOCATION_FUNCTION_INSTRUMENTATION_TYPE_ENTRY.
 *
 * Returns LTTNG_USERSPACE_PROBE_LOCATION_STATUS_OK on success,
 * LTTNG_USERSPACE_PROBE_LOCATION_STATUS_INVALID if invalid parameters
 * are provided.
 */
LTTNG_EXPORT extern enum lttng_userspace_probe_location_status
lttng_userspace_probe_location_function_set_instrumentation_type(
		const struct lttng_userspace_probe_location *location,
		enum lttng_userspace_probe_location_function_instrumentation_type instrumentation_type);

/*
 * Get the lookup method of the given userspace probe location.
 * Returns NULL if the probe location type is unsupported.
 *
 * The ownership of the lookup method is NOT transferred to the caller.
 */
LTTNG_EXPORT extern const struct lttng_userspace_probe_location_lookup_method *
lttng_userspace_probe_location_get_lookup_method(
		const struct lttng_userspace_probe_location *location);

/*
 * Create a probe location of the tracepoint type.
 * Receives the target binary file path, probename and probe provider to
 * instrument.
 * On failure, NULL is returned.
 *
 * The ownership of the lookup method is transferred to the created probe
 * location.
 */
LTTNG_EXPORT extern struct lttng_userspace_probe_location *
lttng_userspace_probe_location_tracepoint_create(const char *binary_path,
		const char *probe_name, const char *provider_name,
		struct lttng_userspace_probe_location_lookup_method *lookup_method);

/*
 * Get the target binary path of the probe location of the tracepoint type.
 */
LTTNG_EXPORT extern const char *lttng_userspace_probe_location_tracepoint_get_binary_path(
		const struct lttng_userspace_probe_location *location);

/*
 * Get the target probe name of the probe location of the tracepoint type.
 */
LTTNG_EXPORT extern const char *lttng_userspace_probe_location_tracepoint_get_probe_name(
		const struct lttng_userspace_probe_location *location);

/*
 * Get the target probe provider name of the probe location of the tracepoint
 * type.
 */
LTTNG_EXPORT extern const char *lttng_userspace_probe_location_tracepoint_get_provider_name(
		const struct lttng_userspace_probe_location *location);

/*
 * Get the FD to the target binary file to the probe location of the tracepoint
 * type. The FD is only valid for the duration of the lifetime of `location`.
 */
LTTNG_EXPORT extern int lttng_userspace_probe_location_tracepoint_get_binary_fd(
		const struct lttng_userspace_probe_location *location);

#ifdef __cplusplus
}
#endif

#endif /* LTTNG_USERSPACE_PROBE_H */
Commit	Line	Data
	1	/*
	2	* Copyright (C) 2017 Jérémie Galarneau <jeremie.galarneau@efficios.com>
	3	*
	4	* SPDX-License-Identifier: LGPL-2.1-only
	5	*
	6	*/
	7
	8	#ifndef LTTNG_USERSPACE_PROBE_H
	9	#define LTTNG_USERSPACE_PROBE_H
	10
	11	#include <lttng/lttng-export.h>
	12
	13	#ifdef __cplusplus
	14	extern "C" {
	15	#endif
	16
	17	/*
	18	* Userspace probe lookup methods specifies how the userspace probe location
	19	* specified by the user should be interpreted.
	20	*/
	21	struct lttng_userspace_probe_location_lookup_method;
	22
	23	enum lttng_userspace_probe_location_lookup_method_type {
	24	LTTNG_USERSPACE_PROBE_LOCATION_LOOKUP_METHOD_TYPE_UNKNOWN = -1,
	25	LTTNG_USERSPACE_PROBE_LOCATION_LOOKUP_METHOD_TYPE_FUNCTION_DEFAULT = 0,
	26	LTTNG_USERSPACE_PROBE_LOCATION_LOOKUP_METHOD_TYPE_FUNCTION_ELF = 1,
	27	LTTNG_USERSPACE_PROBE_LOCATION_LOOKUP_METHOD_TYPE_TRACEPOINT_SDT = 2,
	28	};
	29
	30	/*
	31	* Get the type of a lookup method.
	32	*/
	33	LTTNG_EXPORT extern enum lttng_userspace_probe_location_lookup_method_type
	34	lttng_userspace_probe_location_lookup_method_get_type(
	35	const struct lttng_userspace_probe_location_lookup_method *lookup_method);
	36
	37	/*
	38	* Destroy a lookup method.
	39	*/
	40	LTTNG_EXPORT extern void lttng_userspace_probe_location_lookup_method_destroy(
	41	struct lttng_userspace_probe_location_lookup_method *lookup_method);
	42
	43	/*
	44	* Create a tracepoint ELF function lookup method struct.
	45	* Return NULL on failure.
	46	*/
	47	LTTNG_EXPORT extern struct lttng_userspace_probe_location_lookup_method *
	48	lttng_userspace_probe_location_lookup_method_function_elf_create(void);
	49
	50	/*
	51	* Create a tracepoint SDT tracepoint lookup method struct.
	52	* Return NULL on failure.
	53	*/
	54	LTTNG_EXPORT extern struct lttng_userspace_probe_location_lookup_method *
	55	lttng_userspace_probe_location_lookup_method_tracepoint_sdt_create(void);
	56
	57
	58	/*
	59	* Contains all the information needed to compute the instrumentation point in
	60	* the binary. It is used in conjonction with a lookup method.
	61	*/
	62	struct lttng_userspace_probe_location;
	63
	64	enum lttng_userspace_probe_location_status {
	65	LTTNG_USERSPACE_PROBE_LOCATION_STATUS_OK = 0,
	66	/* Invalid parameters provided. */
	67	LTTNG_USERSPACE_PROBE_LOCATION_STATUS_INVALID = -1,
	68	};
	69
	70	enum lttng_userspace_probe_location_type {
	71	LTTNG_USERSPACE_PROBE_LOCATION_TYPE_UNKNOWN = -1,
	72	/* Function. */
	73	LTTNG_USERSPACE_PROBE_LOCATION_TYPE_FUNCTION = 0,
	74	/* SDT probe's callsites. */
	75	LTTNG_USERSPACE_PROBE_LOCATION_TYPE_TRACEPOINT = 1,
	76	};
	77
	78	/*
	79	* Get the type of the userspace probe location.
	80	*/
	81	LTTNG_EXPORT extern enum lttng_userspace_probe_location_type
	82	lttng_userspace_probe_location_get_type(
	83	const struct lttng_userspace_probe_location *location);
	84
	85	/*
	86	* Destroy the userspace probe location.
	87	*/
	88	LTTNG_EXPORT extern void lttng_userspace_probe_location_destroy(
	89	struct lttng_userspace_probe_location *location);
	90
	91
	92	enum lttng_userspace_probe_location_function_instrumentation_type {
	93	LTTNG_USERSPACE_PROBE_LOCATION_FUNCTION_INSTRUMENTATION_TYPE_UNKNOWN = -1,
	94	/* Only instrument the function's entry. */
	95	LTTNG_USERSPACE_PROBE_LOCATION_FUNCTION_INSTRUMENTATION_TYPE_ENTRY = 0,
	96	};
	97
	98	/*
	99	* Create a probe location of the function type.
	100	* Receives the target binary file path and function to instrument.
	101	* On failure, NULL is returned.
	102	*
	103	* The ownership of the lookup method is transferred to the created probe
	104	* location.
	105	*/
	106	LTTNG_EXPORT extern struct lttng_userspace_probe_location *
	107	lttng_userspace_probe_location_function_create(const char *binary_path,
	108	const char *function_name,
	109	struct lttng_userspace_probe_location_lookup_method *lookup_method);
	110
	111	/*
	112	* Get the target binary path of the probe location of the function type.
	113	*/
	114	LTTNG_EXPORT extern const char *lttng_userspace_probe_location_function_get_binary_path(
	115	const struct lttng_userspace_probe_location *location);
	116
	117	/*
	118	* Get the target function type of the probe location of the function type.
	119	*/
	120	LTTNG_EXPORT extern const char *lttng_userspace_probe_location_function_get_function_name(
	121	const struct lttng_userspace_probe_location *location);
	122
	123	/*
	124	* Get the FD to the target binary file to the probe location of the function
	125	* type. The FD is only valid for the duration of the lifetime of `location`.
	126	*/
	127	LTTNG_EXPORT extern int lttng_userspace_probe_location_function_get_binary_fd(
	128	const struct lttng_userspace_probe_location *location);
	129
	130	/*
	131	* Get the instrumentation type of the function probe location.
	132	*/
	133	LTTNG_EXPORT extern enum lttng_userspace_probe_location_function_instrumentation_type
	134	lttng_userspace_probe_location_function_get_instrumentation_type(
	135	const struct lttng_userspace_probe_location *location);
	136
	137	/*
	138	* Get the instrumentation type of the function probe location.
	139	* Defaults to
	140	* LTTNG_USERSPACE_PROBE_LOCATION_FUNCTION_INSTRUMENTATION_TYPE_ENTRY.
	141	*
	142	* Returns LTTNG_USERSPACE_PROBE_LOCATION_STATUS_OK on success,
	143	* LTTNG_USERSPACE_PROBE_LOCATION_STATUS_INVALID if invalid parameters
	144	* are provided.
	145	*/
	146	LTTNG_EXPORT extern enum lttng_userspace_probe_location_status
	147	lttng_userspace_probe_location_function_set_instrumentation_type(
	148	const struct lttng_userspace_probe_location *location,
	149	enum lttng_userspace_probe_location_function_instrumentation_type instrumentation_type);
	150
	151	/*
	152	* Get the lookup method of the given userspace probe location.
	153	* Returns NULL if the probe location type is unsupported.
	154	*
	155	* The ownership of the lookup method is NOT transferred to the caller.
	156	*/
	157	LTTNG_EXPORT extern const struct lttng_userspace_probe_location_lookup_method *
	158	lttng_userspace_probe_location_get_lookup_method(
	159	const struct lttng_userspace_probe_location *location);
	160
	161	/*
	162	* Create a probe location of the tracepoint type.
	163	* Receives the target binary file path, probename and probe provider to
	164	* instrument.
	165	* On failure, NULL is returned.
	166	*
	167	* The ownership of the lookup method is transferred to the created probe
	168	* location.
	169	*/
	170	LTTNG_EXPORT extern struct lttng_userspace_probe_location *
	171	lttng_userspace_probe_location_tracepoint_create(const char *binary_path,
	172	const char probe_name, const char provider_name,
	173	struct lttng_userspace_probe_location_lookup_method *lookup_method);
	174
	175	/*
	176	* Get the target binary path of the probe location of the tracepoint type.
	177	*/
	178	LTTNG_EXPORT extern const char *lttng_userspace_probe_location_tracepoint_get_binary_path(
	179	const struct lttng_userspace_probe_location *location);
	180
	181	/*
	182	* Get the target probe name of the probe location of the tracepoint type.
	183	*/
	184	LTTNG_EXPORT extern const char *lttng_userspace_probe_location_tracepoint_get_probe_name(
	185	const struct lttng_userspace_probe_location *location);
	186
	187	/*
	188	* Get the target probe provider name of the probe location of the tracepoint
	189	* type.
	190	*/
	191	LTTNG_EXPORT extern const char *lttng_userspace_probe_location_tracepoint_get_provider_name(
	192	const struct lttng_userspace_probe_location *location);
	193
	194	/*
	195	* Get the FD to the target binary file to the probe location of the tracepoint
	196	* type. The FD is only valid for the duration of the lifetime of `location`.
	197	*/
	198	LTTNG_EXPORT extern int lttng_userspace_probe_location_tracepoint_get_binary_fd(
	199	const struct lttng_userspace_probe_location *location);
	200
	201	#ifdef __cplusplus
	202	}
	203	#endif
	204
	205	#endif /* LTTNG_USERSPACE_PROBE_H */