1 \input texinfo @c -*-texinfo-*-
2 @setfilename gccbrig.info
3 @settitle The GNU BRIG (HSAIL) Compiler
4 @set copyrights-brig 2017-2018
6 @c Merge the standard indexes into a single one.
13 @include gcc-common.texi
16 @c man begin COPYRIGHT
17 Copyright @copyright{} @value{copyrights-brig} Free Software Foundation, Inc.
19 Permission is granted to copy, distribute and/or modify this document
20 under the terms of the GNU Free Documentation License, Version 1.3 or
21 any later version published by the Free Software Foundation; with no
22 Invariant Sections, the Front-Cover Texts being (a) (see below), and
23 with the Back-Cover Texts being (b) (see below).
24 A copy of the license is included in the
26 section entitled ``GNU Free Documentation License''.
28 @c man begin COPYRIGHT
33 @c man begin COPYRIGHT
35 (a) The FSF's Front-Cover Text is:
39 (b) The FSF's Back-Cover Text is:
41 You have freedom to copy and modify this GNU Manual, like GNU
42 software. Copies published by the Free Software Foundation raise
43 funds for GNU development.
49 @dircategory Software development
51 * Gccbrig: (gccbrig). A GCC-based compiler for BRIG/HSAIL finalization
59 @title The GNU BRIG (HSAIL) Compiler
61 @author Pekka Jääskeläinen
64 @vskip 0pt plus 1filll
65 Published by the Free Software Foundation @*
66 51 Franklin Street, Fifth Floor@*
67 Boston, MA 02110-1301, USA@*
77 This manual describes how to use @command{gccbrig}, the GNU compiler for
78 the binary representation (BRIG) of the HSA Intermediate Language (HSAIL).
79 For more information about the Heterogeneous System Architecture (HSA)
80 Foundation's standards in general, see @uref{http://www.hsafoundation.com/}.
83 * Copying:: The GNU General Public License.
84 * GNU Free Documentation License::
85 How you can share and copy this manual.
86 * Using Gccbrig:: How to use Gccbrig.
96 @chapter Using Gccbrig
98 @c man title gccbrig A GCC-based compiler for HSAIL
101 @c man begin SYNOPSIS gccbrig
102 gccbrig [@option{-c}|@option{-S}]
103 [@option{-O}@var{level}] [@option{-L}@var{dir}@dots{}]
104 [@option{-o} @var{outfile}] @var{infile}@dots{}
106 Gccbrig is typically not invoked from the command line, but
107 through an HSA finalizer implementation.
110 The Info entry for @file{gccbrig} and
111 @uref{https://github.com/HSAFoundation/phsa}
115 @c man begin DESCRIPTION gccbrig
117 The BRIG frontend (@command{gccbrig}) differs from the
118 other frontends in GCC on how it's typically used. It's a translator
119 for an intermediate language that is not meant to be written directly
120 by programmers. Its input format BRIG is a binary representation of
121 HSAIL, which is a textual assembly format for an imaginary machine
122 of which instruction set is defined in HSA Programmer Reference Manual
123 (PRM) Specification. Gccbrig currently implements the Base profile
124 of the PRM version 1.0.
126 HSA Runtime Specification defines an API which includes means
127 to build and launch ``kernels'' from a host program running on a CPU
128 to one or more heterogeneous ``kernel agents''. A kernel Agent
129 is typically a GPU or a DSP device controlled by the CPU.
130 The build phase is called ``finalization'', which means translation of
131 one or more target-independent BRIG files describing the program that
132 one wants to run in the Agent to the Agent's instruction set. Gccbrig
133 implements the translation process by generating GENERIC, which is
134 translated to the ISA of any supported GCC target by the GCC's backend
135 framework, thus enabling potentially any GCC target to act as an HSA agent.
137 As the kernel finalization process can be only launched from the host API,
138 @command{gccbrig} is not typically used directly from the command line by
139 the end user, but through an HSA runtime implementation that implements
140 the finalizer API running on the host CPU. Gccbrig is
141 designed to work with an open source HSA runtime implementation
142 called ``phsa-runtime'', which can be installed from
143 @uref{https://github.com/HSAFoundation/phsa-runtime}. Phsa-runtime
144 has an example Agent driver that allows any GCC-supported CPU to act as
145 a kernel Agent. The web page has further installation instructions for
146 setting up it to work with a gccbrig binary installed with the GCC.