Tutorial: How To Write An LLVM Register Allocator

[Sean Silva via llvm-commits]

On Wed, Feb 10, 2016 at 11:49 AM, Natanael Ramos <naelr8 at gmail.com> wrote:

> Thank you for the suggestions Sean, I really needed suggestions like that
> when I was writing the document.
> When I was writing the document, as it is a product of my bachelor thesis,
> I was running out of time, so I end up losing myself on how to make the
> best organization.
>

No problem! Often the best way to get the initial content is right when you
are in the heat of the project and you have everything floating around in
your head. This gives you the raw materials for coming back later at a more
relaxed time to revise, reorganize, and get feedback like you've done here.

Like Hal said, we have a systemic lack of documentation of our backend
infrastructure, so this sort of documentation is greatly appreciated. If
you have the time to iterate on the document with us a bit, we definitely
would like to incorporate it into the official LLVM documentation :)

-- Sean Silva


>
> 2016-02-10 3:37 GMT-02:00 Sean Silva <chisophugis at gmail.com>:
>
>> 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
>>>
>>>
>>
>
>
> --
> Natanael Ramos
> Membro do corpo discente de Ciência da Computação pelo Instituto Federal
> de
> Minas Gerais - Campus Formiga
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20160210/7b81f891/attachment.html>