crackNum 4.0 → 4.1
raw patch · 3 files changed
+70/−329 lines, 3 files
Files
- CHANGES.md +36/−1
- README.md +30/−324
- crackNum.cabal +4/−4
CHANGES.md view
@@ -1,7 +1,42 @@ * Hackage: <http://hackage.haskell.org/package/crackNum> * GitHub: <http://github.com/LeventErkok/crackNum/> -* Latest Hackage released version: 4.0, 2026-08-24+* Latest Hackage released version: 4.1, 2026-08-25++### Version 4.1, 2026-08-25++ * Documentation only; no functional changes.++ * Substantially shortened the README. It had grown to fifteen worked examples,+ all showing the same output fields with different numbers in them, plus a copy+ of the per-platform install commands that already ship inside every release+ bundle. The examples are down to four -- an encode with a non-default rounding+ mode, a decode, an E8M0 encode, and a two-lane decode -- and the install+ section now points at the `README.txt` in the bundle rather than repeating it,+ so those steps have a single home and cannot drift.++ * The "Supported formats" section is now just the flag table. The per-format+ prose that followed it -- the FP4 (E0M3) and E8M0 explanations, the integer+ flavors, the TF32 bit-count note -- is gone; the first three were already+ stated in the `--help` output reproduced further down.++ * Downloading a prebuilt binary is now the first thing the README talks about,+ under its own heading, instead of being a sub-section whose point was hidden in+ a parenthetical. Building from Hackage is presented as the alternative, and+ each platform bullet links to the latest release.++ * Replaced the README's markdown tables with lists. Hackage renders the README+ outside the `#description` pane, and its stylesheet only borders tables inside+ that pane, so a table there comes out unstyled and the columns run together.++ * Dropped the per-platform GUI build instructions from the README; each GUI's+ own directory documents itself. `GUI/winGUI/README.md` is new; `GUI/swiftGUI/`+ and `GUI/tclGUI/` already had one. The note about needing `wish` on Linux went+ with it -- when `wish` is missing, the binary already prints the `apt`/`dnf`/`nix`+ command to install it.++ * Reworded the cabal Description's pointer to the releases page: it now leads+ with not needing a Haskell toolchain, rather than with the word "releases". ### Version 4.0, 2026-08-24
README.md view
@@ -1,7 +1,5 @@ ## Decode/Encode Integers, Words, and IEEE754 and other float formats -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:@@ -11,79 +9,39 @@ - **Decoding**: give it a bit-pattern (`0xdeadbeef`, `0b0110`, `32'hfdc71fc6`), and it shows the value it stands for. -### Installation--#### Prebuilt binaries (nothing to build, no Haskell toolchain)--The easiest way to get crackNum is from the-[Releases page](https://github.com/LeventErkok/crackNum/releases). Each bundle is-self-contained: the `crackNum` executable, a copy of `z3`, the graphical interface,-a LICENSE, and a README repeating the steps below.--| Platform | Asset | Notes |-| --- | --- | --- |-| Linux (x86_64) | `crackNum-<version>-linux-x86_64.tar.gz` | Statically linked, so there is no glibc or distribution requirement: it runs as-is on any x86_64 Linux, old or new. |-| macOS (Apple Silicon) | `crackNum-<version>-macos-arm64.tar.gz` | Includes `CrackNum.app`. Ad-hoc signed rather than notarized, so clear the quarantine flag as shown below. |-| Windows (x86_64) | `crackNum-<version>-windows-x86_64.zip` | Includes `CrackNumGUI.exe`. Unsigned, so SmartScreen warns on first run; see below. |--Unpack the bundle anywhere you like, then put the files somewhere on your `PATH`.-`z3` has to go there too, since crackNum shells out to it for every operation.--**Linux** — all three files, the GUI script included:--```-$ tar xzf crackNum-<version>-linux-x86_64.tar.gz-$ cd crackNum-<version>-linux-x86_64-$ mkdir -p ~/bin && cp crackNum z3 crackNum.tcl ~/bin/-$ export PATH=$HOME/bin:$PATH # put this in your shell's startup file-```--The GUI is a Tcl/Tk script, so unlike the two binaries it needs something from your-system: `wish` on your `PATH`. Install it with `sudo apt install tk` (Debian/Ubuntu),-`sudo dnf install tk` (RHEL/Fedora), or `nix profile install nixpkgs#tk`.--**macOS** — clear the quarantine flag first, since these are ad-hoc signed rather-than notarized and nothing will run before you do:--```-$ tar xzf crackNum-<version>-macos-arm64.tar.gz-$ cd crackNum-<version>-macos-arm64-$ xattr -dr com.apple.quarantine crackNum z3 CrackNum.app-$ mkdir -p ~/bin && cp crackNum z3 ~/bin/-$ cp -R CrackNum.app /Applications/-$ export PATH=$HOME/bin:$PATH # put this in your login shell's startup file-```+### Download crackNum -**Windows** — keep the files together in one folder; `crackNum.exe` looks beside-itself for the GUI and the solver before consulting your `PATH`:+**→ [Ready-to-run bundles for Linux, macOS, and Windows](https://github.com/LeventErkok/crackNum/releases)** -```-> Expand-Archive crackNum-<version>-windows-x86_64.zip -DestinationPath .-> cd crackNum-<version>-windows-x86_64-> New-Item -ItemType Directory -Force $env:USERPROFILE\bin-> Copy-Item * $env:USERPROFILE\bin-```+Nothing to build, no Haskell toolchain. Each bundle carries the `crackNum`+executable, a copy of `z3`, the GUI, a LICENSE, and a `README.txt` with the+install steps for that platform. -Then add that folder to your `PATH` and open a new terminal, since a `PATH` change-does not reach terminals that are already running. The binaries are not code-signed,-so the first run may raise a SmartScreen prompt; choose "More info" then "Run-anyway", or tick "Unblock" in the .zip's Properties before extracting.+ - **Linux (x86_64)** — [`crackNum-<version>-linux-x86_64.tar.gz`](https://github.com/LeventErkok/crackNum/releases/latest).+ Statically linked, so it runs as-is on any x86_64 Linux, old or new.+ - **macOS (Apple Silicon)** — [`crackNum-<version>-macos-arm64.tar.gz`](https://github.com/LeventErkok/crackNum/releases/latest).+ Includes `CrackNum.app`. Ad-hoc signed, so clear the quarantine flag first.+ - **Windows (x86_64)** — [`crackNum-<version>-windows-x86_64.zip`](https://github.com/LeventErkok/crackNum/releases/latest).+ Includes `CrackNumGUI.exe`. Unsigned, so SmartScreen warns on first run. -Any of the three, check with:+Unpack it, put the files on your `PATH` — `z3` included, since crackNum shells+out to it for every operation — and check with: ``` $ crackNum -fsp 3.5 $ crackNum --gui ``` -#### From Hackage+### Building from source +crackNum is on [Hackage](http://hackage.haskell.org/package/crackNum):+ ``` $ cabal install crackNum ``` -Installed this way you also need [z3](https://github.com/Z3Prover/z3) on your-`PATH`: crackNum delegates the floating-point reasoning to it, via+This way you also need [z3](https://github.com/Z3Prover/z3) on your `PATH`:+crackNum delegates the floating-point reasoning to it, via [SBV](http://hackage.haskell.org/package/sbv). ### Supported formats@@ -107,51 +65,11 @@ Significand sizes include the implicit bit. -FP4 (E0M3) is the odd one out: with no exponent bits at all it is really a 4-bit-sign-magnitude *integer*, holding a sign and a 3-bit magnitude. It covers -7 to 7,-with both a positive and a negative zero, and has neither NaN nor Inf.--E8M0 is the odd one out in the other direction: it is the shared scale of the OCP-Microscaling (MX) formats, and is *all* exponent. With no sign bit and no-significand, every value it holds is a power of two, from 2^-127 to 2^127. It has-no zero and no subnormals -- an all-zero encoding means 2^-127, not zero -- and no-infinities; `0xFF` is its one and only NaN. Negative inputs are rejected, and-values outside its range saturate to the nearest end-point.--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-Satisfiable. Model:- ENCODED = -2300000.0 :: Float- 3 2 1 0- 1 09876543 21098765432109876543210- S ---E8--- ----------S23----------- Binary layout: 1 10010100 00011000110000110000000- Hex layout: CA0C 6180- Precision: Single- Sign: Negative- Exponent: 21 (Stored: 148, Bias: 127)- Classification: FP_NORMAL- Binary: -0b1.0001100011000011p+21- Octal: -0o1.061414p+21- Decimal: -2300000.0- Hex: -0x2.3186p+20- Rounding mode: RNE: Round nearest ties to even.- Note: Conversion from "-2.3e6" was exact. No rounding happened.-```--### Example: Encode with a different rounding mode+### Example: Encode a single-precision float, rounding towards zero ``` $ crackNum -fsp 1.3 -rRTZ Satisfiable. Model:@@ -173,7 +91,7 @@ Note: Conversion from "1.3" was not faithful. Status: Inexact. ``` -### Example: Decode a single-precision IEEE754 number float from memory-layout+### Example: Decode a single-precision bit-pattern ``` $ crackNum -fsp 0xfc00 abc1 Satisfiable. Model:@@ -193,99 +111,6 @@ 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: Decode an FP4 (E0M3) sign-magnitude integer-```-$ crackNum -ffp4e0m3 0b1101-Satisfiable. Model:- DECODED = -5 :: FP4E0M3- 3 210- S -M-- Binary layout: 1 101- Hex layout: D- Type: 4-bit sign-magnitude integer- Sign: Negative- Binary: -0b101- Octal: -0o5- Decimal: -5- Hex: -0x5-```--### Example: Encode an FP4 (E0M3) sign-magnitude integer-```-$ crackNum -ffp4e0m3 -- -5-Satisfiable. Model:- ENCODED = -5 :: FP4E0M3- 3 210- S -M-- Binary layout: 1 101- Hex layout: D- Type: 4-bit sign-magnitude integer- Sign: Negative- Binary: -0b101- Octal: -0o5- Decimal: -5- Hex: -0x5- Rounding mode: RNE: Round nearest ties to even.- Note: Conversion from "-5" was exact. No rounding happened.-```--### Example: Decode an E8M0 MX scale-```-$ crackNum -fe8m0 0xFE-Satisfiable. Model:- DECODED = 1.7014118346046923e38 :: E8M0- 76543210- ---E8---- Binary layout: 11111110- Hex layout: FE- Precision: 8 exponent bits, no significand- Sign: Positive (always)- Exponent: 127 (Stored: 254, Bias: 127)- Classification: FP_NORMAL- Binary: 0b1p+127- Octal: 0o2p+126- Decimal: 1.7014118346046923e38- Hex: 0x8p+124-```- ### Example: Encode an E8M0 MX scale Only powers of two are representable, so everything else rounds according to `-r`: ```@@ -308,79 +133,7 @@ Note: Original value of 10.0 was rounded to 8.0. ``` -### 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-Satisfiable. Model:- DECODED = -0.75 :: FloatingPoint 2 3- 4 32 10- S E2 S2- Binary layout: 1 00 11- Hex layout: 13- Precision: 2 exponent bits, 2 significand bits- Sign: Negative- Exponent: 0 (Subnormal, with fixed exponent value. Stored: 0, Bias: 1)- Classification: FP_SUBNORMAL- Binary: -0b1.1p-1- Octal: -0o6p-3- Decimal: -0.75- Hex: -0xcp-4-```--### Example: Encode an integer as a 7-bit signed word-```-$ crackNum -i7 12-Satisfiable. Model:- ENCODED = 12 :: IntN 7- 654 3210- Binary layout: 000 1100- Hex layout: 0C- Type: Signed 7-bit 2's complement integer- Sign: Positive- Binary: 0b1100- Octal: 0o14- Decimal: 12- 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+### Example: Decode two half-precision lanes ``` $ crackNum -l2 -fhp 32\'hfdc71fc6 == Lane 1 ============================================================@@ -415,60 +168,17 @@ 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,-and see the encoding/decoding in detail. It is entirely optional — crackNum is-fully functional as a command-line tool without it. The GUI is just a thin-front-end that calls the `crackNum` binary underneath, so it supports exactly-the same formats.--If you installed from a [release bundle](#prebuilt-binaries-nothing-to-build-no-haskell-toolchain)-the GUI is already in it, and there is nothing to build on any of the three. The rest-of this section is for installing from Hackage or from a source checkout.--**macOS** — a native Swift/AppKit app (`GUI/swiftGUI/`). It is not part of the-Hackage package, so building it yourself needs a clone of the repository and the-Swift compiler that comes with the Xcode Command Line Tools-(`xcode-select --install`):--```-$ git clone https://github.com/LeventErkok/crackNum.git-$ cd crackNum/GUI/swiftGUI-$ make install # builds CrackNum.app and copies it into /Applications-```--**Linux** — a Tcl/Tk script (`GUI/tclGUI/crackNum.tcl`). The script ships with the-package and is installed alongside the binary, so there is nothing to build; you-only need `wish` (Tk 8.6+):--```-$ nix profile install nixpkgs#tk # or: sudo apt install tk / sudo dnf install tk-```--Then `crackNum --gui` just works. If you want to run a modified copy of the-script, either put it on your PATH as `crackNum.tcl`, or point at it directly-with `CRACKNUM_TCL=/path/to/crackNum.tcl`.+With verilog notation (`N'h...`) the lane count is inferred from the width, so+`-l` is optional. -**Windows** — a native WinForms app (`GUI/winGUI/`). It targets .NET Framework 4.8,-which ships as part of Windows 10 and 11, so the built executable needs no runtime-install. Like the macOS app it is not part of the Hackage package; building it-needs a clone and the .NET SDK:+### Graphical interface -```-> git clone https://github.com/LeventErkok/crackNum.git-> cd crackNum\GUI\winGUI-> dotnet build -c Release-```+An optional GUI: pick a format on the left, type a value, see the result. It is a+thin front-end over the `crackNum` binary, so it supports exactly the same formats. -Put the resulting `CrackNumGUI.exe` next to `crackNum.exe`, or point at it with-`CRACKNUM_GUI=C:\path\to\CrackNumGUI.exe`.+ -On all three platforms, launch the GUI from the command line via the `--gui` option,-which forwards any format/rounding flags and value to the app:+Launch it with `--gui`, which forwards any flags and value to the app: ``` $ crackNum --gui -- open the graphical interface@@ -476,9 +186,6 @@ $ 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@@ -565,6 +272,5 @@ - If you use verilog input format, then we will infer the number of lanes unless you provide it. ``` -VIM users: You can use the http://github.com/LeventErkok/crackNum/blob/master/crackNum.vim file to-use CrackNum directly from VIM. Simply locate your cursor on the text to crack, and use the-command `:CrackNum options`.+VIM users: [crackNum.vim](http://github.com/LeventErkok/crackNum/blob/master/crackNum.vim)+cracks the text under the cursor with `:CrackNum options`.
crackNum.cabal view
@@ -1,15 +1,15 @@ Cabal-version : 2.2 Name : crackNum-Version : 4.0+Version : 4.1 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. Along with a command-line interface on any platform, native MacOS and Windows GUIs and a Tcl-based Linux GUI are available as well: . <<https://raw.githubusercontent.com/LeventErkok/crackNum/master/crackNumGUI.png>> .- For details, please see: <http://github.com/LeventErkok/crackNum/>. See the- <https://github.com/LeventErkok/crackNum/releases releases page>- for binary releases for Mac, Linux, and Windows.+ For details, please see: <http://github.com/LeventErkok/crackNum/>.+ .+ You do not need a Haskell toolchain to use crackNum: the <https://github.com/LeventErkok/crackNum/releases releases page> has ready-to-run bundles for Mac, Linux, and Windows. License : BSD-3-Clause License-file : LICENSE Author : Levent Erkok