[new docs] Performance Tips for Frontend Authors

[reames]

Summary

As mentioned on llvm-dev, this is a new documentation page intended to collect tips for frontend authors on how to generate IR that LLVM is able to optimize well. These types of things come up repeated in review threads and it would be good to have a place to save them.

I added a small handful to start us off, but I mostly want to get the framework in place. Once the docs are here, we can add to them incrementally.

[silvas]

I really would like this to be in a separate directory for frontend-targeted stuff. That we have some existing frontend-oriented stuff that isn't well-organized is a historical artifact. I would like to set a precedent for future work. We did this for TableGen and it made a world of difference.

[silvas]

Other than putting it in a frontend-targeted directory and a couple tiny things I've suggested inline, the LGTM.

docs/PerformanceTips.rst

29 ↗

(On Diff #20707)

I'm not sure that "modern" has anything to do with whether the ISA provides a sign-extending load (and I wouldn't call x86_64 "modern" either). Maybe just "On some architectures (such as X86_64), ...".

40 ↗

(On Diff #20707)

s/manual/manually/

Also, this paragraph doesn't seem to be folded to 80 columns, unlike the other paragraphs.

44–45 ↗

(On Diff #20707)

Tiny nit: I would prefer if you added a blank line after the ===== (as you are doing here) for the other sections.

llvm/trunk/docs/Frontend/PerformanceTips.rst

+=====================================
+Performance Tips for Frontend Authors
+=====================================
+
+.. contents::
+   :local:
+   :depth: 2
+
+Abstract
+========
+
+The intended audience of this document is developers of language frontends 
+targeting LLVM IR. This document is home to a collection of tips on how to 
+generate IR that optimizes well.  As with any optimizer, LLVM has its strengths
+and weaknesses.  In some cases, surprisingly small changes in the source IR 
+can have a large effect on the generated code.  
+
+Avoid loads and stores of large aggregate type
+================================================
+
+LLVM currently does not optimize well loads and stores of large :ref:`aggregate
+types <t_aggregate>` (i.e. structs and arrays).  As an alternative, consider 
+loading individual fields from memory.
+
+Aggregates that are smaller than the largest (performant) load or store 
+instruction supported by the targeted hardware are well supported.  These can 
+be an effective way to represent collections of small packed fields.  
+
+Prefer zext over sext when legal
+==================================
+
+On some architectures (X86_64 is one), sign extension can involve an extra 
+instruction whereas zero extension can be folded into a load.  LLVM will try to
+replace a sext with a zext when it can be proven safe, but if you have 
+information in your source language about the range of a integer value, it can 
+be profitable to use a zext rather than a sext.  
+
+Alternatively, you can :ref:`specify the range of the value using metadata 
+<range-metadata>` and LLVM can do the sext to zext conversion for you.
+
+Zext GEP indices to machine register width
+============================================
+
+Internally, LLVM often promotes the width of GEP indices to machine register
+width.  When it does so, it will default to using sign extension (sext) 
+operations for safety.  If your source language provides information about 
+the range of the index, you may wish to manually extend indices to machine 
+register width using a zext instruction.
+
+
+Adding to this document
+=======================
+
+If you run across a case that you feel deserves to be covered here, please send
+a patch to `llvm-commits
+<http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits>`_ for review.
+
+If you have questions on these items, please direct them to `llvmdev 
+<http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev>`_.  The more relevant 
+context you are able to give to your question, the more likely it is to be 
+answered.
+

llvm/trunk/docs/LangRef.rst

 
 The metadata node shall consist of a single positive floating point
 number representing the maximum relative error, for example:
 
 .. code-block:: llvm
 
     !0 = !{ float 2.5 } ; maximum acceptable inaccuracy is 2.5 ULPs
 
+.. _range-metadata:
+
 '``range``' Metadata
 ^^^^^^^^^^^^^^^^^^^^
 
 ``range`` metadata may be attached only to ``load``, ``call`` and ``invoke`` of
 integer types. It expresses the possible ranges the loaded value or the value
 returned by the called function at this call site is in. The ranges are
 represented with a flattened list of integers. The loaded value or the value
 returned is known to be in the union of the ranges defined by each consecutive

llvm/trunk/docs/index.rst

.. toctree::
    SphinxQuickstartTemplate
    Phabricator
    TestingGuide
    tutorial/index
    ReleaseNotes
    Passes
    YamlIO
    GetElementPtr
+   Frontend/PerformanceTips
    MCJITDesignAndImplementation
 
 :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:`CMake`

 
 :doc:`YamlIO`
    A reference guide for using LLVM's YAML I/O library.
 
 :doc:`GetElementPtr`
   Answers to some very frequent questions about LLVM's most frequently
   misunderstood instruction.
 
+:doc:`Frontend/PerformanceTips`
+   A collection of tips for frontend authors on how to generate IR 
+   which LLVM is able to effectively optimize.
+
+
 Programming Documentation
 =========================
 
 For developers of applications which use LLVM as a library.
 
 .. toctree::
    :hidden: