https://github.com/DavidSpickett updated https://github.com/llvm/llvm-project/pull/207166
>From f3b3a33fd06ffb72be1ecbbc8c76758f8905c25f Mon Sep 17 00:00:00 2001 From: David Spickett <[email protected]> Date: Mon, 22 Jun 2026 12:08:45 +0000 Subject: [PATCH 1/5] [lldb][docs] Add platform/target support requirements doc This is a very delayed follow up to: https://discourse.llvm.org/t/rfc-surveying-lldbs-supported-platforms-and-architectures/83978 Where I realised that even for upstream supported targets, the level of testing and attention they get varies a lot. Which I think is not a bad thing, because LLDB would be much more chaotic if it were a bad thing. The problem I see is that no one really knows how to start writing proposals for new targets, and no one really knows how to properly assess one. Me included, but what I can do is write out some starting points for both parties. Hopefully this makes the process a bit more fair for those not used to writing RFCs. (and if we want to make the rules more strict, we will now have a place to document that) The document also includes some technical guidance, but I don't want to get stuck in the "How to Write an LLVM backend" type cycle. Where we write a thing and it becomes outdated instantly. So what's there is deliberately high level because Developers will have to learn the codebase anyway to have any chance of writing target support. A bit like adding a new language, which has unknown scope. But unlike a new language, there are plenty of targets to look at, so I think it's more justifiable here. In terms of the famous meme: This document isn't going to tell you how to "draw the rest of the owl", but it gives you the names of some key techniques in owl drawing and advice for how to best present your owl to the "drawings of owls" society when you're done. --- lldb/docs/index.md | 1 + lldb/docs/resources/addingtargetsupport.md | 270 +++++++++++++++++++++ 2 files changed, 271 insertions(+) create mode 100644 lldb/docs/resources/addingtargetsupport.md diff --git a/lldb/docs/index.md b/lldb/docs/index.md index da015b5d2e1ce..b117c4ab386f2 100644 --- a/lldb/docs/index.md +++ b/lldb/docs/index.md @@ -194,6 +194,7 @@ resources/sbapi resources/dataformatters resources/formatterbytecode resources/addinglanguagesupport +resources/addingtargetsupport resources/caveats resources/projects ``` diff --git a/lldb/docs/resources/addingtargetsupport.md b/lldb/docs/resources/addingtargetsupport.md new file mode 100644 index 0000000000000..8a826c972920e --- /dev/null +++ b/lldb/docs/resources/addingtargetsupport.md @@ -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. + * Small: you contact the maintainer and they do it for you. +* Who will fix problems? + * Big: the maintainers and a large group of contributors. + * Small: only the listed maintainer. + +## Target Support Case Studies + +These case studies are to give you starting points for your proposals. Consider +how your target compares to these. + +### Apple Targets + +Apple targets have possibly the most extensive support in LLDB: +* Changes from LLVM's main branch are continuously tested. Results are accessible + publicly, and reported to all LLDB contributors. +* Many employees contribute upstream and are maintainers for these targets. +* Target specific problems are either solved by the upstream community with + maintainer input, or by the maintainers themselves. +* Its specific features either do not impact other targets, or when they + do, they are designed and maintained in collaboration with the community. +* Many people unrelated to Apple itself use Apple hardware, and hardware is + available at retail. So it is fairly easy to find someone who can reproduce + an issue. +* LLDB gets a lot of secondary testing downstream, and exposure to Apple's + own developer community. + +### FreeBSD + +FreeBSD is an example of quite self contained support, managed by the project's community. + +* FreeBSD is open source and available to anyone to build, modify, run on + hardware, emulate or virtualize. +* FreeBSD support is mostly in the native target parts of `lldb-server`, + so issues with it rarely impact any other target. +* It is quite similar to Linux, so it does not cause large scale changes to + fundamental assumptions LLDB makes. +* It has at least one maintainer and sometimes contributions to upstream LLDB + from the FreeBSD community. +* Issues are solved by the maintainer and the FreeBSD community. +* LLDB on FreeBSD is tested each time FreeBSD updates the version used in the + base system, which is roughly per upstream LLVM release. + +### Linux + +Linux is an example where the Linux community as a whole does not do all the work +of Linux support. Some architectures have a wide contributor base and others +have company specific contributors. + +* Linux is open source, freely available, to be installed on hardware, virtualised, + emulated, and so on. Most problems can be reproduced in more than one way. +* Continuous testing for many supported architectures, often supported by the + architecture vendor. +* Remaining architectures are tested per release, or every other release. + Depends on the update schedule of the Linux distributions. +* Support for a new architecture is quite easy to isolate, so problems do not + impact other Linux architectures, or other operating systems. +* Linux's popularity and therefore it's choice of standards means it informs + many core features of LLDB. +* It has more than one listed maintainer and many contributors. + Issues are resolved by the community. + +### MSP430 + +MSP430 is handled as a bare metal (no operating system) target in LLDB. So it +is the most minimal example. + +* LLVM already has MSP430 support, changes to enable it in LLDB were minimal. +* It does not use `lldb-server`, and `lldb` only required minor adjustments to + be compatible with the commonly used debug server. +* An ABI plugin was added, which is isolated to MSP430 only. +* It is not systematically tested anywhere, but gets some use by MSP430 developers. +* It has no documented maintainer. +* We rely on users to report issues with it, and would likely guide them to fix + them themselves. + +## Components Of For Target Support + +This is a very high level view, we recommend you combine this with reading the +changes done for recently added targets, as each target is going to be slightly +different. + +Assuming that: +* You want to support a combination of a new architecture and a new operating + system. +* LLVM already supports your architecture and operating system. +* You want to port most of the LLDB features, which means porting both `lldb` + and `lldb-server`. + +Then this is a list of components you will need to write. If your target is similar +to others you may be able to reuse existing components and we encourage you to do +so. + +First the components concerned with operating systems: + +* A `Platform` plugin. For example `PlatformLinux`. +* A `HostInfo` plugin. For example `HostInfoLinux`. +* A native process plugin (native means it runs on your target). For example `NativeProcessLinux`. +* Signal information. For example `LinuxSignals`. +* A dynamic loader plugin. For example `DynamicLoaderPOSIXDYLD`. +* An object file plugin. For example `ObjectFileELF`. + +Then the components concerned with architecture (though the distinction is often +inexact): + +* ABI plugin. For example `ABISysV_arm64`. +* Architecture plugin. For example `ArchitectureAArch64`. +* Register definitions and register context (a context is a collection of registers). + For example `NativeRegisterContextLinux_arm64`. +* Instruction emulation. Most targets need a small amount for unwind purposes, + but if you lack hardware single step you will need a lot more. For example + `EmulateInstructionARM64`. +* Unwind support. LLDB needs to be taught about any architecture specific + directives. + +The order of implementation will vary in each case. Each component does not +need to be fully implemented for you to start work on the next. + +If you are going to be running `lldb` on your target, then an obvious first step +is to get `lldb` to build there without any changes. This `lldb` will only be +useful for remotely debugging other targets, but you will at least know that +the build system is compatible. + +Next, try `lldb` with any existing debug servers for your target. If they +are similar to `lldb-server` or `gdbserver`, this can flush out some +obvious issues in `lldb`. + +Then begin porting `lldb-server` to your target. We recommend that you +get the test suite to run as soon as possible, however bad the results +are. + +As you have seen above, there are a lot of moving parts to a debugger. So +having some set of results to measure progress is very important. +Sometimes a change will get one test to pass, sometimes hundreds, and it +is easy to regress if you are not careful. >From 918409994741d0ef567eb3c329d99e7ea1f09c47 Mon Sep 17 00:00:00 2001 From: David Spickett <[email protected]> Date: Fri, 3 Jul 2026 10:29:11 +0000 Subject: [PATCH 2/5] review comments round 1 --- lldb/docs/resources/addingtargetsupport.md | 70 +++++++++++----------- 1 file changed, 36 insertions(+), 34 deletions(-) diff --git a/lldb/docs/resources/addingtargetsupport.md b/lldb/docs/resources/addingtargetsupport.md index 8a826c972920e..5df429a7150f6 100644 --- a/lldb/docs/resources/addingtargetsupport.md +++ b/lldb/docs/resources/addingtargetsupport.md @@ -14,7 +14,7 @@ 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 +This document starts with the end of the process, proposing your target 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. @@ -31,13 +31,7 @@ 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 +* These discussions form 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. @@ -60,7 +54,8 @@ 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. +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: @@ -85,7 +80,8 @@ 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? +* How often will it be tested, where, by whom and who will be responsible 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. @@ -98,15 +94,16 @@ adequately maintain the code upstream: ## 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. +The factors above are part of a cost benefit analysis that the LLDB community +will do, prioritising the health of the community and the project. This means +that there is no set level or type of commitment required for a new target. -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. +Each case will have unqiue aspects, so you need to tell the community how much +impact your target will have on LLDB. Below are some questions you can start +with, along with stereotypical "big" and "small" answers. -These are deliberately not "maximum" and "minimum" as that will vary between -targets. +Note that these are intentionally not maximums and minimums. Some target's +impact will be bigger than "big" or smaller than "small". * How many users will use LLDB with this target? * Big: millions of developers worldwide. @@ -133,7 +130,7 @@ targets. * 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. + simulations with very little setup. * Small: you contact the maintainer and they do it for you. * Who will fix problems? * Big: the maintainers and a large group of contributors. @@ -146,9 +143,10 @@ how your target compares to these. ### Apple Targets -Apple targets have possibly the most extensive support in LLDB: -* Changes from LLVM's main branch are continuously tested. Results are accessible - publicly, and reported to all LLDB contributors. +Apple targets have possibly the most extensive support in LLDB. + +* Changes from LLVM's main branch are continuously tested. Results are + accessible publicly, and reported to all LLDB contributors. * Many employees contribute upstream and are maintainers for these targets. * Target specific problems are either solved by the upstream community with maintainer input, or by the maintainers themselves. @@ -162,7 +160,8 @@ Apple targets have possibly the most extensive support in LLDB: ### FreeBSD -FreeBSD is an example of quite self contained support, managed by the project's community. +FreeBSD is an example of quite self contained support, managed by the project's +community. * FreeBSD is open source and available to anyone to build, modify, run on hardware, emulate or virtualize. @@ -178,12 +177,13 @@ FreeBSD is an example of quite self contained support, managed by the project's ### Linux -Linux is an example where the Linux community as a whole does not do all the work -of Linux support. Some architectures have a wide contributor base and others -have company specific contributors. +Linux is an example where the Linux community as a whole does not do all the +work of Linux support. Some architectures have a wide contributor base and +others have company specific contributors. -* Linux is open source, freely available, to be installed on hardware, virtualised, - emulated, and so on. Most problems can be reproduced in more than one way. +* Linux is open source, freely available, to be installed on hardware, + virtualised, emulated, and so on. Most problems can be reproduced in more than + one way. * Continuous testing for many supported architectures, often supported by the architecture vendor. * Remaining architectures are tested per release, or every other release. @@ -204,7 +204,8 @@ is the most minimal example. * It does not use `lldb-server`, and `lldb` only required minor adjustments to be compatible with the commonly used debug server. * An ABI plugin was added, which is isolated to MSP430 only. -* It is not systematically tested anywhere, but gets some use by MSP430 developers. +* It is not systematically tested anywhere, but gets some use by MSP430 + developers. * It has no documented maintainer. * We rely on users to report issues with it, and would likely guide them to fix them themselves. @@ -222,15 +223,16 @@ Assuming that: * You want to port most of the LLDB features, which means porting both `lldb` and `lldb-server`. -Then this is a list of components you will need to write. If your target is similar -to others you may be able to reuse existing components and we encourage you to do -so. +Then this is a list of components you will need to write. If your target is +similar to others you may be able to reuse existing components and we encourage +you to do so. First the components concerned with operating systems: * A `Platform` plugin. For example `PlatformLinux`. * A `HostInfo` plugin. For example `HostInfoLinux`. -* A native process plugin (native means it runs on your target). For example `NativeProcessLinux`. +* A native process plugin (native means it runs on your target). For example + `NativeProcessLinux`. * Signal information. For example `LinuxSignals`. * A dynamic loader plugin. For example `DynamicLoaderPOSIXDYLD`. * An object file plugin. For example `ObjectFileELF`. @@ -240,8 +242,8 @@ inexact): * ABI plugin. For example `ABISysV_arm64`. * Architecture plugin. For example `ArchitectureAArch64`. -* Register definitions and register context (a context is a collection of registers). - For example `NativeRegisterContextLinux_arm64`. +* Register definitions and register context (a context is a collection of + registers). For example `NativeRegisterContextLinux_arm64`. * Instruction emulation. Most targets need a small amount for unwind purposes, but if you lack hardware single step you will need a lot more. For example `EmulateInstructionARM64`. >From bdc413d7d4126de1c3731b50f5f8241c551b5a24 Mon Sep 17 00:00:00 2001 From: David Spickett <[email protected]> Date: Fri, 3 Jul 2026 10:43:21 +0000 Subject: [PATCH 3/5] review comments round 2 --- lldb/docs/resources/addingtargetsupport.md | 49 ++++++++++++---------- 1 file changed, 26 insertions(+), 23 deletions(-) diff --git a/lldb/docs/resources/addingtargetsupport.md b/lldb/docs/resources/addingtargetsupport.md index 5df429a7150f6..99d3cf920b73e 100644 --- a/lldb/docs/resources/addingtargetsupport.md +++ b/lldb/docs/resources/addingtargetsupport.md @@ -2,7 +2,7 @@ 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 +requirements for porting LLDB to a combination of those things which we will refer to as a "target" within this document. :::{note} @@ -21,9 +21,11 @@ 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. +You must send an RFC to the +[LLDB Discourse forum](https://discourse.llvm.org/c/subprojects/lldb/8) 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. @@ -33,7 +35,8 @@ We require an RFC for target support upstreaming because: are written down so that future readers may learn from it. * These discussions form 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. + contrasting current proposals with the previous proposals we can do a better + job assessing them. RFCs are not required to be: * In a set format. Make a logical argument in whatever way you think fit. @@ -57,7 +60,7 @@ 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 +The first set covers your motivation for your being upstream rather than on a fork: * Will it help you distribute an LLDB that includes this target support? @@ -85,7 +88,7 @@ adequately maintain the code upstream: * 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 +* 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 @@ -148,11 +151,11 @@ Apple targets have possibly the most extensive support in LLDB. * Changes from LLVM's main branch are continuously tested. Results are accessible publicly, and reported to all LLDB contributors. * Many employees contribute upstream and are maintainers for these targets. -* Target specific problems are either solved by the upstream community with +* Target-specific problems are either solved by the upstream community with maintainer input, or by the maintainers themselves. -* Its specific features either do not impact other targets, or when they +* Its specific features either do not impact other targets, or, when they do, they are designed and maintained in collaboration with the community. -* Many people unrelated to Apple itself use Apple hardware, and hardware is +* Many people unrelated to Apple itself use Apple hardware, which is available at retail. So it is fairly easy to find someone who can reproduce an issue. * LLDB gets a lot of secondary testing downstream, and exposure to Apple's @@ -184,14 +187,14 @@ others have company specific contributors. * Linux is open source, freely available, to be installed on hardware, virtualised, emulated, and so on. Most problems can be reproduced in more than one way. -* Continuous testing for many supported architectures, often supported by the - architecture vendor. -* Remaining architectures are tested per release, or every other release. - Depends on the update schedule of the Linux distributions. +* Many architectures are tested by the architecture vendor, others + on community provided hardware. +* LLDB is a commonly available Linux package, so further testing happens during + various Linux distribution's release cycles. * Support for a new architecture is quite easy to isolate, so problems do not impact other Linux architectures, or other operating systems. -* Linux's popularity and therefore it's choice of standards means it informs - many core features of LLDB. +* Linux is very popular, therefore it's choice of standards informs many core + features of LLDB. * It has more than one listed maintainer and many contributors. Issues are resolved by the community. @@ -200,7 +203,7 @@ others have company specific contributors. MSP430 is handled as a bare metal (no operating system) target in LLDB. So it is the most minimal example. -* LLVM already has MSP430 support, changes to enable it in LLDB were minimal. +* LLVM already has MSP430 support, so changes to enable it in LLDB were minimal. * It does not use `lldb-server`, and `lldb` only required minor adjustments to be compatible with the commonly used debug server. * An ABI plugin was added, which is isolated to MSP430 only. @@ -210,7 +213,7 @@ is the most minimal example. * We rely on users to report issues with it, and would likely guide them to fix them themselves. -## Components Of For Target Support +## Components Of Target Support This is a very high level view, we recommend you combine this with reading the changes done for recently added targets, as each target is going to be slightly @@ -244,11 +247,11 @@ inexact): * Architecture plugin. For example `ArchitectureAArch64`. * Register definitions and register context (a context is a collection of registers). For example `NativeRegisterContextLinux_arm64`. -* Instruction emulation. Most targets need a small amount for unwind purposes, - but if you lack hardware single step you will need a lot more. For example - `EmulateInstructionARM64`. -* Unwind support. LLDB needs to be taught about any architecture specific - directives. +* Unwinding support for backtracing. LLDB needs to be taught about any + architecture specific directives. +* Instruction emulation. For example `EmulateInstructionARM64`. Most targets + need to emulate a small amount of instructions for unwinding. If you lack + hardware single step, you will need to emulate many times more than that. The order of implementation will vary in each case. Each component does not need to be fully implemented for you to start work on the next. >From 0a675076c8404d252d4371eec78b3a9931fb7875 Mon Sep 17 00:00:00 2001 From: David Spickett <[email protected]> Date: Fri, 3 Jul 2026 11:03:02 +0000 Subject: [PATCH 4/5] self review --- lldb/docs/resources/addingtargetsupport.md | 53 +++++++++++----------- 1 file changed, 27 insertions(+), 26 deletions(-) diff --git a/lldb/docs/resources/addingtargetsupport.md b/lldb/docs/resources/addingtargetsupport.md index 99d3cf920b73e..b338e8a51bea8 100644 --- a/lldb/docs/resources/addingtargetsupport.md +++ b/lldb/docs/resources/addingtargetsupport.md @@ -9,6 +9,7 @@ refer to as a "target" within this document. 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 @@ -30,9 +31,9 @@ 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. +* We want to 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. + are written down so that future readers may learn from them. * These discussions form the basis for future proposals and the assessment of those proposals. Every proposal will be different in some way, and by contrasting current proposals with the previous proposals we can do a better @@ -56,11 +57,11 @@ 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". +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 covers your motivation for your being upstream rather +The first set covers your motivation for your target being upstream, rather than on a fork: * Will it help you distribute an LLDB that includes this target support? @@ -77,7 +78,7 @@ than on a fork: * 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 +The next set is 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 @@ -85,9 +86,9 @@ adequately maintain the code upstream: in a few different ways. * How often will it be tested, where, by whom and who will be responsible 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. +* 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 will + only employees of a specific company 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 @@ -101,12 +102,12 @@ The factors above are part of a cost benefit analysis that the LLDB community will do, prioritising the health of the community and the project. This means that there is no set level or type of commitment required for a new target. -Each case will have unqiue aspects, so you need to tell the community how much +Each case will have unique aspects, so you need to tell the community how much impact your target will have on LLDB. Below are some questions you can start with, along with stereotypical "big" and "small" answers. -Note that these are intentionally not maximums and minimums. Some target's -impact will be bigger than "big" or smaller than "small". +Note that these are intentionally not maximums and minimums. The impact +of some targets will be bigger than "big" or smaller than "small". * How many users will use LLDB with this target? * Big: millions of developers worldwide. @@ -125,8 +126,7 @@ impact will be bigger than "big" or smaller than "small". * 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. + employed by a company with significant investments in 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. @@ -153,7 +153,7 @@ Apple targets have possibly the most extensive support in LLDB. * Many employees contribute upstream and are maintainers for these targets. * Target-specific problems are either solved by the upstream community with maintainer input, or by the maintainers themselves. -* Its specific features either do not impact other targets, or, when they +* Apple-specific features either do not impact other targets, or, when they do, they are designed and maintained in collaboration with the community. * Many people unrelated to Apple itself use Apple hardware, which is available at retail. So it is fairly easy to find someone who can reproduce @@ -163,7 +163,7 @@ Apple targets have possibly the most extensive support in LLDB. ### FreeBSD -FreeBSD is an example of quite self contained support, managed by the project's +FreeBSD is an example of quite self-contained support, managed by the project's community. * FreeBSD is open source and available to anyone to build, modify, run on @@ -182,25 +182,25 @@ community. Linux is an example where the Linux community as a whole does not do all the work of Linux support. Some architectures have a wide contributor base and -others have company specific contributors. +others have company-specific contributors as well. -* Linux is open source, freely available, to be installed on hardware, +* Linux is open source, freely available, and can be installed on hardware, virtualised, emulated, and so on. Most problems can be reproduced in more than one way. * Many architectures are tested by the architecture vendor, others - on community provided hardware. + are tested on community-provided hardware. * LLDB is a commonly available Linux package, so further testing happens during - various Linux distribution's release cycles. + various Linux distributions' release cycles. * Support for a new architecture is quite easy to isolate, so problems do not impact other Linux architectures, or other operating systems. -* Linux is very popular, therefore it's choice of standards informs many core +* Linux is very popular, therefore its choice of standards informs many core features of LLDB. * It has more than one listed maintainer and many contributors. Issues are resolved by the community. ### MSP430 -MSP430 is handled as a bare metal (no operating system) target in LLDB. So it +MSP430 is handled as a bare-metal (no operating system) target in LLDB. So it is the most minimal example. * LLVM already has MSP430 support, so changes to enable it in LLDB were minimal. @@ -215,8 +215,8 @@ is the most minimal example. ## Components Of Target Support -This is a very high level view, we recommend you combine this with reading the -changes done for recently added targets, as each target is going to be slightly +This is a very high-level view. We recommend you combine this with reading the +changes made for recently added targets, as each target is going to be slightly different. Assuming that: @@ -248,10 +248,11 @@ inexact): * Register definitions and register context (a context is a collection of registers). For example `NativeRegisterContextLinux_arm64`. * Unwinding support for backtracing. LLDB needs to be taught about any - architecture specific directives. + architecture-specific directives. * Instruction emulation. For example `EmulateInstructionARM64`. Most targets - need to emulate a small amount of instructions for unwinding. If you lack - hardware single step, you will need to emulate many times more than that. + need to emulate a small number of instructions for unwinding. If your target + does not have hardware single-step, you will need to emulate many times more + than that. The order of implementation will vary in each case. Each component does not need to be fully implemented for you to start work on the next. >From 7ab37cb14554ec90bd48e950d8ed709f0292f65f Mon Sep 17 00:00:00 2001 From: David Spickett <[email protected]> Date: Fri, 3 Jul 2026 11:03:41 +0000 Subject: [PATCH 5/5] wrapping --- lldb/docs/resources/addingtargetsupport.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/lldb/docs/resources/addingtargetsupport.md b/lldb/docs/resources/addingtargetsupport.md index b338e8a51bea8..f24163b34203d 100644 --- a/lldb/docs/resources/addingtargetsupport.md +++ b/lldb/docs/resources/addingtargetsupport.md @@ -89,8 +89,8 @@ adequately maintain the code upstream: * 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 will only employees of a specific company work on it. -* When it breaks, how easy will it be for the upstream LLDB community to continue - their work without disruption? +* 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 @@ -123,7 +123,8 @@ of some targets will be bigger than "big" or smaller than "small". 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. + * 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. _______________________________________________ lldb-commits mailing list [email protected] https://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
