[PATCH v2 20/24] Documentation for the new mtag commands

[Luis Machado]

On 10/23/20 4:04 PM, Luis Machado wrote:
> On 10/23/20 2:52 PM, Eli Zaretskii wrote:
>>> Cc: gdb-patches@sourceware.org, david.spickett@linaro.org
>>> From: Luis Machado <luis.machado@linaro.org>
>>> Date: Fri, 23 Oct 2020 11:33:36 -0300
>>>
>>> But, in general, there will always be a memory-side tag against which a
>>> logical tag (contained in a pointer, for example) will be matched 
>>> against.
>>
>> This is the crucial aspect that should be stated, IMO.
>>
> 
> I realized the order of the phrases was a bit off. I reordered it a bit 
> and added to it. How does the following look?
> 
> "Memory tagging is a memory protection technology that uses a pair of 
> tags to validate memory accesses through pointers.  The tags are integer 
> values usually comprised of a few bits, depending on the architecture.
> 
> There are two types of tags that are used in this setup: logical and
> allocation.  A logical tag is stored in the pointers themselves, usually 
> at the  higher bits of the pointers.  An allocation tag is the tag 
> associated with particular ranges of memory in the physical address 
> space, against which the logical tags from pointers are compared.
> 
> The pointer tag (logical tag) must match the memory tag (allocation tag)
> for the memory access to be valid.  If the logical tag does not match 
> the allocation tag, that will raise a memory violation.
> 
> Allocation tags cover multiple contiguous bytes of physical memory. This 
> range of bytes is called a memory tag granule and is 
> architecture-specific.  For example,  AArch64 has a tag granule of 16 
> bytes, meaning each allocation tag spans 16 bytes of memory.
> 
> If the underlying architecture supports memory tagging, like AArch64 MTE
> or SPARC ADI do,  @value{GDBN} can make use of it to validate addresses 
> and pointers against memory allocation tags.
> 
> A command prefix of @code{mtag} gives access to the various memory 
> tagging commands."
> 
> 
>>>>> +@kindex mtag setltag
>>>>> +@item mtag setltag @var{address_expression} @var{tag_bytes}
>>>>> +Print the address given by @var{address_expression}, augmented 
>>>>> with a logical
>>>>
>>>> It is strange for a command whose name is "set..." to print
>>>> something.  I'd expect it to set something instead.  is the above
>>>> description correct?
>>>>
>>>
>>> Yes. This is one area that I'd welcome some discussion/feedback.
>>>
>>> We don't always have a modifiable value as an argument to the "mtag
>>> setltag" command. We could have a constant value, a read-only value,
>>> some reference or some expression containing multiple pointers.
>>>
>>> Plus, the most natural way to modify a value in GDB is through the
>>> existing "set variable" command.
>>>
>>> The main goal is to be able to augment a particular address with a given
>>> logical tag. That augmented value can then be used to set a particular
>>> pointer or value. It will be stored in the history anyway, so that's
>>> already a value that you can use.
>>>
>>> There won't be much reason to set logical tags other than if you're
>>> chasing bugs and trying to cause one. It is one additional knob so that
>>> you won't need to craft the tagged pointer by hand.
>>
>> Maybe the command should be called something other than "set...",
>> then?
>>
> 
> Maybe. Though honestly I'm not really sure what to call it. Even if we 
> call it "set" and make it really set some variable's value, it won't be 
> able to set the value of an expression with multiple variables, for 
> example.
> 
> I'll have to think about it.
> 

David Spicket (cc-ed, handling LLDB's MTE enablement), has suggested 
"mtag withltag" as opposed to "mtag setltag", which implies we will only 
display the modified/tagged version of a particular address expression, 
without setting any value.

How does that sound?