crackNum 3.23 → 3.24
raw patch · 5 files changed
+173/−10 lines, 5 files
Files
- CHANGES.md +13/−1
- LICENSE +1/−1
- README.md +157/−7
- crackNum.cabal +1/−1
- src/CrackNum/Main.hs +1/−0
CHANGES.md view
@@ -1,7 +1,19 @@ * Hackage: <http://hackage.haskell.org/package/crackNum> * GitHub: <http://github.com/LeventErkok/crackNum/> -* Latest Hackage released version: 3.23, 2026-08-17+* Latest Hackage released version: 3.24, 2026-08-17++### Version 3.24, 2026-08-17++ * Add a quad-precision example to the help output. `-fqp` has always been+ accepted, but `--help` never mentioned it, so the only way to find out it+ existed was to trip over the error message for a bad `-f` argument.++ * Bring the README up to date: document the installation steps (including the+ z3 requirement), add a table of all supported formats, list the rounding+ modes, and add worked examples for the FP8, FP4, TF32, and unsigned-word+ formats. A couple of the existing sample outputs had drifted from what the+ tool actually prints, and are now regenerated. ### Version 3.23, 2026-08-17
LICENSE view
@@ -1,6 +1,6 @@ crackNum: Cracking various Floating/Integer values -Copyright (c) 2015-2021, Levent Erkok (erkokl@gmail.com)+Copyright (c) 2015-2026, Levent Erkok (erkokl@gmail.com) All rights reserved. Redistribution and use in source and binary forms, with or without
README.md view
@@ -2,6 +2,51 @@ On Hackage: http://hackage.haskell.org/package/crackNum +`crackNum` shows you exactly how a number is laid out in memory: the bit+pattern, its fields, the classification, and the value in binary, octal,+decimal, and hex. It works in both directions:++ - **Encoding**: give it a value (`2.5`, `-2.3e6`, `NaN`, `0x3.2p5`), and it shows+ the bit-pattern it turns into, together with the rounding that took place.+ - **Decoding**: give it a bit-pattern (`0xdeadbeef`, `0b0110`, `32'hfdc71fc6`),+ and it shows the value it stands for.++### Installation++```+$ cabal install crackNum+```++`crackNum` uses [SBV](http://hackage.haskell.org/package/sbv) and delegates the+actual floating-point reasoning to an SMT solver, so you also need+[z3](https://github.com/Z3Prover/z3) on your `PATH`.++### Supported formats++| Flag | Format | Exponent | Significand (incl. implicit bit) |+|-----------|-------------------------------------|---------:|---------------------------------:|+| `-fhp` | Half precision (IEEE-754 binary16) | 5 | 11 |+| `-fbp` | Brain float (bfloat16) | 8 | 8 |+| `-ftf32` | TensorFloat-32 | 8 | 11 |+| `-fsp` | Single precision (binary32) | 8 | 24 |+| `-fdp` | Double precision (binary64) | 11 | 53 |+| `-fqp` | Quad precision (binary128) | 15 | 113 |+| `-fe5m2` | FP8, IEEE-754 style | 5 | 3 |+| `-fe4m3` | FP8, alternate (no infinities) | 4 | 4 |+| `-ffp4` | FP4 (E2M1) | 2 | 2 |+| `-fa+b` | Arbitrary IEEE-754 float | a | b |++Integers come in two flavors: `-iN` for a signed `N`-bit 2's complement integer,+and `-wN` for an unsigned `N`-bit word. Both `N` and the arbitrary float sizes+can be as large as you like, within machine-word limits.++Note that TF32 is cracked as its 19 architectural bits; hardware typically+carries these in a 32-bit container with the remaining bits unused.++Rounding mode is selected with `-r`, and defaults to `RNE` if not given:+`RNE` (nearest, ties to even), `RNA` (nearest, ties away), `RTP` (towards+positive infinity), `RTN` (towards negative infinity), and `RTZ` (towards zero).+ ### Example: Encode a decimal number as a single-precision IEEE754 number ``` $ crackNum -fsp -- -2.3e6@@ -24,6 +69,28 @@ Note: Conversion from "-2.3e6" was exact. No rounding happened. ``` +### Example: Encode with a different rounding mode+```+$ crackNum -fsp 1.3 -rRTZ+Satisfiable. Model:+ ENCODED = 1.3 :: Float+ 3 2 1 0+ 1 09876543 21098765432109876543210+ S ---E8--- ----------S23----------+ Binary layout: 0 01111111 01001100110011001100110+ Hex layout: 3FA6 6666+ Precision: Single+ Sign: Positive+ Exponent: 0 (Stored: 127, Bias: 127)+ Classification: FP_NORMAL+ Binary: 0b1.0100110011001100110011+ Octal: 0o1.23146314+ Decimal: 1.3+ Hex: 0x1.4ccccc+ Rounding mode: RTZ: Round towards zero.+ Note: Conversion from "1.3" was not faithful. Status: Inexact.+```+ ### Example: Decode a single-precision IEEE754 number float from memory-layout ``` $ crackNum -fsp 0xfc00 abc1@@ -41,10 +108,69 @@ Binary: -0b1.00000001010101111000001p+121 Octal: -0o2.00527404p+120 Decimal: -2.6723903e36- Hex: -0x2.02AF04p+120-$ crackNum -fdp 0xfc00 abc1 7F80 0001+ Hex: -0x2.02af04p+120 ``` +### Example: Encode as an E4M3 FP8 float+```+$ crackNum -fe4m3 2.5+Satisfiable. Model:+ ENCODED = 2.5 :: E4M3+ 7 6543 210+ S -E4- S3-+ Binary layout: 0 1000 010+ Hex layout: 42+ Precision: 4 exponent bits, 3 significand bits+ Sign: Positive+ Exponent: 1 (Stored: 8, Bias: 7)+ Classification: FP_NORMAL+ Binary: 0b1.01p1+ Octal: 0o2.4+ Decimal: 2.5+ Hex: 0x2.8+```++### Example: Decode an FP4 (E2M1) float+```+$ crackNum -ffp4 0b0111+Satisfiable. Model:+ DECODED = 6.0 :: FP4+ 3 21 0+ S E2 S+ Binary layout: 0 11 1+ Hex layout: 7+ Precision: 2 exponent bits, 1 significand bit+ Sign: Positive+ Exponent: 2 (Stored: 3, Bias: 1)+ Classification: FP_NORMAL+ Binary: 0b1.1p+2+ Octal: 0o6+ Decimal: 6.0+ Hex: 0x6+```++### Example: Encode a TensorFloat-32 number+```+$ crackNum -ftf32 2.5+Satisfiable. Model:+ ENCODED = 2.5 :: FloatingPoint 8 11+ 1 0+ 8 76543210 9876543210+ S ---E8--- ---S10----+ Binary layout: 0 10000000 0100000000+ Hex layout: 2 0100+ Precision: 8 exponent bits, 10 significand bits+ Sign: Positive+ Exponent: 1 (Stored: 128, Bias: 127)+ Classification: FP_NORMAL+ Binary: 0b1.01p1+ Octal: 0o2.4+ Decimal: 2.5+ Hex: 0x2.8+ Rounding mode: RNE: Round nearest ties to even.+ Note: Conversion from "2.5" was exact. No rounding happened.+```+ ### Example: Decode a custom (2+3) float from memory-layout ``` $ crackNum -f2+3 0b10011@@ -80,6 +206,21 @@ Hex: 0xc ``` +### Example: Decode a 4-bit unsigned word+```+$ crackNum -w4 0xE+Satisfiable. Model:+ DECODED = 14 :: WordN 4+ 3210+ Binary layout: 1110+ Hex layout: E+ Type: Unsigned 4-bit word+ Binary: 0b1110+ Octal: 0o16+ Decimal: 14+ Hex: 0xe+```+ ### Example: Decode two half-precision floats in two lanes ``` $ crackNum -l2 -fhp 32\'hfdc71fc6@@ -99,7 +240,7 @@ Note: Representation for NaN's is not unique == Lane 0 ============================================================ Satisfiable. Model:- DECODED = 0.0075912 :: FloatingPoint 5 11+ DECODED = 0.0075912476 :: FloatingPoint 5 11 1 0 5 43210 9876543210 S -E5-- ---S10----@@ -111,10 +252,13 @@ Classification: FP_NORMAL Binary: 0b1.111100011p-8 Octal: 0o3.706p-9- Decimal: 0.0075912+ Decimal: 0.0075912476 Hex: 0x1.f18p-8 ``` +If you use the verilog notation (`N'h...`), the number of lanes is inferred from+the width, so `-l` is optional in that case.+ ### Graphical interface (optional) Optionally, crackNum comes with a GUI: pick a format on the left, type a value,@@ -125,12 +269,14 @@  -**macOS** — a native Swift/AppKit app (`GUI/swiftGUI/`). Building requires the-Swift compiler that comes with the Xcode Command Line Tools+**macOS** — a native Swift/AppKit app (`GUI/swiftGUI/`). It is not part of the+Hackage package, so you need a clone of the repository to build it. You also+need the Swift compiler that comes with the Xcode Command Line Tools (`xcode-select --install`): ```-$ cd GUI/swiftGUI+$ git clone https://github.com/LeventErkok/crackNum.git+$ cd crackNum/GUI/swiftGUI $ make install # builds CrackNum.app and copies it into /Applications ``` @@ -155,6 +301,9 @@ $ crackNum --gui 0xdeadbeef -- open it pre-filled with a value to decode ``` +Bad flags are diagnosed before the GUI comes up: `crackNum -ft32 4 --gui`+reports the unknown format instead of opening an empty window.+ ### Usage info ``` Usage: crackNum value OR binary/hex-pattern@@ -177,6 +326,7 @@ crackNum -fbp 2.5 -- encode as a brain-precision float crackNum -ftf32 2.5 -- encode as a TensorFloat-32 float crackNum -fdp 2.5 -- encode as a double-precision float+ crackNum -fqp 2.5 -- encode as a quad-precision float crackNum -fe4m3 2.5 -- encode as an E4M3 FP8 float crackNum -fe5m2 2.5 -- encode as an E5M2 FP8 float crackNum -ffp4 2.5 -- encode as an FP4 (E2M1) float
crackNum.cabal view
@@ -1,6 +1,6 @@ Cabal-version : 2.2 Name : crackNum-Version : 3.23+Version : 3.24 Synopsis : Crack various integer and floating-point data formats Description : Crack IEEE-754 and other float formats and arbitrary sized words and integers, showing the layout. .
src/CrackNum/Main.hs view
@@ -250,6 +250,7 @@ , " " ++ pn ++ " -fbp 2.5 -- encode as a brain-precision float" , " " ++ pn ++ " -ftf32 2.5 -- encode as a TensorFloat-32 float" , " " ++ pn ++ " -fdp 2.5 -- encode as a double-precision float"+ , " " ++ pn ++ " -fqp 2.5 -- encode as a quad-precision float" , " " ++ pn ++ " -fe4m3 2.5 -- encode as an E4M3 FP8 float" , " " ++ pn ++ " -fe5m2 2.5 -- encode as an E5M2 FP8 float" , " " ++ pn ++ " -ffp4 2.5 -- encode as an FP4 (E2M1) float"