Tutorial: How To Write An LLVM Register Allocator

[Sean Silva via llvm-commits]

caveat: I'm not an expert in register allocation
caveat to the caveat: that means that I'm the audience of this document
presumably, so the issues I see are probably representative

I just got around to reading through your document, and the major thing I
see is that there is not a clear organization and is missing the
"walkthrough" nature of a true HowTo.

I would recommend splitting the document into two sections: "concepts" and
"walkthrough".
- The "concepts" covers the background needed to understand the walkthrough.
- The walkthrough is a numbered list of steps. Each step gives specific
instructions for what the reader should do next and advice for how to do it
(tips, caveats, etc.). This is a careful balance between just saying "paste
this code in" and providing high level details/clarifications. In the case
of this document, focus on the things that a reader cannot infer from just
reading RegAllocBasic. Having a section "How To Start" at the end under
"Tips" which just says "go look at RegAllocBasic" is confusing: the whole
point of a HowTo is to describe how to start! You may want "copy
RegAllocBasic into RegAllocMyAlloc" as step one of the walkthrough though.

You already have a lot of the content you need, it's just a matter of
organizing it into a clear walkthrough style. Organization is actually
*hugely* important for documentation: real documentation reading is highly
non-linear (for example, looking back at something earlier in the document,
or not understanding something and skimming ahead to see if there is
something that helps it make sense). If the reader does not have a clear
"map" in their head they will have a very hard time. For example, having
explicit numbered steps is actually not necessarily about having somebody
read them in that order! It is moreso so that the person reading *knows
where they are* in the order.

-- Sean Silva




On Fri, Feb 5, 2016 at 3:50 PM, Natanael Ramos via llvm-commits <
llvm-commits at lists.llvm.org> wrote:

> Hello
>
> My name is Natanael Ramos, I'm a  student of bachelor degree on Computer
> Science Course, here on Brazil.
>
> Recently I have worked with LLVM for my undergraduate thesis (I don't
> really know how is called in other countries, here is called Completion
> of course work), in my work I have implemented an register allocator
> using LLVM and have tested him with the built-in allocators in LLVM
> (Probably I'll publish a paper soon, if all goes as expected).
>
> As another product of my work, I have created a tutorial of how to write
> an LLVM register allocator, extending the RegAllocBase interface, this
> tutorial is based on my understanding of the LLVM framework for working
> with the register allocation pass.
>
> The tutorial have been written in reStructuredText following the LLVM
> instructions and orientations (
> http://www.llvm.org/docs/SphinxQuickstartTemplate.html). As it's
> suggested, I'm sending the tutorial to this mailing list in order to contribute
> to the community of developers, which use LLLVM.
>
> Any suggestions, please let me know.
>
> --
> Natanael Ramos
> Membro do corpo discente de Ciência da Computação pelo Instituto Federal
> de
> Minas Gerais - Campus Formiga
>
>
> _______________________________________________
> llvm-commits mailing list
> llvm-commits at lists.llvm.org
> http://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-commits
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20160209/09856c00/attachment.html>