From 062ed8f6ea330775fd9c66fbf1154f0de48b587d Mon Sep 17 00:00:00 2001 From: Benjamin Bouvier Date: Wed, 10 Jul 2019 17:03:55 +0200 Subject: [PATCH] [docs] Remove rst annotations in instructions doc comments; --- .../codegen/meta/src/isa/x86/instructions.rs | 4 +- .../codegen/meta/src/shared/instructions.rs | 114 +++++++++--------- 2 files changed, 57 insertions(+), 61 deletions(-) diff --git a/cranelift/codegen/meta/src/isa/x86/instructions.rs b/cranelift/codegen/meta/src/isa/x86/instructions.rs index 2f365165b8..9aa7363e1a 100644 --- a/cranelift/codegen/meta/src/isa/x86/instructions.rs +++ b/cranelift/codegen/meta/src/isa/x86/instructions.rs @@ -151,7 +151,7 @@ pub fn define( Floating point minimum with x86 semantics. This is equivalent to the C ternary operator `x < y ? x : y` which - differs from :inst:`fmin` when either operand is NaN or when comparing + differs from `fmin` when either operand is NaN or when comparing +0.0 to -0.0. When the two operands don't compare as LT, `y` is returned unchanged, @@ -169,7 +169,7 @@ pub fn define( Floating point maximum with x86 semantics. This is equivalent to the C ternary operator `x > y ? x : y` which - differs from :inst:`fmax` when either operand is NaN or when comparing + differs from `fmax` when either operand is NaN or when comparing +0.0 to -0.0. When the two operands don't compare as GT, `y` is returned unchanged, diff --git a/cranelift/codegen/meta/src/shared/instructions.rs b/cranelift/codegen/meta/src/shared/instructions.rs index b89fa019b9..ed8f0b957c 100644 --- a/cranelift/codegen/meta/src/shared/instructions.rs +++ b/cranelift/codegen/meta/src/shared/instructions.rs @@ -168,7 +168,7 @@ pub fn define( r#" Fall through to the next EBB. - This is the same as :inst:`jump`, except the destination EBB must be + This is the same as `jump`, except the destination EBB must be the next one in the layout. Jumps are turned into fall-through instructions by the branch @@ -187,7 +187,7 @@ pub fn define( r#" Branch when zero. - If ``c`` is a :type:`b1` value, take the branch when ``c`` is false. If + If ``c`` is a `b1` value, take the branch when ``c`` is false. If ``c`` is an integer value, take the branch when ``c = 0``. "#, ) @@ -201,7 +201,7 @@ pub fn define( r#" Branch when non-zero. - If ``c`` is a :type:`b1` value, take the branch when ``c`` is true. If + If ``c`` is a `b1` value, take the branch when ``c`` is true. If ``c`` is an integer value, take the branch when ``c != 0``. "#, ) @@ -215,7 +215,7 @@ pub fn define( r#" Compare scalar integers and branch. - Compare ``x`` and ``y`` in the same way as the :inst:`icmp` instruction + Compare ``x`` and ``y`` in the same way as the `icmp` instruction and take the branch if the condition is true:: br_icmp ugt v1, v2, ebb4(v5, v6) @@ -464,11 +464,7 @@ pub fn define( .is_terminator(true), ); - let FN = &operand_doc( - "FN", - func_ref, - "function to call, declared by :inst:`function`", - ); + let FN = &operand_doc("FN", func_ref, "function to call, declared by `function`"); let args = &operand_doc("args", variable_args, "call arguments"); ig.push( @@ -500,7 +496,7 @@ pub fn define( Note that this is different from WebAssembly's ``call_indirect``; the callee is a native address, rather than a table index. For WebAssembly, - :inst:`table_addr` and :inst:`load` are used to obtain a native address + `table_addr` and `load` are used to obtain a native address from a table. "#, ) @@ -517,8 +513,8 @@ pub fn define( Compute the absolute address of a function declared in the preamble. The returned address can be used as a ``callee`` argument to - :inst:`call_indirect`. This is also a method for calling functions that - are too far away to be addressable by a direct :inst:`call` + `call_indirect`. This is also a method for calling functions that + are too far away to be addressable by a direct `call` instruction. "#, ) @@ -877,7 +873,7 @@ pub fn define( The offset is an immediate constant, not an SSA value. The memory access cannot go out of bounds, i.e. - :math:`sizeof(a) + Offset <= sizeof(SS)`. + `sizeof(a) + Offset <= sizeof(SS)`. "#, ) .operands_in(vec![SS, Offset]) @@ -896,7 +892,7 @@ pub fn define( The offset is an immediate constant, not an SSA value. The memory access cannot go out of bounds, i.e. - :math:`sizeof(a) + Offset <= sizeof(SS)`. + `sizeof(a) + Offset <= sizeof(SS)`. "#, ) .operands_in(vec![x, SS, Offset]) @@ -911,7 +907,7 @@ pub fn define( Compute the absolute address of a byte in a stack slot. The offset must refer to a byte inside the stack slot: - :math:`0 <= Offset < sizeof(SS)`. + `0 <= Offset < sizeof(SS)`. "#, ) .operands_in(vec![SS, Offset]) @@ -1027,7 +1023,7 @@ pub fn define( r#" Floating point constant. - Create a :type:`f32` SSA value with an immediate constant value. + Create a `f32` SSA value with an immediate constant value. "#, ) .operands_in(vec![N]) @@ -1043,7 +1039,7 @@ pub fn define( r#" Floating point constant. - Create a :type:`f64` SSA value with an immediate constant value. + Create a `f64` SSA value with an immediate constant value. "#, ) .operands_in(vec![N]) @@ -1087,7 +1083,7 @@ pub fn define( r#" Conditional select. - This instruction selects whole values. Use :inst:`vselect` for + This instruction selects whole values. Use `vselect` for lane-wise selection. "#, ) @@ -1135,7 +1131,7 @@ pub fn define( r#" Spill a register value to a stack slot. - This instruction behaves exactly like :inst:`copy`, but the result + This instruction behaves exactly like `copy`, but the result value is assigned to a spill slot. "#, ) @@ -1150,7 +1146,7 @@ pub fn define( r#" Load a register value from a stack slot. - This instruction behaves exactly like :inst:`copy`, but creates a new + This instruction behaves exactly like `copy`, but creates a new SSA value for the spilled input value. "#, ) @@ -1270,7 +1266,7 @@ pub fn define( r#" Compare ``addr`` with the stack pointer and set the CPU flags. - This is like :inst:`ifcmp` where ``addr`` is the LHS operand and the stack + This is like `ifcmp` where ``addr`` is the LHS operand and the stack pointer is the RHS. "#, ) @@ -1289,7 +1285,7 @@ pub fn define( allocator to temporarily rearrange register assignments in order to satisfy instruction constraints. - See also :inst:`regmove`. + See also `regmove`. "#, ) .operands_in(vec![x, src, SS]) @@ -1307,7 +1303,7 @@ pub fn define( allocator to temporarily rearrange register assignments in order to satisfy instruction constraints. - See also :inst:`regmove`. + See also `regmove`. "#, ) .operands_in(vec![x, SS, dst]) @@ -1481,10 +1477,10 @@ pub fn define( r#" Compare scalar integer to a constant. - This is the same as the :inst:`icmp` instruction, except one operand is + This is the same as the `icmp` instruction, except one operand is an immediate constant. - This instruction can only compare scalars. Use :inst:`icmp` for + This instruction can only compare scalars. Use `icmp` for lane-wise vector comparisons. "#, ) @@ -1516,7 +1512,7 @@ pub fn define( r#" Compare scalar integer to a constant and return flags. - Like :inst:`icmp_imm`, but returns integer CPU flags instead of testing + Like `icmp_imm`, but returns integer CPU flags instead of testing a specific condition code. "#, ) @@ -1532,7 +1528,7 @@ pub fn define( Inst::new( "iadd", r#" - Wrapping integer addition: :math:`a := x + y \pmod{2^B}`. + Wrapping integer addition: `a := x + y \pmod{2^B}`. This instruction does not depend on the signed/unsigned interpretation of the operands. @@ -1546,7 +1542,7 @@ pub fn define( Inst::new( "isub", r#" - Wrapping integer subtraction: :math:`a := x - y \pmod{2^B}`. + Wrapping integer subtraction: `a := x - y \pmod{2^B}`. This instruction does not depend on the signed/unsigned interpretation of the operands. @@ -1560,7 +1556,7 @@ pub fn define( Inst::new( "imul", r#" - Wrapping integer multiplication: :math:`a := x y \pmod{2^B}`. + Wrapping integer multiplication: `a := x y \pmod{2^B}`. This instruction does not depend on the signed/unsigned interpretation of the @@ -1607,7 +1603,7 @@ pub fn define( Inst::new( "udiv", r#" - Unsigned integer division: :math:`a := \lfloor {x \over y} \rfloor`. + Unsigned integer division: `a := \lfloor {x \over y} \rfloor`. This operation traps if the divisor is zero. "#, @@ -1621,12 +1617,12 @@ pub fn define( Inst::new( "sdiv", r#" - Signed integer division rounded toward zero: :math:`a := sign(xy) + Signed integer division rounded toward zero: `a := sign(xy) \lfloor {|x| \over |y|}\rfloor`. This operation traps if the divisor is zero, or if the result is not - representable in :math:`B` bits two's complement. This only happens - when :math:`x = -2^{B-1}, y = -1`. + representable in `B` bits two's complement. This only happens + when `x = -2^{B-1}, y = -1`. "#, ) .operands_in(vec![x, y]) @@ -1672,7 +1668,7 @@ pub fn define( r#" Add immediate integer. - Same as :inst:`iadd`, but one operand is an immediate constant. + Same as `iadd`, but one operand is an immediate constant. Polymorphic over all scalar integer types, but does not support vector types. @@ -1716,8 +1712,8 @@ pub fn define( Signed integer division by an immediate constant. This operation traps if the divisor is zero, or if the result is not - representable in :math:`B` bits two's complement. This only happens - when :math:`x = -2^{B-1}, Y = -1`. + representable in `B` bits two's complement. This only happens + when `x = -2^{B-1}, Y = -1`. "#, ) .operands_in(vec![x, Y]) @@ -1754,9 +1750,9 @@ pub fn define( Inst::new( "irsub_imm", r#" - Immediate reverse wrapping subtraction: :math:`a := Y - x \pmod{2^B}`. + Immediate reverse wrapping subtraction: `a := Y - x \pmod{2^B}`. - Also works as integer negation when :math:`Y = 0`. Use :inst:`iadd_imm` + Also works as integer negation when `Y = 0`. Use `iadd_imm` with a negative immediate operand for the reverse immediate subtraction. @@ -1782,7 +1778,7 @@ pub fn define( r#" Add integers with carry in. - Same as :inst:`iadd` with an additional carry input. Computes: + Same as `iadd` with an additional carry input. Computes: .. math:: @@ -1802,7 +1798,7 @@ pub fn define( r#" Add integers with carry out. - Same as :inst:`iadd` with an additional carry output. + Same as `iadd` with an additional carry output. .. math:: @@ -1823,7 +1819,7 @@ pub fn define( r#" Add integers with carry in and out. - Same as :inst:`iadd` with an additional carry input and output. + Same as `iadd` with an additional carry input and output. .. math:: @@ -1844,7 +1840,7 @@ pub fn define( r#" Subtract integers with borrow in. - Same as :inst:`isub` with an additional borrow flag input. Computes: + Same as `isub` with an additional borrow flag input. Computes: .. math:: @@ -1864,7 +1860,7 @@ pub fn define( r#" Subtract integers with borrow out. - Same as :inst:`isub` with an additional borrow flag output. + Same as `isub` with an additional borrow flag output. .. math:: @@ -1885,7 +1881,7 @@ pub fn define( r#" Subtract integers with borrow in and out. - Same as :inst:`isub` with an additional borrow flag input and output. + Same as `isub` with an additional borrow flag input and output. .. math:: @@ -2008,7 +2004,7 @@ pub fn define( r#" Bitwise and with immediate. - Same as :inst:`band`, but one operand is an immediate constant. + Same as `band`, but one operand is an immediate constant. Polymorphic over all scalar integer types, but does not support vector types. @@ -2024,7 +2020,7 @@ pub fn define( r#" Bitwise or with immediate. - Same as :inst:`bor`, but one operand is an immediate constant. + Same as `bor`, but one operand is an immediate constant. Polymorphic over all scalar integer types, but does not support vector types. @@ -2040,7 +2036,7 @@ pub fn define( r#" Bitwise xor with immediate. - Same as :inst:`bxor`, but one operand is an immediate constant. + Same as `bxor`, but one operand is an immediate constant. Polymorphic over all scalar integer types, but does not support vector types. @@ -2296,12 +2292,12 @@ pub fn define( == ========================================== UN Unordered when one or both numbers is NaN. - EQ When :math:`x = y`. (And :math:`0.0 = -0.0`). - LT When :math:`x < y`. - GT When :math:`x > y`. + EQ When `x = y`. (And `0.0 = -0.0`). + LT When `x < y`. + GT When `x > y`. == ========================================== - The 14 :type:`floatcc` condition codes each correspond to a subset of + The 14 `floatcc` condition codes each correspond to a subset of the four relations, except for the empty set which would always be false, and the full set which would always be true. @@ -2329,7 +2325,7 @@ pub fn define( The standard C comparison operators, `<, <=, >, >=`, are all ordered, so they are false if either operand is NaN. The C equality operator, `==`, is ordered, and since inequality is defined as the logical - inverse it is *unordered*. They map to the :type:`floatcc` condition + inverse it is *unordered*. They map to the `floatcc` condition codes as follows: ==== ====== ============ @@ -2362,7 +2358,7 @@ pub fn define( r#" Floating point comparison returning flags. - Compares two numbers like :inst:`fcmp`, but returns floating point CPU + Compares two numbers like `fcmp`, but returns floating point CPU flags instead of testing a specific condition. "#, ) @@ -2414,8 +2410,8 @@ pub fn define( r#" Floating point division. - Unlike the integer division instructions :clif:inst:`sdiv` and - :clif:inst:`udiv`, this can't trap. Division by zero is infinity or + Unlike the integer division instructions ` and + `udiv`, this can't trap. Division by zero is infinity or NaN, depending on the dividend. "#, ) @@ -2440,7 +2436,7 @@ pub fn define( r#" Floating point fused multiply-and-add. - Computes :math:`a := xy+z` without any intermediate rounding of the + Computes `a := xy+z` without any intermediate rounding of the product. "#, ) @@ -2759,7 +2755,7 @@ pub fn define( Each lane in `x` is converted to a smaller integer type by discarding the most significant bits. This is the same as reducing modulo - :math:`2^n`. + `2^n`. The result type must have the same number of vector lanes as the input, and each lane must not have more bits that the input lanes. If the @@ -2843,7 +2839,7 @@ pub fn define( This is an exact operation. Cranelift currently only supports two floating point formats - - :type:`f32` and :type:`f64`. This may change in the future. + - `f32` and `f64`. This may change in the future. The result type must have the same number of vector lanes as the input, and the result lanes must not have fewer bits than the input lanes. If @@ -2865,7 +2861,7 @@ pub fn define( by rounding to nearest, ties to even. Cranelift currently only supports two floating point formats - - :type:`f32` and :type:`f64`. This may change in the future. + - `f32` and `f64`. This may change in the future. The result type must have the same number of vector lanes as the input, and the result lanes must not have more bits than the input lanes. If