Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
MIME-Version: 1.0
References: <20230819093340.265817-1-leo.yan@linaro.org> <CAM9d7cj=ichFk4bVQSbyptqy9wo8GFm1Z1Q7QzfhMFLjewNF-Q@mail.gmail.com>
 <20230823023838.GF57731@leoy-huanghe.lan>
In-Reply-To: <20230823023838.GF57731@leoy-huanghe.lan>
From:   Namhyung Kim <namhyung@kernel.org>
Date:   Tue, 22 Aug 2023 21:26:05 -0700
Message-ID: <CAM9d7cgaMyH=vSjVEOBjLzBWbZOricm6aHcP9hfLsTJ_gUEh3g@mail.gmail.com>
Subject: Re: [PATCH v6] Documentation: userspace-api: Document perf ring
 buffer mechanism
To:     Leo Yan <leo.yan@linaro.org>
Cc:     Jonathan Corbet <corbet@lwn.net>,
        Arnaldo Carvalho de Melo <acme@kernel.org>,
        Ian Rogers <irogers@google.com>,
        Thomas Richter <tmricht@linux.ibm.com>,
        Peter Zijlstra <peterz@infradead.org>,
        Adrian Hunter <adrian.hunter@intel.com>,
        Jiri Olsa <jolsa@kernel.org>, linux-doc@vger.kernel.org,
        linux-kernel@vger.kernel.org, linux-perf-users@vger.kernel.org
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: 8BIT
Precedence: bulk

On Tue, Aug 22, 2023 at 7:38 PM Leo Yan <leo.yan@linaro.org> wrote:
>
> 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

I think they are all supported.  You can use rw mode with backward
direction but it's just not intuitive.  Also ro mode with forward direction
is working but there's a chance to miss the start position of the
previous event.

Thanks,
Namhyung


>
> > 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