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

Wed Feb 24 23:46:39 PST 2016

Hi Samuel,

Thanks for this detailed explanation on how you plan to do this.

I really much like the idea of bundling and only giving back one single file to the user. This should make it easier to use offloading techniques.

I have one question but don’t know all formats in depth:

Given that the separation is done by respective comments in that format, a tool would concatenate all bundles if it doesn’t know about the bundling, right?

(Imagine a scenario where one object file is compiled with offloading enabled and is afterwards linked into a “plain” executable…)

Are there any “tricks” that could be employed to make the “old” / “normal” tools fall back to the host bundle or a “default” triple?

For example starting a comment section after the first bundle which the clang-offoad-bundler knows about, ignores and correctly extracts the other bundles, but that hides them for other tools?

Thanks,

Jonas

From: samuelfantao at gmail.com [mailto:samuelfantao at gmail.com] On Behalf Of Samuel F Antao
Sent: Thursday, February 25, 2016 1:15 AM
To: Alexey Bataev; Hal Finkel; John McCall; Eric Christopher; Artem Belevich; Hahnfeld, Jonas; cfe-dev at lists.llvm.org
Subject: [RFC][OpenMP][CUDA] Generic Offload File Bundler Tool

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/20160225/d859b69c/attachment.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/pkcs7-signature
Size: 5868 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/cfe-dev/attachments/20160225/d859b69c/attachment.bin>