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 <mjam...@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 <dmalc...@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
