[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

#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_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.
 */
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);


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