gcc/brig/gccbrig.texi

   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
  17 Copyright @copyright{} @value{copyrights-brig} Free Software Foundation, Inc.
  18
  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
  25 @c man end
  26 section entitled ``GNU Free Documentation License''.
  27 @ignore
  28 @c man begin COPYRIGHT
  29 man 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
  65 Published by the Free Software Foundation @*
  66 51 Franklin Street, Fifth Floor@*
  67 Boston, MA 02110-1301, USA@*
  68 @sp 1
  69 @insertcopying
  70 @end titlepage
  71 @contents
  72 @page
  73
  74 @node Top
  75 @top Introduction
  76
  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/}.
  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
 102 gccbrig [@option{-c}|@option{-S}]
 103         [@option{-O}@var{level}] [@option{-L}@var{dir}@dots{}]
 104         [@option{-o} @var{outfile}] @var{infile}@dots{}
 105
 106 Gccbrig is typically not invoked from the command line, but
 107 through an HSA finalizer implementation.
 108 @c man end
 109 @c man begin SEEALSO
 110 The 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
 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.
 125
 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.
 136
 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.
 147
 148 @node Index
 149 @unnumbered Index
 150
 151 @printindex cp
 152
 153 @bye