[docs][TableGen][Target] Improve the documentation of the attribute value for SubtargetFeature.

[craig.topper]

Summary

The value "true" and "false" are treated specially and other values are treated as integers.

[craig.topper]

Clarify that the integer value may be the name of an enum constant.

[paulkirth]

Thanks so much for adding this! This is definitely LGTM from me, but I'll let your other reviewers decide if anything else should be added.

llvm/docs/WritingAnLLVMBackend.rst

1768

Do you think it would help to reference which parameter you're referring to in the example code?

Also, do you think it bears mentioning how the boolean value is determined? It is certainly an implementation detail, but it may be good to specify.

[arsenm]

This sounds better behaved than

llvm/docs/WritingAnLLVMBackend.rst

1772

Is this really true? Where is this implemented?

1773

Don't refer to it as an attribute, attributes are a separate thing entirely

[craig.topper]

llvm/docs/WritingAnLLVMBackend.rst

1772

Here's the X86SSELevel code from X86GenSubtargetInfo.inc as an example

if (Bits[X86::FeatureAVX] && X86SSELevel < AVX) X86SSELevel = AVX;
if (Bits[X86::FeatureAVX2] && X86SSELevel < AVX2) X86SSELevel = AVX2;
if (Bits[X86::FeatureAVX512] && X86SSELevel < AVX512) X86SSELevel = AVX512;

1773

I was following the wording from the paragraph above and the .td. Should I change them all?

[arsenm]

llvm/docs/WritingAnLLVMBackend.rst

1773

Yes. I think there's frequent confusion between "attributes" and subtarget features in "target-features"

[craig.topper]

llvm/docs/WritingAnLLVMBackend.rst

1773

Can I do it as a follow up? Looks like I need to rename the field in the SubtargetFeature class itself to do it correctly which will involve tablegen emitter changes.

llvm/docs/WritingAnLLVMBackend.rst

 TableGen uses definitions in the ``Target.td`` and ``Sparc.td`` files to
 generate code in ``SparcGenSubtarget.inc``.  In ``Target.td``, shown below, the
 ``SubtargetFeature`` interface is defined.  The first 4 string parameters of
 the ``SubtargetFeature`` interface are a feature name, an attribute set by the
 feature, the value of the attribute, and a description of the feature.  (The
 fifth parameter is a list of features whose presence is implied, and its
 default value is an empty array.)
 
+If the value for the attribute is the string "true" or "false", the attribute
+is assumed to be a bool and only one SubtargetFeature should refer to it.
+Otherwise, it is assumed to be an integer. The integer value may be the name
+of an enum constant. If multiple features use the same integer attribute, the
+attribute will be set to the maximum value of all enabled features that share
+the attribute.
+
 .. code-block:: text
 
   class SubtargetFeature<string n, string a, string v, string d,
                          list<SubtargetFeature> i = []> {
     string Name = n;
     string Attribute = a;
     string Value = v;
     string Desc = d;

llvm/include/llvm/Target/Target.td

class SubtargetFeature<string n, string a,  string v, string d,
   string Name = n;
 
   // Attribute - Attribute to be set by feature.
   //
   string Attribute = a;
 
   // Value - Value the attribute to be set to by feature.
   //
+  // A value of "true" or "false" implies the attribute is a bool. Otherwise,
+  // it is assumed to be an integer. the integer value may be the name of an
+  // enum constant. If multiple features use the same integer attribute, the
+  // attribute will be set to the maximum value of all enabled features that
+  // share the attribute.
+  //
   string Value = v;
 
   // Desc - Feature description.  Used by command line (-mattr=) to display help
   // information.
   //
   string Desc = d;
 
   // Implies - Features that this feature implies are present. If one of those