mirror of
https://github.com/RPCS3/llvm-mirror.git
synced 2024-12-22 11:39:35 +00:00
218 lines
8.1 KiB
Plaintext
218 lines
8.1 KiB
Plaintext
=pod
|
|
|
|
=head1 NAME
|
|
|
|
llvm2xpp - LLVM bitcode to LLVM C++ IR translator
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
B<llvm2cpp> [I<options>] [I<filename>]
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
B<llvm2cpp> translates from LLVM bitcode (.bc files) to a
|
|
corresponding C++ source file that will make calls against the LLVM C++ API to
|
|
build the same module as the input. By default, the C++ output is a complete
|
|
program that builds the module, verifies it and then emits the module as
|
|
LLVM assembly. This technique assists with testing because the input to
|
|
B<llvm2cpp> and the output of the generated C++ program should be identical.
|
|
|
|
If F<filename> is omitted or is C<->, then B<llvm2cpp> reads its input from
|
|
standard input.
|
|
|
|
If an output file is not specified with the B<-o> option, then
|
|
B<llvm2cpp> sends its output to a file or standard output by following
|
|
these rules:
|
|
|
|
=over
|
|
|
|
=item *
|
|
|
|
If the input is standard input, then the output is standard output.
|
|
|
|
=item *
|
|
|
|
If the input is a file that ends with C<.bc>, then the output file is of
|
|
the same name, except that the suffix is changed to C<.cpp>.
|
|
|
|
=item *
|
|
|
|
If the input is a file that does not end with the C<.bc> suffix, then the
|
|
output file has the same name as the input file, except that the C<.cpp>
|
|
suffix is appended.
|
|
|
|
=back
|
|
|
|
=head1 OPTIONS
|
|
|
|
=over
|
|
|
|
=item B<-f>
|
|
|
|
Force overwrite. Normally, B<llvm2cpp> will refuse to overwrite an
|
|
output file that already exists. With this option, B<llvm2cpp>
|
|
will overwrite the output file and replace it with new C++ source code.
|
|
|
|
=item B<--help>
|
|
|
|
Print a summary of command line options.
|
|
|
|
=item B<-f>
|
|
|
|
Normally, B<llvm2cpp> will not overwrite an existing output file. With this
|
|
option, that default behavior is changed and the program will overwrite existing
|
|
output files.
|
|
|
|
=item B<-o> F<filename>
|
|
|
|
Specify the output file name. If F<filename> is C<->, then B<llvm2cpp>
|
|
sends its output to standard output.
|
|
|
|
=item B<-funcname> F<functionName>
|
|
|
|
Specify the name of the function to be generated. The generated code contains a
|
|
single function that produces the input module. By default its name is
|
|
I<makeLLVMModule>. The B<-funcname> option overrides this default and allows
|
|
you to control the name of the generated function. This is handy in conjunction
|
|
with the B<-fragment> option when you only want B<llvm2cpp> to generate a
|
|
single function that produces the module. With both options, such generated code
|
|
could be I<#included> into another program.
|
|
|
|
=item B<-for>
|
|
|
|
Specify the name of the thing for which C++ code should be generated. By default
|
|
the entire input module is re-generated. However, use of the various B<-gen-*>
|
|
options can restrict what is produced. This option indicates what that
|
|
restriction is.
|
|
|
|
=item B<-gen-program>
|
|
|
|
Specify that the output should be a complete program. Such program will recreate
|
|
B<llvm2cpp>'s input as an LLVM module, verify that module, and then write out
|
|
the module in LLVM assembly format. This is useful for doing identity tests
|
|
where the output of the generated program is identical to the input to
|
|
B<llvm2cpp>. The LLVM DejaGnu test suite can make use of this fact. This is the
|
|
default form of generated output.
|
|
|
|
If the B<-for> option is given with this option, it specifies the module
|
|
identifier to use for the module created.
|
|
|
|
=item B<-gen-module>
|
|
|
|
Specify that the output should be a function that regenerates the module. It is
|
|
assumed that this output will be #included into another program that has already
|
|
arranged for the correct header files to be #included. The function generated
|
|
takes no arguments and returns a I<Module*>.
|
|
|
|
If the B<-for> option is given with this option, it specifies the module
|
|
identifier to use in creating the module returned by the generated function.
|
|
|
|
=item B<-gen-contents>
|
|
|
|
Specify that the output should be a function that adds the contents of the input
|
|
module to another module. It is assumed that the output will be #included into
|
|
another program that has already arranged for the correct header files to be
|
|
#included. The function generated takes a single argument of type I<Module*> and
|
|
returns that argument. Note that Module level attributes such as endianess,
|
|
pointer size, target triple and inline asm are not passed on from the input
|
|
module to the destination module. Only the sub-elements of the module (types,
|
|
constants, functions, global variables) will be added to the input module.
|
|
|
|
If the B<-for> option is given with this option, it specifies the module
|
|
identifier to set in the input module by the generated function.
|
|
|
|
=item B<-gen-function>
|
|
|
|
Specify that the output should be a function that produces the definitions
|
|
necessary for a specific function to be added to a module. It is assumed that
|
|
the output will be #included into another program that has already arranged
|
|
for the correct header files to be #included. The function generated takes a
|
|
single argument of type I<Module*> and returns the I<Function*> that it added to
|
|
the module. Note that only those things (types, constants, etc.) directly
|
|
needed in the definition of the function will be placed in the generated
|
|
function.
|
|
|
|
The B<-for> option must be given with this option or an error will be produced.
|
|
The value of the option must be the name of a function in the input module for
|
|
which code should be generated. If the named function does not exist an error
|
|
will be produced.
|
|
|
|
=item B<-gen-inline>
|
|
|
|
This option is very analagous to B<-gen-function> except that the generated
|
|
function will not re-produce the target function's definition. Instead, the body
|
|
of the target function is inserted into some other function passed as an
|
|
argument to the generated function. Similarly any arguments to the function must
|
|
be passed to the generated function. The result of the generated function is the
|
|
first basic block of the target function.
|
|
|
|
The B<-for> option works the same way as it does for B<-gen-function>.
|
|
|
|
=item B<-gen-variable>
|
|
|
|
Specify that the output should be a function that produces the definitions
|
|
necessary for a specific global variable to be added to a module. It is assumed
|
|
that the output will be #included into another program that has already arranged
|
|
for the correct header files to be #included. The function generated takes a
|
|
single argument of type I<Module*> and returns the I<GlobalVariable*> that it
|
|
added to the module. Note that only those things (types, constants, etc.)
|
|
directly needed in the definition of the global variable will be placed in the
|
|
generated function.
|
|
|
|
The B<-for> option must be given with this option or an error will be produced.
|
|
THe value of the option must be the name of a global variable in the input
|
|
module for which code should be generated. If the named global variable does not
|
|
exist an error will be produced.
|
|
|
|
=item B<-gen-type>
|
|
|
|
Specify that the output should be a function that produces the definitions
|
|
necessary for specific type to be added to a module. It is assumed that the
|
|
otuput will be #included into another program that has already arranged for the
|
|
correct header files to be #included. The function generated take a single
|
|
argument of type I<Module*> and returns the I<Type*> that it added to the
|
|
module. Note that the generated function will only add the necessary type
|
|
definitions to (possibly recursively) define the requested type.
|
|
|
|
The B<-for> option must be given with this option or an error will be produced.
|
|
The value of the option must be the name of a global type in the input module
|
|
for which code should be generated. If the named type does not exist an error
|
|
will be produced.
|
|
|
|
=item B<-stats>
|
|
|
|
Show pass statistics (not interesting in this program).
|
|
|
|
=item B<-time-passes>
|
|
|
|
Show pass timing statistics (not interesting in this program).
|
|
|
|
=item B<-version>
|
|
|
|
Show the version number of this program.
|
|
|
|
=back
|
|
|
|
|
|
=head1 EXIT STATUS
|
|
|
|
If B<llvm2cpp> succeeds, it will exit with 0. Otherwise, if an error
|
|
occurs, it will exit with a non-zero value.
|
|
|
|
=head1 SEE ALSO
|
|
|
|
L<llvm-as|llvm-as> L<tblgen|tblgen>
|
|
|
|
=head1 NOTES
|
|
|
|
This tool may be removed from a future version of LLVM. Instead, its
|
|
functionality may be incorporated into the llc tool. It would then act similarly
|
|
to other targets except its output would be C++ source that could be compiled to
|
|
construct the input program.
|
|
|
|
=head1 AUTHORS
|
|
|
|
Written by Reid Spencer (L<http://hlvm.org>).
|
|
|
|
=cut
|