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]> --- Changes from v1: - Added "Context:" information and "Assumptions of use" Changes from v2 and v3: - Addressed comments from: https://lore.kernel.org/linux-trace-kernel/CA+wEVJbjhLmA4ZR5w7s6QDCfjET=pf2j9psfhc2wdo1nq5y...@mail.gmail.com/T/#ma46663274411b08c14f380a69363dc6225b09a45 --- kernel/trace/trace_events.c | 84 +++++++++++++++++++++++++++++++++++++ 1 file changed, 84 insertions(+) diff --git a/kernel/trace/trace_events.c b/kernel/trace/trace_events.c index 9f3e9537417d..af89eaed6a43 100644 --- a/kernel/trace/trace_events.c +++ b/kernel/trace/trace_events.c @@ -1772,6 +1772,49 @@ 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: + * - The global event_mutex shall be taken before performing any operation + * on the target event; + * + * - The string copied to user space shall be formatted according to the + * status flags from the target event file: + * - If the enable flag is set AND the soft_disable flag is not set then + * the first character shall be set to "1" ELSE it shall be set to "0"; + * + * - If either the soft_disable flag or the soft_mode flag is set then the + * second character shall be set to "*" ELSE it is skipped; + * + * - The string shall be terminated by a newline ("\n") and any remaining + * character 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 - the event file cannot be retrieved from the input filp + * * 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 +1844,47 @@ 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; + * + * - The global event_mutex shall be taken before performing any operation + * on the target event; + * + * - 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 specified 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 - 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 - 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
