Documentation for the process of adding new targets

[rengolin]

Summary

Plenty of new targets nowadays and I found myself repeating the same
thing over and over, so this is more or less what we said over the last
few years, but condensed in an ordered fashion and easy to digest.

This does not change any of the recommendations, only documents what we
have been saying for years. Some of the new targets have done slightly
different processes because we didn't have this document, so I want to
make sure new targets don't suffer from this problem.

Copying some target owners that I helped upstream to make sure I'm not
missing anything. Feel free to copy more people if needed. Also copying
some active developers that have reviewed documentation changes recently.

[nickdesaulniers]

LGTM; thanks for adding this. Reading through https://llvm.org/docs/DeveloperPolicy.html#adding-a-new-target, consider adding these numbered points under the bulleted list of points under The basic rules for a back-end to be upstreamed in experimental mode are:.

llvm/docs/DeveloperPolicy.rst

820

s/that/then/

[MaskRay]

LGTM, too.

[rengolin]

In D116331#3211517, @nickdesaulniers wrote:

LGTM; thanks for adding this. Reading through https://llvm.org/docs/DeveloperPolicy.html#adding-a-new-target, consider adding these numbered points under the bulleted list of points under The basic rules for a back-end to be upstreamed in experimental mode are:.

IIRC it was numbered on the original patch but we changed to bullets. I'll leave this to another patch, as I'm not sure they should be numbered either.

llvm/docs/DeveloperPolicy.rst

820

I changed to "only after", which I think is what was more confusing.

[rengolin]

Thanks!

[mehdi_amini]

Thanks for adding the doc!

I don't have any concern with what you wrote, but from a "process" point of view: it'd be great to let this kind of things (important documentation) up for review a bit longer than a day, especially in a week of the year where most people may not be online.

llvm/docs/DeveloperPolicy.rst

   nuisance to other targets and be considered a candidate for deprecation and
   ultimately removed.
 
-In essences, these rules are necessary for targets to gain and retain their
+In essence, these rules are necessary for targets to gain and retain their
 status, but also markers to define bit-rot, and will be used to clean up the
 tree from unmaintained targets.
 
+Those wishing to add a new target to LLVM must follow the procedure below:
+
+1. Read this section and make sure your target follows all requirements. For
+   minor issues, your community will be responsible for making all necessary
+   adjustments soon after the initial merge.
+2. Send a request for comment (RFC) to the llvm-dev@ mailing list, describing
+   your target and how it follows all the requirements and what work has been
+   done and will need to be done to accommodate the official target requirements.
+   Make sure to expose any and all controversial issues, changes needed in the
+   base code, table gen, etc.
+3. Once the response is positive, the LLVM community can start reviewing the
+   actual patches (but they can be prepared before, to support the RFC). Create
+   a sequence of N patches, numbered '1/N' to 'N/N' (make sure N is an actual
+   number, not the letter 'N'), that completes the basic structure of the target.
+4. The initial patch should add documentation, code owners and triple support in
+   clang and LLVM. The following patches add TableGen infrastructure to describe
+   the target and lower instructions to assembly. The final patch must show that
+   the target can lower correctly with extensive LIT tests (IR to MIR, MIR to
+   ASM, etc).
+5. Some patches may be approved before others, but only once *all* patches are
+   approved that the whole set can be merged in one go. This is to guarantee
+   that all changes are good as a single block.
+6. After the initial merge, the target community can stop numbering patches and
+   start working asynchronously on the target to complete support. They should
+   still seek review from those who helped them in the initial phase, to make
+   sure the progress is still consistent.
+7. Once all official requirements have been fulfilled (as above), the code owner
+   should request the target to be enabled by default by sending another RFC to
+   the llvm-dev@ mailing list.
+
 Adding an Established Project To the LLVM Monorepo
 --------------------------------------------------