Add a paragraph about the shared buffer usage to kcov.rst.
Signed-off-by: Alexander Potapenko <glider@google.com>
---
Change-Id: Ia47ef7c3fcc74789fe57a6e1d93e29a42dbc0a97
---
Documentation/dev-tools/kcov.rst | 55 ++++++++++++++++++++++++++++++++
1 file changed, 55 insertions(+)
diff --git a/Documentation/dev-tools/kcov.rst b/Documentation/dev-tools/kcov.rst
index 6611434e2dd24..abf3ad2e784e8 100644
--- a/Documentation/dev-tools/kcov.rst
+++ b/Documentation/dev-tools/kcov.rst
@@ -137,6 +137,61 @@ mmaps coverage buffer, and then forks child processes in a loop. The child
processes only need to enable coverage (it gets disabled automatically when
a thread exits).
+Shared buffer for coverage collection
+-------------------------------------
+KCOV employs a shared memory buffer as a central mechanism for efficient and
+direct transfer of code coverage information between the kernel and userspace
+applications.
+
+Calling ``ioctl(fd, KCOV_INIT_TRACE, size)`` initializes coverage collection for
+the current thread associated with the file descriptor ``fd``. The buffer
+allocated will hold ``size`` unsigned long values, as interpreted by the kernel.
+Notably, even in a 32-bit userspace program on a 64-bit kernel, each entry will
+occupy 64 bits.
+
+Following initialization, the actual shared memory buffer is created using::
+
+ mmap(NULL, size * sizeof(unsigned long), PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0)
+
+The size of this memory mapping, calculated as ``size * sizeof(unsigned long)``,
+must be a multiple of ``PAGE_SIZE``.
+
+This buffer is then shared between the kernel and the userspace. The first
+element of the buffer contains the number of PCs stored in it.
+Both the userspace and the kernel may write to the shared buffer, so to avoid
+race conditions each userspace thread should only update its own buffer.
+
+Normally the shared buffer is used as follows::
+
+ Userspace Kernel
+ -----------------------------------------+-------------------------------------------
+ ioctl(fd, KCOV_INIT_TRACE, size) |
+ | Initialize coverage for current thread
+ mmap(..., MAP_SHARED, fd, 0) |
+ | Allocate the buffer, initialize it
+ | with zeroes
+ ioctl(fd, KCOV_ENABLE, KCOV_TRACE_PC) |
+ | Enable PC collection for current thread
+ | starting at buffer[1] (KCOV_ENABLE will
+ | already write some coverage)
+ Atomically write 0 to buffer[0] to |
+ reset the coverage |
+ |
+ Execute some syscall(s) |
+ | Write new coverage starting at
+ | buffer[1]
+ Atomically read buffer[0] to get the |
+ total coverage size at this point in |
+ time |
+ |
+ ioctl(fd, KCOV_DISABLE, 0) |
+ | Write some more coverage for ioctl(),
+ | then disable PC collection for current
+ | thread
+ Safely read and process the coverage |
+ up to the buffer[0] value saved above |
+
+
Comparison operands collection
------------------------------
--
2.50.0.727.gbf7dc18ff4-googOn Thu, 26 Jun 2025 at 15:42, Alexander Potapenko <glider@google.com> wrote: > > Add a paragraph about the shared buffer usage to kcov.rst. > > Signed-off-by: Alexander Potapenko <glider@google.com> > --- > Change-Id: Ia47ef7c3fcc74789fe57a6e1d93e29a42dbc0a97 > --- > Documentation/dev-tools/kcov.rst | 55 ++++++++++++++++++++++++++++++++ > 1 file changed, 55 insertions(+) > > diff --git a/Documentation/dev-tools/kcov.rst b/Documentation/dev-tools/kcov.rst > index 6611434e2dd24..abf3ad2e784e8 100644 > --- a/Documentation/dev-tools/kcov.rst > +++ b/Documentation/dev-tools/kcov.rst > @@ -137,6 +137,61 @@ mmaps coverage buffer, and then forks child processes in a loop. The child > processes only need to enable coverage (it gets disabled automatically when > a thread exits). > > +Shared buffer for coverage collection > +------------------------------------- > +KCOV employs a shared memory buffer as a central mechanism for efficient and > +direct transfer of code coverage information between the kernel and userspace > +applications. > + > +Calling ``ioctl(fd, KCOV_INIT_TRACE, size)`` initializes coverage collection for > +the current thread associated with the file descriptor ``fd``. The buffer > +allocated will hold ``size`` unsigned long values, as interpreted by the kernel. > +Notably, even in a 32-bit userspace program on a 64-bit kernel, each entry will > +occupy 64 bits. > + > +Following initialization, the actual shared memory buffer is created using:: > + > + mmap(NULL, size * sizeof(unsigned long), PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0) > + > +The size of this memory mapping, calculated as ``size * sizeof(unsigned long)``, > +must be a multiple of ``PAGE_SIZE``. > + > +This buffer is then shared between the kernel and the userspace. The first > +element of the buffer contains the number of PCs stored in it. > +Both the userspace and the kernel may write to the shared buffer, so to avoid > +race conditions each userspace thread should only update its own buffer. > + > +Normally the shared buffer is used as follows:: > + > + Userspace Kernel > + -----------------------------------------+------------------------------------------- > + ioctl(fd, KCOV_INIT_TRACE, size) | > + | Initialize coverage for current thread > + mmap(..., MAP_SHARED, fd, 0) | > + | Allocate the buffer, initialize it > + | with zeroes > + ioctl(fd, KCOV_ENABLE, KCOV_TRACE_PC) | > + | Enable PC collection for current thread > + | starting at buffer[1] (KCOV_ENABLE will > + | already write some coverage) > + Atomically write 0 to buffer[0] to | > + reset the coverage | > + | > + Execute some syscall(s) | > + | Write new coverage starting at > + | buffer[1] > + Atomically read buffer[0] to get the | > + total coverage size at this point in | > + time | > + | > + ioctl(fd, KCOV_DISABLE, 0) | > + | Write some more coverage for ioctl(), > + | then disable PC collection for current > + | thread > + Safely read and process the coverage | > + up to the buffer[0] value saved above | > + > + > Comparison operands collection > ------------------------------ Reviewed-by: Dmitry Vyukov <dvyukov@google.com>
© 2016 - 2025 Red Hat, Inc.