The doc for IR instructions used definition lists to structure
the instructions names and their description. This is simple
to write and present well but it doesn't put the instructions'
name in the index.
Fix this by adding a new domain, with a single directive 'op'
which takes the instruction name, inserts an index entry and uses
it for the definition.
Signed-off-by: Luc Van Oostenryck <luc.vanoostenryck@xxxxxxxxx>
---
Documentation/IR.rst | 154 +++++++++++++++++++-----------------
Documentation/conf.py | 1 +
Documentation/doc-guide.rst | 4 +
Documentation/sphinx/ir.py | 75 ++++++++++++++++++
4 files changed, 160 insertions(+), 74 deletions(-)
create mode 100755 Documentation/sphinx/ir.py
diff --git a/Documentation/IR.rst b/Documentation/IR.rst
index ec297eed0..67ef06a5d 100644
--- a/Documentation/IR.rst
+++ b/Documentation/IR.rst
@@ -1,3 +1,5 @@
+.. default-domain:: ir
+
Sparse's Intermediate Representation
====================================
@@ -20,32 +22,32 @@ The common ones are:
Terminators
-----------
-OP_RET
+.. op:: OP_RET
Return from subroutine.
* .src : returned value (NULL if void)
* .type: type of .src
-OP_BR
+.. op:: OP_BR
Unconditional branch
* .bb_true: destination basic block
-OP_CBR
+.. op:: OP_CBR
Conditional branch
* .cond: condition
* .type: type of .cond, must be an integral type
* .bb_true, .bb_false: destination basic blocks
-OP_SWITCH
+.. op:: OP_SWITCH
Switch / multi-branch
* .cond: condition
* .type: type of .cond, must be an integral type
* .multijmp_list: pairs of case-value - destination basic block
-OP_COMPUTEDGOTO
+.. op:: OP_COMPUTEDGOTO
Computed goto / branch to register
* .src: address to branch to (void*)
@@ -58,34 +60,34 @@ They all follow the same signature:
* .target: result of the operation (must be an integral type)
* .type: type of .target
-OP_ADD
+.. op:: OP_ADD
Integer addition.
-OP_SUB
+.. op:: OP_SUB
Integer subtraction.
-OP_MUL
+.. op:: OP_MUL
Integer multiplication.
-OP_DIVU
+.. op:: OP_DIVU
Integer unsigned division.
-OP_DIVS
+.. op:: OP_DIVS
Integer signed division.
-OP_MODU
+.. op:: OP_MODU
Integer unsigned remainder.
-OP_MODS
+.. op:: OP_MODS
Integer signed remainder.
-OP_SHL
+.. op:: OP_SHL
Shift left (integer only)
-OP_LSR
+.. op:: OP_LSR
Logical Shift right (integer only)
-OP_ASR
+.. op:: OP_ASR
Arithmetic Shift right (integer only)
Floating-point binops
@@ -95,16 +97,16 @@ They all follow the same signature:
* .target: result of the operation (must be a floating-point type)
* .type: type of .target
-OP_FADD
+.. op:: OP_FADD
Floating-point addition.
-OP_FSUB
+.. op:: OP_FSUB
Floating-point subtraction.
-OP_FMUL
+.. op:: OP_FMUL
Floating-point multiplication.
-OP_FDIV
+.. op:: OP_FDIV
Floating-point division.
Logical ops
@@ -114,21 +116,21 @@ They all follow the same signature:
* .target: result of the operation
* .type: type of .target, must be an integral type
-OP_AND
+.. op:: OP_AND
Logical AND
-OP_OR
+.. op:: OP_OR
Logical OR
-OP_XOR
+.. op:: OP_XOR
Logical XOR
Boolean ops
-----------
-OP_AND_BOOL
+.. op:: OP_AND_BOOL
Boolean AND
-OP_OR_BOOL
+.. op:: OP_OR_BOOL
Boolean OR
Integer compares
@@ -138,34 +140,34 @@ They all have the following signature:
* .target: result of the operation (0/1 valued integer)
* .type: type of .target, must be an integral type
-OP_SET_EQ
+.. op:: OP_SET_EQ
Compare equal.
-OP_SET_NE
+.. op:: OP_SET_NE
Compare not-equal.
-OP_SET_LE
+.. op:: OP_SET_LE
Compare less-than-or-equal (signed).
-OP_SET_GE
+.. op:: OP_SET_GE
Compare greater-than-or-equal (signed).
-OP_SET_LT
+.. op:: OP_SET_LT
Compare less-than (signed).
-OP_SET_GT
+.. op:: OP_SET_GT
Compare greater-than (signed).
-OP_SET_B
+.. op:: OP_SET_B
Compare less-than (unsigned).
-OP_SET_A
+.. op:: OP_SET_A
Compare greater-than (unsigned).
-OP_SET_BE
+.. op:: OP_SET_BE
Compare less-than-or-equal (unsigned).
-OP_SET_AE
+.. op:: OP_SET_AE
Compare greater-than-or-equal (unsigned).
Floating-point compares
@@ -178,76 +180,76 @@ NaN and if it is the case the ordered compares return false
and then unordered return true, otherwise the result of the
comparison, now guaranteed to be done on non-NaNs, is returned.
-OP_FCMP_OEQ
+.. op:: OP_FCMP_OEQ
Floating-point compare ordered equal
-OP_FCMP_ONE
+.. op:: OP_FCMP_ONE
Floating-point compare ordered not-equal
-OP_FCMP_OLE
+.. op:: OP_FCMP_OLE
Floating-point compare ordered less-than-or-equal
-OP_FCMP_OGE
+.. op:: OP_FCMP_OGE
Floating-point compare ordered greater-or-equal
-OP_FCMP_OLT
+.. op:: OP_FCMP_OLT
Floating-point compare ordered less-than
-OP_FCMP_OGT
+.. op:: OP_FCMP_OGT
Floating-point compare ordered greater-than
-OP_FCMP_UEQ
+.. op:: OP_FCMP_UEQ
Floating-point compare unordered equal
-OP_FCMP_UNE
+.. op:: OP_FCMP_UNE
Floating-point compare unordered not-equal
-OP_FCMP_ULE
+.. op:: OP_FCMP_ULE
Floating-point compare unordered less-than-or-equal
-OP_FCMP_UGE
+.. op:: OP_FCMP_UGE
Floating-point compare unordered greater-or-equal
-OP_FCMP_ULT
+.. op:: OP_FCMP_ULT
Floating-point compare unordered less-than
-OP_FCMP_UGT
+.. op:: OP_FCMP_UGT
Floating-point compare unordered greater-than
-OP_FCMP_ORD
+.. op:: OP_FCMP_ORD
Floating-point compare ordered: return true if both operands are ordered
(none of the operands are a NaN) and false otherwise.
-OP_FCMP_UNO
+.. op:: OP_FCMP_UNO
Floating-point compare unordered: return false if no operands is ordered
and true otherwise.
Unary ops
---------
-OP_NOT
+.. op:: OP_NOT
Logical not.
* .src: operand (type must be compatible with .target)
* .target: result of the operation
* .type: type of .target, must be an integral type
-OP_NEG
+.. op:: OP_NEG
Integer negation.
* .src: operand (type must be compatible with .target)
* .target: result of the operation (must be an integral type)
* .type: type of .target
-OP_FNEG
+.. op:: OP_FNEG
Floating-point negation.
* .src: operand (type must be compatible with .target)
* .target: result of the operation (must be a floating-point type)
* .type: type of .target
-OP_COPY
+.. op:: OP_COPY
Copy (only needed after out-of-SSA).
* .src: operand (type must be compatible with .target)
@@ -262,27 +264,27 @@ They all have the following signature:
* .target: result value
* .type: type of .target
-OP_CAST
+.. op:: OP_CAST
Cast to unsigned integer (and to void pointer).
-OP_SCAST
+.. op:: OP_SCAST
Cast to signed integer.
-OP_FPCAST
+.. op:: OP_FPCAST
Cast to floating-point.
-OP_PTRCAST
+.. op:: OP_PTRCAST
Cast to pointer.
Ternary ops
-----------
-OP_SEL
+.. op:: OP_SEL
* .src1: condition, must be of integral type
* .src2, .src3: operands (types must be compatible with .target)
* .target: result of the operation
* .type: type of .target
-OP_RANGE
+.. op:: OP_RANGE
Range/bounds checking (only used for an unused sparse extension).
* .src1: value to be checked
@@ -291,7 +293,7 @@ OP_RANGE
Memory ops
----------
-OP_LOAD
+.. op:: OP_LOAD
Load.
* .src: base address to load from
@@ -299,7 +301,7 @@ OP_LOAD
* .target: loaded value
* .type: type of .target
-OP_STORE
+.. op:: OP_STORE
Store.
* .src: base address to store to
@@ -309,20 +311,20 @@ OP_STORE
Others
------
-OP_SYMADDR
+.. op:: OP_SYMADDR
Create a pseudo corresponding to the address of a symbol.
* .symbol: (pseudo_t) input symbol (alias .src)
* .target: symbol's address
-OP_SETFVAL
+.. op:: OP_SETFVAL
Create a pseudo corresponding to a floating-point literal.
* .fvalue: the literal's value (long double)
* .target: the corresponding pseudo
* .type: type of the literal & .target
-OP_SETVAL
+.. op:: OP_SETVAL
Create a pseudo corresponding to a string literal or a label-as-value.
The value is given as an expression EXPR_STRING or EXPR_LABEL.
@@ -330,23 +332,24 @@ OP_SETVAL
* .target: the resulting value
* .type: type of .target, the value
-OP_PHI
+.. op:: OP_PHI
Phi-node (for SSA form).
* .phi_list: phi-operands (type must be compatible with .target)
* .target: "result"
* .type: type of .target
-OP_PHISOURCE
+.. op:: OP_PHISOURCE
Phi-node source.
Like OP_COPY but exclusively used to give a defining instructions
(and thus also a type) to *all* OP_PHI operands.
+
* .phi_src: operand (type must be compatible with .target, alias .src)
* .target: the "result" PSEUDO_PHI
* .type: type of .target
* .phi_users: list of phi instructions using the target pseudo
-OP_CALL
+.. op:: OP_CALL
Function call.
* .func: (pseudo_t) the function (can be a symbol or a "register",
@@ -358,15 +361,16 @@ OP_CALL
entry is the full function type, the next ones are the type of
each arguments
-OP_INLINED_CALL
+.. op:: OP_INLINED_CALL
Only used as an annotation to show that the instructions just above
correspond to a function that have been inlined.
+
* .func: (pseudo_t) the function (must be a symbol, alias .src))
* .arguments: list of pseudos that where the function's arguments
* .target: function return value (if any)
* .type: type of .target
-OP_SLICE
+.. op:: OP_SLICE
Extract a "slice" from an aggregate.
* .base: (pseudo_t) aggregate (alias .src)
@@ -374,7 +378,7 @@ OP_SLICE
* .target: result
* .type: type of .target
-OP_ASM
+.. op:: OP_ASM
Inlined assembly code.
* .string: asm template
@@ -382,7 +386,7 @@ OP_ASM
Sparse tagging (line numbers, context, whatever)
------------------------------------------------
-OP_CONTEXT
+.. op:: OP_CONTEXT
Currently only used for lock/unlock tracking.
* .context_expr: unused
@@ -391,15 +395,17 @@ OP_CONTEXT
Misc ops
--------
-OP_ENTRY
+.. op:: OP_ENTRY
Function entry point (no associated semantic).
-OP_BADOP
+.. op:: OP_BADOP
Invalid operation (should never be generated).
-OP_NOP
+.. op:: OP_NOP
No-op (should never be generated).
-OP_DEATHNOTE
+.. op:: OP_DEATHNOTE
Annotation telling the pseudo will be death after the next
instruction (other than some other annotation, that is).
+
+.. # vim: tabstop=4
diff --git a/Documentation/conf.py b/Documentation/conf.py
index f7a680147..aae9d39bb 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -29,6 +29,7 @@ needs_sphinx = '1.3'
sys.path.insert(0, os.path.abspath('sphinx'))
extensions = [
'cdoc'
+ , 'ir'
]
# support .md with python2 & python3
diff --git a/Documentation/doc-guide.rst b/Documentation/doc-guide.rst
index 80ec82c25..8133cb3a5 100644
--- a/Documentation/doc-guide.rst
+++ b/Documentation/doc-guide.rst
@@ -149,3 +149,7 @@ will be displayed like this:
It's strongly encouraged to use this
function instead of open coding a simple
``++``.
+
+Intermediate Representation
+---------------------------
+.. c:autodoc:: Documentation/sphinx/ir.py
diff --git a/Documentation/sphinx/ir.py b/Documentation/sphinx/ir.py
new file mode 100755
index 000000000..3028200a6
--- /dev/null
+++ b/Documentation/sphinx/ir.py
@@ -0,0 +1,75 @@
+#!/usr/bin/env python
+# SPDX_License-Identifier: MIT
+#
+# Copyright (C) 2018 Luc Van Oostenryck <luc.vanoostenryck@xxxxxxxxx>
+#
+
+"""
+///
+// To document the instructions used in the intermediate representation
+// a new domain is defined: 'ir' with a directive::
+//
+// .. op: <OP_NAME>
+// <description of OP_NAME>
+// ...
+//
+// This is equivalent to using a definition list but with the name
+// also placed in the index (with 'IR instruction' as descriptions).
+
+"""
+
+import docutils
+import sphinx
+
+class IROpDirective(docutils.parsers.rst.Directive):
+
+ # use the first line of content as the argument, this allow
+ # to not have to write a blanck line after the directive
+ final_argument_whitespace = True
+ required_argument = 0
+ #optional_arguments = 0
+ has_content = True
+
+ objtype = None
+
+ def run(self):
+ self.env = self.state.document.settings.env
+
+ source = self.state.document
+ lineno = self.lineno
+ text = self.content
+ name = text[0]
+
+ node = docutils.nodes.section()
+ node['ids'].append(name)
+ node.document = source
+
+ index = '.. index:: pair: %s; IR instruction' % name
+ content = docutils.statemachine.ViewList()
+ content.append(index, source, lineno)
+ content.append('' , source, lineno)
+ content.append(name , source, lineno)
+ content.append('' , source, lineno)
+ self.state.nested_parse(content, self.content_offset, node)
+
+ defnode = docutils.nodes.definition()
+ self.state.nested_parse(text[1:], self.content_offset, defnode)
+ node.append(defnode)
+
+ return [node]
+
+class IRDomain(sphinx.domains.Domain):
+
+ """IR domain."""
+ name = 'ir'
+
+def setup(app):
+ app.add_domain(IRDomain)
+ app.add_directive_to_domain('ir', 'op', IROpDirective)
+
+ return {
+ 'version': '1.0',
+ 'parallel_read_safe': True,
+ }
+
+# vim: tabstop=4
--
2.17.0
--
To unsubscribe from this list: send the line "unsubscribe linux-sparse" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
