Code documentation

Hello,
is there any documentation for LLVM codebase other than produced by doxygen?
The reason I'm asking is that doxygen docs are
(1) not very complete at the moment, as lot of classes don't even have a
description
(2) is generally not the best way to get high-level view of a big codebase.

As an example, consider this code:

     %tmp.1 = setgt int %i, 0
     br bool %tmp.1, label %then.0, label %else.0

It appears that Value* that corresponds to the %tmp.1 operand of the second
instruction is actually a pointer to Instruction* which represents the first
instruction.

This looks a nice design, given that all code is in SSA, but I've spend
considerable time today before understanding it, because I first tried to
look up a ways to find the instruction which defines tmp.1, then looked for
a method which returns destination of an instruction, and so on..

I realize all the developers must be busy, but some overview would be really
good.

- Volodya

Vladimir Prus wrote:
}
} Hello,
} is there any documentation for LLVM codebase other than produced by doxygen?
} The reason I'm asking is that doxygen docs are
} (1) not very complete at the moment, as lot of classes don't even have a
} description
} (2) is generally not the best way to get high-level view of a big codebase.
}
} As an example, consider this code:
}
} %tmp.1 = setgt int %i, 0
} br bool %tmp.1, label %then.0, label %else.0
}
} It appears that Value* that corresponds to the %tmp.1 operand of the second
} instruction is actually a pointer to Instruction* which represents the first
} instruction.
}
} This looks a nice design, given that all code is in SSA, but I've spend
} considerable time today before understanding it, because I first tried to
} look up a ways to find the instruction which defines tmp.1, then looked for
} a method which returns destination of an instruction, and so on..
}
There is a lot of documentation other than Doxygen. Try here:

    http://llvm.cs.uiuc.edu/Documentation.html

There is a paper on LLVM's design. There's also the language reference
manual. And information on writing an LLVM pass.

I think the answer to your question above is: since LLVM is in SSA form,
you have one definition and multiple uses of a variable. Since names are
meaningless in LLVM, variables used in an instruction are pointers to
the definition of that varialbe, which is just an Instruction*. I
believe that they are Value* because the operands can be other than
Instructions (Constants, for instance).

I hope this helps :slight_smile:

-bw

is there any documentation for LLVM codebase other than produced by doxygen?

Yes, most definitely:
http://llvm.cs.uiuc.edu/Documentation.html

The reason I'm asking is that doxygen docs are
(1) not very complete at the moment, as lot of classes don't even have a
description
(2) is generally not the best way to get high-level view of a big codebase.

Quite true. Note that, in general, there are reasonable comments and
descriptions of each interface at the top of each header file. I don't
think that doxygen picks these descriptions up, so it might be good to
look there. For example, contrast this:
http://llvm.cs.uiuc.edu/doxygen/LoopInfo_8h-source.html
to this:
http://llvm.cs.uiuc.edu/doxygen/classllvm_1_1Loop.html

As an example, consider this code:

     %tmp.1 = setgt int %i, 0
     br bool %tmp.1, label %then.0, label %else.0

It appears that Value* that corresponds to the %tmp.1 operand of the second
instruction is actually a pointer to Instruction* which represents the first
instruction.

This is exactly right.

This looks a nice design, given that all code is in SSA, but I've spend
considerable time today before understanding it, because I first tried to
look up a ways to find the instruction which defines tmp.1, then looked for
a method which returns destination of an instruction, and so on..

This should be described in the developer's guide:
http://llvm.cs.uiuc.edu/docs/ProgrammersManual.html#iterate_chains

Like all documentation, it can probably be improved. If you would like to
contribute a paragraph or two describing what you've learned, we would
love to include it in the manual for others to learn from. :slight_smile:

I realize all the developers must be busy, but some overview would be really
good.

Sure, we think that documentation is really important. If you have any
questions that are not covered in the documentation, please feel free to
ask on the list.

-Chris

Chris Lattner wrote:

> is there any documentation for LLVM codebase other than produced by
> doxygen?

Yes, most definitely:
http://llvm.cs.uiuc.edu/Documentation.html

Hmm.. I've looked at almost everything there... except for "Programmer
Manual". Well, printing it now :wink:

> The reason I'm asking is that doxygen docs are
> (1) not very complete at the moment, as lot of classes don't even have a
> description
> (2) is generally not the best way to get high-level view of a big
> codebase.

Quite true. Note that, in general, there are reasonable comments and
descriptions of each interface at the top of each header file. I don't
think that doxygen picks these descriptions up, so it might be good to
look there. For example, contrast this:
http://llvm.cs.uiuc.edu/doxygen/LoopInfo_8h-source.html
to this:
http://llvm.cs.uiuc.edu/doxygen/classllvm_1_1Loop.html

Okay, understood.

> This looks a nice design, given that all code is in SSA, but I've spend
> considerable time today before understanding it, because I first tried to
> look up a ways to find the instruction which defines tmp.1, then looked
> for a method which returns destination of an instruction, and so on..

This should be described in the developer's guide:
http://llvm.cs.uiuc.edu/docs/ProgrammersManual.html#iterate_chains

Like all documentation, it can probably be improved. If you would like to
contribute a paragraph or two describing what you've learned, we would
love to include it in the manual for others to learn from. :slight_smile:

Yes, I'll try to see if those paragraphs can be improved -- as written, then
still don't say that operand can be just pointer to instruction.

> I realize all the developers must be busy, but some overview would be
> really good.

Sure, we think that documentation is really important. If you have any
questions that are not covered in the documentation, please feel free to
ask on the list.

Thanks,
Volodya