1\input texinfo @c -*-texinfo-*-
2@setfilename gccbrig.info
3@settitle The GNU BRIG (HSAIL) Compiler
4@set copyrights-brig 2017-2018
5
6@c Merge the standard indexes into a single one.
7@syncodeindex fn cp
8@syncodeindex vr cp
9@syncodeindex ky cp
10@syncodeindex pg cp
11@syncodeindex tp cp
12
13@include gcc-common.texi
14
15@copying
16@c man begin COPYRIGHT
17Copyright @copyright{} @value{copyrights-brig} Free Software Foundation, Inc.
18
19Permission is granted to copy, distribute and/or modify this document
20under the terms of the GNU Free Documentation License, Version 1.3 or
21any later version published by the Free Software Foundation; with no
22Invariant Sections, the Front-Cover Texts being (a) (see below), and
23with the Back-Cover Texts being (b) (see below).
24A copy of the license is included in the
25@c man end
26section entitled ``GNU Free Documentation License''.
27@ignore
28@c man begin COPYRIGHT
29man page gfdl(7).
30@c man end
31@end ignore
32
33@c man begin COPYRIGHT
34
35(a) The FSF's Front-Cover Text is:
36
37     A GNU Manual
38
39(b) The FSF's Back-Cover Text is:
40
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.
44@c man end
45@end copying
46
47@ifinfo
48@format
49@dircategory Software development
50@direntry
51* Gccbrig: (gccbrig).           A GCC-based compiler for BRIG/HSAIL finalization
52@end direntry
53@end format
54
55@insertcopying
56@end ifinfo
57
58@titlepage
59@title The GNU BRIG (HSAIL) Compiler
60@versionsubtitle
61@author Pekka Jääskeläinen
62
63@page
64@vskip 0pt plus 1filll
65Published by the Free Software Foundation @*
6651 Franklin Street, Fifth Floor@*
67Boston, MA 02110-1301, USA@*
68@sp 1
69@insertcopying
70@end titlepage
71@contents
72@page
73
74@node Top
75@top Introduction
76
77This manual describes how to use @command{gccbrig}, the GNU compiler for
78the binary representation (BRIG) of the HSA Intermediate Language (HSAIL).
79For more information about the Heterogeneous System Architecture (HSA)
80Foundation's standards in general, see @uref{http://www.hsafoundation.com/}.
81
82@menu
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.
87* Index::                       Index.
88@end menu
89
90@include gpl_v3.texi
91
92@include fdl.texi
93
94
95@node Using Gccbrig
96@chapter Using Gccbrig
97
98@c man title gccbrig A GCC-based compiler for HSAIL
99
100@ignore
101@c man begin SYNOPSIS gccbrig
102gccbrig [@option{-c}|@option{-S}]
103        [@option{-O}@var{level}] [@option{-L}@var{dir}@dots{}]
104        [@option{-o} @var{outfile}] @var{infile}@dots{}
105
106Gccbrig is typically not invoked from the command line, but
107through an HSA finalizer implementation.
108@c man end
109@c man begin SEEALSO
110The Info entry for @file{gccbrig} and
111@uref{https://github.com/HSAFoundation/phsa}
112@c man end
113@end ignore
114
115@c man begin DESCRIPTION gccbrig
116
117The BRIG frontend (@command{gccbrig}) differs from the
118other frontends in GCC on how it's typically used.  It's a translator
119for an intermediate language that is not meant to be written directly
120by programmers.  Its input format BRIG is a binary representation of
121HSAIL, which is a textual assembly format for an imaginary machine
122of which instruction set is defined in HSA Programmer Reference Manual
123(PRM) Specification.  Gccbrig currently implements the Base profile
124of the PRM version 1.0.
125
126HSA Runtime Specification defines an API which includes means
127to build and launch ``kernels'' from a host program running on a CPU
128to one or more heterogeneous ``kernel agents''. A kernel Agent
129is typically a GPU or a DSP device controlled by the CPU.
130The build phase is called ``finalization'', which means translation of
131one or more target-independent BRIG files describing the program that
132one wants to run in the Agent to the Agent's instruction set.  Gccbrig
133implements the translation process by generating GENERIC, which is
134translated to the ISA of any supported GCC target by the GCC's backend
135framework, thus enabling potentially any GCC target to act as an HSA agent.
136
137As 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
139the end user, but through an HSA runtime implementation that implements
140the finalizer API running on the host CPU.  Gccbrig is
141designed to work with an open source HSA runtime implementation
142called ``phsa-runtime'', which can be installed from
143@uref{https://github.com/HSAFoundation/phsa-runtime}.  Phsa-runtime
144has an example Agent driver that allows any GCC-supported CPU to act as
145a kernel Agent.  The web page has further installation instructions for
146setting up it to work with a gccbrig binary installed with the GCC.
147
148@node Index
149@unnumbered Index
150
151@printindex cp
152
153@bye
154