From 121bef76df415e4cfc9543630b23f2e648b9a18a Mon Sep 17 00:00:00 2001 From: Fangrui Song Date: Fri, 3 May 2024 10:16:54 -0700 Subject: [PATCH] [docs,utils] Convert text files from CRLF to LF Skip *.bat, *.natvis, utils/lit/tests/Inputs/shtest-shell/diff-in.dos --- llvm/docs/CommandGuide/llvm-pdbutil.rst | 76 +- llvm/docs/GettingInvolved.rst | 1022 +++++++++++------------ llvm/docs/GettingStartedTutorials.rst | 86 +- llvm/docs/PDB/CodeViewSymbols.rst | 6 +- llvm/docs/Reference.rst | 468 +++++------ llvm/docs/UserGuides.rst | 572 ++++++------- llvm/utils/emacs/llvm-mir-mode.el | 140 ++-- 7 files changed, 1185 insertions(+), 1185 deletions(-) diff --git a/llvm/docs/CommandGuide/llvm-pdbutil.rst b/llvm/docs/CommandGuide/llvm-pdbutil.rst index 955353187112..74e1444794df 100644 --- a/llvm/docs/CommandGuide/llvm-pdbutil.rst +++ b/llvm/docs/CommandGuide/llvm-pdbutil.rst @@ -27,18 +27,18 @@ Subcommands a different purpose. A brief summary of each command follows, with more detail in the sections that follow. - * :ref:`pretty_subcommand` - Dump symbol and type information in a format that + * :ref:`pretty_subcommand` - Dump symbol and type information in a format that tries to look as much like the original source code as possible. - * :ref:`dump_subcommand` - Dump low level types and structures from the PDB + * :ref:`dump_subcommand` - Dump low level types and structures from the PDB file, including CodeView records, hash tables, PDB streams, etc. - * :ref:`bytes_subcommand` - Dump data from the PDB file's streams, records, + * :ref:`bytes_subcommand` - Dump data from the PDB file's streams, records, types, symbols, etc as raw bytes. - * :ref:`yaml2pdb_subcommand` - Given a yaml description of a PDB file, produce + * :ref:`yaml2pdb_subcommand` - Given a yaml description of a PDB file, produce a valid PDB file that matches that description. - * :ref:`pdb2yaml_subcommand` - For a given PDB file, produce a YAML - description of some or all of the file in a way that the PDB can be + * :ref:`pdb2yaml_subcommand` - For a given PDB file, produce a YAML + description of some or all of the file in a way that the PDB can be reconstructed. - * :ref:`merge_subcommand` - Given two PDBs, produce a third PDB that is the + * :ref:`merge_subcommand` - Given two PDBs, produce a third PDB that is the result of merging the two input PDBs. .. _pretty_subcommand: @@ -49,7 +49,7 @@ pretty .. program:: llvm-pdbutil pretty .. important:: - The **pretty** subcommand is built on the Windows DIA SDK, and as such is not + The **pretty** subcommand is built on the Windows DIA SDK, and as such is not supported on non-Windows platforms. USAGE: :program:`llvm-pdbutil` pretty [*options*] @@ -57,10 +57,10 @@ USAGE: :program:`llvm-pdbutil` pretty [*options*] Summary ^^^^^^^^^^^ -The *pretty* subcommand displays a very high level representation of your -program's debug info. Since it is built on the Windows DIA SDK which is the -standard API that Windows tools and debuggers query debug information, it -presents a more authoritative view of how a debugger is going to interpret your +The *pretty* subcommand displays a very high level representation of your +program's debug info. Since it is built on the Windows DIA SDK which is the +standard API that Windows tools and debuggers query debug information, it +presents a more authoritative view of how a debugger is going to interpret your debug information than a mode which displays low-level CodeView records. Options @@ -70,55 +70,55 @@ Filtering and Sorting Options +++++++++++++++++++++++++++++ .. note:: - *exclude* filters take priority over *include* filters. So if a filter + *exclude* filters take priority over *include* filters. So if a filter matches both an include and an exclude rule, then it is excluded. .. option:: -exclude-compilands= - When dumping compilands, compiland source-file contributions, or per-compiland - symbols, this option instructs **llvm-pdbutil** to omit any compilands that + When dumping compilands, compiland source-file contributions, or per-compiland + symbols, this option instructs **llvm-pdbutil** to omit any compilands that match the specified regular expression. .. option:: -exclude-symbols= - When dumping global, public, or per-compiland symbols, this option instructs - **llvm-pdbutil** to omit any symbols that match the specified regular + When dumping global, public, or per-compiland symbols, this option instructs + **llvm-pdbutil** to omit any symbols that match the specified regular expression. .. option:: -exclude-types= - When dumping types, this option instructs **llvm-pdbutil** to omit any types + When dumping types, this option instructs **llvm-pdbutil** to omit any types that match the specified regular expression. .. option:: -include-compilands= - When dumping compilands, compiland source-file contributions, or per-compiland - symbols, limit the initial search to only those compilands that match the + When dumping compilands, compiland source-file contributions, or per-compiland + symbols, limit the initial search to only those compilands that match the specified regular expression. .. option:: -include-symbols= - When dumping global, public, or per-compiland symbols, limit the initial + When dumping global, public, or per-compiland symbols, limit the initial search to only those symbols that match the specified regular expression. .. option:: -include-types= - When dumping types, limit the initial search to only those types that match + When dumping types, limit the initial search to only those types that match the specified regular expression. .. option:: -min-class-padding= - Only display types that have at least the specified amount of alignment + Only display types that have at least the specified amount of alignment padding, accounting for padding in base classes and aggregate field members. .. option:: -min-class-padding-imm= - Only display types that have at least the specified amount of alignment + Only display types that have at least the specified amount of alignment padding, ignoring padding in base classes and aggregate field members. .. option:: -min-type-size= - Only display types T where sizeof(T) is greater than or equal to the specified + Only display types T where sizeof(T) is greater than or equal to the specified amount. .. option:: -no-compiler-generated @@ -127,7 +127,7 @@ Filtering and Sorting Options .. option:: -no-enum-definitions - When dumping an enum, don't show the full enum (e.g. the individual enumerator + When dumping an enum, don't show the full enum (e.g. the individual enumerator values). .. option:: -no-system-libs @@ -233,12 +233,12 @@ Other Options .. option:: -color-output - Force color output on or off. By default, color if used if outputting to a + Force color output on or off. By default, color if used if outputting to a terminal. .. option:: -load-address= - When displaying relative virtual addresses, assume the process is loaded at the + When displaying relative virtual addresses, assume the process is loaded at the given address and display what would be the absolute address. .. _dump_subcommand: @@ -253,14 +253,14 @@ USAGE: :program:`llvm-pdbutil` dump [*options*] Summary ^^^^^^^^^^^ -The **dump** subcommand displays low level information about the structure of a -PDB file. It is used heavily by LLVM's testing infrastructure, but can also be -used for PDB forensics. It serves a role similar to that of Microsoft's -`cvdump` tool. - -.. note:: - The **dump** subcommand exposes internal details of the file format. As - such, the reader should be familiar with :doc:`/PDB/index` before using this +The **dump** subcommand displays low level information about the structure of a +PDB file. It is used heavily by LLVM's testing infrastructure, but can also be +used for PDB forensics. It serves a role similar to that of Microsoft's +`cvdump` tool. + +.. note:: + The **dump** subcommand exposes internal details of the file format. As + such, the reader should be familiar with :doc:`/PDB/index` before using this command. Options @@ -388,8 +388,8 @@ Type Record Options When used in conjunction with :option:`-type-index` or :option:`-id-index`, dumps the entire dependency graph for the specified index instead of just the single record with the specified index. For example, if type index 0x4000 is - a function whose return type has index 0x3000, and you specify - `-dependents=0x4000`, then this would dump both records (as well as any other + a function whose return type has index 0x3000, and you specify + `-dependents=0x4000`, then this would dump both records (as well as any other dependents in the tree). Miscellaneous Options diff --git a/llvm/docs/GettingInvolved.rst b/llvm/docs/GettingInvolved.rst index a45d73a9a3d4..f5df71e661cc 100644 --- a/llvm/docs/GettingInvolved.rst +++ b/llvm/docs/GettingInvolved.rst @@ -1,511 +1,511 @@ -Getting Involved -================ - -LLVM welcomes contributions of all kinds. To get started, please review the following topics: - -.. contents:: - :local: - -.. toctree:: - :hidden: - - Contributing - DeveloperPolicy - CodeReview - SupportPolicy - SphinxQuickstartTemplate - HowToSubmitABug - BugLifeCycle - CodingStandards - GitHub - GitBisecting - GitRepositoryPolicy - -:doc:`Contributing` - An overview on how to contribute to LLVM. - -:doc:`DeveloperPolicy` - The LLVM project's policy towards developers and their contributions. - -:doc:`CodeReview` - The LLVM project's code-review process. - -:doc:`SupportPolicy` - The LLVM support policy for core and non-core components. - -:doc:`SphinxQuickstartTemplate` - A template + tutorial for writing new Sphinx documentation. It is meant - to be read in source form. - -:doc:`HowToSubmitABug` - Instructions for properly submitting information about any bugs you run into - in the LLVM system. - -:doc:`BugLifeCycle` - Describes how bugs are reported, triaged and closed. - -:doc:`CodingStandards` - Details the LLVM coding standards and provides useful information on writing - efficient C++ code. - -:doc:`GitHub` - Describes how to use the llvm-project repository and code reviews on GitHub. - -:doc:`GitBisecting` - Describes how to use ``git bisect`` on LLVM's repository. - -:doc:`GitRepositoryPolicy` - Collection of policies around the git repositories. - -.. _development-process: - -Development Process -------------------- - -Information about LLVM's development process. - -.. toctree:: - :hidden: - - Projects - HowToReleaseLLVM - ReleaseProcess - HowToAddABuilder - ReleaseNotes - -:doc:`Projects` - How-to guide and templates for new projects that *use* the LLVM - infrastructure. The templates (directory organization, Makefiles, and test - tree) allow the project code to be located outside (or inside) the ``llvm/`` - tree, while using LLVM header files and libraries. - -:doc:`HowToReleaseLLVM` - This is a guide to preparing LLVM releases. Most developers can ignore it. - -:doc:`ReleaseProcess` - This is a guide to validate a new release, during the release process. Most developers can ignore it. - -:doc:`HowToAddABuilder` - Instructions for adding new builder to LLVM buildbot master. - -:doc:`Release notes for the current release ` - This describes new features, known bugs, and other limitations. - -.. _lists-forums: - -Forums & Mailing Lists ----------------------- - -If you can't find what you need in these docs, try consulting the -Discourse forums. There are also commit mailing lists for all commits to the LLVM Project. -The :doc:`CodeOfConduct` applies to all these forums and mailing lists. - -`LLVM Discourse`__ - The forums for all things LLVM and related sub-projects. There are categories and subcategories for a wide variety of areas within LLVM. You can also view tags or search for a specific topic. - - .. __: https://discourse.llvm.org/ - -`Commits Archive (llvm-commits)`__ - This list contains all commit messages that are made when LLVM developers - commit code changes to the repository. It also serves as a forum for - patch review (i.e. send patches here). It is useful for those who want to - stay on the bleeding edge of LLVM development. This list is very high - volume. - - .. __: http://lists.llvm.org/pipermail/llvm-commits/ - -`Bugs & Patches Archive (llvm-bugs)`__ - This list gets emailed every time a bug is opened and closed. It is - higher volume than the LLVM-dev list. - - .. __: http://lists.llvm.org/pipermail/llvm-bugs/ - -`LLVM Announcements`__ - If you just want project wide announcements such as releases, developers meetings, or blog posts, then you should check out the Announcement category on LLVM Discourse. - - .. __: https://discourse.llvm.org/c/announce/46 - -.. _online-sync-ups: - -Online Sync-Ups ---------------- - -A number of regular calls are organized on specific topics. It should be -expected that the range of topics will change over time. At the time of -writing, the following sync-ups are organized. -The :doc:`CodeOfConduct` applies to all online sync-ups. - -If you'd like to organize a new sync-up, please add the info in the table -below. Please also create a calendar event for it and invite calendar@llvm.org -to the event, so that it'll show up on the :ref:`llvm-community-calendar`. -Please see :ref:`llvm-community-calendar-host-guidance` for more guidance on -what to add to your calendar invite. - -.. list-table:: LLVM regular sync-up calls - :widths: 25 25 25 25 - :header-rows: 1 - - * - Topic - - Frequency - - Calendar link - - Minutes/docs link - * - Loop Optimization Working Group - - Every 2 weeks on Wednesday - - `ics <./_static/LoopOptWG_invite.ics>`__ - - `Minutes/docs `__ - * - RISC-V - - Every 2 weeks on Thursday - - `ics `__ - `gcal `__ - - `Minutes/docs `__ - * - ML Guided Compiler Optimizations - - Monthly - - - - `Minutes/docs `__ - * - `LLVM security group `__ - - Monthly, every 3rd Tuesday - - `ics `__ - `gcal `__ - - `Minutes/docs `__ - * - `CIRCT `__ - - Weekly, on Wednesday - - - - `Minutes/docs `__ - * - flang - - Multiple meeting series, `documented here `__ - - - - - * - OpenMP - - Multiple meeting series, `documented here `__ - - - - - * - LLVM Alias Analysis - - Every 4 weeks on Tuesdays - - `ics `__ - - `Minutes/docs `__ - * - LLVM Pointer Authentication - - Every month on Mondays - - `ics `__ - - `Minutes/docs `__ - * - LLVM Embedded Toolchains - - Every 4 weeks on Thursdays - - `ics `__ - `gcal `__ - - `Minutes/docs `__ - * - Clang C and C++ Language Working Group - - 1st and 3rd Wednesday of the month - - `gcal `__ - - `Minutes/docs `__ - * - LLVM SPIR-V Backend Working Group - - Every week on Monday - - - - `Meeting details/agenda `__ - * - SYCL Upstream Working Group - - Every 2 weeks on Mondays - - `gcal `__ - - `Meeting details/agenda `__ - * - Floating Point Working Group - - Every 3rd Wednesday of the month - - `ics `__ - `gcal `__ - - `Meeting details/agenda: `__ - -Past online sync-ups -^^^^^^^^^^^^^^^^^^^^ - -Some online sync-ups are no longer happening. We keep pointing to them here to -keep track of the meeting notes and in case anyone would want to revive them in -the future. - -.. list-table:: LLVM no-longer-happening sync-up calls - :widths: 25 25 25 25 - :header-rows: 1 - - * - Topic - - Frequency - - Calendar link - - Minutes/docs link - * - Scalable Vectors and Arm SVE - - Monthly, every 3rd Tuesday - - `ics `__ - `gcal `__ - - `Minutes/docs `__ - * - MemorySSA in LLVM - - Every 8 weeks on Mondays - - `ics `__ - `gcal `__ - - `Minutes/docs `__ - * - GlobalISel - - Every 2nd Tuesday of the month - - `gcal `__ - - `Meeting details/agenda `__ - * - Vector Predication - - Every 2 weeks on Tuesdays, 3pm UTC - - - - `Minutes/docs `__ - * - `MLIR `__ design meetings - - Weekly, on Thursdays - - - - `Minutes/docs `__ - -.. _office-hours: - -Office hours ------------- - -A number of experienced LLVM contributors make themselves available for a chat -on a regular schedule, to anyone who is looking for some guidance. Please find -the list of who is available when, through which medium, and what their area of -expertise is. Don't be too shy to dial in! - -Office hours are also listed on the :ref:`llvm-community-calendar`. Of course, -people take time off from time to time, so if you dial in and you don't find -anyone present, chances are they happen to be off that day. - -The :doc:`CodeOfConduct` applies to all office hours. - -.. list-table:: LLVM office hours - :widths: 15 40 15 15 15 - :header-rows: 1 - - * - Name - - In-scope topics - - When? - - Where? - - Languages - * - Kristof Beyls - - General questions on how to contribute to LLVM; organizing meetups; - submitting talks; and other general LLVM-related topics. Arm/AArch64 - codegen. LLVM security group. LLVM Office Hours. - - Every 2nd and 4th Wednesday of the month at 9.30am CET, for 30 minutes. - `ics `__ - - `Jitsi `__ - - English, Flemish, Dutch - * - Alina Sbirlea - - General questions on how to contribute to LLVM; women in compilers; - MemorySSA, BatchAA, various loop passes, new pass manager. - - Monthly, 2nd Tuesdays, 10.00am PT/7:00pm CET, for 30 minutes. - `ics `__ - `gcal `__ - - `GoogleMeet `__ - - English, Romanian - * - Aaron Ballman (he/him) - - Clang internals; frontend attributes; clang-tidy; clang-query; AST matchers - - Monthly, 2nd Monday and 3rd Friday of the month at 10:00am Eastern and again at 2:00pm Eastern, for 60 minutes. - `ics `__ - `gcal `__ - - `GoogleMeet `__ - - English, Norwegian (not fluently) - * - Johannes Doerfert (he/him) - - OpenMP, LLVM-IR, interprocedural optimizations, Attributor, workshops, research, ... - - Every week, Wednesdays 9:30am (Pacific Time), for 1 hour. - `ics `__ - - `MS Teams `__ - - English, German - * - Tobias Grosser - - General questions on how to contribute to LLVM/MLIR, Polly, Loop Optimization, FPL, Research in LLVM, PhD in CS, Summer of Code. - - Monthly, last Monday of the month at 18:00 London time (typically 9am PT), for 30 minutes. - - `Video Call `__ - - English, German, Spanish, French - * - Anastasia Stulova - - Clang internals for C/C++ language extensions and dialects, OpenCL, GPU, SPIR-V, how to contribute, women in compilers. - - Monthly, 1st Tuesday of the month at 17:00 BST - London time (9:00am PT except for 2 weeks in spring), 30 mins slot. - - `GoogleMeet `__ - - English, Russian, German (not fluently) - * - Alexey Bader - - SYCL compiler, offload tools, OpenCL and SPIR-V, how to contribute. - - Monthly, 2nd Monday of the month at 9:30am PT, for 30 minutes. - - `GoogleMeet `__ - - English, Russian - * - Maksim Panchenko - - BOLT internals, IR, new passes, proposals, etc. - - Monthly, 2nd Wednesday of the month at 11:00am PT, for 30 minutes. - - `Zoom `__ - - English, Russian - * - Quentin Colombet (he/him) - - LLVM/MLIR; Codegen (Instruction selection (GlobalISel/SDISel), Machine IR, - Register allocation, etc.); Optimizations; MCA - - Monthly, 1st Wednesday of the month at 8.00am PT, for 30 minutes. - `ics `__ - `gcal `__ - - `Google meet `__ - - English, French - * - Phoebe Wang (she/her) - - X86 backend, General questions to X86, women in compilers. - - Monthly, 3rd Wednesday of the month at 8:30am Beijing time, for 30 minutes. - - `MS Teams `__ - - English, Chinese - * - Amara Emerson - - GlobalISel questions. - - Monthly, 4th Wednesday of the month at 9:30am PT, for 30 minutes. - - `Google meet `__ - - English - * - Maksim Levental and Jeremy Kun - - MLIR newcomers and general discussion (`livestreamed `__) - - Every two weeks, Fridays at 3:00pm US Pacific, for 90 minutes. - - Livestream chat or `Google meet `__ - - English - * - Rotating hosts - - Getting Started, beginner questions, new contributors. - - Every Tuesday at 2 PM ET (11 AM PT), for 30 minutes. - - `Google meet `__ - - English - - -Guidance for office hours hosts -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -* If you're interested in becoming an office hours host, please add your - information to the list above. Please create a calendar event for it and - invite calendar@llvm.org to the event so that it'll show up on the - :ref:`llvm-community-calendar`. - Please see :ref:`llvm-community-calendar-host-guidance` for more guidance on - what to add to your calendar invite. -* When starting an office hours session, consider typing something like "*Hi, - I'm available for chats in the next half hour at* video chat URL. *I'm - looking forward to having conversations on the video chat or here.*" on the - LLVM chat channels that you are already on. These could include: - - * the `#office-hours Discord channel - `__. - * :ref:`IRC` - - Doing this can help: - * overcome potential anxiety to call in for a first time, - * people who prefer to first exchange a few messages through text chat - before dialing in, and - * remind the wider community that office hours do exist. -* If you decide to no longer host office hours, please do remove your entry - from the list above. - - -.. _IRC: - -IRC ---- - -Users and developers of the LLVM project (including subprojects such as Clang) -can be found in #llvm on `irc.oftc.net `_. The channel -is actively moderated. - -The #llvm-build channel has a bot for -`LLVM buildbot `_ status changes. The -bot will post a message with a link to a build bot and a blamelist when a build -goes from passing to failing and again (without the blamelist) when the build -goes from failing back to passing. It is a good channel for actively monitoring -build statuses, but it is a noisy channel due to the automated messages. The -channel is not actively moderated. - -In addition to the traditional IRC there is a -`Discord `_ -chat server available. To sign up, please use this -`invitation link `_. - - -.. _meetups-social-events: - -Meetups and social events -------------------------- - -.. toctree:: - :hidden: - - MeetupGuidelines - -Besides developer `meetings and conferences `_, -there are several user groups called -`LLVM Socials `_. We greatly encourage you to -join one in your city. Or start a new one if there is none: - -:doc:`MeetupGuidelines` - -.. _community-proposals: - -Community wide proposals ------------------------- - -Proposals for massive changes in how the community behaves and how the work flow -can be better. - -.. toctree:: - :hidden: - - Proposals/GitHubMove - BugpointRedesign - Proposals/TestSuite - Proposals/VariableNames - Proposals/VectorPredication - -:doc:`Proposals/GitHubMove` - Proposal to move from SVN/Git to GitHub. - -:doc:`BugpointRedesign` - Design doc for a redesign of the Bugpoint tool. - -:doc:`Proposals/TestSuite` - Proposals for additional benchmarks/programs for llvm's test-suite. - -:doc:`Proposals/VariableNames` - Proposal to change the variable names coding standard. - -:doc:`Proposals/VectorPredication` - Proposal for predicated vector instructions in LLVM. - -.. _llvm-community-calendar: - -LLVM community calendar ------------------------ - -We aim to maintain a public calendar view of all events happening in the LLVM -community such as :ref:`online-sync-ups` and :ref:`office-hours`. The calendar -can be found at -https://calendar.google.com/calendar/u/0/embed?src=calendar@llvm.org and can -also be seen inline below: - -.. raw:: html - - - -Note that the web view of the LLVM community calendar shows events in -Coordinated Universal Time (UTC). If you use Google Calendar, consider -subscribing to it with the + button in the bottom-right corner to view all -events in your local timezone alongside your other calendars. - -.. _llvm-community-calendar-host-guidance: - -Guidance on what to put into LLVM community calendar invites -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -To add your event, create a calendar event for it and invite calendar@llvm.org -on it. Your event should then show up on the community calendar. - -Please put the following pieces of information in your calendar invite: - -* Write a single paragraph describing what the event is about. Include things - such as who the event is for and what sort of topics are discussed. -* State explicitly that the :doc:`CodeOfConduct` applies to this event. -* Make it clear who: - - * the organizer is. - - * the person to contact is in case of any code-of-conduct issues. Typically, - this would be the organizer. - -* If you have meeting minutes for your event, add a pointer to where those live. - A good place for meeting minutes could be as a post on LLVM Discourse. - -An example invite looks as follows - -.. code-block:: none - - This event is a meetup for all developers of LLDB. Meeting agendas are posted - on discourse before the event. - - Attendees are required to adhere to the LLVM Code of Conduct - (https://llvm.org/docs/CodeOfConduct.html). For any Code of Conduct reports, - please contact the organizers, and also email conduct@llvm.org. - - Agenda/Meeting Minutes: Link to minutes - - Organizer(s): First Surname (name@email.com) - +Getting Involved +================ + +LLVM welcomes contributions of all kinds. To get started, please review the following topics: + +.. contents:: + :local: + +.. toctree:: + :hidden: + + Contributing + DeveloperPolicy + CodeReview + SupportPolicy + SphinxQuickstartTemplate + HowToSubmitABug + BugLifeCycle + CodingStandards + GitHub + GitBisecting + GitRepositoryPolicy + +:doc:`Contributing` + An overview on how to contribute to LLVM. + +:doc:`DeveloperPolicy` + The LLVM project's policy towards developers and their contributions. + +:doc:`CodeReview` + The LLVM project's code-review process. + +:doc:`SupportPolicy` + The LLVM support policy for core and non-core components. + +:doc:`SphinxQuickstartTemplate` + A template + tutorial for writing new Sphinx documentation. It is meant + to be read in source form. + +:doc:`HowToSubmitABug` + Instructions for properly submitting information about any bugs you run into + in the LLVM system. + +:doc:`BugLifeCycle` + Describes how bugs are reported, triaged and closed. + +:doc:`CodingStandards` + Details the LLVM coding standards and provides useful information on writing + efficient C++ code. + +:doc:`GitHub` + Describes how to use the llvm-project repository and code reviews on GitHub. + +:doc:`GitBisecting` + Describes how to use ``git bisect`` on LLVM's repository. + +:doc:`GitRepositoryPolicy` + Collection of policies around the git repositories. + +.. _development-process: + +Development Process +------------------- + +Information about LLVM's development process. + +.. toctree:: + :hidden: + + Projects + HowToReleaseLLVM + ReleaseProcess + HowToAddABuilder + ReleaseNotes + +:doc:`Projects` + How-to guide and templates for new projects that *use* the LLVM + infrastructure. The templates (directory organization, Makefiles, and test + tree) allow the project code to be located outside (or inside) the ``llvm/`` + tree, while using LLVM header files and libraries. + +:doc:`HowToReleaseLLVM` + This is a guide to preparing LLVM releases. Most developers can ignore it. + +:doc:`ReleaseProcess` + This is a guide to validate a new release, during the release process. Most developers can ignore it. + +:doc:`HowToAddABuilder` + Instructions for adding new builder to LLVM buildbot master. + +:doc:`Release notes for the current release ` + This describes new features, known bugs, and other limitations. + +.. _lists-forums: + +Forums & Mailing Lists +---------------------- + +If you can't find what you need in these docs, try consulting the +Discourse forums. There are also commit mailing lists for all commits to the LLVM Project. +The :doc:`CodeOfConduct` applies to all these forums and mailing lists. + +`LLVM Discourse`__ + The forums for all things LLVM and related sub-projects. There are categories and subcategories for a wide variety of areas within LLVM. You can also view tags or search for a specific topic. + + .. __: https://discourse.llvm.org/ + +`Commits Archive (llvm-commits)`__ + This list contains all commit messages that are made when LLVM developers + commit code changes to the repository. It also serves as a forum for + patch review (i.e. send patches here). It is useful for those who want to + stay on the bleeding edge of LLVM development. This list is very high + volume. + + .. __: http://lists.llvm.org/pipermail/llvm-commits/ + +`Bugs & Patches Archive (llvm-bugs)`__ + This list gets emailed every time a bug is opened and closed. It is + higher volume than the LLVM-dev list. + + .. __: http://lists.llvm.org/pipermail/llvm-bugs/ + +`LLVM Announcements`__ + If you just want project wide announcements such as releases, developers meetings, or blog posts, then you should check out the Announcement category on LLVM Discourse. + + .. __: https://discourse.llvm.org/c/announce/46 + +.. _online-sync-ups: + +Online Sync-Ups +--------------- + +A number of regular calls are organized on specific topics. It should be +expected that the range of topics will change over time. At the time of +writing, the following sync-ups are organized. +The :doc:`CodeOfConduct` applies to all online sync-ups. + +If you'd like to organize a new sync-up, please add the info in the table +below. Please also create a calendar event for it and invite calendar@llvm.org +to the event, so that it'll show up on the :ref:`llvm-community-calendar`. +Please see :ref:`llvm-community-calendar-host-guidance` for more guidance on +what to add to your calendar invite. + +.. list-table:: LLVM regular sync-up calls + :widths: 25 25 25 25 + :header-rows: 1 + + * - Topic + - Frequency + - Calendar link + - Minutes/docs link + * - Loop Optimization Working Group + - Every 2 weeks on Wednesday + - `ics <./_static/LoopOptWG_invite.ics>`__ + - `Minutes/docs `__ + * - RISC-V + - Every 2 weeks on Thursday + - `ics `__ + `gcal `__ + - `Minutes/docs `__ + * - ML Guided Compiler Optimizations + - Monthly + - + - `Minutes/docs `__ + * - `LLVM security group `__ + - Monthly, every 3rd Tuesday + - `ics `__ + `gcal `__ + - `Minutes/docs `__ + * - `CIRCT `__ + - Weekly, on Wednesday + - + - `Minutes/docs `__ + * - flang + - Multiple meeting series, `documented here `__ + - + - + * - OpenMP + - Multiple meeting series, `documented here `__ + - + - + * - LLVM Alias Analysis + - Every 4 weeks on Tuesdays + - `ics `__ + - `Minutes/docs `__ + * - LLVM Pointer Authentication + - Every month on Mondays + - `ics `__ + - `Minutes/docs `__ + * - LLVM Embedded Toolchains + - Every 4 weeks on Thursdays + - `ics `__ + `gcal `__ + - `Minutes/docs `__ + * - Clang C and C++ Language Working Group + - 1st and 3rd Wednesday of the month + - `gcal `__ + - `Minutes/docs `__ + * - LLVM SPIR-V Backend Working Group + - Every week on Monday + - + - `Meeting details/agenda `__ + * - SYCL Upstream Working Group + - Every 2 weeks on Mondays + - `gcal `__ + - `Meeting details/agenda `__ + * - Floating Point Working Group + - Every 3rd Wednesday of the month + - `ics `__ + `gcal `__ + - `Meeting details/agenda: `__ + +Past online sync-ups +^^^^^^^^^^^^^^^^^^^^ + +Some online sync-ups are no longer happening. We keep pointing to them here to +keep track of the meeting notes and in case anyone would want to revive them in +the future. + +.. list-table:: LLVM no-longer-happening sync-up calls + :widths: 25 25 25 25 + :header-rows: 1 + + * - Topic + - Frequency + - Calendar link + - Minutes/docs link + * - Scalable Vectors and Arm SVE + - Monthly, every 3rd Tuesday + - `ics `__ + `gcal `__ + - `Minutes/docs `__ + * - MemorySSA in LLVM + - Every 8 weeks on Mondays + - `ics `__ + `gcal `__ + - `Minutes/docs `__ + * - GlobalISel + - Every 2nd Tuesday of the month + - `gcal `__ + - `Meeting details/agenda `__ + * - Vector Predication + - Every 2 weeks on Tuesdays, 3pm UTC + - + - `Minutes/docs `__ + * - `MLIR `__ design meetings + - Weekly, on Thursdays + - + - `Minutes/docs `__ + +.. _office-hours: + +Office hours +------------ + +A number of experienced LLVM contributors make themselves available for a chat +on a regular schedule, to anyone who is looking for some guidance. Please find +the list of who is available when, through which medium, and what their area of +expertise is. Don't be too shy to dial in! + +Office hours are also listed on the :ref:`llvm-community-calendar`. Of course, +people take time off from time to time, so if you dial in and you don't find +anyone present, chances are they happen to be off that day. + +The :doc:`CodeOfConduct` applies to all office hours. + +.. list-table:: LLVM office hours + :widths: 15 40 15 15 15 + :header-rows: 1 + + * - Name + - In-scope topics + - When? + - Where? + - Languages + * - Kristof Beyls + - General questions on how to contribute to LLVM; organizing meetups; + submitting talks; and other general LLVM-related topics. Arm/AArch64 + codegen. LLVM security group. LLVM Office Hours. + - Every 2nd and 4th Wednesday of the month at 9.30am CET, for 30 minutes. + `ics `__ + - `Jitsi `__ + - English, Flemish, Dutch + * - Alina Sbirlea + - General questions on how to contribute to LLVM; women in compilers; + MemorySSA, BatchAA, various loop passes, new pass manager. + - Monthly, 2nd Tuesdays, 10.00am PT/7:00pm CET, for 30 minutes. + `ics `__ + `gcal `__ + - `GoogleMeet `__ + - English, Romanian + * - Aaron Ballman (he/him) + - Clang internals; frontend attributes; clang-tidy; clang-query; AST matchers + - Monthly, 2nd Monday and 3rd Friday of the month at 10:00am Eastern and again at 2:00pm Eastern, for 60 minutes. + `ics `__ + `gcal `__ + - `GoogleMeet `__ + - English, Norwegian (not fluently) + * - Johannes Doerfert (he/him) + - OpenMP, LLVM-IR, interprocedural optimizations, Attributor, workshops, research, ... + - Every week, Wednesdays 9:30am (Pacific Time), for 1 hour. + `ics `__ + - `MS Teams `__ + - English, German + * - Tobias Grosser + - General questions on how to contribute to LLVM/MLIR, Polly, Loop Optimization, FPL, Research in LLVM, PhD in CS, Summer of Code. + - Monthly, last Monday of the month at 18:00 London time (typically 9am PT), for 30 minutes. + - `Video Call `__ + - English, German, Spanish, French + * - Anastasia Stulova + - Clang internals for C/C++ language extensions and dialects, OpenCL, GPU, SPIR-V, how to contribute, women in compilers. + - Monthly, 1st Tuesday of the month at 17:00 BST - London time (9:00am PT except for 2 weeks in spring), 30 mins slot. + - `GoogleMeet `__ + - English, Russian, German (not fluently) + * - Alexey Bader + - SYCL compiler, offload tools, OpenCL and SPIR-V, how to contribute. + - Monthly, 2nd Monday of the month at 9:30am PT, for 30 minutes. + - `GoogleMeet `__ + - English, Russian + * - Maksim Panchenko + - BOLT internals, IR, new passes, proposals, etc. + - Monthly, 2nd Wednesday of the month at 11:00am PT, for 30 minutes. + - `Zoom `__ + - English, Russian + * - Quentin Colombet (he/him) + - LLVM/MLIR; Codegen (Instruction selection (GlobalISel/SDISel), Machine IR, + Register allocation, etc.); Optimizations; MCA + - Monthly, 1st Wednesday of the month at 8.00am PT, for 30 minutes. + `ics `__ + `gcal `__ + - `Google meet `__ + - English, French + * - Phoebe Wang (she/her) + - X86 backend, General questions to X86, women in compilers. + - Monthly, 3rd Wednesday of the month at 8:30am Beijing time, for 30 minutes. + - `MS Teams `__ + - English, Chinese + * - Amara Emerson + - GlobalISel questions. + - Monthly, 4th Wednesday of the month at 9:30am PT, for 30 minutes. + - `Google meet `__ + - English + * - Maksim Levental and Jeremy Kun + - MLIR newcomers and general discussion (`livestreamed `__) + - Every two weeks, Fridays at 3:00pm US Pacific, for 90 minutes. + - Livestream chat or `Google meet `__ + - English + * - Rotating hosts + - Getting Started, beginner questions, new contributors. + - Every Tuesday at 2 PM ET (11 AM PT), for 30 minutes. + - `Google meet `__ + - English + + +Guidance for office hours hosts +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* If you're interested in becoming an office hours host, please add your + information to the list above. Please create a calendar event for it and + invite calendar@llvm.org to the event so that it'll show up on the + :ref:`llvm-community-calendar`. + Please see :ref:`llvm-community-calendar-host-guidance` for more guidance on + what to add to your calendar invite. +* When starting an office hours session, consider typing something like "*Hi, + I'm available for chats in the next half hour at* video chat URL. *I'm + looking forward to having conversations on the video chat or here.*" on the + LLVM chat channels that you are already on. These could include: + + * the `#office-hours Discord channel + `__. + * :ref:`IRC` + + Doing this can help: + * overcome potential anxiety to call in for a first time, + * people who prefer to first exchange a few messages through text chat + before dialing in, and + * remind the wider community that office hours do exist. +* If you decide to no longer host office hours, please do remove your entry + from the list above. + + +.. _IRC: + +IRC +--- + +Users and developers of the LLVM project (including subprojects such as Clang) +can be found in #llvm on `irc.oftc.net `_. The channel +is actively moderated. + +The #llvm-build channel has a bot for +`LLVM buildbot `_ status changes. The +bot will post a message with a link to a build bot and a blamelist when a build +goes from passing to failing and again (without the blamelist) when the build +goes from failing back to passing. It is a good channel for actively monitoring +build statuses, but it is a noisy channel due to the automated messages. The +channel is not actively moderated. + +In addition to the traditional IRC there is a +`Discord `_ +chat server available. To sign up, please use this +`invitation link `_. + + +.. _meetups-social-events: + +Meetups and social events +------------------------- + +.. toctree:: + :hidden: + + MeetupGuidelines + +Besides developer `meetings and conferences `_, +there are several user groups called +`LLVM Socials `_. We greatly encourage you to +join one in your city. Or start a new one if there is none: + +:doc:`MeetupGuidelines` + +.. _community-proposals: + +Community wide proposals +------------------------ + +Proposals for massive changes in how the community behaves and how the work flow +can be better. + +.. toctree:: + :hidden: + + Proposals/GitHubMove + BugpointRedesign + Proposals/TestSuite + Proposals/VariableNames + Proposals/VectorPredication + +:doc:`Proposals/GitHubMove` + Proposal to move from SVN/Git to GitHub. + +:doc:`BugpointRedesign` + Design doc for a redesign of the Bugpoint tool. + +:doc:`Proposals/TestSuite` + Proposals for additional benchmarks/programs for llvm's test-suite. + +:doc:`Proposals/VariableNames` + Proposal to change the variable names coding standard. + +:doc:`Proposals/VectorPredication` + Proposal for predicated vector instructions in LLVM. + +.. _llvm-community-calendar: + +LLVM community calendar +----------------------- + +We aim to maintain a public calendar view of all events happening in the LLVM +community such as :ref:`online-sync-ups` and :ref:`office-hours`. The calendar +can be found at +https://calendar.google.com/calendar/u/0/embed?src=calendar@llvm.org and can +also be seen inline below: + +.. raw:: html + + + +Note that the web view of the LLVM community calendar shows events in +Coordinated Universal Time (UTC). If you use Google Calendar, consider +subscribing to it with the + button in the bottom-right corner to view all +events in your local timezone alongside your other calendars. + +.. _llvm-community-calendar-host-guidance: + +Guidance on what to put into LLVM community calendar invites +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To add your event, create a calendar event for it and invite calendar@llvm.org +on it. Your event should then show up on the community calendar. + +Please put the following pieces of information in your calendar invite: + +* Write a single paragraph describing what the event is about. Include things + such as who the event is for and what sort of topics are discussed. +* State explicitly that the :doc:`CodeOfConduct` applies to this event. +* Make it clear who: + + * the organizer is. + + * the person to contact is in case of any code-of-conduct issues. Typically, + this would be the organizer. + +* If you have meeting minutes for your event, add a pointer to where those live. + A good place for meeting minutes could be as a post on LLVM Discourse. + +An example invite looks as follows + +.. code-block:: none + + This event is a meetup for all developers of LLDB. Meeting agendas are posted + on discourse before the event. + + Attendees are required to adhere to the LLVM Code of Conduct + (https://llvm.org/docs/CodeOfConduct.html). For any Code of Conduct reports, + please contact the organizers, and also email conduct@llvm.org. + + Agenda/Meeting Minutes: Link to minutes + + Organizer(s): First Surname (name@email.com) + diff --git a/llvm/docs/GettingStartedTutorials.rst b/llvm/docs/GettingStartedTutorials.rst index a6541acf47ad..55060343ba36 100644 --- a/llvm/docs/GettingStartedTutorials.rst +++ b/llvm/docs/GettingStartedTutorials.rst @@ -1,43 +1,43 @@ -Getting Started/Tutorials -========================= - -For those new to the LLVM system. - -.. toctree:: - :hidden: - - CompilerWriterInfo - Frontend/PerformanceTips - GettingStarted - GettingStartedVS - ProgrammersManual - tutorial/index - MyFirstTypoFix - -:doc:`GettingStarted` - Discusses how to get up and running quickly with the LLVM infrastructure. - Everything from unpacking and compilation of the distribution to execution - of some tools. - -:doc:`tutorial/index` - Tutorials about using LLVM. Includes a tutorial about making a custom - language with LLVM. - -:doc:`ProgrammersManual` - Introduction to the general layout of the LLVM sourcebase, important classes - and APIs, and some tips & tricks. - -:doc:`Frontend/PerformanceTips` - A collection of tips for frontend authors on how to generate IR - which LLVM is able to effectively optimize. - -:doc:`GettingStartedVS` - An addendum to the main Getting Started guide for those using Visual Studio - on Windows. - -:doc:`CompilerWriterInfo` - A list of helpful links for compiler writers. - -:doc:`MyFirstTypoFix` - This tutorial will guide you through the process of making a change to - LLVM, and contributing it back to the LLVM project. +Getting Started/Tutorials +========================= + +For those new to the LLVM system. + +.. toctree:: + :hidden: + + CompilerWriterInfo + Frontend/PerformanceTips + GettingStarted + GettingStartedVS + ProgrammersManual + tutorial/index + MyFirstTypoFix + +:doc:`GettingStarted` + Discusses how to get up and running quickly with the LLVM infrastructure. + Everything from unpacking and compilation of the distribution to execution + of some tools. + +:doc:`tutorial/index` + Tutorials about using LLVM. Includes a tutorial about making a custom + language with LLVM. + +:doc:`ProgrammersManual` + Introduction to the general layout of the LLVM sourcebase, important classes + and APIs, and some tips & tricks. + +:doc:`Frontend/PerformanceTips` + A collection of tips for frontend authors on how to generate IR + which LLVM is able to effectively optimize. + +:doc:`GettingStartedVS` + An addendum to the main Getting Started guide for those using Visual Studio + on Windows. + +:doc:`CompilerWriterInfo` + A list of helpful links for compiler writers. + +:doc:`MyFirstTypoFix` + This tutorial will guide you through the process of making a change to + LLVM, and contributing it back to the LLVM project. diff --git a/llvm/docs/PDB/CodeViewSymbols.rst b/llvm/docs/PDB/CodeViewSymbols.rst index b056b804e5ad..0f218db412f3 100644 --- a/llvm/docs/PDB/CodeViewSymbols.rst +++ b/llvm/docs/PDB/CodeViewSymbols.rst @@ -93,9 +93,9 @@ the compiler decided to emit is impractical. This differs from DWARF, where eve though we don't necessarily have O(1) lookup by basename within a given scope (including O(1) scope, we at least have O(n) access within a given scope). -.. important:: - Program-wide lookup of names by anything other than an exact textually matching fully - qualified name is not possible. +.. important:: + Program-wide lookup of names by anything other than an exact textually matching fully + qualified name is not possible. S_GDATA32 diff --git a/llvm/docs/Reference.rst b/llvm/docs/Reference.rst index 1661c8c533db..df61628b06c7 100644 --- a/llvm/docs/Reference.rst +++ b/llvm/docs/Reference.rst @@ -1,234 +1,234 @@ -Reference -========= - -LLVM and API reference documentation. - -.. contents:: - :local: - -.. toctree:: - :hidden: - - Atomics - BitCodeFormat - BlockFrequencyTerminology - BranchWeightMetadata - Bugpoint - CommandGuide/index - ConvergenceAndUniformity - ConvergentOperations - Coroutines - DependenceGraphs/index - ExceptionHandling - Extensions - FaultMaps - FuzzingLLVM - GarbageCollection - GetElementPtr - GlobalISel/index - GwpAsan - HowToSetUpLLVMStyleRTTI - HowToUseAttributes - InAlloca - LangRef - LibFuzzer - MarkedUpDisassembly - MIRLangRef - OptBisect - PCSectionsMetadata - PDB/index - PointerAuth - ScudoHardenedAllocator - MemoryModelRelaxationAnnotations - MemTagSanitizer - Security - SecurityTransparencyReports - SegmentedStacks - StackMaps - SpeculativeLoadHardening - Statepoints - SymbolizerMarkupFormat - SystemLibrary - TestingGuide - TransformMetadata - TypeMetadata - XRay - XRayExample - XRayFDRFormat - YamlIO - -API Reference -------------- - -`Doxygen generated documentation `_ - (`classes `_) - -:doc:`HowToUseAttributes` - Answers some questions about the new Attributes infrastructure. - -LLVM Reference --------------- - -====================== -Command Line Utilities -====================== - -:doc:`LLVM Command Guide ` - A reference manual for the LLVM command line utilities ("man" pages for LLVM - tools). - -:doc:`Bugpoint` - Automatic bug finder and test-case reducer description and usage - information. - -:doc:`OptBisect` - A command line option for debugging optimization-induced failures. - -:doc:`SymbolizerMarkupFormat` - A reference for the log symbolizer markup accepted by ``llvm-symbolizer``. - -:doc:`The Microsoft PDB File Format ` - A detailed description of the Microsoft PDB (Program Database) file format. - -================== -Garbage Collection -================== - -:doc:`GarbageCollection` - The interfaces source-language compilers should use for compiling GC'd - programs. - -:doc:`Statepoints` - This describes a set of experimental extensions for garbage - collection support. - -========= -LibFuzzer -========= - -:doc:`LibFuzzer` - A library for writing in-process guided fuzzers. - -:doc:`FuzzingLLVM` - Information on writing and using Fuzzers to find bugs in LLVM. - -======== -LLVM IR -======== - -:doc:`LLVM Language Reference Manual ` - Defines the LLVM intermediate representation and the assembly form of the - different nodes. - -:doc:`InAlloca` - Description of the ``inalloca`` argument attribute. - -:doc:`BitCodeFormat` - This describes the file format and encoding used for LLVM "bc" files. - -:doc:`Machine IR (MIR) Format Reference Manual ` - A reference manual for the MIR serialization format, which is used to test - LLVM's code generation passes. - -:doc:`GlobalISel/index` - This describes the prototype instruction selection replacement, GlobalISel. - -:doc:`ConvergentOperations` - Description of ``convergent`` operation semantics and related intrinsics. - -===================== -Testing and Debugging -===================== - -:doc:`LLVM Testing Infrastructure Guide ` - A reference manual for using the LLVM testing infrastructure. - -:doc:`TestSuiteGuide` - Describes how to compile and run the test-suite benchmarks. - - -:doc:`GwpAsan` - A sampled heap memory error detection toolkit designed for production use. - -==== -XRay -==== - -:doc:`XRay` - High-level documentation of how to use XRay in LLVM. - -:doc:`XRayExample` - An example of how to debug an application with XRay. - -================= -Additional Topics -================= - -:doc:`FaultMaps` - LLVM support for folding control flow into faulting machine instructions. - -:doc:`Atomics` - Information about LLVM's concurrency model. - -:doc:`ExceptionHandling` - This document describes the design and implementation of exception handling - in LLVM. - -:doc:`Extensions` - LLVM-specific extensions to tools and formats LLVM seeks compatibility with. - -:doc:`HowToSetUpLLVMStyleRTTI` - How to make ``isa<>``, ``dyn_cast<>``, etc. available for clients of your - class hierarchy. - -:doc:`BlockFrequencyTerminology` - Provides information about terminology used in the ``BlockFrequencyInfo`` - analysis pass. - -:doc:`BranchWeightMetadata` - Provides information about Branch Prediction Information. - -:doc:`GetElementPtr` - Answers to some very frequent questions about LLVM's most frequently - misunderstood instruction. - -:doc:`ScudoHardenedAllocator` - A library that implements a security-hardened `malloc()`. - -:doc:`MemoryModelRelaxationAnnotations` - Target-defined relaxation to LLVM's concurrency model. - -:doc:`MemTagSanitizer` - Security hardening for production code aiming to mitigate memory - related vulnerabilities. Based on the Armv8.5-A Memory Tagging Extension. - -:doc:`Dependence Graphs ` - A description of the design of the various dependence graphs such as - the DDG (Data Dependence Graph). - -:doc:`SpeculativeLoadHardening` - A description of the Speculative Load Hardening mitigation for Spectre v1. - -:doc:`SegmentedStacks` - This document describes segmented stacks and how they are used in LLVM. - -:doc:`MarkedUpDisassembly` - This document describes the optional rich disassembly output syntax. - -:doc:`StackMaps` - LLVM support for mapping instruction addresses to the location of - values and allowing code to be patched. - -:doc:`Coroutines` - LLVM support for coroutines. - -:doc:`PointerAuth` - A description of pointer authentication, its LLVM IR representation, and its - support in the backend. - -:doc:`YamlIO` - A reference guide for using LLVM's YAML I/O library. - -:doc:`ConvergenceAndUniformity` - A description of uniformity analysis in the presence of irreducible - control flow, and its implementation. +Reference +========= + +LLVM and API reference documentation. + +.. contents:: + :local: + +.. toctree:: + :hidden: + + Atomics + BitCodeFormat + BlockFrequencyTerminology + BranchWeightMetadata + Bugpoint + CommandGuide/index + ConvergenceAndUniformity + ConvergentOperations + Coroutines + DependenceGraphs/index + ExceptionHandling + Extensions + FaultMaps + FuzzingLLVM + GarbageCollection + GetElementPtr + GlobalISel/index + GwpAsan + HowToSetUpLLVMStyleRTTI + HowToUseAttributes + InAlloca + LangRef + LibFuzzer + MarkedUpDisassembly + MIRLangRef + OptBisect + PCSectionsMetadata + PDB/index + PointerAuth + ScudoHardenedAllocator + MemoryModelRelaxationAnnotations + MemTagSanitizer + Security + SecurityTransparencyReports + SegmentedStacks + StackMaps + SpeculativeLoadHardening + Statepoints + SymbolizerMarkupFormat + SystemLibrary + TestingGuide + TransformMetadata + TypeMetadata + XRay + XRayExample + XRayFDRFormat + YamlIO + +API Reference +------------- + +`Doxygen generated documentation `_ + (`classes `_) + +:doc:`HowToUseAttributes` + Answers some questions about the new Attributes infrastructure. + +LLVM Reference +-------------- + +====================== +Command Line Utilities +====================== + +:doc:`LLVM Command Guide ` + A reference manual for the LLVM command line utilities ("man" pages for LLVM + tools). + +:doc:`Bugpoint` + Automatic bug finder and test-case reducer description and usage + information. + +:doc:`OptBisect` + A command line option for debugging optimization-induced failures. + +:doc:`SymbolizerMarkupFormat` + A reference for the log symbolizer markup accepted by ``llvm-symbolizer``. + +:doc:`The Microsoft PDB File Format ` + A detailed description of the Microsoft PDB (Program Database) file format. + +================== +Garbage Collection +================== + +:doc:`GarbageCollection` + The interfaces source-language compilers should use for compiling GC'd + programs. + +:doc:`Statepoints` + This describes a set of experimental extensions for garbage + collection support. + +========= +LibFuzzer +========= + +:doc:`LibFuzzer` + A library for writing in-process guided fuzzers. + +:doc:`FuzzingLLVM` + Information on writing and using Fuzzers to find bugs in LLVM. + +======== +LLVM IR +======== + +:doc:`LLVM Language Reference Manual ` + Defines the LLVM intermediate representation and the assembly form of the + different nodes. + +:doc:`InAlloca` + Description of the ``inalloca`` argument attribute. + +:doc:`BitCodeFormat` + This describes the file format and encoding used for LLVM "bc" files. + +:doc:`Machine IR (MIR) Format Reference Manual ` + A reference manual for the MIR serialization format, which is used to test + LLVM's code generation passes. + +:doc:`GlobalISel/index` + This describes the prototype instruction selection replacement, GlobalISel. + +:doc:`ConvergentOperations` + Description of ``convergent`` operation semantics and related intrinsics. + +===================== +Testing and Debugging +===================== + +:doc:`LLVM Testing Infrastructure Guide ` + A reference manual for using the LLVM testing infrastructure. + +:doc:`TestSuiteGuide` + Describes how to compile and run the test-suite benchmarks. + + +:doc:`GwpAsan` + A sampled heap memory error detection toolkit designed for production use. + +==== +XRay +==== + +:doc:`XRay` + High-level documentation of how to use XRay in LLVM. + +:doc:`XRayExample` + An example of how to debug an application with XRay. + +================= +Additional Topics +================= + +:doc:`FaultMaps` + LLVM support for folding control flow into faulting machine instructions. + +:doc:`Atomics` + Information about LLVM's concurrency model. + +:doc:`ExceptionHandling` + This document describes the design and implementation of exception handling + in LLVM. + +:doc:`Extensions` + LLVM-specific extensions to tools and formats LLVM seeks compatibility with. + +:doc:`HowToSetUpLLVMStyleRTTI` + How to make ``isa<>``, ``dyn_cast<>``, etc. available for clients of your + class hierarchy. + +:doc:`BlockFrequencyTerminology` + Provides information about terminology used in the ``BlockFrequencyInfo`` + analysis pass. + +:doc:`BranchWeightMetadata` + Provides information about Branch Prediction Information. + +:doc:`GetElementPtr` + Answers to some very frequent questions about LLVM's most frequently + misunderstood instruction. + +:doc:`ScudoHardenedAllocator` + A library that implements a security-hardened `malloc()`. + +:doc:`MemoryModelRelaxationAnnotations` + Target-defined relaxation to LLVM's concurrency model. + +:doc:`MemTagSanitizer` + Security hardening for production code aiming to mitigate memory + related vulnerabilities. Based on the Armv8.5-A Memory Tagging Extension. + +:doc:`Dependence Graphs ` + A description of the design of the various dependence graphs such as + the DDG (Data Dependence Graph). + +:doc:`SpeculativeLoadHardening` + A description of the Speculative Load Hardening mitigation for Spectre v1. + +:doc:`SegmentedStacks` + This document describes segmented stacks and how they are used in LLVM. + +:doc:`MarkedUpDisassembly` + This document describes the optional rich disassembly output syntax. + +:doc:`StackMaps` + LLVM support for mapping instruction addresses to the location of + values and allowing code to be patched. + +:doc:`Coroutines` + LLVM support for coroutines. + +:doc:`PointerAuth` + A description of pointer authentication, its LLVM IR representation, and its + support in the backend. + +:doc:`YamlIO` + A reference guide for using LLVM's YAML I/O library. + +:doc:`ConvergenceAndUniformity` + A description of uniformity analysis in the presence of irreducible + control flow, and its implementation. diff --git a/llvm/docs/UserGuides.rst b/llvm/docs/UserGuides.rst index f40a04d414a2..18d273a51daf 100644 --- a/llvm/docs/UserGuides.rst +++ b/llvm/docs/UserGuides.rst @@ -1,286 +1,286 @@ -User Guides -=========== - -NOTE: If you are a user who is only interested in using an LLVM-based compiler, -you should look into `Clang `_ instead. The -documentation here is intended for users who have a need to work with the -intermediate LLVM representation. - -.. contents:: - :local: - -.. toctree:: - :hidden: - - AArch64SME - AddingConstrainedIntrinsics - AdvancedBuilds - AliasAnalysis - AMDGPUUsage - Benchmarking - BigEndianNEON - BuildingADistribution - CFIVerify - CMake - CMakePrimer - CodeGenerator - CodeOfConduct - CommandLine - CompileCudaWithLLVM - CoverageMappingFormat - CycleTerminology - DebuggingJITedCode - DirectXUsage - Docker - FatLTO - ExtendingLLVM - GitHub - GoldPlugin - GlobalISel/MIRPatterns - HowToBuildOnARM - HowToBuildWithPGO - HowToBuildWindowsItaniumPrograms - HowToCrossCompileBuiltinsOnArm - HowToCrossCompileLLVM - HowToUpdateDebugInfo - InstCombineContributorGuide - InstrProfileFormat - InstrRefDebugInfo - LinkTimeOptimization - LoopTerminology - MarkdownQuickstartTemplate - MemorySSA - MergeFunctions - MCJITDesignAndImplementation - MisExpect - ORCv2 - OpaquePointers - JITLink - NewPassManager - NVPTXUsage - Passes - ReportingGuide - ResponseGuide - Remarks - RemoveDIsDebugInfo - RISCVUsage - SourceLevelDebugging - SPIRVUsage - StackSafetyAnalysis - SupportLibrary - TableGen/index - TableGenFundamentals - Vectorizers - WritingAnLLVMPass - WritingAnLLVMNewPMPass - WritingAnLLVMBackend - yaml2obj - -Clang ------ - -:doc:`HowToBuildOnARM` - Notes on building and testing LLVM/Clang on ARM. - -:doc:`HowToBuildWithPGO` - Notes on building LLVM/Clang with PGO. - -:doc:`HowToCrossCompileLLVM` - Notes on cross-building and testing LLVM/Clang. - -`How to build the C, C++, ObjC, and ObjC++ front end`__ - Instructions for building the clang front-end from source. - - .. __: https://clang.llvm.org/get_started.html - -:doc:`CoverageMappingFormat` - This describes the format and encoding used for LLVM’s code coverage mapping. - -:doc:`CFIVerify` - A description of the verification tool for Control Flow Integrity. - -LLVM Builds and Distributions ------------------------------ - -:doc:`BuildingADistribution` - A best-practices guide for using LLVM's CMake build system to package and - distribute LLVM-based tools. - -:doc:`CMake` - An addendum to the main Getting Started guide for those using the `CMake - build system `_. - -:doc:`Docker` - A reference for using Dockerfiles provided with LLVM. - -:doc:`Support Library ` - This document describes the LLVM Support Library (``lib/Support``) and - how to keep LLVM source code portable. - -:doc:`AdvancedBuilds` - This document describes more advanced build configurations. - -Optimizations -------------- - -:doc:`WritingAnLLVMNewPMPass` - Information on how to write LLVM transformations under the new pass - manager. - -:doc:`WritingAnLLVMPass` - Information on how to write LLVM transformations and analyses under the - legacy pass manager. - -:doc:`Passes` - A list of optimizations and analyses implemented in LLVM. - -:doc:`StackSafetyAnalysis` - This document describes the design of the stack safety analysis of local - variables. - -:doc:`MergeFunctions` - Describes functions merging optimization. - -:doc:`AliasAnalysis` - Information on how to write a new alias analysis implementation or how to - use existing analyses. - -:doc:`MemorySSA` - Information about the MemorySSA utility in LLVM, as well as how to use it. - -:doc:`LoopTerminology` - A document describing Loops and associated terms as used in LLVM. - -:doc:`CycleTerminology` - A document describing cycles as a generalization of loops. - -:doc:`Vectorizers` - This document describes the current status of vectorization in LLVM. - -:doc:`LinkTimeOptimization` - This document describes the interface between LLVM intermodular optimizer - and the linker and its design - -:doc:`GoldPlugin` - How to build your programs with link-time optimization on Linux. - -:doc:`Remarks` - A reference on the implementation of remarks in LLVM. - -:doc:`Source Level Debugging with LLVM ` - This document describes the design and philosophy behind the LLVM - source-level debugger. - -:doc:`How to Update Debug Info ` - This document specifies how to correctly update debug info in various kinds - of code transformations. - -:doc:`InstrRefDebugInfo` - This document explains how LLVM uses value tracking, or instruction - referencing, to determine variable locations for debug info in the final - stages of compilation. - -:doc:`RemoveDIsDebugInfo` - This is a migration guide describing how to move from debug info using - intrinsics such as dbg.value to using the non-instruction DbgRecord object. - -:doc:`InstrProfileFormat` - This document explains two binary formats of instrumentation-based profiles. - -:doc:`InstCombineContributorGuide` - This document specifies guidelines for contributions for InstCombine and - related passes. - -Code Generation ---------------- - -:doc:`WritingAnLLVMBackend` - Information on how to write LLVM backends for machine targets. - -:doc:`CodeGenerator` - The design and implementation of the LLVM code generator. Useful if you are - working on retargetting LLVM to a new architecture, designing a new codegen - pass, or enhancing existing components. - -:doc:`TableGen ` - Describes the TableGen tool, which is used heavily by the LLVM code - generator. - -========== -GlobalISel -========== - -:doc:`MIRPatterns ` - Describes the design of MIR Patterns and how to use them. - -=== -JIT -=== - -:doc:`MCJITDesignAndImplementation` - Describes the inner workings of MCJIT execution engine. - -:doc:`ORCv2` - Describes the design and implementation of the ORC APIs, including some - usage examples, and a guide for users transitioning from ORCv1 to ORCv2. - -:doc:`JITLink` - Describes the design and APIs for the JITLink library, ORC's new JIT - linker. - -:doc:`DebuggingJITedCode` - How to debug JITed code with GDB. - -Additional Topics ------------------ - -:doc:`CommandLine` - Provides information on using the command line parsing library. - -:doc:`ExtendingLLVM` - Look here to see how to add instructions and intrinsics to LLVM. - -:doc:`AddingConstrainedIntrinsics` - Gives the steps necessary when adding a new constrained math intrinsic - to LLVM. - -:doc:`HowToBuildWindowsItaniumPrograms` - Notes on assembling a Windows Itanium environment. - -:doc:`HowToCrossCompileBuiltinsOnArm` - Notes on cross-building and testing the compiler-rt builtins for Arm. - -:doc:`BigEndianNEON` - LLVM's support for generating NEON instructions on big endian ARM targets is - somewhat nonintuitive. This document explains the implementation and rationale. - -:doc:`AArch64SME` - LLVM's support for AArch64 SME ACLE and ABI. - -:doc:`CompileCudaWithLLVM` - LLVM support for CUDA. - -:doc:`NVPTXUsage` - This document describes using the NVPTX backend to compile GPU kernels. - -:doc:`AMDGPUUsage` - This document describes using the AMDGPU backend to compile GPU kernels. - -:doc:`AMDGPUDwarfExtensionsForHeterogeneousDebugging` - This document describes DWARF extensions to support heterogeneous debugging - for targets such as the AMDGPU backend. - -:doc:`AMDGPUDwarfExtensionAllowLocationDescriptionOnTheDwarfExpressionStack/AMDGPUDwarfExtensionAllowLocationDescriptionOnTheDwarfExpressionStack` - This document describes a DWARF extension to allow location descriptions on - the DWARF expression stack. It is part of - :doc:`AMDGPUDwarfExtensionsForHeterogeneousDebugging`. - -:doc:`SPIRVUsage` - This document describes using the SPIR-V target to compile GPU kernels. - -:doc:`DirectXUsage` - This document describes using the DirectX target to compile GPU code for the - DirectX runtime. - -:doc:`RISCVUsage` - This document describes using the RISCV-V target. +User Guides +=========== + +NOTE: If you are a user who is only interested in using an LLVM-based compiler, +you should look into `Clang `_ instead. The +documentation here is intended for users who have a need to work with the +intermediate LLVM representation. + +.. contents:: + :local: + +.. toctree:: + :hidden: + + AArch64SME + AddingConstrainedIntrinsics + AdvancedBuilds + AliasAnalysis + AMDGPUUsage + Benchmarking + BigEndianNEON + BuildingADistribution + CFIVerify + CMake + CMakePrimer + CodeGenerator + CodeOfConduct + CommandLine + CompileCudaWithLLVM + CoverageMappingFormat + CycleTerminology + DebuggingJITedCode + DirectXUsage + Docker + FatLTO + ExtendingLLVM + GitHub + GoldPlugin + GlobalISel/MIRPatterns + HowToBuildOnARM + HowToBuildWithPGO + HowToBuildWindowsItaniumPrograms + HowToCrossCompileBuiltinsOnArm + HowToCrossCompileLLVM + HowToUpdateDebugInfo + InstCombineContributorGuide + InstrProfileFormat + InstrRefDebugInfo + LinkTimeOptimization + LoopTerminology + MarkdownQuickstartTemplate + MemorySSA + MergeFunctions + MCJITDesignAndImplementation + MisExpect + ORCv2 + OpaquePointers + JITLink + NewPassManager + NVPTXUsage + Passes + ReportingGuide + ResponseGuide + Remarks + RemoveDIsDebugInfo + RISCVUsage + SourceLevelDebugging + SPIRVUsage + StackSafetyAnalysis + SupportLibrary + TableGen/index + TableGenFundamentals + Vectorizers + WritingAnLLVMPass + WritingAnLLVMNewPMPass + WritingAnLLVMBackend + yaml2obj + +Clang +----- + +:doc:`HowToBuildOnARM` + Notes on building and testing LLVM/Clang on ARM. + +:doc:`HowToBuildWithPGO` + Notes on building LLVM/Clang with PGO. + +:doc:`HowToCrossCompileLLVM` + Notes on cross-building and testing LLVM/Clang. + +`How to build the C, C++, ObjC, and ObjC++ front end`__ + Instructions for building the clang front-end from source. + + .. __: https://clang.llvm.org/get_started.html + +:doc:`CoverageMappingFormat` + This describes the format and encoding used for LLVM’s code coverage mapping. + +:doc:`CFIVerify` + A description of the verification tool for Control Flow Integrity. + +LLVM Builds and Distributions +----------------------------- + +:doc:`BuildingADistribution` + A best-practices guide for using LLVM's CMake build system to package and + distribute LLVM-based tools. + +:doc:`CMake` + An addendum to the main Getting Started guide for those using the `CMake + build system `_. + +:doc:`Docker` + A reference for using Dockerfiles provided with LLVM. + +:doc:`Support Library ` + This document describes the LLVM Support Library (``lib/Support``) and + how to keep LLVM source code portable. + +:doc:`AdvancedBuilds` + This document describes more advanced build configurations. + +Optimizations +------------- + +:doc:`WritingAnLLVMNewPMPass` + Information on how to write LLVM transformations under the new pass + manager. + +:doc:`WritingAnLLVMPass` + Information on how to write LLVM transformations and analyses under the + legacy pass manager. + +:doc:`Passes` + A list of optimizations and analyses implemented in LLVM. + +:doc:`StackSafetyAnalysis` + This document describes the design of the stack safety analysis of local + variables. + +:doc:`MergeFunctions` + Describes functions merging optimization. + +:doc:`AliasAnalysis` + Information on how to write a new alias analysis implementation or how to + use existing analyses. + +:doc:`MemorySSA` + Information about the MemorySSA utility in LLVM, as well as how to use it. + +:doc:`LoopTerminology` + A document describing Loops and associated terms as used in LLVM. + +:doc:`CycleTerminology` + A document describing cycles as a generalization of loops. + +:doc:`Vectorizers` + This document describes the current status of vectorization in LLVM. + +:doc:`LinkTimeOptimization` + This document describes the interface between LLVM intermodular optimizer + and the linker and its design + +:doc:`GoldPlugin` + How to build your programs with link-time optimization on Linux. + +:doc:`Remarks` + A reference on the implementation of remarks in LLVM. + +:doc:`Source Level Debugging with LLVM ` + This document describes the design and philosophy behind the LLVM + source-level debugger. + +:doc:`How to Update Debug Info ` + This document specifies how to correctly update debug info in various kinds + of code transformations. + +:doc:`InstrRefDebugInfo` + This document explains how LLVM uses value tracking, or instruction + referencing, to determine variable locations for debug info in the final + stages of compilation. + +:doc:`RemoveDIsDebugInfo` + This is a migration guide describing how to move from debug info using + intrinsics such as dbg.value to using the non-instruction DbgRecord object. + +:doc:`InstrProfileFormat` + This document explains two binary formats of instrumentation-based profiles. + +:doc:`InstCombineContributorGuide` + This document specifies guidelines for contributions for InstCombine and + related passes. + +Code Generation +--------------- + +:doc:`WritingAnLLVMBackend` + Information on how to write LLVM backends for machine targets. + +:doc:`CodeGenerator` + The design and implementation of the LLVM code generator. Useful if you are + working on retargetting LLVM to a new architecture, designing a new codegen + pass, or enhancing existing components. + +:doc:`TableGen ` + Describes the TableGen tool, which is used heavily by the LLVM code + generator. + +========== +GlobalISel +========== + +:doc:`MIRPatterns ` + Describes the design of MIR Patterns and how to use them. + +=== +JIT +=== + +:doc:`MCJITDesignAndImplementation` + Describes the inner workings of MCJIT execution engine. + +:doc:`ORCv2` + Describes the design and implementation of the ORC APIs, including some + usage examples, and a guide for users transitioning from ORCv1 to ORCv2. + +:doc:`JITLink` + Describes the design and APIs for the JITLink library, ORC's new JIT + linker. + +:doc:`DebuggingJITedCode` + How to debug JITed code with GDB. + +Additional Topics +----------------- + +:doc:`CommandLine` + Provides information on using the command line parsing library. + +:doc:`ExtendingLLVM` + Look here to see how to add instructions and intrinsics to LLVM. + +:doc:`AddingConstrainedIntrinsics` + Gives the steps necessary when adding a new constrained math intrinsic + to LLVM. + +:doc:`HowToBuildWindowsItaniumPrograms` + Notes on assembling a Windows Itanium environment. + +:doc:`HowToCrossCompileBuiltinsOnArm` + Notes on cross-building and testing the compiler-rt builtins for Arm. + +:doc:`BigEndianNEON` + LLVM's support for generating NEON instructions on big endian ARM targets is + somewhat nonintuitive. This document explains the implementation and rationale. + +:doc:`AArch64SME` + LLVM's support for AArch64 SME ACLE and ABI. + +:doc:`CompileCudaWithLLVM` + LLVM support for CUDA. + +:doc:`NVPTXUsage` + This document describes using the NVPTX backend to compile GPU kernels. + +:doc:`AMDGPUUsage` + This document describes using the AMDGPU backend to compile GPU kernels. + +:doc:`AMDGPUDwarfExtensionsForHeterogeneousDebugging` + This document describes DWARF extensions to support heterogeneous debugging + for targets such as the AMDGPU backend. + +:doc:`AMDGPUDwarfExtensionAllowLocationDescriptionOnTheDwarfExpressionStack/AMDGPUDwarfExtensionAllowLocationDescriptionOnTheDwarfExpressionStack` + This document describes a DWARF extension to allow location descriptions on + the DWARF expression stack. It is part of + :doc:`AMDGPUDwarfExtensionsForHeterogeneousDebugging`. + +:doc:`SPIRVUsage` + This document describes using the SPIR-V target to compile GPU kernels. + +:doc:`DirectXUsage` + This document describes using the DirectX target to compile GPU code for the + DirectX runtime. + +:doc:`RISCVUsage` + This document describes using the RISCV-V target. diff --git a/llvm/utils/emacs/llvm-mir-mode.el b/llvm/utils/emacs/llvm-mir-mode.el index 6f1de4252445..5ded9cce50bb 100644 --- a/llvm/utils/emacs/llvm-mir-mode.el +++ b/llvm/utils/emacs/llvm-mir-mode.el @@ -1,70 +1,70 @@ -;;; llvm-mir-mode.el --- Major mode for LLVM Machine IR - -;; Maintainer: The LLVM team, http://llvm.org/ -;; Version: 1.0 - -;;; Commentary: - -;; Major mode for editing LLVM MIR files. - -;;; Code: - -(require 'llvm-mode) - -(defvar llvm-mir-mode-map - (let ((map (make-sparse-keymap))) - map) - "Keymap for `llvm-mir-mode'.") - -(defvar llvm-mir-mode-syntax-table - (let ((st (make-syntax-table))) - (modify-syntax-entry ?% "_" st) - (modify-syntax-entry ?$ "_" st) - (modify-syntax-entry ?. "_" st) - (modify-syntax-entry ?# "< " st) - (modify-syntax-entry ?\; "< " st) - (modify-syntax-entry ?\n "> " st) - st) - "Syntax table for `llvm-mir-mode'.") - -(defvar llvm-mir-font-lock-keywords - (append - (list - ; YAML Attributes - '("^name: +\\([a-zA-Z._][-a-zA-Z._0-9]*\\)" - 1 font-lock-function-name-face) - '("^body: +|" . font-lock-keyword-face) - '("^[a-zA-Z_.][-a-zA-Z._0-9]*:" . font-lock-keyword-face) - `(,(regexp-opt '("true" "false")) . font-lock-constant-face) - ; YAML separators - '("^\\(---\\( |\\)?\\|\\.\\.\\.\\)$" . font-lock-comment-face) - ; Registers - '("%[a-zA-Z_.][-a-zA-Z._0-9]*" . font-lock-variable-name-face) - '("%[0-9]+\\(\\.[a-zA-Z._0-9]+\\)?" . font-lock-variable-name-face) - '("$[a-zA-Z_.][-a-zA-Z._0-9]*" . font-lock-constant-face) - ; Register classes - `(,(concat - "%\\([a-zA-Z_.][-a-zA-Z._0-9]*\\|[0-9]+\\(\\.[a-zA-Z._0-9]+\\)?\\)" - "\\(:[a-zA-Z_.][-a-zA-Z._0-9]*\\)") - 3 font-lock-type-face) - '("class: \\([a-zA-Z_.][-a-zA-Z._0-9]*\\)" 1 font-lock-type-face) - ; MO Register flags - `(,(regexp-opt '("dead" "debug-use" "def" "early-clobber" "implicit" - "implicit-def" "internal" "killed" "renamable" "undef") - 'symbols) - . font-lock-keyword-face)) - llvm-font-lock-keywords) - "Keyword highlighting specification for `llvm-mir-mode'.") - - ;;;###autoload -(define-derived-mode llvm-mir-mode prog-mode "LLVM MIR" - "A major mode for editing LLVM MIR files." - (setq-local comment-start "; ") - (setq-local font-lock-defaults `(llvm-mir-font-lock-keywords))) - -;;;###autoload -(add-to-list 'auto-mode-alist (cons "\\.mir\\'" 'llvm-mir-mode)) - -(provide 'llvm-mir-mode) - -;;; llvm-mir-mode.el ends here +;;; llvm-mir-mode.el --- Major mode for LLVM Machine IR + +;; Maintainer: The LLVM team, http://llvm.org/ +;; Version: 1.0 + +;;; Commentary: + +;; Major mode for editing LLVM MIR files. + +;;; Code: + +(require 'llvm-mode) + +(defvar llvm-mir-mode-map + (let ((map (make-sparse-keymap))) + map) + "Keymap for `llvm-mir-mode'.") + +(defvar llvm-mir-mode-syntax-table + (let ((st (make-syntax-table))) + (modify-syntax-entry ?% "_" st) + (modify-syntax-entry ?$ "_" st) + (modify-syntax-entry ?. "_" st) + (modify-syntax-entry ?# "< " st) + (modify-syntax-entry ?\; "< " st) + (modify-syntax-entry ?\n "> " st) + st) + "Syntax table for `llvm-mir-mode'.") + +(defvar llvm-mir-font-lock-keywords + (append + (list + ; YAML Attributes + '("^name: +\\([a-zA-Z._][-a-zA-Z._0-9]*\\)" + 1 font-lock-function-name-face) + '("^body: +|" . font-lock-keyword-face) + '("^[a-zA-Z_.][-a-zA-Z._0-9]*:" . font-lock-keyword-face) + `(,(regexp-opt '("true" "false")) . font-lock-constant-face) + ; YAML separators + '("^\\(---\\( |\\)?\\|\\.\\.\\.\\)$" . font-lock-comment-face) + ; Registers + '("%[a-zA-Z_.][-a-zA-Z._0-9]*" . font-lock-variable-name-face) + '("%[0-9]+\\(\\.[a-zA-Z._0-9]+\\)?" . font-lock-variable-name-face) + '("$[a-zA-Z_.][-a-zA-Z._0-9]*" . font-lock-constant-face) + ; Register classes + `(,(concat + "%\\([a-zA-Z_.][-a-zA-Z._0-9]*\\|[0-9]+\\(\\.[a-zA-Z._0-9]+\\)?\\)" + "\\(:[a-zA-Z_.][-a-zA-Z._0-9]*\\)") + 3 font-lock-type-face) + '("class: \\([a-zA-Z_.][-a-zA-Z._0-9]*\\)" 1 font-lock-type-face) + ; MO Register flags + `(,(regexp-opt '("dead" "debug-use" "def" "early-clobber" "implicit" + "implicit-def" "internal" "killed" "renamable" "undef") + 'symbols) + . font-lock-keyword-face)) + llvm-font-lock-keywords) + "Keyword highlighting specification for `llvm-mir-mode'.") + + ;;;###autoload +(define-derived-mode llvm-mir-mode prog-mode "LLVM MIR" + "A major mode for editing LLVM MIR files." + (setq-local comment-start "; ") + (setq-local font-lock-defaults `(llvm-mir-font-lock-keywords))) + +;;;###autoload +(add-to-list 'auto-mode-alist (cons "\\.mir\\'" 'llvm-mir-mode)) + +(provide 'llvm-mir-mode) + +;;; llvm-mir-mode.el ends here