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

["Schimpe, Christina" <christina.schimpe@intel.com>]

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

Hi Eli, 

Thanks a lot for your detailed explanations.

I understand that the NEWS text seems rather short, especially compared
to my commit message.
One reason why I kept the NEWS generic (without LAM and its specifics) is
because theoretically the patch should work for AMD's tagged pointer support, too. 
They call their tagged pointer support "upper address ignore" (UAI).

However, I still could mention LAM in that way in the NEWS:  

- GDB now supports watchpoints for tagged data pointers on amd64,
 e.g. as provided by Intel's linear address masking (LAM) feature.

or 

- GDB now supports watchpoints for tagged data pointers on amd64. 
For more information on tagged data pointers, see
https://en.wikipedia.org/wiki/Tagged_pointer.

Although given that I did not test UAI and don't know about its current
state, I think it's better to use my first suggestion.

If the user reads about LAM (or tagged pointer support in general), I 
hope he should be able to answer the questions you mentioned:

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

What do you think?

If you don't like my current suggestion, I have no problem adding a
proper documentation on tagged pointers in the manual or adding
more info to the NEWS. 

And sorry for moving this discussion into a general direction.  I just
want to be sure that I understand this topic in general, such that I
will make it better next time. 😊

Thanks again,
Christina 
Intel Deutschland GmbH
Registered Address: Am Campeon 10, 85579 Neubiberg, Germany
Tel: +49 89 99 8853-0, www.intel.de
Managing Directors: Sean Fennelly, Jeffrey Schneiderman, Tiffany Doon Silva
Chairperson of the Supervisory Board: Nicole Lau
Registered Office: Munich
Commercial Register: Amtsgericht Muenchen HRB 186928