From d9be3278f5d0c93b59033286ac5e2d30f5dff6bc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ond=C5=99ej=20Hru=C5=A1ka?= <ondra@ondrovo.com>
Date: Tue, 20 Oct 2020 00:53:43 +0200
Subject: [PATCH] docs for float

---
 README.md | 127 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 126 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index fc2dcc7..64debf8 100644
--- a/README.md
+++ b/README.md
@@ -169,7 +169,8 @@ This document uses the following notation for arguments:
 - `NUM` - literal values
    - unsigned `123`
    - signed `-123`
-   - float `-45.6789`
+   - float `-45.6789`. For now, you must use literals with a period to enter float literals, integers will not be converted to 
+     float when used in floating point instructions!
    - hex `0xabcd`, `#abcd`
    - binary `0b0101`
    - character `'a'`, `'🐁'`. Supports unicode and C-style escapes. Use `\\` for a literal backslash.
@@ -428,6 +429,17 @@ Many instructions have two forms:
 (mod Wr Rd Rd'divider)
 (mod RW Rd'divider)
 
+; Get abs value
+(abs Wr Rd)
+(abs RW)
+
+; Get signum
+(sgn Wr Rd)
+(sgn RW)
+
+; Power - e.g. (pow r0 2 8) is 256
+(pow Wr Rd Rd'pow)
+
 ; Swap the 32-bit halves of a value
 ; 0x01234567_89abcdef -> 0x89abcdef_01234567
 (sw32 Wr Rd)
@@ -515,6 +527,119 @@ Many instructions have two forms:
 (del @Rd)
 ```
 
+### Floating Point Arithmetics
+
+The arithmetics module has support for floating point values. There are some gotchas though:
+
+- Floating point is simply the binary representation of it in an unsigned integer register.
+  I thought of adding special float registers for this, but then you can't easily pass floats
+  to subroutines, push them on a stack etc. Not worth it.
+- To enter a float literal, always use the notation with a decimal point. It should support minus and scientific notation too.
+- There are special instructions dedicated to working with floats. The regular integer instructions 
+  will happily work with their binary forms, but that's absolutely not what you want.
+
+```
+(itf r0 1.0)  ; NO!!!                 it is already float, what are you doing
+(ld r0 1.0)   ; okay
+(itf r0 1)    ; also okay
+
+(fmul r0 2)   ; NO!!!!!!!!!!!!!       2 is not float
+(mul r0 2.0)  ; ALSO NO!!!!!!!!!!!!!  mul is not a float instruction!
+(fmul r0 2.0) ; good
+```
+
+You have to be a bit careful, that's all.
+
+Here's an abridged summary of the floating point submodule:
+
+(most of these support the shorthand version too - `RW` in place of `Wr Rd`)
+
+```
+; IntToFloat
+(itf Wr Rd)
+; FloatToInt (round)
+(fti Wr Rd)
+; FloatToInt (ceil)
+(ftic Wr Rd)
+; FloatToInt (floor)
+(ftif Wr Rd)
+
+; FloatTest - nan->invalid, infinities->overflow, positive, negative, zero
+(ftst Rd)
+; FloatCompare
+(fcmp Rd Rd)
+; FloatRangeTest
+(fcmpr Rd Rd'min Rd'max)
+
+; FloatRng
+(frng Wr Rd'min Rd'max)
+
+; --- Basic float arith ---
+
+; FloatAdd
+(fadd Wr Rd Rd)
+; FloatSub
+(fsub Wr Rd Rd)
+; FloatMul
+(fmul Wr Rd Rd)
+; FloatPow
+(fpow Wr Rd Rd'pow)
+; FloatRoot
+(froot Wr Rd Rd'root)
+; FloatHyp
+(fhyp Wr Rd Rd)
+; FloatDiv
+(fdiv Wr Wr'rem Rd'a Rd'div)
+; FloatMod
+(fmod Wr Rd'a Rd'div)
+; FloatAbs
+(fabs Wr Rd)
+; FloatSgn
+(fsgn Wr Rd)
+
+; --- Basic trig ---
+
+; FloatSin
+(fsin Wr Rd)
+; FloatAsin
+(fasin Wr Rd)
+; FloatCos
+(fcos Wr Rd)
+; FloatAcos
+(facos Wr Rd)
+; FloatTan
+(ftan Wr Rd)
+; FloatAtan
+(fatan Wr Rd)
+; FloatAtan2
+(fatan2 Wr Rd'y Rd'x)
+; FloatCot
+(fcot Wr Rd)
+; FloatAcot
+(facot Wr Rd)
+
+; --- Hyperbolic trig ---
+
+; FloatHypSin
+(fsinh Wr Rd)
+; FloatHypAsin
+(fasinh Wr Rd)
+; FloatHypCos
+(fcosh Wr Rd)
+; FloatHypAcos
+(facosh Wr Rd)
+; FloatHypTan
+(ftanh Wr Rd)
+; FloatHypAtan
+(fatanh Wr Rd)
+; FloatHypCot
+(fcoth Wr Rd)
+; FloatHypAcot
+(facoth Wr Rd)
+```
+
+Wow, thats a lot. I didn't test many of these yet. There may be bugs.
+
 ## Buffers Module
 
 This module defines dynamic size integer buffers.