Re: [PATCH] BRIG frontend: request for a global review

[Pekka Jääskeläinen <pekka at parmance dot com>]

Hi,

I added some content to gccbrig.texi in r254820 as below. If you have something
that I could describe further there, please just let me know.

Index: gcc/brig/gccbrig.texi
===================================================================
--- gcc/brig/gccbrig.texi (revision 254819)
+++ gcc/brig/gccbrig.texi (revision 254820)
@@ -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

On Tue, Sep 26, 2017 at 2:55 PM, Martin Jambor <mjambor@suse.cz> wrote:
> Hi,
>
> On Sun, Sep 17, 2017 at 02:13:34PM +0200, Thomas Schwinge wrote:
>> Hi!
>>
>> On Tue, 24 Jan 2017 15:30:34 -0500, David Malcolm <dmalcolm@redhat.com> wrote:
>> > On Tue, 2017-01-24 at 13:52 +0100, Martin Jambor wrote:
>> > > [...] I have just
>> > > committed the BRIG FE as revision 244867.
>>
>> In a build with that enabled, I just happened to "make html" in "gcc/",
>> and ran into:
>>
>>     [...]
>>     makeinfo --split-size=5000000 --html -I [...]/source-gcc/gcc/doc -I [...]/source-gcc/gcc/doc/include \
>>             -I [...]/source-gcc/gcc/brig -o [...]/build-gcc/gcc/HTML/gcc-8.0.0/brig
>>     makeinfo: missing file argument.
>>     Try `makeinfo --help' for more information.
>>     [...]/source-gcc/gcc/brig/Make-lang.in:117: recipe for target '[...]/build-gcc/gcc/HTML/gcc-8.0.0/brig/index.html' failed
>>     make: *** [[...]/build-gcc/gcc/HTML/gcc-8.0.0/brig/index.html] Error 255
>>
>> > A deps issue for the docs I noticed when glancing through the commit:
>> >
>> > diff --git a/gcc/brig/Make-lang.in b/gcc/brig/Make-lang.in
>> > new file mode 100644 (file)
>> > index 0000000..b85b1b0
>> > --- /dev/null
>> > +++ b/gcc/brig/Make-lang.in
>> >
>> > [...snip...]
>> >
>> > +# Documentation.
>> > +
>> > +GO_TEXI_FILES = \
>> > +       brig/gccbrig.texi \
>> > +       $(gcc_docdir)/include/fdl.texi \
>> > +       $(gcc_docdir)/include/gpl_v3.texi \
>> > +       $(gcc_docdir)/include/gcc-common.texi \
>> > +       gcc-vers.texi
>> >
>> > Presumably this should be BRIG_TEXI_FILES, rather than GO_TEXI_FILES?
>> >
>> > +# doc/gccbrig.info: $(BRIG_TEXI_FILES)
>> > +#      if test "x$(BUILD_INFO)" = xinfo; then \
>> > +#        rm -f doc/gccbrig.info*; \
>> > +#        $(MAKEINFO) $(MAKEINFOFLAGS) -I $(gcc_docdir) \
>> > +#              -I $(gcc_docdir)/include -o $@ $<; \
>> > +#      else true; fi
>> > +
>> > +# doc/gccbrig.dvi: $(BRIG_TEXI_FILES)
>> > +#      $(TEXI2DVI) -I $(abs_docdir) -I $(abs_docdir)/include -o $@ $<
>> > +
>> > +# doc/gccbrig.pdf: $(BRIG_TEXI_FILES)
>> > +#      $(TEXI2PDF) -I $(abs_docdir) -I $(abs_docdir)/include -o $@ $<
>> > +
>> > +$(build_htmldir)/brig/index.html: $(BRIG_TEXI_FILES)
>> > +       $(mkinstalldirs) $(@D)
>> > +       rm -f $(@D)/*
>> > +       $(TEXI2HTML) -I $(gcc_docdir) -I $(gcc_docdir)/include \
>> > +               -I $(srcdir)/brig -o $(@D) $<
>> >
>> > ...for use in describing the deps of the above.
>>
>> ..., so that still needs to be fixed.  Alas, that won't help: the
>> "gccbrig.texi" file doesn't actually exist.  ;-)
>>
>
> I see, I always only check "make info" when verifying documentation
> changes and so missed this.  Thanks for providing the interim fix, me
> and/or Pekka will add some basic content by the time next gcc 7 is
> released (IIRC, it is supposed to come out at the end of this or the
> beginning of next year).
>
> Martin