     [file gcc-common.texi not included]

Copyright © 2017-2021 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 section entitled ``GNU Free Documentation License''.

(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.

Introduction
************

This manual describes how to use 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 http://www.hsafoundation.com/.

     [file gpl_v3.texi not included]

     [file fdl.texi not included]

Using Gccbrig
*************

The BRIG frontend (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, 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 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.