This is an archive of the discontinued LLVM Phabricator instance.

Differential D24724

AMDGPU: Improve documentation.
ClosedPublic

Authored by nhaustov on Sep 19 2016, 5:41 AM.

Details

Reviewers
• tstellarAMD
vpykhtin
SamWot
Commits
rG96a56bd0c613: AMDGPU: Improve documentation.
rL281962: AMDGPU: Improve documentation.
Summary

Add links to ISA manuals and ABI.
Add text about assembler syntax.
Add info about instructions operands.
Add instruction examples for each encoding.
Update directives section, add missing .amdgpu_hsa_kernel.

Diff Detail

Event Timeline

nhaustov updated this revision to Diff 71816.Sep 19 2016, 5:41 AM
nhaustov retitled this revision from to AMDGPU: Improve documentation..
nhaustov updated this object.
nhaustov added reviewers: • tstellarAMD, SamWot, vpykhtin.
nhaustov added subscribers: llvm-commits, artem.tamazov.
Herald added subscribers: tony-tye, yaxunl, nhaehnle and 2 others. · View Herald TranscriptSep 19 2016, 5:41 AM
nhaustov updated this revision to Diff 71817.Sep 19 2016, 5:43 AM

Add generated html file for easy review (will be removed in the commit).

SamWot accepted this revision.Sep 19 2016, 7:49 AM
SamWot edited edge metadata.

LGTM

This revision is now accepted and ready to land.Sep 19 2016, 7:49 AM
artem.tamazov added inline comments.Sep 19 2016, 12:25 PM
docs/AMDGPUUsage.rst
73

I would add quotes around off.

• tstellarAMD added inline comments.Sep 19 2016, 1:58 PM
docs/AMDGPUUsage.rst
11–19

The convention is to put these in CompilerWriterInfo.rst Maybe we move these to this file and then add a link to it.

Closed by commit rL281962: AMDGPU: Improve documentation. (authored by nhaustov). · Explain WhySep 20 2016, 2:13 AM
This revision was automatically updated to reflect the committed changes.

Revision Contents

PathSize
build.doc/
docs/
html/
431 lines
docs/
291 lines

Diff 71817

build.doc/docs/html/AMDGPUUsage.html

  • This file was added.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>User Guide for AMDGPU Back-end &#8212; LLVM 4.0 documentation</title>
<link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: '4.0',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="top" title="LLVM 4.0 documentation" href="index.html" />
<link rel="next" title="Stack maps and patch points in LLVM" href="StackMaps.html" />
<link rel="prev" title="User Guide for NVPTX Back-end" href="NVPTXUsage.html" />
<style type="text/css">
table.right { float: right; margin-left: 20px; }
table.right td { border: 1px solid #ccc; }
</style>
</head>
<body role="document">
<div class="logo">
<a href="index.html">
<img src="_static/logo.png"
alt="LLVM Logo" width="250" height="88"/></a>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="StackMaps.html" title="Stack maps and patch points in LLVM"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="NVPTXUsage.html" title="User Guide for NVPTX Back-end"
accesskey="P">previous</a> |</li>
<li><a href="http://llvm.org/">LLVM Home</a>&nbsp;|&nbsp;</li>
<li><a href="index.html">Documentation</a>&raquo;</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="body" role="main">
<div class="section" id="user-guide-for-amdgpu-back-end">
<h1>User Guide for AMDGPU Back-end<a class="headerlink" href="#user-guide-for-amdgpu-back-end" title="Permalink to this headline"></a></h1>
<div class="section" id="introduction">
<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline"></a></h2>
<p>The AMDGPU back-end provides ISA code generation for AMD GPUs, starting with
the R600 family up until the current Volcanic Islands (GCN Gen 3).</p>
<p>The following additional documentation is available:</p>
<ul class="simple">
<li>AMD GCN3 Instruction Set Architecture: <a class="reference external" href="http://amd-dev.wpengine.netdna-cdn.com/wordpress/media/2013/12/AMD_GCN3_Instruction_Set_Architecture_rev1.1.pdf">PDF</a></li>
<li>Southern Islands Series Instruction Set Architecture: <a class="reference external" href="http://amd-dev.wpengine.netdna-cdn.com/wordpress/media/2013/07/AMD_Southern_Islands_Instruction_Set_Architecture1.pdf">PDF</a></li>
<li>R600-Family Instruction Set Architecture: <a class="reference external" href="http://amd-dev.wpengine.netdna-cdn.com/wordpress/media/2012/10/r600isa.pdf">PDF</a></li>
<li>AMDGPU Compute Application Binary Interface: <a class="reference external" href="https://github.com/RadeonOpenCompute/ROCm-ComputeABI-Doc/blob/master/AMDGPU-ABI.md">MD</a></li>
</ul>
</div>
<div class="section" id="conventions">
<h2>Conventions<a class="headerlink" href="#conventions" title="Permalink to this headline"></a></h2>
<div class="section" id="address-spaces">
<h3>Address Spaces<a class="headerlink" href="#address-spaces" title="Permalink to this headline"></a></h3>
<p>The AMDGPU back-end uses the following address space mapping:</p>
<blockquote>
<div><table border="1" class="docutils">
<colgroup>
<col width="23%" />
<col width="77%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Address Space</th>
<th class="head">Memory Space</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>0</td>
<td>Private</td>
</tr>
<tr class="row-odd"><td>1</td>
<td>Global</td>
</tr>
<tr class="row-even"><td>2</td>
<td>Constant</td>
</tr>
<tr class="row-odd"><td>3</td>
<td>Local</td>
</tr>
<tr class="row-even"><td>4</td>
<td>Generic (Flat)</td>
</tr>
<tr class="row-odd"><td>5</td>
<td>Region</td>
</tr>
</tbody>
</table>
</div></blockquote>
<p>The terminology in the table, aside from the region memory space, is from the
OpenCL standard.</p>
</div>
</div>
<div class="section" id="assembler">
<h2>Assembler<a class="headerlink" href="#assembler" title="Permalink to this headline"></a></h2>
<p>AMDGPU backend has LLVM-MC based assembler which is currently in development.
It supports Southern Islands ISA, Sea Islands and Volcanic Islands.</p>
<p>This document describes general syntax for instructions and operands. For more
information about instructions, their semantics and supported combinations
of operands, refer to one of Instruction Set Architecture manuals.</p>
<p>An instruction has the following syntax (register operands are
normally comma-separated while extra operands are space-separated):</p>
<p><em>&lt;opcode&gt; &lt;register_operand0&gt;, ... &lt;extra_operand0&gt; ...</em></p>
<div class="section" id="operands">
<h3>Operands<a class="headerlink" href="#operands" title="Permalink to this headline"></a></h3>
<p>The following syntax for register operands is supported:</p>
<ul class="simple">
<li>SGPR registers: s0, ... or s[0], ...</li>
<li>VGPR registers: v0, ... or v[0], ...</li>
<li>TTMP registers: ttmp0, ... or ttmp[0], ...</li>
<li>Special registers: exec (exec_lo, exec_hi), vcc (vcc_lo, vcc_hi), flat_scratch (flat_scratch_lo, flat_scratch_hi)</li>
<li>Special trap registers: tba (tba_lo, tba_hi), tma (tma_lo, tma_hi)</li>
<li>Register pairs, quads, etc: s[2:3], v[10:11], ttmp[5:6], s[4:7], v[12:15], ttmp[4:7], s[8:15], ...</li>
<li>Register lists: [s0, s1], [ttmp0, ttmp1, ttmp2, ttmp3]</li>
<li>Register index expressions: v[2*2], s[1-1:2-1]</li>
<li>off indicates that an operand is not enabled</li>
</ul>
<p>The following extra operands are supported:</p>
<ul class="simple">
<li>offset, offset0, offset1</li>
<li>idxen, offen bits</li>
<li>glc, slc, tfe bits</li>
<li>waitcnt: integer or combination of counter values</li>
<li>VOP3 modifiers:<ul>
<li>abs (| |), neg (-)</li>
</ul>
</li>
<li>DPP modifiers:<ul>
<li>row_shl, row_shr, row_ror, row_rol</li>
<li>row_mirror, row_half_mirror, row_bcast</li>
<li>wave_shl, wave_shr, wave_ror, wave_rol, quad_perm</li>
<li>row_mask, bank_mask, bound_ctrl</li>
</ul>
</li>
<li>SDWA modifiers:<ul>
<li>dst_sel, src0_sel, src1_sel (BYTE_N, WORD_M, DWORD)</li>
<li>dst_unused (UNUSED_PAD, UNUSED_SEXT, UNUSED_PRESERVE)</li>
<li>abs, neg, sext</li>
</ul>
</li>
</ul>
</div>
<div class="section" id="ds-instructions-examples">
<h3>DS Instructions Examples<a class="headerlink" href="#ds-instructions-examples" title="Permalink to this headline"></a></h3>
<div class="highlight-nasm"><div class="highlight"><pre><span></span><span class="nf">ds_add_u32</span> <span class="nv">v2</span><span class="p">,</span> <span class="nv">v4</span> <span class="nv">offset</span><span class="p">:</span><span class="mi">16</span>
<span class="nf">ds_write_src2_b64</span> <span class="nv">v2</span> <span class="nv">offset0</span><span class="p">:</span><span class="mi">4</span> <span class="nv">offset1</span><span class="p">:</span><span class="mi">8</span>
<span class="nf">ds_cmpst_f32</span> <span class="nv">v2</span><span class="p">,</span> <span class="nv">v4</span><span class="p">,</span> <span class="nv">v6</span>
<span class="nf">ds_min_rtn_f64</span> <span class="nv">v</span><span class="p">[</span><span class="mi">8</span><span class="p">:</span><span class="mi">9</span><span class="p">],</span> <span class="nv">v2</span><span class="p">,</span> <span class="nv">v</span><span class="p">[</span><span class="mi">4</span><span class="p">:</span><span class="mi">5</span><span class="p">]</span>
</pre></div>
</div>
<p>For full list of supported instructions, refer to &#8220;LDS/GDS instructions&#8221; in ISA Manual.</p>
</div>
<div class="section" id="flat-instruction-examples">
<h3>FLAT Instruction Examples<a class="headerlink" href="#flat-instruction-examples" title="Permalink to this headline"></a></h3>
<div class="highlight-nasm"><div class="highlight"><pre><span></span><span class="nf">flat_load_dword</span> <span class="nv">v1</span><span class="p">,</span> <span class="nv">v</span><span class="p">[</span><span class="mi">3</span><span class="p">:</span><span class="mi">4</span><span class="p">]</span>
<span class="nf">flat_store_dwordx3</span> <span class="nv">v</span><span class="p">[</span><span class="mi">3</span><span class="p">:</span><span class="mi">4</span><span class="p">],</span> <span class="nv">v</span><span class="p">[</span><span class="mi">5</span><span class="p">:</span><span class="mi">7</span><span class="p">]</span>
<span class="nf">flat_atomic_swap</span> <span class="nv">v1</span><span class="p">,</span> <span class="nv">v</span><span class="p">[</span><span class="mi">3</span><span class="p">:</span><span class="mi">4</span><span class="p">],</span> <span class="nv">v5</span> <span class="nv">glc</span>
<span class="nf">flat_atomic_cmpswap</span> <span class="nv">v1</span><span class="p">,</span> <span class="nv">v</span><span class="p">[</span><span class="mi">3</span><span class="p">:</span><span class="mi">4</span><span class="p">],</span> <span class="nv">v</span><span class="p">[</span><span class="mi">5</span><span class="p">:</span><span class="mi">6</span><span class="p">]</span> <span class="nv">glc</span> <span class="nv">slc</span>
<span class="nf">flat_atomic_fmax_x2</span> <span class="nv">v</span><span class="p">[</span><span class="mi">1</span><span class="p">:</span><span class="mi">2</span><span class="p">],</span> <span class="nv">v</span><span class="p">[</span><span class="mi">3</span><span class="p">:</span><span class="mi">4</span><span class="p">],</span> <span class="nv">v</span><span class="p">[</span><span class="mi">5</span><span class="p">:</span><span class="mi">6</span><span class="p">]</span> <span class="nv">glc</span>
</pre></div>
</div>
<p>For full list of supported instructions, refer to &#8220;FLAT instructions&#8221; in ISA Manual.</p>
</div>
<div class="section" id="mubuf-instruction-examples">
<h3>MUBUF Instruction Examples<a class="headerlink" href="#mubuf-instruction-examples" title="Permalink to this headline"></a></h3>
<div class="highlight-nasm"><div class="highlight"><pre><span></span><span class="nf">buffer_load_dword</span> <span class="nv">v1</span><span class="p">,</span> <span class="nv">off</span><span class="p">,</span> <span class="nv">s</span><span class="p">[</span><span class="mi">4</span><span class="p">:</span><span class="mi">7</span><span class="p">],</span> <span class="nv">s1</span>
<span class="nf">buffer_store_dwordx4</span> <span class="nv">v</span><span class="p">[</span><span class="mi">1</span><span class="p">:</span><span class="mi">4</span><span class="p">],</span> <span class="nv">v2</span><span class="p">,</span> <span class="nv">ttmp</span><span class="p">[</span><span class="mi">4</span><span class="p">:</span><span class="mi">7</span><span class="p">],</span> <span class="nv">s1</span> <span class="nv">offen</span> <span class="nv">offset</span><span class="p">:</span><span class="mi">4</span> <span class="nv">glc</span> <span class="nv">tfe</span>
<span class="nf">buffer_store_format_xy</span> <span class="nv">v</span><span class="p">[</span><span class="mi">1</span><span class="p">:</span><span class="mi">2</span><span class="p">],</span> <span class="nv">off</span><span class="p">,</span> <span class="nv">s</span><span class="p">[</span><span class="mi">4</span><span class="p">:</span><span class="mi">7</span><span class="p">],</span> <span class="nv">s1</span>
<span class="nf">buffer_wbinvl1</span>
<span class="nf">buffer_atomic_inc</span> <span class="nv">v1</span><span class="p">,</span> <span class="nv">v2</span><span class="p">,</span> <span class="nv">s</span><span class="p">[</span><span class="mi">8</span><span class="p">:</span><span class="mi">11</span><span class="p">],</span> <span class="nv">s4</span> <span class="nv">idxen</span> <span class="nv">offset</span><span class="p">:</span><span class="mi">4</span> <span class="nv">slc</span>
</pre></div>
</div>
<p>For full list of supported instructions, refer to &#8220;MUBUF Instructions&#8221; in ISA Manual.</p>
</div>
<div class="section" id="smrd-smem-instruction-examples">
<h3>SMRD/SMEM Instruction Examples<a class="headerlink" href="#smrd-smem-instruction-examples" title="Permalink to this headline"></a></h3>
<div class="highlight-nasm"><div class="highlight"><pre><span></span><span class="nf">s_load_dword</span> <span class="nv">s1</span><span class="p">,</span> <span class="nv">s</span><span class="p">[</span><span class="mi">2</span><span class="p">:</span><span class="mi">3</span><span class="p">],</span> <span class="mh">0xfc</span>
<span class="nf">s_load_dwordx8</span> <span class="nv">s</span><span class="p">[</span><span class="mi">8</span><span class="p">:</span><span class="mi">15</span><span class="p">],</span> <span class="nv">s</span><span class="p">[</span><span class="mi">2</span><span class="p">:</span><span class="mi">3</span><span class="p">],</span> <span class="nv">s4</span>
<span class="nf">s_load_dwordx16</span> <span class="nv">s</span><span class="p">[</span><span class="mi">88</span><span class="p">:</span><span class="mi">103</span><span class="p">],</span> <span class="nv">s</span><span class="p">[</span><span class="mi">2</span><span class="p">:</span><span class="mi">3</span><span class="p">],</span> <span class="nv">s4</span>
<span class="nf">s_dcache_inv_vol</span>
<span class="nf">s_memtime</span> <span class="nv">s</span><span class="p">[</span><span class="mi">4</span><span class="p">:</span><span class="mi">5</span><span class="p">]</span>
</pre></div>
</div>
<p>For full list of supported instructions, refer to &#8220;Scalar Memory Operations&#8221; in ISA Manual.</p>
</div>
<div class="section" id="sop1-instruction-examples">
<h3>SOP1 Instruction Examples<a class="headerlink" href="#sop1-instruction-examples" title="Permalink to this headline"></a></h3>
<div class="highlight-nasm"><div class="highlight"><pre><span></span><span class="nf">s_mov_b32</span> <span class="nv">s1</span><span class="p">,</span> <span class="nv">s2</span>
<span class="nf">s_mov_b64</span> <span class="nv">s</span><span class="p">[</span><span class="mi">0</span><span class="p">:</span><span class="mi">1</span><span class="p">],</span> <span class="mh">0x80000000</span>
<span class="nf">s_cmov_b32</span> <span class="nv">s1</span><span class="p">,</span> <span class="mi">200</span>
<span class="nf">s_wqm_b64</span> <span class="nv">s</span><span class="p">[</span><span class="mi">2</span><span class="p">:</span><span class="mi">3</span><span class="p">],</span> <span class="nv">s</span><span class="p">[</span><span class="mi">4</span><span class="p">:</span><span class="mi">5</span><span class="p">]</span>
<span class="nf">s_bcnt0_i32_b64</span> <span class="nv">s1</span><span class="p">,</span> <span class="nv">s</span><span class="p">[</span><span class="mi">2</span><span class="p">:</span><span class="mi">3</span><span class="p">]</span>
<span class="nf">s_swappc_b64</span> <span class="nv">s</span><span class="p">[</span><span class="mi">2</span><span class="p">:</span><span class="mi">3</span><span class="p">],</span> <span class="nv">s</span><span class="p">[</span><span class="mi">4</span><span class="p">:</span><span class="mi">5</span><span class="p">]</span>
<span class="nf">s_cbranch_join</span> <span class="nv">s</span><span class="p">[</span><span class="mi">4</span><span class="p">:</span><span class="mi">5</span><span class="p">]</span>
</pre></div>
</div>
<p>For full list of supported instructions, refer to &#8220;SOP1 Instructions&#8221; in ISA Manual.</p>
</div>
<div class="section" id="sop2-instruction-examples">
<h3>SOP2 Instruction Examples<a class="headerlink" href="#sop2-instruction-examples" title="Permalink to this headline"></a></h3>
<div class="highlight-nasm"><div class="highlight"><pre><span></span><span class="nf">s_add_u32</span> <span class="nv">s1</span><span class="p">,</span> <span class="nv">s2</span><span class="p">,</span> <span class="nv">s3</span>
<span class="nf">s_and_b64</span> <span class="nv">s</span><span class="p">[</span><span class="mi">2</span><span class="p">:</span><span class="mi">3</span><span class="p">],</span> <span class="nv">s</span><span class="p">[</span><span class="mi">4</span><span class="p">:</span><span class="mi">5</span><span class="p">],</span> <span class="nv">s</span><span class="p">[</span><span class="mi">6</span><span class="p">:</span><span class="mi">7</span><span class="p">]</span>
<span class="nf">s_cselect_b32</span> <span class="nv">s1</span><span class="p">,</span> <span class="nv">s2</span><span class="p">,</span> <span class="nv">s3</span>
<span class="nf">s_andn2_b32</span> <span class="nv">s2</span><span class="p">,</span> <span class="nv">s4</span><span class="p">,</span> <span class="nv">s6</span>
<span class="nf">s_lshr_b64</span> <span class="nv">s</span><span class="p">[</span><span class="mi">2</span><span class="p">:</span><span class="mi">3</span><span class="p">],</span> <span class="nv">s</span><span class="p">[</span><span class="mi">4</span><span class="p">:</span><span class="mi">5</span><span class="p">],</span> <span class="nv">s6</span>
<span class="nf">s_ashr_i32</span> <span class="nv">s2</span><span class="p">,</span> <span class="nv">s4</span><span class="p">,</span> <span class="nv">s6</span>
<span class="nf">s_bfm_b64</span> <span class="nv">s</span><span class="p">[</span><span class="mi">2</span><span class="p">:</span><span class="mi">3</span><span class="p">],</span> <span class="nv">s4</span><span class="p">,</span> <span class="nv">s6</span>
<span class="nf">s_bfe_i64</span> <span class="nv">s</span><span class="p">[</span><span class="mi">2</span><span class="p">:</span><span class="mi">3</span><span class="p">],</span> <span class="nv">s</span><span class="p">[</span><span class="mi">4</span><span class="p">:</span><span class="mi">5</span><span class="p">],</span> <span class="nv">s6</span>
<span class="nf">s_cbranch_g_fork</span> <span class="nv">s</span><span class="p">[</span><span class="mi">4</span><span class="p">:</span><span class="mi">5</span><span class="p">],</span> <span class="nv">s</span><span class="p">[</span><span class="mi">6</span><span class="p">:</span><span class="mi">7</span><span class="p">]</span>
</pre></div>
</div>
<p>For full list of supported instructions, refer to &#8220;SOP2 Instructions&#8221; in ISA Manual.</p>
</div>
<div class="section" id="sopc-instruction-examples">
<h3>SOPC Instruction Examples<a class="headerlink" href="#sopc-instruction-examples" title="Permalink to this headline"></a></h3>
<div class="highlight-nasm"><div class="highlight"><pre><span></span><span class="nf">s_cmp_eq_i32</span> <span class="nv">s1</span><span class="p">,</span> <span class="nv">s2</span>
<span class="nf">s_bitcmp1_b32</span> <span class="nv">s1</span><span class="p">,</span> <span class="nv">s2</span>
<span class="nf">s_bitcmp0_b64</span> <span class="nv">s</span><span class="p">[</span><span class="mi">2</span><span class="p">:</span><span class="mi">3</span><span class="p">],</span> <span class="nv">s4</span>
<span class="nf">s_setvskip</span> <span class="nv">s3</span><span class="p">,</span> <span class="nv">s5</span>
</pre></div>
</div>
<p>For full list of supported instructions, refer to &#8220;SOPC Instructions&#8221; in ISA Manual.</p>
</div>
<div class="section" id="sopp-instruction-examples">
<h3>SOPP Instruction Examples<a class="headerlink" href="#sopp-instruction-examples" title="Permalink to this headline"></a></h3>
<div class="highlight-nasm"><div class="highlight"><pre><span></span><span class="nf">s_barrier</span>
<span class="nf">s_nop</span> <span class="mi">2</span>
<span class="nf">s_endpgm</span>
<span class="nf">s_waitcnt</span> <span class="mi">0</span> <span class="c1">; Wait for all counters to be 0</span>
<span class="nf">s_waitcnt</span> <span class="nv">vmcnt</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span> <span class="o">&amp;</span> <span class="nv">expcnt</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span> <span class="o">&amp;</span> <span class="nv">lgkmcnt</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span> <span class="c1">; Equivalent to above</span>
<span class="nf">s_waitcnt</span> <span class="nv">vmcnt</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span> <span class="c1">; Wait for vmcnt counter to be 1.</span>
<span class="nf">s_sethalt</span> <span class="mi">9</span>
<span class="nf">s_sleep</span> <span class="mi">10</span>
<span class="nf">s_sendmsg</span> <span class="mh">0x1</span>
<span class="nf">s_sendmsg</span> <span class="nv">sendmsg</span><span class="p">(</span><span class="nv">MSG_INTERRUPT</span><span class="p">)</span>
<span class="nf">s_trap</span> <span class="mi">1</span>
</pre></div>
</div>
<p>For full list of supported instructions, refer to &#8220;SOPP Instructions&#8221; in ISA Manual.</p>
<p>Unless otherwise mentioned, little verification is performed on the operands
of SOPP Instrucitons, so it is up to the programmer to be familiar with the
range or acceptable values.</p>
</div>
<div class="section" id="vector-alu-instruction-examples">
<h3>Vector ALU Instruction Examples<a class="headerlink" href="#vector-alu-instruction-examples" title="Permalink to this headline"></a></h3>
<p>For vector ALU instruction opcodes (VOP1, VOP2, VOP3, VOPC, VOP_DPP, VOP_SDWA),
the assembler will automatically use optimal encoding based on its operands.
To force specific encoding, one can add a suffix to the opcode of the instruction:</p>
<ul class="simple">
<li>_e32 for 32-bit VOP1/VOP2/VOPC</li>
<li>_e64 for 64-bit VOP3</li>
<li>_dpp for VOP_DPP</li>
<li>_sdwa for VOP_SDWA</li>
</ul>
<p>VOP1/VOP2/VOP3/VOPC examples:</p>
<div class="highlight-nasm"><div class="highlight"><pre><span></span><span class="nf">v_mov_b32</span> <span class="nv">v1</span><span class="p">,</span> <span class="nv">v2</span>
<span class="nf">v_mov_b32_e32</span> <span class="nv">v1</span><span class="p">,</span> <span class="nv">v2</span>
<span class="nf">v_nop</span>
<span class="nf">v_cvt_f64_i32_e32</span> <span class="nv">v</span><span class="p">[</span><span class="mi">1</span><span class="p">:</span><span class="mi">2</span><span class="p">],</span> <span class="nv">v2</span>
<span class="nf">v_floor_f32_e32</span> <span class="nv">v1</span><span class="p">,</span> <span class="nv">v2</span>
<span class="nf">v_bfrev_b32_e32</span> <span class="nv">v1</span><span class="p">,</span> <span class="nv">v2</span>
<span class="nf">v_add_f32_e32</span> <span class="nv">v1</span><span class="p">,</span> <span class="nv">v2</span><span class="p">,</span> <span class="nv">v3</span>
<span class="nf">v_mul_i32_i24_e64</span> <span class="nv">v1</span><span class="p">,</span> <span class="nv">v2</span><span class="p">,</span> <span class="mi">3</span>
<span class="nf">v_mul_i32_i24_e32</span> <span class="nv">v1</span><span class="p">,</span> <span class="o">-</span><span class="mi">3</span><span class="p">,</span> <span class="nv">v3</span>
<span class="nf">v_mul_i32_i24_e32</span> <span class="nv">v1</span><span class="p">,</span> <span class="o">-</span><span class="mi">100</span><span class="p">,</span> <span class="nv">v3</span>
<span class="nf">v_addc_u32</span> <span class="nv">v1</span><span class="p">,</span> <span class="nv">s</span><span class="p">[</span><span class="mi">0</span><span class="p">:</span><span class="mi">1</span><span class="p">],</span> <span class="nv">v2</span><span class="p">,</span> <span class="nv">v3</span><span class="p">,</span> <span class="nv">s</span><span class="p">[</span><span class="mi">2</span><span class="p">:</span><span class="mi">3</span><span class="p">]</span>
<span class="nf">v_max_f16_e32</span> <span class="nv">v1</span><span class="p">,</span> <span class="nv">v2</span><span class="p">,</span> <span class="nv">v3</span>
</pre></div>
</div>
<p>VOP_DPP examples:</p>
<div class="highlight-nasm"><div class="highlight"><pre><span></span><span class="nf">v_mov_b32</span> <span class="nv">v0</span><span class="p">,</span> <span class="nv">v0</span> <span class="nv">quad_perm</span><span class="p">:[</span><span class="mi">0</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">1</span><span class="p">]</span>
<span class="nf">v_sin_f32</span> <span class="nv">v0</span><span class="p">,</span> <span class="nv">v0</span> <span class="nv">row_shl</span><span class="p">:</span><span class="mi">1</span> <span class="nv">row_mask</span><span class="p">:</span><span class="mh">0xa</span> <span class="nv">bank_mask</span><span class="p">:</span><span class="mh">0x1</span> <span class="nv">bound_ctrl</span><span class="p">:</span><span class="mi">0</span>
<span class="nf">v_mov_b32</span> <span class="nv">v0</span><span class="p">,</span> <span class="nv">v0</span> <span class="nv">wave_shl</span><span class="p">:</span><span class="mi">1</span>
<span class="nf">v_mov_b32</span> <span class="nv">v0</span><span class="p">,</span> <span class="nv">v0</span> <span class="nv">row_mirror</span>
<span class="nf">v_mov_b32</span> <span class="nv">v0</span><span class="p">,</span> <span class="nv">v0</span> <span class="nv">row_bcast</span><span class="p">:</span><span class="mi">31</span>
<span class="nf">v_mov_b32</span> <span class="nv">v0</span><span class="p">,</span> <span class="nv">v0</span> <span class="nv">quad_perm</span><span class="p">:[</span><span class="mi">1</span><span class="p">,</span><span class="mi">3</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">]</span> <span class="nv">row_mask</span><span class="p">:</span><span class="mh">0xa</span> <span class="nv">bank_mask</span><span class="p">:</span><span class="mh">0x1</span> <span class="nv">bound_ctrl</span><span class="p">:</span><span class="mi">0</span>
<span class="nf">v_add_f32</span> <span class="nv">v0</span><span class="p">,</span> <span class="nv">v0</span><span class="p">,</span> <span class="o">|</span><span class="nv">v0</span><span class="o">|</span> <span class="nv">row_shl</span><span class="p">:</span><span class="mi">1</span> <span class="nv">row_mask</span><span class="p">:</span><span class="mh">0xa</span> <span class="nv">bank_mask</span><span class="p">:</span><span class="mh">0x1</span> <span class="nv">bound_ctrl</span><span class="p">:</span><span class="mi">0</span>
<span class="nf">v_max_f16</span> <span class="nv">v1</span><span class="p">,</span> <span class="nv">v2</span><span class="p">,</span> <span class="nv">v3</span> <span class="nv">row_shl</span><span class="p">:</span><span class="mi">1</span> <span class="nv">row_mask</span><span class="p">:</span><span class="mh">0xa</span> <span class="nv">bank_mask</span><span class="p">:</span><span class="mh">0x1</span> <span class="nv">bound_ctrl</span><span class="p">:</span><span class="mi">0</span>
</pre></div>
</div>
<p>VOP_SDWA examples:</p>
<div class="highlight-nasm"><div class="highlight"><pre><span></span><span class="nf">v_mov_b32</span> <span class="nv">v1</span><span class="p">,</span> <span class="nv">v2</span> <span class="nb">ds</span><span class="nv">t_sel</span><span class="p">:</span><span class="kt">BYTE</span><span class="nv">_0</span> <span class="nb">ds</span><span class="nv">t_unused</span><span class="p">:</span><span class="nv">UNUSED_PRESERVE</span> <span class="nv">src0_sel</span><span class="p">:</span><span class="kt">DWORD</span>
<span class="nf">v_min_u32</span> <span class="nv">v200</span><span class="p">,</span> <span class="nv">v200</span><span class="p">,</span> <span class="nv">v1</span> <span class="nb">ds</span><span class="nv">t_sel</span><span class="p">:</span><span class="kt">WORD</span><span class="nv">_1</span> <span class="nb">ds</span><span class="nv">t_unused</span><span class="p">:</span><span class="nv">UNUSED_PAD</span> <span class="nv">src0_sel</span><span class="p">:</span><span class="kt">BYTE</span><span class="nv">_1</span> <span class="nv">src1_sel</span><span class="p">:</span><span class="kt">DWORD</span>
<span class="nf">v_sin_f32</span> <span class="nv">v0</span><span class="p">,</span> <span class="nv">v0</span> <span class="nb">ds</span><span class="nv">t_unused</span><span class="p">:</span><span class="nv">UNUSED_PAD</span> <span class="nv">src0_sel</span><span class="p">:</span><span class="kt">WORD</span><span class="nv">_1</span>
<span class="nf">v_fract_f32</span> <span class="nv">v0</span><span class="p">,</span> <span class="o">|</span><span class="nv">v0</span><span class="o">|</span> <span class="nb">ds</span><span class="nv">t_sel</span><span class="p">:</span><span class="kt">DWORD</span> <span class="nb">ds</span><span class="nv">t_unused</span><span class="p">:</span><span class="nv">UNUSED_PAD</span> <span class="nv">src0_sel</span><span class="p">:</span><span class="kt">WORD</span><span class="nv">_1</span>
<span class="nf">v_cmpx_le_u32</span> <span class="nv">vcc</span><span class="p">,</span> <span class="nv">v1</span><span class="p">,</span> <span class="nv">v2</span> <span class="nv">src0_sel</span><span class="p">:</span><span class="kt">BYTE</span><span class="nv">_2</span> <span class="nv">src1_sel</span><span class="p">:</span><span class="kt">WORD</span><span class="nv">_0</span>
</pre></div>
</div>
<p>For full list of supported instructions, refer to &#8220;Vector ALU instructions&#8221;.</p>
</div>
<div class="section" id="hsa-code-object-directives">
<h3>HSA Code Object Directives<a class="headerlink" href="#hsa-code-object-directives" title="Permalink to this headline"></a></h3>
<p>AMDGPU ABI defines auxiliary data in output code object. In assembly source,
one can specify them with assembler directives.</p>
<div class="section" id="hsa-code-object-version-major-minor">
<h4>.hsa_code_object_version major, minor<a class="headerlink" href="#hsa-code-object-version-major-minor" title="Permalink to this headline"></a></h4>
<p><em>major</em> and <em>minor</em> are integers that specify the version of the HSA code
object that will be generated by the assembler.</p>
</div>
<div class="section" id="hsa-code-object-isa-major-minor-stepping-vendor-arch">
<h4>.hsa_code_object_isa [major, minor, stepping, vendor, arch]<a class="headerlink" href="#hsa-code-object-isa-major-minor-stepping-vendor-arch" title="Permalink to this headline"></a></h4>
<p><em>major</em>, <em>minor</em>, and <em>stepping</em> are all integers that describe the instruction
set architecture (ISA) version of the assembly program.</p>
<p><em>vendor</em> and <em>arch</em> are quoted strings. <em>vendor</em> should always be equal to
&#8220;AMD&#8221; and <em>arch</em> should always be equal to &#8220;AMDGPU&#8221;.</p>
<p>By default, the assembler will derive the ISA version, <em>vendor</em>, and <em>arch</em>
from the value of the -mcpu option that is passed to the assembler.</p>
</div>
<div class="section" id="amdgpu-hsa-kernel-name">
<h4>.amdgpu_hsa_kernel (name)<a class="headerlink" href="#amdgpu-hsa-kernel-name" title="Permalink to this headline"></a></h4>
<p>This directives specifies that the symbol with given name is a kernel entry point
(label) and the object should contain corresponding symbol of type STT_AMDGPU_HSA_KERNEL.</p>
</div>
<div class="section" id="amd-kernel-code-t">
<h4>.amd_kernel_code_t<a class="headerlink" href="#amd-kernel-code-t" title="Permalink to this headline"></a></h4>
<p>This directive marks the beginning of a list of key / value pairs that are used
to specify the amd_kernel_code_t object that will be emitted by the assembler.
The list must be terminated by the <em>.end_amd_kernel_code_t</em> directive. For
any amd_kernel_code_t values that are unspecified a default value will be
used. The default value for all keys is 0, with the following exceptions:</p>
<ul class="simple">
<li><em>kernel_code_version_major</em> defaults to 1.</li>
<li><em>machine_kind</em> defaults to 1.</li>
<li><em>machine_version_major</em>, <em>machine_version_minor</em>, and
<em>machine_version_stepping</em> are derived from the value of the -mcpu option
that is passed to the assembler.</li>
<li><em>kernel_code_entry_byte_offset</em> defaults to 256.</li>
<li><em>wavefront_size</em> defaults to 6.</li>
<li><em>kernarg_segment_alignment</em>, <em>group_segment_alignment</em>, and
<em>private_segment_alignment</em> default to 4. Note that alignments are specified
as a power of two, so a value of <strong>n</strong> means an alignment of 2^ <strong>n</strong>.</li>
</ul>
<p>The <em>.amd_kernel_code_t</em> directive must be placed immediately after the
function label and before any instructions.</p>
<p>For a full list of amd_kernel_code_t keys, refer to AMDGPU ABI document,
comments in lib/Target/AMDGPU/AmdKernelCodeT.h and test/CodeGen/AMDGPU/hsa.s.</p>
<p>Here is an example of a minimal amd_kernel_code_t specification:</p>
<div class="highlight-none"><div class="highlight"><pre><span></span>.hsa_code_object_version 1,0
.hsa_code_object_isa
.hsatext
.globl hello_world
.p2align 8
.amdgpu_hsa_kernel hello_world
hello_world:
.amd_kernel_code_t
enable_sgpr_kernarg_segment_ptr = 1
is_ptr64 = 1
compute_pgm_rsrc1_vgprs = 0
compute_pgm_rsrc1_sgprs = 0
compute_pgm_rsrc2_user_sgpr = 2
kernarg_segment_byte_size = 8
wavefront_sgpr_count = 2
workitem_vgpr_count = 3
.end_amd_kernel_code_t
s_load_dwordx2 s[0:1], s[0:1] 0x0
v_mov_b32 v0, 3.14159
s_waitcnt lgkmcnt(0)
v_mov_b32 v1, s0
v_mov_b32 v2, s1
flat_store_dword v[1:2], v0
s_endpgm
.Lfunc_end0:
.size hello_world, .Lfunc_end0-hello_world
</pre></div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="StackMaps.html" title="Stack maps and patch points in LLVM"
>next</a> |</li>
<li class="right" >
<a href="NVPTXUsage.html" title="User Guide for NVPTX Back-end"
>previous</a> |</li>
<li><a href="http://llvm.org/">LLVM Home</a>&nbsp;|&nbsp;</li>
<li><a href="index.html">Documentation</a>&raquo;</li>
</ul>
</div>
<div class="footer" role="contentinfo">
&#169; Copyright 2003-2016, LLVM Project.
Last updated on 2016-09-19.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.4.6.
</div>
</body>
</html>
No newline at end of file

docs/AMDGPUUsage.rst

============================== ==============================
User Guide for AMDGPU Back-end User Guide for AMDGPU Back-end
============================== ==============================
Introduction Introduction
============ ============
The AMDGPU back-end provides ISA code generation for AMD GPUs, starting with The AMDGPU back-end provides ISA code generation for AMD GPUs, starting with
the R600 family up until the current Volcanic Islands (GCN Gen 3). the R600 family up until the current Volcanic Islands (GCN Gen 3).
The following additional documentation is available:
* AMD GCN3 Instruction Set Architecture: `PDF <http://amd-dev.wpengine.netdna-cdn.com/wordpress/media/2013/12/AMD_GCN3_Instruction_Set_Architecture_rev1.1.pdf>`__
* Southern Islands Series Instruction Set Architecture: `PDF <http://amd-dev.wpengine.netdna-cdn.com/wordpress/media/2013/07/AMD_Southern_Islands_Instruction_Set_Architecture1.pdf>`__
* R600-Family Instruction Set Architecture: `PDF <http://amd-dev.wpengine.netdna-cdn.com/wordpress/media/2012/10/r600isa.pdf>`__
* AMDGPU Compute Application Binary Interface: `MD <https://github.com/RadeonOpenCompute/ROCm-ComputeABI-Doc/blob/master/AMDGPU-ABI.md>`__
tstellarAMDUnsubmitted
Not Done
ReplyInline Actions

The convention is to put these in CompilerWriterInfo.rst Maybe we move these to this file and then add a link to it.

tstellarAMD: The convention is to put these in CompilerWriterInfo.rst Maybe we move these to this file and…
Conventions Conventions
=========== ===========
Address Spaces Address Spaces
-------------- --------------
The AMDGPU back-end uses the following address space mapping: The AMDGPU back-end uses the following address space mapping:
Show All 11 Lines
The terminology in the table, aside from the region memory space, is from the The terminology in the table, aside from the region memory space, is from the
OpenCL standard. OpenCL standard.
Assembler Assembler
========= =========
The assembler is currently considered experimental. AMDGPU backend has LLVM-MC based assembler which is currently in development.
It supports Southern Islands ISA, Sea Islands and Volcanic Islands.
For syntax examples look in test/MC/AMDGPU. This document describes general syntax for instructions and operands. For more
information about instructions, their semantics and supported combinations
of operands, refer to one of Instruction Set Architecture manuals.
Below some of the currently supported features (modulo bugs). These An instruction has the following syntax (register operands are
all apply to the Southern Islands ISA, Sea Islands and Volcanic Islands normally comma-separated while extra operands are space-separated):
are also supported but may be missing some instructions and have more bugs:
DS Instructions *<opcode> <register_operand0>, ... <extra_operand0> ...*
---------------
All DS instructions are supported.
FLAT Instructions
------------------
These instructions are only present in the Sea Islands and Volcanic Islands
instruction set. All FLAT instructions are supported for these architectures
MUBUF Instructions Operands
------------------ --------
All non-atomic MUBUF instructions are supported.
SMRD Instructions The following syntax for register operands is supported:
-----------------
Only the s_load_dword* SMRD instructions are supported.
SOP1 Instructions * SGPR registers: s0, ... or s[0], ...
----------------- * VGPR registers: v0, ... or v[0], ...
All SOP1 instructions are supported. * TTMP registers: ttmp0, ... or ttmp[0], ...
* Special registers: exec (exec_lo, exec_hi), vcc (vcc_lo, vcc_hi), flat_scratch (flat_scratch_lo, flat_scratch_hi)
* Special trap registers: tba (tba_lo, tba_hi), tma (tma_lo, tma_hi)
* Register pairs, quads, etc: s[2:3], v[10:11], ttmp[5:6], s[4:7], v[12:15], ttmp[4:7], s[8:15], ...
* Register lists: [s0, s1], [ttmp0, ttmp1, ttmp2, ttmp3]
* Register index expressions: v[2*2], s[1-1:2-1]
* off indicates that an operand is not enabled
artem.tamazovUnsubmitted
Not Done
ReplyInline Actions

I would add quotes around off.

artem.tamazov: I would add quotes around off.
SOP2 Instructions The following extra operands are supported:
-----------------
All SOP2 instructions are supported.
SOPC Instructions * offset, offset0, offset1
----------------- * idxen, offen bits
All SOPC instructions are supported. * glc, slc, tfe bits
* waitcnt: integer or combination of counter values
* VOP3 modifiers:
SOPP Instructions - abs (\| \|), neg (\-)
-----------------
Unless otherwise mentioned, all SOPP instructions that have one or more * DPP modifiers:
operands accept integer operands only. No verification is performed
on the operands, so it is up to the programmer to be familiar with the - row_shl, row_shr, row_ror, row_rol
range or acceptable values. - row_mirror, row_half_mirror, row_bcast
- wave_shl, wave_shr, wave_ror, wave_rol, quad_perm
- row_mask, bank_mask, bound_ctrl
* SDWA modifiers:
- dst_sel, src0_sel, src1_sel (BYTE_N, WORD_M, DWORD)
- dst_unused (UNUSED_PAD, UNUSED_SEXT, UNUSED_PRESERVE)
- abs, neg, sext
DS Instructions Examples
------------------------
.. code-block:: nasm
ds_add_u32 v2, v4 offset:16
ds_write_src2_b64 v2 offset0:4 offset1:8
ds_cmpst_f32 v2, v4, v6
ds_min_rtn_f64 v[8:9], v2, v[4:5]
For full list of supported instructions, refer to "LDS/GDS instructions" in ISA Manual.
FLAT Instruction Examples
--------------------------
.. code-block:: nasm
flat_load_dword v1, v[3:4]
flat_store_dwordx3 v[3:4], v[5:7]
flat_atomic_swap v1, v[3:4], v5 glc
flat_atomic_cmpswap v1, v[3:4], v[5:6] glc slc
flat_atomic_fmax_x2 v[1:2], v[3:4], v[5:6] glc
For full list of supported instructions, refer to "FLAT instructions" in ISA Manual.
MUBUF Instruction Examples
---------------------------
.. code-block:: nasm
buffer_load_dword v1, off, s[4:7], s1
buffer_store_dwordx4 v[1:4], v2, ttmp[4:7], s1 offen offset:4 glc tfe
buffer_store_format_xy v[1:2], off, s[4:7], s1
buffer_wbinvl1
buffer_atomic_inc v1, v2, s[8:11], s4 idxen offset:4 slc
For full list of supported instructions, refer to "MUBUF Instructions" in ISA Manual.
SMRD/SMEM Instruction Examples
-------------------------------
.. code-block:: nasm
s_load_dword s1, s[2:3], 0xfc
s_load_dwordx8 s[8:15], s[2:3], s4
s_load_dwordx16 s[88:103], s[2:3], s4
s_dcache_inv_vol
s_memtime s[4:5]
s_waitcnt For full list of supported instructions, refer to "Scalar Memory Operations" in ISA Manual.
^^^^^^^^^
s_waitcnt accepts named arguments to specify which memory counter(s) to SOP1 Instruction Examples
wait for. --------------------------
.. code-block:: nasm .. code-block:: nasm
; Wait for all counters to be 0 s_mov_b32 s1, s2
s_waitcnt 0 s_mov_b64 s[0:1], 0x80000000
s_cmov_b32 s1, 200
s_wqm_b64 s[2:3], s[4:5]
s_bcnt0_i32_b64 s1, s[2:3]
s_swappc_b64 s[2:3], s[4:5]
s_cbranch_join s[4:5]
; Equivalent to s_waitcnt 0. Counter names can also be delimited by For full list of supported instructions, refer to "SOP1 Instructions" in ISA Manual.
; '&' or ','.
s_waitcnt vmcnt(0) expcnt(0) lgkcmt(0)
; Wait for vmcnt counter to be 1. SOP2 Instruction Examples
s_waitcnt vmcnt(1) -------------------------
VOP1, VOP2, VOP3, VOPC Instructions .. code-block:: nasm
-----------------------------------
s_add_u32 s1, s2, s3
s_and_b64 s[2:3], s[4:5], s[6:7]
s_cselect_b32 s1, s2, s3
s_andn2_b32 s2, s4, s6
s_lshr_b64 s[2:3], s[4:5], s6
s_ashr_i32 s2, s4, s6
s_bfm_b64 s[2:3], s4, s6
s_bfe_i64 s[2:3], s[4:5], s6
s_cbranch_g_fork s[4:5], s[6:7]
For full list of supported instructions, refer to "SOP2 Instructions" in ISA Manual.
SOPC Instruction Examples
--------------------------
.. code-block:: nasm
s_cmp_eq_i32 s1, s2
s_bitcmp1_b32 s1, s2
s_bitcmp0_b64 s[2:3], s4
s_setvskip s3, s5
For full list of supported instructions, refer to "SOPC Instructions" in ISA Manual.
SOPP Instruction Examples
--------------------------
.. code-block:: nasm
s_barrier
s_nop 2
s_endpgm
s_waitcnt 0 ; Wait for all counters to be 0
s_waitcnt vmcnt(0) & expcnt(0) & lgkmcnt(0) ; Equivalent to above
s_waitcnt vmcnt(1) ; Wait for vmcnt counter to be 1.
s_sethalt 9
s_sleep 10
s_sendmsg 0x1
s_sendmsg sendmsg(MSG_INTERRUPT)
s_trap 1
For full list of supported instructions, refer to "SOPP Instructions" in ISA Manual.
All 32-bit and 64-bit encodings should work. Unless otherwise mentioned, little verification is performed on the operands
of SOPP Instrucitons, so it is up to the programmer to be familiar with the
range or acceptable values.
Vector ALU Instruction Examples
-------------------------------
For vector ALU instruction opcodes (VOP1, VOP2, VOP3, VOPC, VOP_DPP, VOP_SDWA),
the assembler will automatically use optimal encoding based on its operands.
To force specific encoding, one can add a suffix to the opcode of the instruction:
* _e32 for 32-bit VOP1/VOP2/VOPC
* _e64 for 64-bit VOP3
* _dpp for VOP_DPP
* _sdwa for VOP_SDWA
VOP1/VOP2/VOP3/VOPC examples:
.. code-block:: nasm
v_mov_b32 v1, v2
v_mov_b32_e32 v1, v2
v_nop
v_cvt_f64_i32_e32 v[1:2], v2
v_floor_f32_e32 v1, v2
v_bfrev_b32_e32 v1, v2
v_add_f32_e32 v1, v2, v3
v_mul_i32_i24_e64 v1, v2, 3
v_mul_i32_i24_e32 v1, -3, v3
v_mul_i32_i24_e32 v1, -100, v3
v_addc_u32 v1, s[0:1], v2, v3, s[2:3]
v_max_f16_e32 v1, v2, v3
The assembler will automatically detect which encoding size to use for VOP_DPP examples:
VOP1, VOP2, and VOPC instructions based on the operands. If you want to force
a specific encoding size, you can add an _e32 (for 32-bit encoding) or
_e64 (for 64-bit encoding) suffix to the instruction. Most, but not all
instructions support an explicit suffix. These are all valid assembly
strings:
.. code-block:: nasm .. code-block:: nasm
v_mul_i32_i24 v1, v2, v3 v_mov_b32 v0, v0 quad_perm:[0,2,1,1]
v_mul_i32_i24_e32 v1, v2, v3 v_sin_f32 v0, v0 row_shl:1 row_mask:0xa bank_mask:0x1 bound_ctrl:0
v_mul_i32_i24_e64 v1, v2, v3 v_mov_b32 v0, v0 wave_shl:1
v_mov_b32 v0, v0 row_mirror
v_mov_b32 v0, v0 row_bcast:31
v_mov_b32 v0, v0 quad_perm:[1,3,0,1] row_mask:0xa bank_mask:0x1 bound_ctrl:0
v_add_f32 v0, v0, |v0| row_shl:1 row_mask:0xa bank_mask:0x1 bound_ctrl:0
v_max_f16 v1, v2, v3 row_shl:1 row_mask:0xa bank_mask:0x1 bound_ctrl:0
Assembler Directives VOP_SDWA examples:
--------------------
.. code-block:: nasm
v_mov_b32 v1, v2 dst_sel:BYTE_0 dst_unused:UNUSED_PRESERVE src0_sel:DWORD
v_min_u32 v200, v200, v1 dst_sel:WORD_1 dst_unused:UNUSED_PAD src0_sel:BYTE_1 src1_sel:DWORD
v_sin_f32 v0, v0 dst_unused:UNUSED_PAD src0_sel:WORD_1
v_fract_f32 v0, |v0| dst_sel:DWORD dst_unused:UNUSED_PAD src0_sel:WORD_1
v_cmpx_le_u32 vcc, v1, v2 src0_sel:BYTE_2 src1_sel:WORD_0
For full list of supported instructions, refer to "Vector ALU instructions".
HSA Code Object Directives
--------------------------
AMDGPU ABI defines auxiliary data in output code object. In assembly source,
one can specify them with assembler directives.
.hsa_code_object_version major, minor .hsa_code_object_version major, minor
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
*major* and *minor* are integers that specify the version of the HSA code *major* and *minor* are integers that specify the version of the HSA code
object that will be generated by the assembler. This value will be stored object that will be generated by the assembler.
in an entry of the .note section.
.hsa_code_object_isa [major, minor, stepping, vendor, arch] .hsa_code_object_isa [major, minor, stepping, vendor, arch]
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
*major*, *minor*, and *stepping* are all integers that describe the instruction *major*, *minor*, and *stepping* are all integers that describe the instruction
set architecture (ISA) version of the assembly program. set architecture (ISA) version of the assembly program.
*vendor* and *arch* are quoted strings. *vendor* should always be equal to *vendor* and *arch* are quoted strings. *vendor* should always be equal to
"AMD" and *arch* should always be equal to "AMDGPU". "AMD" and *arch* should always be equal to "AMDGPU".
If no arguments are specified, then the assembler will derive the ISA version, By default, the assembler will derive the ISA version, *vendor*, and *arch*
*vendor*, and *arch* from the value of the -mcpu option that is passed to the from the value of the -mcpu option that is passed to the assembler.
assembler.
.amdgpu_hsa_kernel (name)
^^^^^^^^^^^^^^^^^^^^^^^^^
ISA version, *vendor*, and *arch* will all be stored in a single entry of the This directives specifies that the symbol with given name is a kernel entry point
.note section. (label) and the object should contain corresponding symbol of type STT_AMDGPU_HSA_KERNEL.
.amd_kernel_code_t .amd_kernel_code_t
^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^
This directive marks the beginning of a list of key / value pairs that are used This directive marks the beginning of a list of key / value pairs that are used
to specify the amd_kernel_code_t object that will be emitted by the assembler. to specify the amd_kernel_code_t object that will be emitted by the assembler.
The list must be terminated by the *.end_amd_kernel_code_t* directive. For The list must be terminated by the *.end_amd_kernel_code_t* directive. For
any amd_kernel_code_t values that are unspecified a default value will be any amd_kernel_code_t values that are unspecified a default value will be
used. The default value for all keys is 0, with the following exceptions: used. The default value for all keys is 0, with the following exceptions:
- *kernel_code_version_major* defaults to 1. - *kernel_code_version_major* defaults to 1.
- *machine_kind* defaults to 1. - *machine_kind* defaults to 1.
- *machine_version_major*, *machine_version_minor*, and - *machine_version_major*, *machine_version_minor*, and
*machine_version_stepping* are derived from the value of the -mcpu option *machine_version_stepping* are derived from the value of the -mcpu option
that is passed to the assembler. that is passed to the assembler.
- *kernel_code_entry_byte_offset* defaults to 256. - *kernel_code_entry_byte_offset* defaults to 256.
- *wavefront_size* defaults to 6. - *wavefront_size* defaults to 6.
- *kernarg_segment_alignment*, *group_segment_alignment*, and - *kernarg_segment_alignment*, *group_segment_alignment*, and
*private_segment_alignment* default to 4. Note that alignments are specified *private_segment_alignment* default to 4. Note that alignments are specified
as a power of two, so a value of **n** means an alignment of 2^ **n**. as a power of two, so a value of **n** means an alignment of 2^ **n**.
The *.amd_kernel_code_t* directive must be placed immediately after the The *.amd_kernel_code_t* directive must be placed immediately after the
function label and before any instructions. function label and before any instructions.
For a full list of amd_kernel_code_t keys, see the examples in For a full list of amd_kernel_code_t keys, refer to AMDGPU ABI document,
test/CodeGen/AMDGPU/hsa.s. For an explanation of the meanings of the different comments in lib/Target/AMDGPU/AmdKernelCodeT.h and test/CodeGen/AMDGPU/hsa.s.
keys, see the comments in lib/Target/AMDGPU/AmdKernelCodeT.h
Here is an example of a minimal amd_kernel_code_t specification: Here is an example of a minimal amd_kernel_code_t specification:
.. code-block:: none .. code-block:: none
.hsa_code_object_version 1,0 .hsa_code_object_version 1,0
.hsa_code_object_isa .hsa_code_object_isa
Show All 27 Lines