\input texinfo @c -*-texinfo-*-
@setfilename gccbrig.info
@settitle The GNU BRIG (HSAIL) Compiler
@set copyrights-brig 2017-2020

@c Merge the standard indexes into a single one.
@syncodeindex fn cp
@syncodeindex vr cp
@syncodeindex ky cp
@syncodeindex pg cp
@syncodeindex tp cp

@include gcc-common.texi

@copying
@c man begin COPYRIGHT
Copyright @copyright{} @value{copyrights-brig} Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, the Front-Cover Texts being (a) (see below), and
with the Back-Cover Texts being (b) (see below).
A copy of the license is included in the
@c man end
section entitled ``GNU Free Documentation License''.
@ignore
@c man begin COPYRIGHT
man page gfdl(7).
@c man end
@end ignore

@c man begin COPYRIGHT

(a) The FSF's Front-Cover Text is:

     A GNU Manual

(b) The FSF's Back-Cover Text is:

     You have freedom to copy and modify this GNU Manual, like GNU
     software.  Copies published by the Free Software Foundation raise
     funds for GNU development.
@c man end
@end copying

@ifinfo
@format
@dircategory Software development
@direntry
* Gccbrig: (gccbrig).           A GCC-based compiler for BRIG/HSAIL finalization
@end direntry
@end format

@insertcopying
@end ifinfo

@titlepage
@title The GNU BRIG (HSAIL) Compiler
@versionsubtitle
@author Pekka Jääskeläinen

@page
@vskip 0pt plus 1filll
Published by the Free Software Foundation @*
51 Franklin Street, Fifth Floor@*
Boston, MA 02110-1301, USA@*
@sp 1
@insertcopying
@end titlepage
@contents
@page

@node Top
@top Introduction

This manual describes how to use @command{gccbrig}, the GNU compiler for
the binary representation (BRIG) of the HSA Intermediate Language (HSAIL).
For more information about the Heterogeneous System Architecture (HSA)
Foundation's standards in general, see @uref{http://www.hsafoundation.com/}.

@menu
* Copying::                     The GNU General Public License.
* GNU Free Documentation License::
                                How you can share and copy this manual.
* Using Gccbrig::               How to use Gccbrig.
* Index::                       Index.
@end menu

@include gpl_v3.texi

@include fdl.texi


@node Using Gccbrig
@chapter Using Gccbrig

@c man title gccbrig A GCC-based compiler for HSAIL

@ignore
@c man begin SYNOPSIS gccbrig
gccbrig [@option{-c}|@option{-S}]
        [@option{-O}@var{level}] [@option{-L}@var{dir}@dots{}]
        [@option{-o} @var{outfile}] @var{infile}@dots{}

Gccbrig is typically not invoked from the command line, but
through an HSA finalizer implementation.
@c man end
@c man begin SEEALSO
The Info entry for @file{gccbrig} and
@uref{https://github.com/HSAFoundation/phsa}
@c man end
@end ignore

@c man begin DESCRIPTION gccbrig

The BRIG frontend (@command{gccbrig}) differs from the
other frontends in GCC on how it's typically used.  It's a translator
for an intermediate language that is not meant to be written directly
by programmers.  Its input format BRIG is a binary representation of
HSAIL, which is a textual assembly format for an imaginary machine
of which instruction set is defined in HSA Programmer Reference Manual
(PRM) Specification.  Gccbrig currently implements the Base profile
of the PRM version 1.0.

HSA Runtime Specification defines an API which includes means
to build and launch ``kernels'' from a host program running on a CPU
to one or more heterogeneous ``kernel agents''. A kernel Agent
is typically a GPU or a DSP device controlled by the CPU.
The build phase is called ``finalization'', which means translation of
one or more target-independent BRIG files describing the program that
one wants to run in the Agent to the Agent's instruction set.  Gccbrig
implements the translation process by generating GENERIC, which is
translated to the ISA of any supported GCC target by the GCC's backend
framework, thus enabling potentially any GCC target to act as an HSA agent.

As the kernel finalization process can be only launched from the host API,
@command{gccbrig} is not typically used directly from the command line by
the end user, but through an HSA runtime implementation that implements
the finalizer API running on the host CPU.  Gccbrig is
designed to work with an open source HSA runtime implementation
called ``phsa-runtime'', which can be installed from
@uref{https://github.com/HSAFoundation/phsa-runtime}.  Phsa-runtime
has an example Agent driver that allows any GCC-supported CPU to act as
a kernel Agent.  The web page has further installation instructions for
setting up it to work with a gccbrig binary installed with the GCC.

@node Index
@unnumbered Index

@printindex cp

@bye