From: Pekka Jääskeläinen Date: Thu, 16 Nov 2017 13:59:16 +0000 (+0000) Subject: [BRIG] added documentation in gccbrig.texi X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=6748a40f131f846d40e7c93a1a3211bd81d17812;p=gcc.git [BRIG] added documentation in gccbrig.texi From-SVN: r254820 --- diff --git a/gcc/brig/ChangeLog b/gcc/brig/ChangeLog index dede3f405f5..0945aa41baa 100644 --- a/gcc/brig/ChangeLog +++ b/gcc/brig/ChangeLog @@ -1,3 +1,7 @@ +2017-11-16 Pekka Jääskeläinen + + * gccbrig.texi: Added some documentation. + 2017-10-31 Henry Linjamäki * brig-lang.c (brig_langhook_type_for_mode): Fix PR 82771. diff --git a/gcc/brig/gccbrig.texi b/gcc/brig/gccbrig.texi index 9636c00f06c..7ee1b0259cd 100644 --- a/gcc/brig/gccbrig.texi +++ b/gcc/brig/gccbrig.texi @@ -1,5 +1,153 @@ \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