diff options
| author | Luc Van Oostenryck <luc.vanoostenryck@gmail.com> | 2018-05-20 16:55:23 +0200 |
|---|---|---|
| committer | Luc Van Oostenryck <luc.vanoostenryck@gmail.com> | 2018-05-21 03:50:16 +0200 |
| commit | f477cb74ff136db72e810819283a957b44275fb8 (patch) | |
| tree | d74a170f7e6fd30516020d8f2da5fed7350c9d6e /Documentation | |
| parent | 9a6bc349fa1f3f9bd39a242dbef74609038c8946 (diff) | |
| download | sparse-dev-f477cb74ff136db72e810819283a957b44275fb8.tar.gz | |
doc: add sphinx domain for IR instruction indexation
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@gmail.com>
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/IR.rst | 154 | ||||
| -rw-r--r-- | Documentation/conf.py | 1 | ||||
| -rw-r--r-- | Documentation/doc-guide.rst | 4 | ||||
| -rwxr-xr-x | Documentation/sphinx/ir.py | 75 |
4 files changed, 160 insertions, 74 deletions
diff --git a/Documentation/IR.rst b/Documentation/IR.rst index ec297eed..67ef06a5 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 f7a68014..aae9d39b 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 80ec82c2..8133cb3a 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 00000000..3028200a --- /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@gmail.com> +# + +""" +/// +// 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 |