[llvm-commits] [PATCH] TableGen backend support to express relations between instruction

[Sean Silva]

> Sure, I can put it in a new .rst file. However, I don't see why a link in
> WritingAnLLVMBackend.html is more desirable over a complete description of
> the feature.

One reason is that WritingAnLLVMBackend covers the components of an
LLVM backend (i.e. what you need to have in order to "be" an LLVM
backend). The instruction mapping functionality is a utility for
implementing backends (AFAIK), not a core backend component. Also, a
complete description would be quite lengthy; just the "how to" for the
instruction mapping infrastructure is likely to be as long as the
entire section of WritingAnLLVMBackend.html dedicated to
TargetMachine, so including it there is just going to confuse readers.

-- Sean Silva

On Thu, Oct 11, 2012 at 1:43 PM, Jyotsna Verma <jverma at codeaurora.org> wrote:
> Sure, I can put it in a new .rst file. However, I don't see why a link in
> WritingAnLLVMBackend.html is more desirable over a complete description of
> the feature.
>
> Thanks,
> Jyotsna
>
> --
> Qualcomm Innovation Center, Inc. is a member of Code Aurora Forum, hosted by
> The Linux Foundation
>
>
>> -----Original Message-----
>> From: Sean Silva [mailto:silvas at purdue.edu]
>> Sent: Thursday, October 11, 2012 11:59 AM
>> To: Jyotsna Verma
>> Cc: Jakob Stoklund Olesen; llvm-commits at cs.uiuc.edu
>> Subject: Re: [llvm-commits] [PATCH] TableGen backend support to express
>> relations between instruction
>>
>> Hi Jyotsna, could you please break the documentation out into a separate
> .rst
>> file (and link to it from WritingAnLLVMBackend.html).
>> Also, could you please take another look at my previous suggestion:
>>
>> >> >> I briefly looked at your documentation patch and it looks like it
>> >> >> would be more useful/natural to make it more of a "howto". So my
>> >> >> suggestion is to break out the documentation you added to
>> >> >> WritingAnLLVMBackend.html and make a new document
>> >> >> HowToUseInstructionMappings.rst (or whatever name you think is
>> >> >> most
>> >> >> appropriate) and then later we can link to it from
>> >> >> WritingAnLLVMBackend.html. To get started, you can just copy
>> >> >> HowToBuildOnARM.rst or HowToAddABuilder.rst and use it as a
>> >> >> template for your work.
>>
>> I have attached a prototype Sphinx quickstart template which you can use
> to
>> base the new documentation. Just copy the file to
>> docs/HowToUseInstructionMappings.rst (or whatever name you think is
>> most appropriate), and then just write the new documentation and delete
>> the old content (which is a mini-Sphinx tutorial) as you make progress.
>>
>> Also, I think you may have missed my message where I made some
>> suggestions about how to structure the description for this feature.
>> Here is the message:
>>
>> >> I would also recommend structuring the description differently. I
>> >> think
>> > you
>> >> should first introduce the problem that this solves. I.e., describe
>> >> what
>> > you
>> >> want getPredSense to do eventually (e.g. "we want to be able to call
>> >> getPredSense(x) and have it ..."). After that, you should introduce
>> >> the
>> > ADD*
>> >> instructions before you change them so that this mapping is emitted.
>> >> Then
>> > I
>> >> would walk through all of the steps needed in order to generate
>> >> getPredSense. So for example the first step would probably be to
>> >> decide on a base class name to mark the instructions that participate
>> >> in the mapping (e.g. "PredRel" in the current patch).
>>
>> Thanks,
>> -- Sean Silva
>>
>> On Thu, Oct 11, 2012 at 11:35 AM, Jyotsna Verma <jverma at codeaurora.org>
>> wrote:
>> > Hello Jakob/Sean,
>> >
>> > Here is the updated patch which addresses your review comments.
>> > Please take a look and let me know if you have any other suggestions.
>> >
>> > Thanks,
>> > Jyotsna
>> >
>> > --
>> > Qualcomm Innovation Center, Inc. is a member of Code Aurora Forum,
>> > hosted by The Linux Foundation
>> >
>> >> -----Original Message-----
>> >> From: Sean Silva [mailto:silvas at purdue.edu]
>> >> Sent: Monday, October 01, 2012 9:53 PM
>> >> To: Jyotsna Verma
>> >> Cc: Jakob Stoklund Olesen; llvm-commits at cs.uiuc.edu
>> >> Subject: Re: [llvm-commits] [PATCH] TableGen backend support to
>> >> express relations between instruction
>> >>
>> >> Hi Jyotsna, I took a look at the content of the documentation of your
>> > patch,
>> >> and I think that it is good but there is one thing missing. You need
>> >> to
>> > describe
>> >> what the interface looks like for the generated code.
>> >>
>> >> I would also recommend structuring the description differently. I
>> >> think
>> > you
>> >> should first introduce the problem that this solves. I.e., describe
>> >> what
>> > you
>> >> want getPredSense to do eventually (e.g. "we want to be able to call
>> >> getPredSense(x) and have it ..."). After that, you should introduce
>> >> the
>> > ADD*
>> >> instructions before you change them so that this mapping is emitted.
>> >> Then
>> > I
>> >> would walk through all of the steps needed in order to generate
>> >> getPredSense. So for example the first step would probably be to
>> >> decide on a base class name to mark the instructions that participate
>> >> in the mapping (e.g. "PredRel" in the current patch).
>> >>
>> >> --Sean Silva
>> >>
>> >> On Mon, Oct 1, 2012 at 4:14 PM, Jyotsna Verma
>> <jverma at codeaurora.org>
>> >> wrote:
>> >> > Thanks Sean.
>> >> >
>> >> > I can move the documentation into an .rst file. But personally, I
>> >> > think it should be included in the WritingAnLLVMBackend.html file
>> >> > too since this is a TableGen feature that people may be interested
>> >> > in while adding/improving their backend.
>> >> >
>> >> > I have never used Sphinx before, so I might run in to some issues.
>> >> > I will get in touch with you if that happens.
>> >> >
>> >> > -Jyotsna
>> >> > --
>> >> > Qualcomm Innovation Center, Inc. is a member of Code Aurora Forum,
>> >> > hosted by The Linux Foundation
>> >> >
>> >> >
>> >> >> -----Original Message-----
>> >> >> From: Sean Silva [mailto:silvas at purdue.edu]
>> >> >> Sent: Monday, October 01, 2012 12:31 PM
>> >> >> To: Jakob Stoklund Olesen
>> >> >> Cc: Jyotsna Verma; llvm-commits at cs.uiuc.edu
>> >> >> Subject: Re: [llvm-commits] [PATCH] TableGen backend support to
>> >> >> express relations between instruction
>> >> >>
>> >> >> > Thanks. This feature is quite complicated, I think it is best if
>> >> > somebody else
>> >> >> reviews the documentation. I want to know if this explanation is
>> >> >> understandable by somebody who wasn't involved in the design.
>> >> >>
>> >> >> I'll take a look at this later today.
>> >> >>
>> >> >> One idea for Jyotsna though: could you break this out into a
>> >> >> separate .rst document, and then link to it?
>> >> >>
>> >> >> I briefly looked at your documentation patch and it looks like it
>> >> >> would be more useful/natural to make it more of a "howto". So my
>> >> >> suggestion is to break out the documentation you added to
>> >> >> WritingAnLLVMBackend.html and make a new document
>> >> >> HowToUseInstructionMappings.rst (or whatever name you think is
>> >> >> most
>> >> >> appropriate) and then later we can link to it from
>> >> >> WritingAnLLVMBackend.html. To get started, you can just copy
>> >> >> HowToBuildOnARM.rst or HowToAddABuilder.rst and use it as a
>> >> >> template for your work.
>> >> >>
>> >> >> Let me know if you need any help with the Sphinx docs. Focus first
>> >> >> on the content since that is the most important. It's easy to
>> >> >> clean up once the content is written.
>> >> >>
>> >> >> --Sean Silva
>> >> >>
>> >> >> On Mon, Oct 1, 2012 at 12:39 PM, Jakob Stoklund Olesen
>> >> >> <stoklund at 2pi.dk>
>> >> >> wrote:
>> >> >> >
>> >> >> > On Oct 1, 2012, at 8:52 AM, "Jyotsna Verma"
>> >> >> > <jverma at codeaurora.org>
>> >> >> wrote:
>> >> >> >
>> >> >> >> Here is the updated patch which includes a new section into
>> >> >> >> docs/WritingAnLLVMBackend.html and a high-level description of
>> >> >> >> the algorithm in CodeGenMapTable.cpp file.
>> >> >> >
>> >> >> > Thanks. This feature is quite complicated, I think it is best if
>> >> > somebody else
>> >> >> reviews the documentation. I want to know if this explanation is
>> >> >> understandable by somebody who wasn't involved in the design.
>> >> >> >
>> >> >> > /jakob
>> >> >> >
>> >> >> > _______________________________________________
>> >> >> > llvm-commits mailing list
>> >> >> > llvm-commits at cs.uiuc.edu
>> >> >> > http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits
>> >> >
>