From 36b67da602ab7a8d85f4db6045e1f8fe4d1fdf45 Mon Sep 17 00:00:00 2001
From: Andreas Kloeckner <inform@tiker.net>
Date: Tue, 16 Jul 2013 00:29:04 -0400
Subject: [PATCH] Build some docs
---
doc/reference.rst | 127 ++++++++++++++++++++++++++++++-------------
loopy/kernel/data.py | 2 +-
2 files changed, 90 insertions(+), 39 deletions(-)
diff --git a/doc/reference.rst b/doc/reference.rst
index a3051d9bd..9485c3b03 100644
--- a/doc/reference.rst
+++ b/doc/reference.rst
@@ -8,6 +8,8 @@ This guide defines all functionality exposed by loopy. If you would like
a more gentle introduction, you may consider reading the example-based
guide :ref:`guide` instead.
+.. _inames:
+
Inames
------
@@ -28,39 +30,18 @@ Expressions
* complex-valued arithmetic
* tagging of array access and substitution rule use ("$")
-Assignments and Substitution Rules
-----------------------------------
-
-Syntax of an instruction::
-
- label: [i,j|k,l] <float32> lhs[i,j,k] = EXPRESSION : dep_label, dep_label_2
-
-The above example illustrates all the parts that are allowed in loo.py's
-instruction syntax. All of these except for `lhs` and `EXPRESSION` are
-optional.
-
-* `label` is a unique identifier for this instruction, enabling you to
- refer back to the instruction uniquely during further transformation
- as well as specifying ordering dependencies.
+.. _types:
-* `dep_label,dep_label_2` are dependencies of the current instruction.
- Loo.py will enforce that the instructions marked with these labels
- are scheduled before this instruction.
-
-* `<float32>` declares `lhs` as a temporary variable, with shape given
- by the ranges of the `lhs` subscripts. (Note that in this case, the
- `lhs` subscripts must be pure inames, not expressions, for now.)
- Instead of a concrete type, an empty set of angle brackets `<>` may be
- given to indicate that type inference should figure out the type of the
- temporary.
+Specifying Types
+----------------
-* `[i,j|k,l]` specifies the inames within which this instruction is run.
- Independent copies of the inames `k` and `l` will be made for this
- instruction.
+:mod:`loopy` uses the same type system as :mod:`numpy`. (See
+:class:`numpy.dtype`) It also uses :mod:`pyopencl` for a registry of
+user-defined types and their C equivalents. See :func:`pyopencl.get_or_register_dtype`
+and related functions.
-Syntax of an substitution rule::
-
- rule_name(arg1, arg2) := EXPRESSION
+For a string representation of types, all numpy types (e.g. ``float32`` etc.)
+are accepted, in addition to what is registered in :mod:`pyopencl`.
.. _tags:
@@ -135,28 +116,96 @@ Arguments
:members:
:undoc-members:
+.. _temporaries:
+
Temporary Variables
^^^^^^^^^^^^^^^^^^^
+Temporary variables model OpenCL's ``private`` and ``local`` address spaces. Both
+have the lifetime of a kernel invocation.
+
.. autoclass:: TemporaryVariable
:members:
:undoc-members:
-Substitution rules
-^^^^^^^^^^^^^^^^^^
+Instructions
+^^^^^^^^^^^^
-.. autoclass:: SubstitutionRule
+.. _assignments:
-String sytnax: FIXME
+Assignments
+~~~~~~~~~~~
-Instructions
-^^^^^^^^^^^^
+The general syntax of an instruction is a simple assignment::
+
+ LHS[i,j,k] = EXPRESSION
+
+Several extensions of this syntax are defined, as discussed below. They
+may be combined freely.
+
+You can also use an instruction to declare a new temporary variable. (See
+:ref:`temporaries`.) See :ref:`types` for what types are acceptable. If the
+``LHS`` has a subscript, bounds on the indices are inferred (which must be
+constants at the time of kernel creation) and the declared temporary is
+created as an array. Instructions declaring temporaries have the following
+form::
+
+ <temp_var_type> LHS[i,j,k] = EXPRESSION
+
+You can also create a temporary and ask loopy to determine its type
+automatically. This uses the following syntax::
+
+ <> LHS[i,j,k] = EXPRESSION
+
+Lastly, each instruction may optionally have a number of attributes
+specified, using the following format::
+
+ LHS[i,j,k] = EXPRESSION {attr1,attr2=value1:value2}
+
+These are usually key-value pairs. The following attributes are recognized:
+
+* ``id=value`` sets the instruction's identifier to ``value``. ``value``
+ must be unique within the kernel. This identifier is used to refer to the
+ instruction after it has been created, such as from ``dep`` attributes
+ (see below) or from :mod:`context matches <loopy.context_matching>`.
+
+* ``id_prefix=value`` also sets the instruction's identifier, however
+ uniqueness is ensured by loopy itself, by appending further components
+ (often numbers) to the given ``id_prefix``.
+
+* ``inames=i:j:k`` forces the instruction to reside within the loops over
+ :ref:`inames` ``i``, ``j`` and ``k``.
+
+* ``dep=id1:id2`` creates a dependency of this instruction on the
+ instructions with identifiers ``id1`` and ``id2``. This requires that the
+ code generated for this instruction appears textually after both of these
+ instructions' generated code.
+
+ .. note::
+
+ Loopy will automatically add a depdencies of reading instructions
+ on writing instructions *if and only if* there is exactly one writing
+ instruction for the written variable (temporary or argument).
+
+* ``priority=integer`` sets the instructions priority to the value
+ ``integer``. Instructions with higher priority will be scheduled sooner,
+ if possible. Note that the scheduler may still schedule a lower-priority
+ instruction ahead of a higher-priority one if loop orders or dependencies
+ require it.
.. autoclass:: ExpressionInstruction
+C Block Instructions
+~~~~~~~~~~~~~~~~~~~~
+
.. autoclass:: CInstruction
-String sytnax: FIXME
+Substitution Rules
+^^^^^^^^^^^^^^^^^^
+
+Syntax of an substitution rule::
+
+ rule_name(arg1, arg2) := EXPRESSION
Kernels
^^^^^^^
@@ -164,7 +213,7 @@ Kernels
.. class:: LoopKernel
Do not create :class:`LoopKernel` objects directly. Instead, use the following
-function, which takes the same arguments, but does some extra post-processing.
+function, which is responsible for creating kernels:
.. autofunction:: make_kernel
@@ -294,3 +343,5 @@ following always works::
.. autofunction:: preprocess_kernel
.. autofunction:: get_dot_dependency_graph
+
+.. vim: tw=75
diff --git a/loopy/kernel/data.py b/loopy/kernel/data.py
index 22e1ae10f..e9c125fd1 100644
--- a/loopy/kernel/data.py
+++ b/loopy/kernel/data.py
@@ -592,7 +592,7 @@ def _remove_common_indentation(code):
class CInstruction(InstructionBase):
"""
- .. atttribute:: iname_exprs
+ .. attribute:: iname_exprs
A list of tuples *(name, expr)* of inames or expressions based on them
that the instruction needs access to.
--
GitLab