RPCS3/llvm-mirror
1
0
Fork 0
mirror of https://github.com/RPCS3/llvm-mirror.git synced 2025-02-01 05:01:59 +01:00
Code Issues Projects Releases Wiki Activity

Delete the file llvmc2/doc/LLVMC-Enhancements.rst + some minor language/spelling fixes.

Browse Source 
llvm-svn: 56458
This commit is contained in:
Mikhail Glushenkov 2008-09-22 20:45:17 +00:00
parent a28dd108a4
commit 54297e6546
4 changed files with 9 additions and 274 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

264
tools/llvmc2/doc/LLVMC-Enhancements.rst
View File

@ -1,264 +0,0 @@
Introduction
============
Disclaimer: this document is currently somewhat out-of-date and is
retained for reference; for more recent documentation please refer to
LLVMC-Tutorial.rst.
A complete rewrite of the LLVMC compiler driver is proposed, aimed at
making it more configurable and useful.
Motivation
==========
As it stands, the current version of LLVMC does not meet its stated goals
of configurability and extensibility, and is therefore not used
much. The need for enhancements to LLVMC is also reflected in [1]_. The
proposed rewrite will fix the aforementioned deficiences and provide
an extensible, future-proof solution.
Design
======
A compiler driver's job is essentially to find a way to transform a set
of input files into a set of targets, depending on the user-provided
options. Since several methods of transformation can potentially exist,
it's natural to use a directed graph to represent all of them. In this
graph, nodes are tools -- e.g., ``gcc -S`` is a tool that generates
assembly from C language files -- and edges between the nodes indicate
that the output of one tool can be given as input to another -- i.e.,
``gcc -S -o - file.c | as``. We'll call this graph the compilation graph.
The proposed design revolves around the compilation graph and the
following core abstractions:
- Target - An (intermediate) compilation target.
- Action - A shell command template that represents a basic compilation
transformation -- example: ``gcc -S $INPUT_FILE -o $OUTPUT_FILE``.
- Tool - Encapsulates information about a concrete tool used in the
compilation process, produces Actions. Its operation depends on
command-line options provided by the user.
- GraphBuilder - Constructs the compilation graph. Its operation
depends on command-line options.
- GraphTraverser - Traverses the compilation graph and constructs a
sequence of Actions needed to build the target file. Its operation
depends on command-line options.
A high-level view of the compilation process:
1. Configuration libraries (see below) are loaded in and the
compilation graph is constructed from the tool descriptions.
2. Information about possible options is gathered from (the nodes of)
the compilation graph.
3. Options are parsed based on data gathered in step 2.
4. A sequence of Actions needed to build the target is constructed
using the compilation graph and provided options.
5. The resulting action sequence is executed.
Extensibility
==============
To make this design extensible, TableGen [2]_ will be used for
automatic generation of the Tool classes. Users wanting to customize
LLVMC need to write a configuration library consisting of a set of
TableGen descriptions of compilation tools plus a number of hooks
that influence compilation graph construction and traversal. LLVMC
will have the ability to load user configuration libraries at runtime;
in fact, its own basic functionality will be implemented as a
configuration library.
TableGen specification example
------------------------------
This small example specifies a Tool that converts C source to object
files. Note that it is only a mock-up of intended functionality, not a
final specification::
def GCC : Tool<
GCCProperties, // Properties of this tool
GCCOptions // Options description for this tool
>;
def GCCProperties : ToolProperties<[
ToolName<"GCC">,
InputLanguageName<"C">,
OutputLanguageName<"Object-Code">
InputFileExtension<"c">,
OutputFileExtension<"o">,
CommandFormat<"gcc -c $OPTIONS $FILES">
]>;
def GCCOptions : ToolOptions<[
Option<
"-Wall", // Option name
[None], // Allowed values
[AddOption<"-Wall">]>, // Action
Option<
"-Wextra", // Option name
[None], // Allowed values
[AddOption<"-Wextra">]>, // Action
Option<
"-W", // Option name
[None], // Allowed values
[AddOption<"-W">]>, // Action
Option<
"-D", // Option name
[AnyString], // Allowed values
[AddOptionWithArgument<"-D",GetOptionArgument<"-D">>]
// Action:
// If the driver was given option "-D<argument>", add
// option "-D" with the same argument to the invocation string of
// this tool.
>
]>;
Example of generated code
-------------------------
The specification above compiles to the following code (again, it's a
mock-up)::
class GCC : public Tool {
public:
GCC() { //... }
// Properties
static const char* ToolName = "GCC";
static const char* InputLanguageName = "C";
static const char* OutputLanguageName = "Object-Code";
static const char* InputFileExtension = "c";
static const char* OutputFileExtension = "o";
static const char* CommandFormat = "gcc -c $OPTIONS $FILES";
// Options
OptionsDescription SupportedOptions() {
OptionsDescription supportedOptions;
supportedOptions.Add(Option("-Wall"));
supportedOptions.Add(Option("-Wextra"));
supportedOptions.Add(Option("-W"));
supportedOptions.Add(Option("-D", AllowedArgs::ANY_STRING));
return supportedOptions;
}
Action GenerateAction(Options providedOptions) {
Action generatedAction(CommandFormat); Option curOpt;
curOpt = providedOptions.Get("-D");
if (curOpt) {
assert(curOpt.HasArgument());
generatedAction.AddOption(Option("-D", curOpt.GetArgument()));
}
curOpt = providedOptions.Get("-Wall");
if (curOpt)
generatedAction.AddOption(Option("-Wall"));
curOpt = providedOptions.Get("-Wextra");
if (curOpt)
generatedAction.AddOption(Option("-Wall"));
curOpt = providedOptions.Get("-W");
if (curOpt)
generatedAction.AddOption(Option("-Wall")); }
return generatedAction;
}
};
// defined somewhere...
class Action { public: void AddOption(const Option& opt) {...}
int Run(const Filenames& fnms) {...}
}
Option handling
===============
Because one of the main tasks of the compiler driver is to correctly
handle user-provided options, it is important to define this process
in an exact way. The intent of the proposed scheme is to function as
a drop-in replacement for GCC.
Option syntax
-------------
The option syntax is specified by the following formal grammar::
<command-line> ::= <option>*
<option> ::= <positional-option> | <named-option>
<named-option> ::= -[-]<option-name>[<delimeter><option-argument>]
<delimeter> ::= ',' | '=' | ' '
<positional-option> ::= <string>
<option-name> ::= <string>
<option-argument> ::= <string>
This roughly corresponds to the GCC option syntax. Note that grouping
of short options (as in ``ls -la``) is forbidden.
Example::
llvmc -O3 -Wa,-foo,-bar -pedantic -std=c++0x a.c b.c c.c
Option arguments can also have special forms. For example, an argument
can be a comma-separated list (like in -Wa,-foo,-bar). In such cases,
it's up to the option handler to parse the argument.
Option semantics
----------------
According to their meaning, options are classified into the following
categories:
- Global options - Options that influence compilation graph
construction/traversal. Example: -E (stop after preprocessing).
- Local options - Options that influence one or several Actions in
the generated action sequence. Example: -O3 (turn on optimization).
- Prefix options - Options that influence the meaning of the following
command-line arguments. Example: -x language (specify language for
the input files explicitly). Prefix options can be local or global.
- Built-in options - Options that are hard-coded into the
driver. Examples: --help, -o file/-pipe (redirect output). Can be
local or global.
Issues
======
1. Should global-options-influencing hooks be written by hand or
auto-generated from TableGen specifications?
2. More?
References
==========
.. [1] LLVM Bug#686
http://llvm.org/bugs/show_bug.cgi?id=686
.. [2] TableGen Fundamentals
http://llvm.org/docs/TableGenFundamentals.html

3
tools/llvmc2/doc/LLVMC-Reference.rst
View File

@ -182,7 +182,8 @@ The complete list of the currently implemented tool properties follows:
* Possible tool properties:
- ``in_language`` - input language name.
- ``in_language`` - input language name. Can be either a string or a
list, in case the tool supports multiple input languages.
- ``out_language`` - output language name.

11
tools/llvmc2/doc/LLVMC-Tutorial.rst
View File

@ -30,7 +30,7 @@ Using LLVMC to generate toolchain drivers
At the time of writing LLVMC does not support on-the-fly reloading of
configuration, so it will be necessary to recompile its source
code. LLVMC uses TableGen [1]_ as its configuration language, so
you'll need to familiar with it.
you need to be familiar with it.
Start by compiling ``examples/Simple.td``, which is a simple wrapper
for ``gcc``::
@ -66,11 +66,10 @@ As you can see, this file consists of three parts: tool descriptions,
language map, and the compilation graph definition.
At the heart of LLVMC is the idea of a transformation graph: vertices
in this graph are tools, and edges signify that there is a
transformation path between two tools (for example, assembly source
produced by the compiler can be transformed into executable code by an
assembler). A special node named ``root`` is used to mark the graph
entry points.
in this graph are tools, and edges represent a transformation path
between two tools (for example, assembly source produced by the
compiler can be transformed into executable code by an assembler). A
special node named ``root`` is used to mark graph entry points.
Tool descriptions are basically lists of properties: most properties
in the example above should be self-explanatory; the ``sink`` property

5
utils/TableGen/LLVMCConfigurationEmitter.cpp
View File

@ -796,7 +796,6 @@ bool EmitCaseTest1Arg(const std::string& TestName,
const DagInit& d,
const GlobalOptionDescriptions& OptDescs,
std::ostream& O) {
// TOFIX - Add a mechanism for OS detection.
checkNumberOfArguments(&d, 1);
const std::string& OptName = InitPtrToString(d.getArg(0));
if (TestName == "switch_on") {
@ -1462,8 +1461,8 @@ void FillInToolToLang (const ToolPropertiesList& TPList,
// and multiple default edges in the graph (better error
// reporting). Unfortunately, it is awkward to do right now because
// our intermediate representation is not sufficiently
// sofisticated. Algorithms like these should be run on a real graph
// instead of AST.
// sophisticated. Algorithms like these require a real graph instead of
// an AST.
void TypecheckGraph (Record* CompilationGraph,
const ToolPropertiesList& TPList) {
StringMap<StringSet<> > ToolToInLang;