This patch implements the documentation of event_enable_write and event_enable_read in the form of testable function's expectations.
Signed-off-by: Gabriele Paoloni <[email protected]> --- Following the discussion in v1 (see [1]), v2 adds improvements with the "Context" specifications and the definition of the assumptions of use for the correct invocation of the documented functions. [1] https://lore.kernel.org/linux-trace-kernel/[email protected]/ --- kernel/trace/trace_events.c | 81 +++++++++++++++++++++++++++++++++++++ 1 file changed, 81 insertions(+) diff --git a/kernel/trace/trace_events.c b/kernel/trace/trace_events.c index 120531268abf..57284f540566 100644 --- a/kernel/trace/trace_events.c +++ b/kernel/trace/trace_events.c @@ -1771,6 +1771,52 @@ static void p_stop(struct seq_file *m, void *p) mutex_unlock(&event_mutex); } +/** + * event_enable_read - read from a trace event file to retrieve its status. + * @filp: file pointer associated with the target trace event; + * @ubuf: user space buffer where the event status is copied to; + * @cnt: number of bytes to be copied to the user space buffer; + * @ppos: the current position in the buffer. + * + * This is a way for user space executables to retrieve the status of a + * specific event + * + * Function's expectations: + * - This function shall lock the global event_mutex before performing any + * operation on the target event file and unlock it after all operations on + * the target event file have completed; + * - This function shall retrieve the status flags from the file associated + * with the target event; + * - This function shall format the string to report the event status to user + * space: + * - The first character of the string to be copied to user space shall be + * set to "1" if the enabled flag is set AND the soft_disabled flag is not + * set, else it shall be set to "0"; + * - The second character of the string to be copied to user space shall be + * set to "*" if either the soft_disabled flag or the soft_mode flag is + * set, else it shall be set to "\n"; + * - The third character of the string to be copied to user space shall b + * set to "\n" if either the soft_disabled flag or the soft_mode flag is + * set, else it shall be set to "0"; + * - Any other character in the string to be copied to user space shall be + * set to "0"; + * - This function shall invoke simple_read_from_buffer() to perform the copy + * of the kernel space string to ubuf. + * + * Assumptions of Use: + * - The caller shall pass cnt equal or greater than the length of the string + * to be copied to user space; + * - Any read operation on a file descriptor, unless it is the first operation + * following a trace event file open, shall be preceded by an lseek + * invocation to reposition the file offset to zero. + * + * Context: process context, locks and unlocks event_mutex. + * + * Return: the number of copied bytes on success, -ENODEV if the event file + * cannot be retrieved from the input filp, -EINVAL if cnt is less than the + * length of the string to be copied to ubuf, any error returned by + * simple_read_from_buffer + */ static ssize_t event_enable_read(struct file *filp, char __user *ubuf, size_t cnt, loff_t *ppos) @@ -1801,6 +1847,41 @@ event_enable_read(struct file *filp, char __user *ubuf, size_t cnt, return simple_read_from_buffer(ubuf, cnt, ppos, buf, strlen(buf)); } +/** + * event_enable_write - write to a trace event file to enable/disable it. + * @filp: file pointer associated with the target trace event; + * @ubuf: user space buffer where the enable/disable value is copied from; + * @cnt: number of bytes to be copied from the user space buffer; + * @ppos: the current position in the buffer. + * + * This is a way for user space executables to enable or disable event + * recording. + * + * Function's expectations: + * - This function shall copy cnt bytes from the input ubuf buffer to a kernel + * space buffer and shall convert the string within the kernel space buffer + * into a decimal base format number; + * - This function shall lock the global event_mutex before performing any + * operation on the target event file and unlock it after all operations on + * the target event file have completed; + * - This function shall check the size of the per-cpu ring-buffers used for + * the event trace data and, if smaller than TRACE_BUF_SIZE_DEFAULT, expand + * them to TRACE_BUF_SIZE_DEFAULT bytes (sizes larger than + * TRACE_BUF_SIZE_DEFAULT are not allowed); + * - This function shall invoke ftrace_event_enable_disable to enable or + * disable the target trace event according to the value read from user space + * (0 - disable, 1 - enable); + * - This function shall increase the file position pointed by ppos by the + * number of bytes speicified by cnt; + * + * Context: process context, locks and unlocks event_mutex. + * + * Return: the number of written bytes on success, any error returned by + * kstrtoul_from_user, -ENODEV if the event file cannot be retrieved from the + * input filp, any error returned by tracing_update_buffers, any error returned + * by ftrace_event_enable_disable, -EINVAL if the value copied from the user + * space ubuf is different from 0 or 1. + */ static ssize_t event_enable_write(struct file *filp, const char __user *ubuf, size_t cnt, loff_t *ppos) -- 2.48.1
