[BRIG] added documentation in gccbrig.texi

From-SVN: r254820

gcc/brig/ChangeLog

+2017-11-16  Pekka Jääskeläinen  <pekka.jaaskelainen@parmance.com>
+
+	* gccbrig.texi: Added some documentation.
+
 2017-10-31  Henry Linjamäki  <henry.linjamaki@parmance.com>
 
 	* brig-lang.c (brig_langhook_type_for_mode): Fix PR 82771.

gcc/brig/gccbrig.texi

 \input texinfo @c -*-texinfo-*-
 @setfilename gccbrig.info
-@settitle The GNU BRIG Compiler
+@settitle The GNU BRIG (HSAIL) Compiler
+@set copyrights-brig 2017
+
+@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