[v3,7/8] libtracefs: Add man pages for tracefs_cpu_alloc_fd() and tracefs_cpu_free_fd()

Commit Message

Steven Rostedt Nov. 9, 2022, 11:52 p.m. UTC

From: "Steven Rostedt (Google)" <[e-mail]>

Update the man pages to describe the tracefs_cpu_alloc_fd() and
tracefs_cpu_free_fd().

Signed-off-by: Steven Rostedt (Google) <[e-mail]>
---
 Documentation/libtracefs-cpu-open.txt | 24 +++++++++++++++++++++++-
 Documentation/libtracefs.txt          |  2 ++
 2 files changed, 25 insertions(+), 1 deletion(-)

Patch

diff --git a/Documentation/libtracefs-cpu-open.txt b/Documentation/libtracefs-cpu-open.txt
index 58dde508290d..c5a900a06e8e 100644
--- a/Documentation/libtracefs-cpu-open.txt
+++ b/Documentation/libtracefs-cpu-open.txt
@@ -3,7 +3,7 @@  libtracefs(3)
 
 NAME
 ----
-tracefs_cpu_open, tracefs_cpu_close - Opening trace_pipe_raw data for reading
+tracefs_cpu_open, tracefs_cpu_close, tracefs_cpu_alloc_fd, tracefs_cpu_free_fd - Opening trace_pipe_raw data for reading
 
 SYNOPSIS
 --------
@@ -14,6 +14,9 @@  SYNOPSIS
 struct tracefs_cpu pass:[*]*tracefs_cpu_open*(struct tracefs_instance pass:[*]_instance_,
 				     int _cpu_, bool _nonblock_);
 void *tracefs_cpu_close*(struct tracefs_cpu pass:[*]_tcpu_);
+
+struct tracefs_cpu pass:[*]*tracefs_cpu_alloc_fd*(int _fd_, int _subbuf_size_, bool _nonblock_);
+void *tracefs_cpu_free_fd*(struct tracefs_cpu pass:[*]_tcpu_);
 --
 
 DESCRIPTION
@@ -29,11 +32,30 @@  NULL than the toplevel trace_pipe_raw file is used.
 The *tracefs_cpu_close()* closes all the file descriptors associated to the trace_pipe_raw
 opened by *tracefs_cpu_open()*.
 
+The *tracefs_cpu_alloc_fd()* will create a tracefs_cpu descriptor from an existing
+file descriptor _fd_. This is useful to use when connecting to a socket or pipe where
+the other end is feeding raw tracing data in the same format as the trace_pipe_raw
+file would (like in guest to host tracing). The caller is responsible for determining
+the _subbuf_size_ that will be used to break up the sub-buffers being read by the
+file descriptor. The _nonblock_ is treated the same as the same parameter in
+*tracefs_cpu_open()*.
+
+The *tracefs_cpu_free_fd()* is used to free the descriptor returned by *tracefs_cpu_alloc_fd()*.
+It does all the clean up that *tracefs_cpu_close()* performs, and that could also be
+used to free up the descriptor created by *tracefs_cpu_alloc_fd()* but will also close
+the file descriptor passed in. Note that *tracefs_cpu_free_fd()* should not be used
+on the descriptor returned by *tracefs_cpu_open()* as it will not close the file descriptor
+created by it.
+
 RETURN VALUE
 ------------
 The *tracefs_cpu_open()* returns a struct tracefs_cpu descriptor that can be
 used by the other functions or NULL on error.
 
+The *tracefs_cpu_alloc_fd()* returns a struct tracefs_cpu descriptor that can
+be used by the *tracefs_cpu_read*(3) related functions, where the descriptor
+will be reading the passed in _fd_ file descriptor.
+
 EXAMPLE
 -------
 See *tracefs_cpu_read*(3) for an example.
diff --git a/Documentation/libtracefs.txt b/Documentation/libtracefs.txt
index d41c7ab382ee..50af23e33026 100644
--- a/Documentation/libtracefs.txt
+++ b/Documentation/libtracefs.txt
@@ -270,7 +270,9 @@  Histograms:
 Recording of trace_pipe_raw files:
 	struct tracefs_cpu pass:[*]*tracefs_cpu_open*(struct tracefs_instance pass:[*]_instance_,
 					     int _cpu_, bool _nonblock_);
+	struct tracefs_cpu pass:[*]*tracefs_cpu_alloc_fd*(int _fd_, int _subbuf_size_, bool _nonblock_);
 	void *tracefs_cpu_close*(struct tracefs_cpu pass:[*]_tcpu_);
+	void *tracefs_cpu_free_fd*(struct tracefs_cpu pass:[*]_tcpu_);
 	int *tracefs_cpu_read_size*(struct tracefs_cpu pass:[*]_tcpu_);
 	int *tracefs_cpu_read*(struct tracefs_cpu pass:[*]_tcpu_, void pass:[*]_buffer_, bool _nonblock_);
 	int *tracefs_cpu_buffered_read*(struct tracefs_cpu pass:[*]_tcpu_, void pass:[*]_buffer_, bool _nonblock_);