X-Git-Url: https://git.libre-soc.org/?a=blobdiff_plain;f=ztrans_proposal.mdwn;h=ca73c4220a0faf66a30917a4b688fe32d0a6a657;hb=517306571ec9f1bf792118acec4100c47c73f413;hp=b1f13e5216cc0dcaccafb9325b0ee1a2bb3b6330;hpb=dd539f5ef6e75ad7ef59470857c9ee698defbf7e;p=libreriscv.git

diff --git a/ztrans_proposal.mdwn b/ztrans_proposal.mdwn
index b1f13e521..ca73c4220 100644
--- a/ztrans_proposal.mdwn
+++ b/ztrans_proposal.mdwn
@@ -1,7 +1,14 @@
+**OBSOLETE**, superceded by [[openpower/transcendentals]]
+
 # Zftrans - transcendental operations
 
-With thanks to:
+Summary:
+
+*This proposal extends RISC-V scalar floating point operations to add IEEE754 transcendental functions (pow, log etc) and trigonometric functions (sin, cos etc). These functions are also 98% shared with the Khronos Group OpenCL Extended Instruction Set.*
 
+Authors/Contributors:
+
+* Luke Kenneth Casson Leighton
 * Jacob Lifshay
 * Dan Petroski
 * Mitch Alsup
@@ -33,10 +40,10 @@ Extension subsets:
 * **ZftransAdv**: much more complex to implement in hardware
 * **Zfrsqrt**: Reciprocal square-root.
 
-Minimum recommended requirements for 3D: Zftrans, Ztrigpi, Ztrignpi, Zarctrigpi,
-Zarctrignpi
+Minimum recommended requirements for 3D: Zftrans, Ztrignpi,
+Zarctrignpi, with Ztrigpi and Zarctrigpi as augmentations.
 
-Minimum recommended requirements for Mobile-Embedded 3D: Ztrigpi, Zftrans, Ztrignpi
+Minimum recommended requirements for Mobile-Embedded 3D: Ztrignpi, Zftrans, with Ztrigpi as an augmentation.
 
 # TODO:
 
@@ -54,7 +61,7 @@ Minimum recommended requirements for Mobile-Embedded 3D: Ztrigpi, Zftrans, Ztrig
 
 This proposal is designed to meet a wide range of extremely diverse needs,
 allowing implementors from all of them to benefit from the tools and hardware
-cost reductions associated with common standards adoption.
+cost reductions associated with common standards adoption in RISC-V (primarily IEEE754 and Vulkan).
 
 **There are *four* different, disparate platform's needs (two new)**:
 
@@ -94,9 +101,13 @@ covered by Supercomputer Vectorisation Standards (such as RVV).
 
 **The "contra"-requirements are**:
 
+* NOT for use with RVV (RISC-V Vector Extension). These are *scalar* opcodes.
+  Ultra Low Power Embedded platforms (smart watches) are sufficiently
+  resource constrained that Vectorisation (of any kind) is likely to be
+  unnecessary and inappropriate.
 * The requirements are **not** for the purposes of developing a full custom
-  proprietary GPU with proprietary firmware
-  driven by *hardware* centric optimised design decisions as a priority over collaboration.
+  proprietary GPU with proprietary firmware driven by *hardware* centric
+  optimised design decisions as a priority over collaboration.
 * A full custom proprietary GPU ASIC Manufacturer *may* benefit from
   this proposal however the fact that they typically develop proprietary
   software that is not shared with the rest of the community likely to
@@ -132,9 +143,10 @@ have extremely competitive power-efficiency and power-budget requirements
 that are completely at odds with the other market at the other end of
 the spectrum: Numerical Computation.
 
-Interoperability in Numerical Computation is absolutely critical: it implies (correlates directly with)
-IEEE754 compliance.  However full IEEE754 compliance automatically and
-inherently penalises a GPU on performance and die area, where accuracy is simply just not necessary.
+Interoperability in Numerical Computation is absolutely critical: it
+implies (correlates directly with) IEEE754 compliance.  However full
+IEEE754 compliance automatically and inherently penalises a GPU on
+performance and die area, where accuracy is simply just not necessary.
 
 To meet the needs of both markets, the two new platforms have to be created,
 and [[zfpacc_proposal]] is a critical dependency.  Runtime selection of
@@ -158,8 +170,9 @@ Compiler) would conclude, reasonably and rationally, that, likewise, the
 opcodes were best suited to be added to RVV, and, further, that their
 requirements conflict with the HPC world, due to the reduced accuracy.
 This on the basis that the silicon die area required for IEEE754 is far
-greater than that needed for reduced-accuracy, and thus their product would
-be completely unacceptable in the market if it had to meet IEEE754, unnecessarily.
+greater than that needed for reduced-accuracy, and thus their product
+would be completely unacceptable in the market if it had to meet IEEE754,
+unnecessarily.
 
 An "Embedded 3D" GPU has radically different performance, power
 and die-area requirements (and may even target SoftCores in FPGA).
@@ -194,20 +207,24 @@ of the RISC-V ecosystem.
 
 However given that 3D revolves around Standards - DirectX, Vulkan, OpenGL,
 OpenCL - users have much more influence than first appears.  Compliance
-with these standards is critical as the userbase (Games writers, scientific
-applications) expects not to have to rewrite extremely large and costly codebases to conform
-with *non-standards-compliant* hardware.
+with these standards is critical as the userbase (Games writers,
+scientific applications) expects not to have to rewrite extremely large
+and costly codebases to conform with *non-standards-compliant* hardware.
 
-Therefore, compliance with public APIs (Vulkan, OpenCL, OpenGL, DirectX) is paramount, and compliance with
-Trademarked Standards is critical.  Any deviation from Trademarked Standards
-means that an implementation may not be sold and also make a claim of being,
-for example, "Vulkan compatible".
+Therefore, compliance with public APIs (Vulkan, OpenCL, OpenGL, DirectX)
+is paramount, and compliance with Trademarked Standards is critical.
+Any deviation from Trademarked Standards means that an implementation
+may not be sold and also make a claim of being, for example, "Vulkan
+compatible".
 
-This in turn reinforces and makes a hard requirement a need for public
+For 3D, this in turn reinforces and makes a hard requirement a need for public
 compliance with such standards, over-and-above what would otherwise be
 set by a RISC-V Standards Development Process, including both the
 software compliance and the knock-on implications that has for hardware.
 
+For libraries such as libm and numpy, accuracy is paramount, for software  interoperability across multiple platforms. Some algorithms critically rely on correct IEEE754, for example.
+The conflicting accuracy requirements can be met through the zfpacc extension.
+
 **Collaboration**:
 
 The case for collaboration on any Extension is already well-known.
@@ -217,9 +234,9 @@ these primitives well-established in high-profile software libraries and
 compilers in both GPU and HPC Computer Science divisions.  Collaboration
 and shared public compliance with those standards brooks no argument.
 
-The combined requirements of collaboration and multi accuracy requirements mean that
-*overall this proposal is categorically and wholly unsuited to
-relegation of "custom" status*.
+The combined requirements of collaboration and multi accuracy requirements
+mean that *overall this proposal is categorically and wholly unsuited
+to relegation of "custom" status*.
 
 # Quantitative Analysis <a name="analysis"></a>
 
@@ -283,29 +300,39 @@ However, some markets may not wish to *use* CORDIC, for reasons mentioned
 above, and, again, one market would be penalised if SINPI was prioritised
 over SIN, or vice-versa.
 
-In essence, then, even when only the two primary markets (3D and Numerical Computation) have been identified, this still leaves two (three) diametrically-opposed *accuracy* sub-markets as the prime conflict drivers:
+In essence, then, even when only the two primary markets (3D and
+Numerical Computation) have been identified, this still leaves two
+(three) diametrically-opposed *accuracy* sub-markets as the prime
+conflict drivers:
 
 * Embedded Ultra Low Power
 * IEEE754 compliance
 * Khronos Vulkan compliance
 
 Thus the best that can be done is to use Quantitative Analysis to work
-out which "subsets" - sub-Extensions - to include, provide an additional "accuracy" extension, be as "inclusive"
-as possible, and thus allow implementors to decide what to add to their
-implementation, and how best to optimise them.
+out which "subsets" - sub-Extensions - to include, provide an additional
+"accuracy" extension, be as "inclusive" as possible, and thus allow
+implementors to decide what to add to their implementation, and how best
+to optimise them.
 
 This approach *only* works due to the uniformity of the function space,
 and is **not** an appropriate methodology for use in other Extensions
-with huge (non-uniform) market diversity even with similarly large numbers of potential opcodes.
-BitManip is the perfect counter-example.
+with huge (non-uniform) market diversity even with similarly large
+numbers of potential opcodes.  BitManip is the perfect counter-example.
 
-# Proposed Opcodes vs Khronos OpenCL Opcodes <a name="khronos_equiv"></a>
+# Proposed Opcodes vs Khronos OpenCL vs IEEE754-2019<a name="khronos_equiv"></a>
 
-This list shows the (direct) equivalence between proposed opcodes and
-their Khronos OpenCL equivalents.
+This list shows the (direct) equivalence between proposed opcodes,
+their Khronos OpenCL equivalents, and their IEEE754-2019 equivalents.
+98% of the opcodes in this proposal that are in the IEEE754-2019 standard
+are present in the Khronos Extended Instruction Set.
+
+For RISCV opcode encodings see 
+[[rv_major_opcode_1010011]]
 
 See
 <https://www.khronos.org/registry/spir-v/specs/unified1/OpenCL.ExtendedInstructionSet.100.html>
+and <https://ieeexplore.ieee.org/document/8766229>
 
 * Special FP16 opcodes are *not* being proposed, except by indirect / inherent
   use of the "fmt" field that is already present in the RISC-V Specification.
@@ -321,59 +348,76 @@ Khronos Specification accuracy requirements - is not an option, as it
 results in non-compliance, and the vendor may not use the Trademarked words
 "Vulkan" etc. in conjunction with their product.
 
+IEEE754-2019 Table 9.1 lists "additional mathematical operations".
+Interestingly the only functions missing when compared to OpenCL are
+compound, exp2m1, exp10m1, log2p1, log10p1, pown (integer power) and powr.
+
 [[!table data="""
-Proposed opcode | OpenCL FP32 | OpenCL FP16 | OpenCL native | OpenCL fast |
-FSIN            | sin         | half\_sin   | native\_sin   | NONE        |
-FCOS            | cos         | half\_cos   | native\_cos   | NONE        |
-FTAN            | tan         | half\_tan   | native\_tan   | NONE        |
-NONE (1)        | sincos      | NONE        | NONE          | NONE        |
-FASIN           | asin        | NONE        | NONE          | NONE        |
-FACOS           | acos        | NONE        | NONE          | NONE        |
-FATAN           | atan        | NONE        | NONE          | NONE        |
-FSINPI          | sinpi       | NONE        | NONE          | NONE        |
-FCOSPI          | cospi       | NONE        | NONE          | NONE        |
-FTANPI          | tanpi       | NONE        | NONE          | NONE        |
-FASINPI         | asinpi      | NONE        | NONE          | NONE        |
-FACOSPI         | acospi      | NONE        | NONE          | NONE        |
-FATANPI         | atanpi      | NONE        | NONE          | NONE        |
-FSINH           | sinh        | NONE        | NONE          | NONE        |
-FCOSH           | cosh        | NONE        | NONE          | NONE        |
-FTANH           | tanh        | NONE        | NONE          | NONE        |
-FASINH          | asinh       | NONE        | NONE          | NONE        |
-FACOSH          | acosh       | NONE        | NONE          | NONE        |
-FATANH          | atanh       | NONE        | NONE          | NONE        |
-FRSQRT          | rsqrt       | half\_rsqrt | native\_rsqrt | NONE        |
-FCBRT           | cbrt        | NONE        | NONE          | NONE        |
-FEXP2           | exp2        | half\_exp2  | native\_exp2  | NONE        |
-FLOG2           | log2        | half\_log2  | native\_log2  | NONE        |
-FEXPM1          | expm1       | NONE        | NONE          | NONE        |
-FLOG1P          | log1p       | NONE        | NONE          | NONE        |
-FEXP            | exp         | half\_exp   | native\_exp   | NONE        |
-FLOG            | log         | half\_log   | native\_log   | NONE        |
-FEXP10          | exp10       | half\_exp10 | native\_exp10 | NONE        |
-FLOG10          | log10       | half\_log10 | native\_log10 | NONE        |
-FATAN2          | atan2       | NONE        | NONE          | NONE        |
-FATAN2PI        | atan2pi     | NONE        | NONE          | NONE        |
-FPOW            | pow         | NONE        | NONE          | NONE        |
-FROOT           | rootn       | NONE        | NONE          | NONE        |
-FHYPOT          | hypot       | NONE        | NONE          | NONE        |
-FRECIP          | NONE        | half\_recip | native\_recip | NONE        |
+opcode   | OpenCL FP32 | OpenCL FP16 | OpenCL native | OpenCL fast | IEEE754  |
+FSIN     | sin         | half\_sin   | native\_sin   | NONE        | sin      |
+FCOS     | cos         | half\_cos   | native\_cos   | NONE        | cos      |
+FTAN     | tan         | half\_tan   | native\_tan   | NONE        | tan      |
+NONE (1) | sincos      | NONE        | NONE          | NONE        | NONE     |
+FASIN    | asin        | NONE        | NONE          | NONE        | asin     |
+FACOS    | acos        | NONE        | NONE          | NONE        | acos     |
+FATAN    | atan        | NONE        | NONE          | NONE        | atan     |
+FSINPI   | sinpi       | NONE        | NONE          | NONE        | sinPi    |
+FCOSPI   | cospi       | NONE        | NONE          | NONE        | cosPi    |
+FTANPI   | tanpi       | NONE        | NONE          | NONE        | tanPi    |
+FASINPI  | asinpi      | NONE        | NONE          | NONE        | asinPi   |
+FACOSPI  | acospi      | NONE        | NONE          | NONE        | acosPi   |
+FATANPI  | atanpi      | NONE        | NONE          | NONE        | atanPi   |
+FSINH    | sinh        | NONE        | NONE          | NONE        | sinh     |
+FCOSH    | cosh        | NONE        | NONE          | NONE        | cosh     |
+FTANH    | tanh        | NONE        | NONE          | NONE        | tanh     |
+FASINH   | asinh       | NONE        | NONE          | NONE        | asinh    |
+FACOSH   | acosh       | NONE        | NONE          | NONE        | acosh    |
+FATANH   | atanh       | NONE        | NONE          | NONE        | atanh    |
+FATAN2   | atan2       | NONE        | NONE          | NONE        | atan2    |
+FATAN2PI | atan2pi     | NONE        | NONE          | NONE        | atan2pi  |
+FRSQRT   | rsqrt       | half\_rsqrt | native\_rsqrt | NONE        | rSqrt    |
+FCBRT    | cbrt        | NONE        | NONE          | NONE        | NONE (2) |
+FEXP2    | exp2        | half\_exp2  | native\_exp2  | NONE        | exp2     |
+FLOG2    | log2        | half\_log2  | native\_log2  | NONE        | log2     |
+FEXPM1   | expm1       | NONE        | NONE          | NONE        | expm1    |
+FLOG1P   | log1p       | NONE        | NONE          | NONE        | logp1    |
+FEXP     | exp         | half\_exp   | native\_exp   | NONE        | exp      |
+FLOG     | log         | half\_log   | native\_log   | NONE        | log      |
+FEXP10   | exp10       | half\_exp10 | native\_exp10 | NONE        | exp10    |
+FLOG10   | log10       | half\_log10 | native\_log10 | NONE        | log10    |
+FPOW     | pow         | NONE        | NONE          | NONE        | pow      |
+FPOWN    | pown        | NONE        | NONE          | NONE        | pown     |
+FPOWR    | powr        | half\_powr  | native\_powr  | NONE        | powr     |
+FROOTN   | rootn       | NONE        | NONE          | NONE        | rootn    |
+FHYPOT   | hypot       | NONE        | NONE          | NONE        | hypot    |
+FRECIP   | NONE        | half\_recip | native\_recip | NONE        | NONE (3) |
+NONE     | NONE        | NONE        | NONE          | NONE        | compound |
+NONE     | NONE        | NONE        | NONE          | NONE        | exp2m1   |
+NONE     | NONE        | NONE        | NONE          | NONE        | exp10m1  |
+NONE     | NONE        | NONE        | NONE          | NONE        | log2p1   |
+NONE     | NONE        | NONE        | NONE          | NONE        | log10p1  |
 """]]
 
 Note (1) FSINCOS is macro-op fused (see below).
 
-# List of 2-arg opcodes
+Note (2) synthesised in IEEE754-2019 as "pown(x, 3)"
+
+Note (3) synthesised in IEEE754-2019 using "1.0 / x"
+
+## List of 2-arg opcodes
 
 [[!table  data="""
 opcode    | Description            | pseudocode                 | Extension   |
 FATAN2    | atan2 arc tangent      | rd = atan2(rs2, rs1)       | Zarctrignpi |
 FATAN2PI  | atan2 arc tangent / pi | rd = atan2(rs2, rs1) / pi  | Zarctrigpi  |
 FPOW      | x power of y           | rd = pow(rs1, rs2)         | ZftransAdv  |
-FROOT     | x power 1/y            | rd = pow(rs1, 1/rs2)       | ZftransAdv  |
+FPOWN     | x power of n (n int)   | rd = pow(rs1, rs2)         | ZftransAdv  |
+FPOWR     | x power of y (x +ve)   | rd = exp(rs1 log(rs2))     | ZftransAdv  |
+FROOTN    | x power 1/n (n integer)| rd = pow(rs1, 1/rs2)       | ZftransAdv  |
 FHYPOT    | hypotenuse             | rd = sqrt(rs1^2 + rs2^2)   | ZftransAdv  |
 """]]
 
-# List of 1-arg transcendental opcodes
+## List of 1-arg transcendental opcodes
 
 [[!table  data="""
 opcode   | Description              | pseudocode              | Extension  |
@@ -390,7 +434,7 @@ FEXP10   | power-of-10              | rd = pow(10, rs1)       | ZftransExt |
 FLOG10   | log base 10              | rd = log(10, rs1)       | ZftransExt |
 """]]
 
-# List of 1-arg trigonometric opcodes
+## List of 1-arg trigonometric opcodes
 
 [[!table  data="""
 opcode      | Description              | pseudo-code             | Extension |
@@ -399,13 +443,13 @@ FCOS        | cos (radians)            | rd = cos(rs1)           | Ztrignpi    |
 FTAN        | tan (radians)            | rd = tan(rs1)           | Ztrignpi    |
 FASIN       | arcsin (radians)         | rd = asin(rs1)          | Zarctrignpi |
 FACOS       | arccos (radians)         | rd = acos(rs1)          | Zarctrignpi |
-FATAN (1)   | arctan (radians)         | rd = atan(rs1)          | Zarctrignpi |
+FATAN       | arctan (radians)         | rd = atan(rs1)          | Zarctrignpi |
 FSINPI      | sin times pi             | rd = sin(pi * rs1)      | Ztrigpi |
 FCOSPI      | cos times pi             | rd = cos(pi * rs1)      | Ztrigpi |
 FTANPI      | tan times pi             | rd = tan(pi * rs1)      | Ztrigpi |
 FASINPI     | arcsin / pi              | rd = asin(rs1) / pi     | Zarctrigpi |
 FACOSPI     | arccos / pi              | rd = acos(rs1) / pi     | Zarctrigpi |
-FATANPI (1) | arctan / pi              | rd = atan(rs1) / pi     | Zarctrigpi |
+FATANPI     | arctan / pi              | rd = atan(rs1) / pi     | Zarctrigpi |
 FSINH       | hyperbolic sin (radians) | rd = sinh(rs1)          | Zfhyp |
 FCOSH       | hyperbolic cos (radians) | rd = cosh(rs1)          | Zfhyp |
 FTANH       | hyperbolic tan (radians) | rd = tanh(rs1)          | Zfhyp |
@@ -414,15 +458,17 @@ FACOSH      | inverse hyperbolic cos   | rd = acosh(rs1)         | Zfhyp |
 FATANH      | inverse hyperbolic tan   | rd = atanh(rs1)         | Zfhyp |
 """]]
 
-Note (1): FATAN/FATANPI is a pseudo-op expanding to FATAN2/FATAN2PI (needs deciding)
-
 # Subsets
 
-The full set is based on the Khronos OpenCL opcodes. If implemented entirely it would be too much for both Embedded and also 3D.
+The full set is based on the Khronos OpenCL opcodes. If implemented
+entirely it would be too much for both Embedded and also 3D.
 
-The subsets are organised by hardware complexity, need (3D, HPC), however due to synthesis producing inaccurate results at the range limits, the less common subsets are still required for IEEE754 HPC.
+The subsets are organised by hardware complexity, need (3D, HPC), however
+due to synthesis producing inaccurate results at the range limits,
+the less common subsets are still required for IEEE754 HPC.
 
-MALI Midgard, an embedded / mobile 3D GPU, for example only has the following opcodes:
+MALI Midgard, an embedded / mobile 3D GPU, for example only has the
+following opcodes:
 
     E8 - fatan_pt2
     F0 - frcp (reciprocal)
@@ -430,8 +476,8 @@ MALI Midgard, an embedded / mobile 3D GPU, for example only has the following op
     F3 - fsqrt (square root)
     F4 - fexp2 (2^x)
     F5 - flog2
-    F6 - fsin
-    F7 - fcos
+    F6 - fsin1pi
+    F7 - fcos1pi
     F9 - fatan_pt1
 
 These in FP32 and FP16 only: no FP32 hardware, at all.
@@ -446,71 +492,126 @@ Vivante Embedded/Mobile 3D (etnaviv <https://github.com/laanwj/etna_viv/blob/mas
 
 It also has fast variants of some of these, as a CSR Mode.
 
-Also a general point, that customised optimised hardware targetting FP32 3D with less accuracy simply can neither be used for IEEE754 nor for FP64 (except as a starting point for hardware or software driven Newton Raphson or other iterative method).
+AMD's R600 GPU (R600\_Instruction\_Set\_Architecture.pdf) and the
+RDNA ISA (RDNA\_Shader\_ISA\_5August2019.pdf, Table 22, Section 6.3) have:
+
+    COS2PI (appx)
+    EXP2
+    LOG (IEEE754)
+    RECIP
+    RSQRT
+    SQRT
+    SIN2PI (appx)
+
+AMD RDNA has F16 and F32 variants of all the above, and also has F64
+variants of SQRT, RSQRT and RECIP.  It is interesting that even the
+modern high-end AMD GPU does not have TAN or ATAN, where MALI Midgard
+does.
+
+Also a general point, that customised optimised hardware targetting
+FP32 3D with less accuracy simply can neither be used for IEEE754 nor
+for FP64 (except as a starting point for hardware or software driven
+Newton Raphson or other iterative method).
+
+Also in cost/area sensitive applications even the extra ROM lookup tables
+for certain algorithms may be too costly.
+
+These wildly differing and incompatible driving factors lead to the
+subset subdivisions, below.
 
-Also in cost/area sensitive applications even the extra ROM lookup tables for certain algorithms may be too costly.
+## Transcendental Subsets
 
-These wildly differing and incompatible driving factors lead to the subset subdivisions, below.
+### Zftrans
 
-## Zftrans
+LOG2 EXP2 RECIP RSQRT
 
-Zftrans contains the minimum standard transcendentals best suited to 3D: log2, exp2, recip, rsqrt. They are also the minimum subset for synthesising log10, exp10, exp1m, log1p, the hyperbolic trigonometric functions sinh and so on.
+Zftrans contains the minimum standard transcendentals best suited to
+3D. They are also the minimum subset for synthesising log10, exp10,
+exp1m, log1p, the hyperbolic trigonometric functions sinh and so on.
 
-## ZftransExt
+They are therefore considered "base" (essential) transcendentals.
+
+### ZftransExt
 
 LOG, EXP, EXP10, LOG10, LOGP1, EXP1M
 
-These are extra transcendental functions that are useful, not generally needed for 3D, however for Numerical Computation they may be useful.
+These are extra transcendental functions that are useful, not generally
+needed for 3D, however for Numerical Computation they may be useful.
 
-Although they can be synthesised using Ztrans (LOG2 multiplied by a constant), there is both a performance penalty as well as an accuracy penalty towards the limits, which for IEEE754 compliance is unacceptable. In particular, LOG(1+rs1) in hardware 
- may give much better accuracy at the lower end (very small rs1) than LOG(rs1).
+Although they can be synthesised using Ztrans (LOG2 multiplied
+by a constant), there is both a performance penalty as well as an
+accuracy penalty towards the limits, which for IEEE754 compliance is
+unacceptable. In particular, LOG(1+rs1) in hardware may give much better
+accuracy at the lower end (very small rs1) than LOG(rs1).
 
-Their forced inclusion would be inappropriate as it would penalise embedded systems with tight power and area budgets.  However if they were completely excluded the HPC applications would be penalised on performance and accuracy.
+Their forced inclusion would be inappropriate as it would penalise
+embedded systems with tight power and area budgets.  However if they
+were completely excluded the HPC applications would be penalised on
+performance and accuracy.
 
 Therefore they are their own subset extension.
 
-## Ztrigpi vs Ztrignpi
+### Zfhyp
 
-* **Ztrigpi**: trig. xxx-pi sinpi cospi tanpi
-* **Ztrignpi**: trig non-xxx-pi sin cos tan
+SINH, COSH, TANH, ASINH, ACOSH, ATANH
 
-Ztrignpi are the basic trigonometric functions through which all others could be synthesised, and they are typically the base trigonometrics provided by GPUs for 3D, warranting their own subset.
+These are the hyperbolic/inverse-hyperbolic functions. Their use in 3D is limited.
 
-However as can be correspondingly seen from other sections, there is an accuracy penalty for doing so which will not be acceptable for IEEE754 compliance.
+They can all be synthesised using LOG, SQRT and so on, so depend
+on Zftrans.  However, once again, at the limits of the range, IEEE754
+compliance becomes impossible, and thus a hardware implementation may
+be required.
 
-In the case of the Ztrigpi subset, these are commonly used in for loops with a power of two number of subdivisions, and the cost of multiplying by PI inside each loop (or cumulative addition, resulting in cumulative errors) is not acceptable.
+HPC and high-end GPUs are likely markets for these.
 
-In for example CORDIC the multiplication by PI may be moved outside of the hardware algorithm as a loop invariant, with no power or area penalty.
+### ZftransAdv
 
-Thus again, the same general argument applies to give Ztrignpi and Ztrigpi as subsets.
+CBRT, POW, POWN, POWR, ROOTN
 
-## Zarctrigpi and Zarctrignpi
+These are simply much more complex to implement in hardware, and typically
+will only be put into HPC applications.
 
-* **Zarctrigpi**: arc-trig. a-xxx-pi: atan2pi asinpi acospi
-* **Zarctrignpi**: arc-trig. non-a-xxx-pi: atan2, asin, acos
+* **Zfrsqrt**: Reciprocal square-root.
 
-These are extra trigonometric functions that are useful in some applications, but even for 3D GPUs, particularly embedded and mobile class GPUs, they are not so common and so are synthesised, there.
+## Trigonometric subsets
 
-Although they can be synthesised using Ztrigpi and Ztrignpi, there is, once again, both a performance penalty as well as an accuracy penalty towards the limits, which for IEEE754 compliance is unacceptable, yet is acceptable for 3D.
+### Ztrigpi vs Ztrignpi
 
-Therefore they are their own subset extension.
+* **Ztrigpi**: SINPI COSPI TANPI
+* **Ztrignpi**: SIN COS TAN
 
-## Zfhyp
+Ztrignpi are the basic trigonometric functions through which all others
+could be synthesised, and they are typically the base trigonometrics
+provided by GPUs for 3D, warranting their own subset.
 
-These are the hyperbolic/inverse-hyperbolic finctions: sinh, cosh, tanh, asinh, acosh, atanh. Their use in 3D is limited.
+In the case of the Ztrigpi subset, these are commonly used in for loops
+with a power of two number of subdivisions, and the cost of multiplying
+by PI inside each loop (or cumulative addition, resulting in cumulative
+errors) is not acceptable.
 
-They can all be synthesised using LOG, SQRT and so on, so depend on Zftrans.
-However, once again, at the limits of the range, IEEE754 compliance becomes impossible, and thus a hardware implementation may be required.
+In for example CORDIC the multiplication by PI may be moved outside of
+the hardware algorithm as a loop invariant, with no power or area penalty.
 
-HPC and high-end GPUs are likely markets for these.
+Again, therefore, if SINPI (etc.) were excluded, programmers would be penalised by being forced to divide by PI in some circumstances. Likewise if SIN were excluded, programmers would be penaslised by being forced to *multiply* by PI in some circumstances.
 
-## ZftransAdv
+Thus again, a slightly different application of the same general argument applies to give Ztrignpi and
+Ztrigpi as subsets.  3D GPUs will almost certainly provide both.
 
-Cube-root, Power, Root: these are simply much more complex to implement in hardware, and typically will only be put into HPC applications.
+### Zarctrigpi and Zarctrignpi
 
-Root is included as well as Power because at the extreme ranges one is more accurate than the other.
+* **Zarctrigpi**: ATAN2PI ASINPI ACOSPI
+* **Zarctrignpi**: ATAN2 ACOS ASIN
 
-* **Zfrsqrt**: Reciprocal square-root.
+These are extra trigonometric functions that are useful in some
+applications, but even for 3D GPUs, particularly embedded and mobile class
+GPUs, they are not so common and so are typically synthesised, there.
+
+Although they can be synthesised using Ztrigpi and Ztrignpi, there is,
+once again, both a performance penalty as well as an accuracy penalty
+towards the limits, which for IEEE754 compliance is unacceptable, yet
+is acceptable for 3D.
+
+Therefore they are their own subset extensions.
 
 # Synthesis, Pseudo-code ops and macro-ops
 
@@ -533,15 +634,20 @@ high-performance or correctly-rounding):
 
     ASINH( x ) = ln( x + SQRT(x**2+1))
 
-# Reciprocal
+# Evaluation and commentary
+
+This section will move later to discussion.
+
+## Reciprocal
 
-Used to be an alias. Some implementors may wish to implement divide as y times recip(x).
+Used to be an alias. Some implementors may wish to implement divide as
+y times recip(x).
 
 Others may have shared hardware for recip and divide, others may not.
 
 To avoid penalising one implementor over another, recip stays.
 
-# To evaluate: should LOG be replaced with LOG1P (and EXP with EXPM1)?
+## To evaluate: should LOG be replaced with LOG1P (and EXP with EXPM1)?
 
 RISC principle says "exclude LOG because it's covered by LOGP1 plus an ADD".
 Research needed to ensure that implementors are not compromised by such
@@ -553,7 +659,7 @@ a decision
 
 > ok, they stay in as real opcodes, then.
 
-# ATAN / ATAN2 commentary
+## ATAN / ATAN2 commentary
 
 Discussion starts here:
 <http://lists.libre-riscv.org/pipermail/libre-riscv-dev/2019-August/002470.html>
@@ -613,11 +719,18 @@ The reason is that whilst a microcode-like GPU-centric platform would do ATAN2 i
 
 (that is the hypothesis, to be evaluated for correctness. feedback requested).
 
-Thie because we cannot compromise or prioritise one platfrom's speed/accuracy over another. That is not reasonable or desirable, to penalise one implementor over another.
+This because we cannot compromise or prioritise one platfrom's
+speed/accuracy over another. That is not reasonable or desirable, to
+penalise one implementor over another.
 
-Thus, all implementors, to keep interoperability, must both have both opcodes and may choose, at the architectural and routing level, which one to implement in terms of the other.
+Thus, all implementors, to keep interoperability, must both have both
+opcodes and may choose, at the architectural and routing level, which
+one to implement in terms of the other.
 
-Allowing implementors to choose to add either opcode and let traps sort it out leaves an uncertainty in the software developer's mind: they cannot trust the hardware, available from many vendors, to be performant right across the board.
+Allowing implementors to choose to add either opcode and let traps sort it
+out leaves an uncertainty in the software developer's mind: they cannot
+trust the hardware, available from many vendors, to be performant right
+across the board.
 
 Standards are a pig.