Re: [PATCH v4 2/2] LAM: Enable tagged pointer support for watchpoints.

[Eli Zaretskii <eliz@gnu.org>]

> From: "Schimpe, Christina" <christina.schimpe@intel.com>
> CC: "gdb-patches@sourceware.org" <gdb-patches@sourceware.org>, "Willgerodt,
>  Felix" <felix.willgerodt@intel.com>, "luis.machado@arm.com"
> 	<luis.machado@arm.com>
> Date: Mon, 8 Jul 2024 08:52:17 +0000
> 
> > > I will try to come up with a section on tagged addresses/pointers in the
> > manual.
> > 
> > Thank you.
> 
> Hi Eli, 
> 
> I discussed this internally and we still wonder whether we need to document tagged
> pointers. I think I missed to mention one important detail, which is that tagged
> pointers are no gdb concept but a generic concept: 
> https://en.wikipedia.org/wiki/Tagged_pointer.
> 
> Do we need to document such generic concepts, too?

I think this discussion moved too far off the main issue here.  So let
me try to bring the main issue back into focus.

The original NEWS item said just this:

  * GDB now supports watchpoints for tagged data pointers on amd64.

Let's put ourselves in the shoes of a GDB user, which just happens to
run and debug programs on an amd64 machine, and try to imagine what
will such a user understand from this entry.  Here are some questions
which I think will come to his/her mind:

  . are all the pointers in my programs "tagged"?
  . if not all pointers are "tagged", when and how will I ever
    encounter "tagged" pointers in my programs?
  . what didn't work with "tagged" pointers until now and will work
    henceforth?

We need to give some hints to the readers, either in NEWS or in the
manual, that will help them answer these questions.  One possibility
is just to place the Wikipedia URL in NEWS.  Another possibility is to
mention "the Intel (R) linear address masking (LAM) feature", which
you so abundantly refer to in the commit log and in the comments, but
neither in NEWS nor in the manual, and maybe tell how to
"LAM57-enable" a program and why is that useful.  (If this is
described somewhere on the Internet, a URL could replace the actual
description.)

IOW, please compare the detailed and clear text you wrote for the
commit log message and the code comments with what you decided to put
in NEWS.  The text in the log basically answers all the questions I
think a reader will ask him/herself, and even includes what seems to
be important details, like which LAM widths are now supported.  Yet
none of that ended up in our docs.  Why not have in NEWS and/or in the
manual at least some of that helpful and clearly described
information?

Thanks.