[llvm][utils] Update llc test updater documentation

[zbrid]

Summary

This commit explains a common reason this utility fails to work on a given
file it was applied to. I didn't find any other place this utility was
documented, so I added this information in the script's header comment.

[MaskRay]

Added some users of update_llc_test_checks.py.

link attributes is not clear. Do you mean dso_local or dso_preemptable? The problem you described seems like a general stale test problem. Missing dso_local may be a problem but I don't know whether that is common. Maybe there are more common problems that are worth mentioning.

[zbrid]

In D78968#2006646, @MaskRay wrote:

Added some users of update_llc_test_checks.py.

link attributes is not clear. Do you mean dso_local or dso_preemptable? The problem you described seems like a general stale test problem. Missing dso_local may be a problem but I don't know whether that is common. Maybe there are more common problems that are worth mentioning.

The problem is: If dso_local (or any attribute that can be in the same place as dso_local) is an attribute on the function, then the script won't take any action even when there's no reason it should not take action. I am guessing this is a common problem because @jyknight immediately guessed that might be my issue when I was running this script. I assume other people encounter this problem enough it's tribal knowledge among people who use this script.

As for the link attributes terminology, that's what jyknight called it when he guessed my problem. I see that dso_local is called a runtime preemption specifier. https://llvm.org/docs/LangRef.html#runtime-preemption-specifiers

I'll update the patch to say that instead of link attribute and assume that those are the two things that might show up where dso_local shows up.

[zbrid]

[utils] Update comment to be more specific based on maskray's comment

[RKSimon]

If this is a problem we should be doing more than just adding a comment in the script.

Possible things to consider:
1 - add support for matching dso_preemptable / dso_local - pretty trivial to add the relevant regex(s)
2 - detect any specifiers and warn that it might not be necessary

[zbrid]

Add FIXME and bug link

[zbrid]

In D78968#2007501, @RKSimon wrote:

If this is a problem we should be doing more than just adding a comment in the script.

Possible things to consider:
1 - add support for matching dso_preemptable / dso_local - pretty trivial to add the relevant regex(s)
2 - detect any specifiers and warn that it might not be necessary

Hi @RKSimon ,

That's a good point. I agree that it better if this is fixed in the script, however I can't fix it right now and I think that this comment is useful in the meantime. I filed a bug and updated the comment to reference it: https://bugs.llvm.org/show_bug.cgi?id=45714. The comment can be removed at the point this is fixed.

Given that multiple people have encountered this bug, it seems worthwhile to add a comment until the point it's fixed, so they don't have to spend time reaching out to people or reading the script until they understand the lack of output.

[zbrid]

I'm also happy to close this if you want to fix the regexes in a patch instead since I agree that would be better.

llvm/utils/update_llc_test_checks.py

 #!/usr/bin/env python3
 
 """A test case update script.
 
 This script is a utility to update LLVM 'llc' based test cases with new
 FileCheck patterns. It can either update all of the tests in the file or
 a single test function.
+
+If your function has runtime preemption specifiers (such as dso_local or
+dso_preemptable), then it will not match the regex this script uses when
+deciding which functions need to be updated. Often the runtime preemption
+specifiers are unnecessary for the test and you should delete them.
+FIXME: https://bugs.llvm.org/show_bug.cgi?id=45714.
 """
 
 from __future__ import print_function
 
 import argparse
 import glob
 import os         # Used to advertise this file's name ("autogenerated_note").
 import string