linux-kernel - Re: [PATCH v6] Documentation: userspace-api: Document perf ring buffer mechanism

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Date:   Wed, 23 Aug 2023 10:38:38 +0800
From:   Leo Yan <leo.yan@...aro.org>
To:     Namhyung Kim <namhyung@...nel.org>
Cc:     Jonathan Corbet <corbet@....net>,
        Arnaldo Carvalho de Melo <acme@...nel.org>,
        Ian Rogers <irogers@...gle.com>,
        Thomas Richter <tmricht@...ux.ibm.com>,
        Peter Zijlstra <peterz@...radead.org>,
        Adrian Hunter <adrian.hunter@...el.com>,
        Jiri Olsa <jolsa@...nel.org>, linux-doc@...r.kernel.org,
        linux-kernel@...r.kernel.org, linux-perf-users@...r.kernel.org
Subject: Re: [PATCH v6] Documentation: userspace-api: Document perf ring
 buffer mechanism

Hi Namhyung,

On Tue, Aug 22, 2023 at 05:43:25PM -0700, Namhyung Kim wrote:

[...]

> > +2.3.2 Writing samples into buffer
> > +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> > +
> > +Ring buffers are mapped as read-write mode or read-only mode, which is
> > +used for a normal ring buffer and an overwritable ring buffer
> > +respectively.
> > +
> > +The ring buffer in the read-write mode is mapped with the property
> > +``PROT_READ | PROT_WRITE``.  With the write permission, the perf tool
> > +updates the ``data_tail`` to indicate the data start position.  Combining
> > +with the head pointer ``data_head``, which works as the end position of
> > +the current data, the perf tool can easily know where read out the data
> > +from.
> > +
> > +Alternatively, in the read-only mode, only the kernel keeps to update
> > +the ``data_head`` while the user space cannot access the ``data_tail`` due
> > +to the mapping property ``PROT_READ``.
> > +
> > +Why ring buffers are mapped with above two different modes?  Here the
> > +write direction matters.  The forward writing starts to save data from
> > +the beginning of the ring buffer and wrap around when overflow, which is
> > +used with the read-write mode in the normal ring buffer.  When the
> > +consumer doesn't keep up with the producer, it would lose some data, the
> > +kernel keeps how many records it lost and generates the
> > +``PERF_RECORD_LOST`` records in the next time when it finds a space in the
> > +ring buffer.
> 
> Thanks for the update.  It's unclear to me if all 4 combination of
> (rw, ro) x (fwd, bwd) are possible (yes!).  The rw mode and back-
> ward is also possible but just not used for perf tool.

I can add a matrix for the combinations:

  The combination is supported in perf tool:

  ---+------------+-----------
     |  Forward   | Backward
  ---+------------+-----------
  rw |  Yes       |   No
  ---+------------+-----------
  ro |  X         |   Yes
  ---+------------+-----------

  Yes: is supported
  No: is not supported
  X: is not feasible

> And I think the description below in this section shows kernel
> internals too much.  Name of kernel functions and data structure
> is not an API and can be changed any time.  You can describe
> the logic without the names.

Understand, I agree this will introduce maintenance efforts in later.

I will refine the description and send a new patch.

Thanks for reviewing!

Leo