On Mon, Jun 30, 2025 at 3:55 PM Gabriele Paoloni <gpaol...@redhat.com> wrote: > > 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 <gpaol...@redhat.com> > --- > 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/20250612104349.5047-1-gpaol...@redhat.com/ > --- > 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
Please neglect this RFC since the above return value is not correct. I have fixed the issue in v3. Apologies for the noise Gab > + */ > 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 >
