[cfe-dev] [RFC][OpenMP][CUDA] Generic Offload File Bundler Tool

[Samuel F Antao via cfe-dev]

Hi all,


Programming models that support offloading require different toolchains
involved in the compilation process. Usually, one toolchain for host and as
many toolchains as different devices one wants to offload to is required.
If separate compilation is used this means that for a single source file
one may get multiple output files.

Also, one of the goals of programming models that support offloading (e.g.
OpenMP, CUDA) is to enable users to offload with little effort, by
annotating the code with a few pragmas or attributes. It is also desirable
that we can save users the trouble of changing their existent applications'
build system to deal all the different files for the different toolchains.
So having the compiler always return a single file instead of one for the
host and each target even if the user is doing separate compilation would
be in my view a very welcomed feature.

I am proposing a tool that I am naming clang-offload-bundler (happy to
change the name if required) that is used to bundle files associated with
the same user source file but different targets, or to unbundle a file into
separate files associated with different targets. A tentative
implementation of what is proposed in this RFC is posted in
http://reviews.llvm.org/D13909.

This RFC complements the RFC related with offloading driver changes
in [RFC][OpenMP][CUDA] Unified Offloading Support in Clang Driver.

Let me know your thoughts. Any feedback is very welcomed!

Thanks!

Samuel

================

Proposal Description

================

a) Bundler/Unbundler behavior:

This tool could be invoked with the commands:

clang-offload-bundler -targets=device1ID,device2ID -type=ii
-inputs=a.device1.ii,a.device2.ii -outputs=a.ii

or

clang-offload-bundler -targets=device1ID,device2ID -type=ii
-outputs=a.device1.ii,a.device2.ii -inputs=a.ii -unbundle

In “bundling mode” the tool takes as input multiple files and produce a
single one whereas in “unbundling mode” (activated with the -unbundle flag)
the opposite is true. In the bundled files, the content of the input files
are stored "as is” and associated with an ID that is provided with the
-targets option. The ID can be anything that uniquely identifes a bundle,
e.g a combination of the device triple and programming model name.

The order of the IDs in the -targets options should be consistent with the
order of the input (bundling) or output file (unbundling).

In unbundling mode, the input file is always expected to have the format of
a bundler. The device IDs are used to retrieve the right content from the
bundler and produce the output files in the order the user requested.



b) Bundled file format.

The bundled file should be agnostic of the format of the input file so that
it can easily cover all the formats produced in clang. It should however
distinguish text formats from binary formats. That distinction is made
through the -type option whose possible values are the same as in Types.def.

For text formats the -type option also allows the tool to understand how a
comment is implemented in that format so that the deviceID associated with
a bundle is encoded as comment. These comments would work as separators
between bundles so the user can conveniently read/edit the bundler if he
feels like it without bothering about bundler format.

For binary files, the bundler would have an header that specify the offsets
of the different bundlers.

I propose the following for the bundler format (this is the format I
employed in http://reviews.llvm.org/D13909):

b-i) Format for binary bundlers:

// "OFFLOAD_BUNDLER_MAGIC_STR" (ASCII encoding of the string)

//

// NumberOfOffloadBundles (8-byte integer)

//

// OffsetOfBundle1 (8-byte integer)

// SizeOfBundle1 (8-byte integer)

// NumberOfBytesInTripleOfBundle1 (8-byte integer)

// TripleOfBundle1 (byte length defined before)

//

// ...

//

// OffsetOfBundleN (8-byte integer)

// SizeOfBundleN (8-byte integer)

// NumberOfBytesInTripleOfBundleN (8-byte integer)

// TripleOfBundleN (byte length defined before)

//

// Bundle1

// ...

// BundleN


b-ii) Format for text bundlers:

// "Comment OFFLOAD_BUNDLER_MAGIC_STR__START__ triple"

// Bundle 1

// "Comment OFFLOAD_BUNDLER_MAGIC_STR__END__ triple"

// ...

// "Comment OFFLOAD_BUNDLER_MAGIC_STR__START__ triple"

// Bundle N

// "Comment OFFLOAD_BUNDLER_MAGIC_STR__END__ triple”


============

Call For Action

============

Please review this proposal if you are concerned with support of offloading
models, or any other use case that may require multiple file generation by
the driver, and provide your feedback. Our goal is to reach an agreement in
the community and proceed with implementation.


=================

Implementation Plan

=================

1. Upon reaching the agreement on the proposal, we (IBM compiler team) will
start to submit patches implementing the bundler tool including the
required changes for the build system. Code review would be much
appreciated!

2. The implementation will be articulated with the ongoing developments in
the clang driver given that would be (at least initially) the major client
of this tool, and where several tests could be implemented.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-dev/attachments/20160224/70bba276/attachment.html>