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

/*
 * Copyright (C) 2017 - Jérémie Galarneau <jeremie.galarneau@efficios.com>
 *
 * This library is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License, version 2.1 only,
 * as published by the Free Software Foundation.
 *
 * This library is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
 * for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this library; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
 */

#ifndef LTTNG_USERSPACE_PROBE_H
#define LTTNG_USERSPACE_PROBE_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.
 */
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.
 */
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.
 */
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.
 */
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_type {
	LTTNG_USERSPACE_PROBE_LOCATION_TYPE_UNKNOWN	= -1,
	/* Traces a function's entry and exit. */
	LTTNG_USERSPACE_PROBE_LOCATION_TYPE_FUNCTION	= 0,
	/* Trace a single point. */
	LTTNG_USERSPACE_PROBE_LOCATION_TYPE_TRACEPOINT	= 1,
};

/*
 * Get the type of the userspace probe location.
 */
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.
 */
extern void lttng_userspace_probe_location_destroy(
		struct lttng_userspace_probe_location *location);

/*
 * 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.
 */
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.
 */
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.
 */
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.
 */
extern int lttng_userspace_probe_location_function_get_binary_fd(
		const struct lttng_userspace_probe_location *location);

/*
 * 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.
 */
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.
 */
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.
 */
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.
 */
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.
 */
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.
 */
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	* This library is free software; you can redistribute it and/or modify it
	5	* under the terms of the GNU Lesser General Public License, version 2.1 only,
	6	* as published by the Free Software Foundation.
	7	*
	8	* This library is distributed in the hope that it will be useful, but WITHOUT
	9	* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
	10	* FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
	11	* for more details.
	12	*
	13	* You should have received a copy of the GNU Lesser General Public License
	14	* along with this library; if not, write to the Free Software Foundation,
	15	* Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
	16	*/
	17
	18	#ifndef LTTNG_USERSPACE_PROBE_H
	19	#define LTTNG_USERSPACE_PROBE_H
	20
	21	#ifdef __cplusplus
	22	extern "C" {
	23	#endif
	24
	25	/*
	26	* Userspace probe lookup methods specifies how the userspace probe location
	27	* specified by the user should be interpreted.
	28	*/
	29	struct lttng_userspace_probe_location_lookup_method;
	30
	31	enum lttng_userspace_probe_location_lookup_method_type {
	32	LTTNG_USERSPACE_PROBE_LOCATION_LOOKUP_METHOD_TYPE_UNKNOWN = -1,
	33	LTTNG_USERSPACE_PROBE_LOCATION_LOOKUP_METHOD_TYPE_FUNCTION_DEFAULT = 0,
	34	LTTNG_USERSPACE_PROBE_LOCATION_LOOKUP_METHOD_TYPE_FUNCTION_ELF = 1,
	35	LTTNG_USERSPACE_PROBE_LOCATION_LOOKUP_METHOD_TYPE_TRACEPOINT_SDT = 2,
	36	};
	37
	38	/*
	39	* Get the type of a lookup method.
	40	*/
	41	extern enum lttng_userspace_probe_location_lookup_method_type
	42	lttng_userspace_probe_location_lookup_method_get_type(
	43	const struct lttng_userspace_probe_location_lookup_method *lookup_method);
	44
	45	/*
	46	* Destroy a lookup method.
	47	*/
	48	extern void lttng_userspace_probe_location_lookup_method_destroy(
	49	struct lttng_userspace_probe_location_lookup_method *lookup_method);
	50
	51	/*
	52	* Create a tracepoint ELF function lookup method struct.
	53	* Return NULL on failure.
	54	*/
	55	extern struct lttng_userspace_probe_location_lookup_method *
	56	lttng_userspace_probe_location_lookup_method_function_elf_create(void);
	57
	58	/*
	59	* Create a tracepoint SDT tracepoint lookup method struct.
	60	* Return NULL on failure.
	61	*/
	62	extern struct lttng_userspace_probe_location_lookup_method *
	63	lttng_userspace_probe_location_lookup_method_tracepoint_sdt_create(void);
	64
	65
	66	/*
	67	* Contains all the information needed to compute the instrumentation point in
	68	* the binary. It is used in conjonction with a lookup method.
	69	*/
	70	struct lttng_userspace_probe_location;
	71
	72	enum lttng_userspace_probe_location_type {
	73	LTTNG_USERSPACE_PROBE_LOCATION_TYPE_UNKNOWN = -1,
	74	/* Traces a function's entry and exit. */
	75	LTTNG_USERSPACE_PROBE_LOCATION_TYPE_FUNCTION = 0,
	76	/* Trace a single point. */
	77	LTTNG_USERSPACE_PROBE_LOCATION_TYPE_TRACEPOINT = 1,
	78	};
	79
	80	/*
	81	* Get the type of the userspace probe location.
	82	*/
	83	extern enum lttng_userspace_probe_location_type
	84	lttng_userspace_probe_location_get_type(
	85	const struct lttng_userspace_probe_location *location);
	86
	87	/*
	88	* Destroy the userspace probe location.
	89	*/
	90	extern void lttng_userspace_probe_location_destroy(
	91	struct lttng_userspace_probe_location *location);
	92
	93	/*
	94	* Create a probe location of the function type.
	95	* Receives the target binary file path and function to instrument.
	96	* On failure, NULL is returned.
	97	*
	98	* The ownership of the lookup method is transferred to the created probe
	99	* location.
	100	*/
	101	extern struct lttng_userspace_probe_location *
	102	lttng_userspace_probe_location_function_create(const char *binary_path,
	103	const char *function_name,
	104	struct lttng_userspace_probe_location_lookup_method *lookup_method);
	105
	106	/*
	107	* Get the target binary path of the probe location of the function type.
	108	*/
	109	extern const char *lttng_userspace_probe_location_function_get_binary_path(
	110	const struct lttng_userspace_probe_location *location);
	111
	112	/*
	113	* Get the target function type of the probe location of the function type.
	114	*/
	115	extern const char *lttng_userspace_probe_location_function_get_function_name(
	116	const struct lttng_userspace_probe_location *location);
	117
	118	/*
	119	* Get the FD to the target binary file to the probe location of the function
	120	* type.
	121	*/
	122	extern int lttng_userspace_probe_location_function_get_binary_fd(
	123	const struct lttng_userspace_probe_location *location);
	124
	125	/*
	126	* Get the lookup method of the given userspace probe location.
	127	* Returns NULL if the probe location type is unsupported.
	128	*
	129	* The ownership of the lookup method is NOT transferred to the caller.
	130	*/
	131	extern const struct lttng_userspace_probe_location_lookup_method *
	132	lttng_userspace_probe_location_get_lookup_method(
	133	const struct lttng_userspace_probe_location *location);
	134
	135	/*
	136	* Create a probe location of the tracepoint type.
	137	* Receives the target binary file path, probename and probe provider to
	138	* instrument.
	139	* On failure, NULL is returned.
	140	*
	141	* The ownership of the lookup method is transferred to the created probe
	142	* location.
	143	*/
	144	extern struct lttng_userspace_probe_location *
	145	lttng_userspace_probe_location_tracepoint_create(const char *binary_path,
	146	const char probe_name, const char provider_name,
	147	struct lttng_userspace_probe_location_lookup_method *lookup_method);
	148
	149	/*
	150	* Get the target binary path of the probe location of the tracepoint type.
	151	*/
	152	extern const char *lttng_userspace_probe_location_tracepoint_get_binary_path(
	153	const struct lttng_userspace_probe_location *location);
	154
	155	/*
	156	* Get the target probe name of the probe location of the tracepoint type.
	157	*/
	158	extern const char *lttng_userspace_probe_location_tracepoint_get_probe_name(
	159	const struct lttng_userspace_probe_location *location);
	160
	161	/*
	162	* Get the target probe provider name of the probe location of the tracepoint
	163	* type.
	164	*/
	165	extern const char *lttng_userspace_probe_location_tracepoint_get_provider_name(
	166	const struct lttng_userspace_probe_location *location);
	167
	168	/*
	169	* Get the FD to the target binary file to the probe location of the tracepoint
	170	* type.
	171	*/
	172	extern int lttng_userspace_probe_location_tracepoint_get_binary_fd(
	173	const struct lttng_userspace_probe_location *location);
	174
	175	#ifdef __cplusplus
	176	}
	177	#endif
	178
	179	#endif /* LTTNG_USERSPACE_PROBE_H */