================
@@ -0,0 +1,270 @@
+# Adding Target Support
+
+LLDB supports many combinations of architecture, operating system and other
+system components. In this document we describe the considerations and
+requirements for porting LLDB to a combination of those things. Which we will
+refer to as a "target" within this document.
+
+:::{note}
+The terms `Target` and `Platform` are used throughout LLDB, often
+referring to a subset of what this document calls a "target".
+Unfortunately there is no more specific word to use here.
+
+This document provides some hints on implementation, but because every target
+is unique, we expect developers to learn about implementation from existing
+targets.
+
+This document starts with the end of the process, proposing your taret for
+upstream inclusion. It is worth reading through this even if that is not one of
+your goals, as you will have to tackle the same topics even in a downstream
+implementation.
+
+## Upstreaming Proposal Process
+
+You must send an RFC to the LLDB Discourse forum before upstreaming
+new target support. This RFC must be accepted in some form by the community
+before any changes can be merged upstream that are specific to your target.
+
+This RFC follows the normal rules of the LLVM community decision making
process.
+
+We require an RFC for target support upstreaming because:
+* We want ensure there is some level of public discussion on the topic.
+ It is important that details, even those obvious to the community at the
time,
+ are written down so that future readers may learn from it.
+
+ :::{note}
+ Assuming they were done in good faith, these discussions are not to be used
+ to personally criticise anyone after the fact. Situations change, people make
+ mistakes, and that is ok.
+
+* These discussions forms the basis for future proposals and the assessment
+ of those proposals. Every proposal will be different in some way, and by
+ contrast with the past we can do the best job assessing them.
+
+RFCs are not required to be:
+* In a set format. Make a logical argument in whatever way you think fit.
+* Exhaustively detailed. Include what you think is relevant and the community
+ will ask for the rest.
+* Answering all the same questions, or making all the same points, as previous
+ proposals. Compare your target with existing targets, but not everything
will,
+ or has to, apply to yours.
+* A commitment to the maximum theoretical level of support (more on this
later).
+ If your resources are limited, say so, and that will be taken into account
+ (and vice versa, committing to a lot of work does not guarantee acceptance).
+
+## Expectations Of Upstream Code
+
+Listed below are some examples of factors considered when considering accepting
+code upstream. These are examples and RFC authors are free to add their own,
+leave some out, or explain why they do not apply to their proposal.
+
+If you do use these points, they need to come with an answer and evidence to
+justify the answer. Rather than simply "yes this applies to my target".
+In other words, your proposal must stand alone without requiring readers to
read this document as well.
+
+The first set cover your motivation for your being upstream rather
+than on a fork:
+
+* Will it help you distribute an LLDB that includes this target support?
+ For example if there is an existing community for this
+ target, and how would they acquire LLDB?
+* Will it enable a wider community than your own forks would?
+ For example for it to be included in Linux distribution packaging.
+* Will it improve support for other targets by being there?
+ For example if we already support Operating System X on Architecture Y,
+ adding Architecture Z support may improve both as a side effect.
+* Will it help you keep your changes in sync?
+ For example if it involves fundamental changes to LLDB, or you have a very
+ small amount of maintenance resources in your community.
+* What other costs (or benefits) do you incur staying on a fork?
+ For example, your company might already have a fork.
+
+The next set are about whether you, your community, or the LLDB community, can
+adequately maintain the code upstream:
+
+* Who will be the maintainers for this target? Ideally there will be more than
+ one, who is present in the LLVM community and can be contacted
+ in a few different ways.
+* How often will it be tested, where, by whom and who will pay for it?
+* Who will address problems with it? Will it always be the named maintainers,
+ is it so common that anyone in upstream LLDB can deal with it, or perhaps
+ only employees of a specific company will be required to work on it.
+* When it breaks how easy will it be for the upstream LLDB community to
continue
+ their work without disruption?
+* If upstream contributors want to reproduce issues on your target, how can
+ they access it? Can it be emulated or virtualized? Does it require them to
+ sign a license? Do you offer access for open source projects? (and does that
+ include employees of other companies)
+
+## The Extent of Target Support
+
+Many of the factors mentioned above are on a spectrum. Not everyone can commit
+to spend maximum time, money, or effort on all those things. This is ok, not
+every target needs that and not every contributor is able to commit to that.
+
+We need you to help us understand the scope of your target's impact on LLDB. So
+below are some questions and sterotypical "small" and "big" answers.
+
+These are deliberately not "maximum" and "minimum" as that will vary between
+targets.
+
+* How many users will use LLDB with this target?
+ * Big: millions of developers worldwide.
+ * Small: you and a small community of target users.
+* How many changes will it require?
+ * Big: large changes to all parts of LLDB. On the level of the existing
+ code for C and C++ support.
+ * Small: small changes to enable existing support from LLVM, changes
+ to packet parsing (see the MSP430 case study below).
+* What parts and features of LLDB will work on, or with, this target?
+ * Big: `lldb`, `lldb-server` and advanced features like shared libraries.
+ * Small: just `lldb` and only basic features like continue, stop, reading
+ memory and registers.
+* How often is it tested?
+ * Big: per-commit testing of LLDB, following the upstream llvm-project.
+ * Small: per release of a downstream community or individual developer's
tools.
+* Who will maintain it?
+ * Big: there are several listed maintainers for this target, who are
+ employed by a company with significant investments in the target, to work
+ on the target.
+ * Small: there is a single maintainer listed for this target.
+* When it breaks, who will be affected?
+ * Big: every single developer and user of LLDB.
+ * Small: you and your target's community.
+* How do I reproduce a problem on this target?
+ * Big: all components are open source and can be run anywhere by using
+ simulations.
----------------
DavidSpickett wrote:
That's a good point. Vendor login to get proprietary simulator vs. apt install
qemu, that's something we want to know about.
https://github.com/llvm/llvm-project/pull/207166
_______________________________________________
lldb-commits mailing list
[email protected]
https://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
