crackNum
Crack various integer and floating-point data formats
http://github.com/LeventErkok/CrackNum
LTS Haskell 22.33: | 3.4 |
Stackage Nightly 2024-09-07: | 3.12 |
Latest on Hackage: | 3.12 |
crackNum-3.12@sha256:5ca2a3903384a9d55beec37ca6926bd41b0c7cf3305efae6b82c7f9f400698d5,1249
Module documentation for 3.12
There are no documented modules for this package.
Decode/Encode Integers, Words, and IEE754 Floats
On Hackage: http://hackage.haskell.org/package/crackNum
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: Decode a single-precision IEEE754 number float from memory-layout
$ crackNum -fsp 0xfc00 abc1
Satisfiable. Model:
DECODED = -2.6723903e36 :: Float
3 2 1 0
1 09876543 21098765432109876543210
S ---E8--- ----------S23----------
Binary layout: 1 11111000 00000001010101111000001
Hex layout: FC00 ABC1
Precision: Single
Sign: Negative
Exponent: 121 (Stored: 248, Bias: 127)
Classification: FP_NORMAL
Binary: -0b1.00000001010101111000001p+121
Octal: -0o2.00527404p+120
Decimal: -2.6723903e36
Hex: -0x2.02AF04p+120
$ crackNum -fdp 0xfc00 abc1 7F80 0001
Example: Decode a custom (2+3) IEEE754 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 two half-precision floats in two lanes
$ crackNum -l2 -fhp 32\'hfdc71fc6
== Lane 1 ============================================================
Satisfiable. Model:
DECODED = NaN :: FloatingPoint 5 11
1 0
5 43210 9876543210
S -E5-- ---S10----
Binary layout: 1 11111 0111000111
Hex layout: FDC7
Precision: Half (5 exponent bits, 10 significand bits.)
Sign: Negative
Exponent: 16 (Stored: 31, Bias: 15)
Classification: FP_NAN (Signaling)
Value: NaN
Note: Representation for NaN's is not unique
== Lane 0 ============================================================
Satisfiable. Model:
DECODED = 0.0075912 :: FloatingPoint 5 11
1 0
5 43210 9876543210
S -E5-- ---S10----
Binary layout: 0 00111 1111000110
Hex layout: 1FC6
Precision: Half (5 exponent bits, 10 significand bits.)
Sign: Positive
Exponent: -8 (Stored: 7, Bias: 15)
Classification: FP_NORMAL
Binary: 0b1.111100011p-8
Octal: 0o3.706p-9
Decimal: 0.0075912
Hex: 0x1.f18p-8
Usage info
Usage: crackNum value OR binary/hex-pattern
-i N Signed integer of N-bits
-w N Unsigned integer of N-bits
-f fp Floating point format fp
-r rm Rounding mode to use. If not given, Nearest-ties-to-Even.
-l lanes Number of lanes to decode
-h, -? --help print help, with examples
-v --version print version info
-d --debug debug mode, developers only
Examples:
Encoding:
crackNum -i4 -- -2 -- encode as 4-bit signed integer
crackNum -w4 2 -- encode as 4-bit unsigned integer
crackNum -f3+4 2.5 -- encode as float with 3 bits exponent, 4 bits significand
crackNum -f3+4 2.5 -rRTZ -- encode as above, but use RTZ rounding mode.
crackNum -fbp 2.5 -- encode as a brain-precision float
crackNum -fdp 2.5 -- encode as a double-precision float
crackNum -fe4m3 2.5 -- encode as an E4M3 FP8 float
crackNum -fe5m2 2.5 -- encode as an E5M2 FP8 float
crackNum -fsp 0x3.2p5 -- encode as single-precision from hex-float
Decoding:
crackNum -i4 0b0110 -- decode as 4-bit signed integer, from binary
crackNum -w4 0xE -- decode as 4-bit unsigned integer, from hex
crackNum -f3+4 0b0111001 -- decode as float with 3 bits exponent, 4 bits significand
crackNum -fbp 0x000F -- decode as a brain-precision float
crackNum -fdp 0x8000000000000000 -- decode as a double-precision float
crackNum -fhp 0x8000000000000000 -- decode as a double-precision float
crackNum -l4 -fhp 64\'hbdffaaffdc71fc60 -- decode as half-precision float over 4 lanes using verilog notation
Notes:
- For encoding:
- Use -- to separate your argument if it's a negative number.
- For floats: You can pass in NaN, Inf, -0, -Inf etc as the argument
along with a decimal (2.3, -4.1e5) or hexadecimal float (0x2.4p3)
- For decoding:
- Use hexadecimal (0x) binary (0b), or N'h (verilog) notation as input.
Input must have one of these prefixes.
- You can use _,- or space as a digit to improve readability for the pattern to be decoded
- With -lN parameter, you can decode multiple lanes of data.
- 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
.
Changes
-
Latest Hackage released version: 3.10, 2024-03-01
Version 3.12, 2024-04-05
- Fix hexadecimal float parsing for e4m3
Version 3.11, 2024-04-05
- Allow for encoding of hexadecimal floats
Version 3.10, 2024-03-01
- More relaxed parsing for verilog input format
Version 3.9, 2024-02-23
- Fix verilog input format parsing
Version 3.8, 2024-02-21
-
Add support for FP8 formats, as decribed in: https://arxiv.org/pdf/2209.05433.pdf
- E5M2: Which is essentially a synonym for f5+3
- E4M3: Similar to f4+4, except it does not have infinities and interprets NaN values differently
-
Fix a bug in cracking of arbitrary-sized floats, that yielded wrong values for some NaN cases
Version 3.7, 2024-02-15
-
Support signaling/quiet indication for decoded NaN values.
-
Add support for decoding over multiple lanes. See the -l option.
-
Add support for verilog bit-vector notation, e.g., 128’hXXX. If you use this notation, crackNum will automatically infer the number of lanes to crack based on the width given; unless explicitly specified.
Version 3.6, 2024-01-24
- Be more clear when the provided input isn’t a recognizable float, instead of treating it as NaN implicitly. Thanks to Dmitry Blotsky for pointing out the confusion.
Version 3.5, 2024-01-11
- Resolve compilation issues with GHC 9.8 series
Version 3.4, 2023-04-14
- Fix compilation in previous build
Version 3.3, 2023-04-14
- Allow compilation with newer versions of SBV
Version 3.2, 2021-06-30
- Add an explicit note when conversion is exact.
Version 3.1, 2021-03-29
- Fix readme
Version 3.0, 2021-03-29
- A complete rewrite, much simplified, and supporting arbitrary precision floats. Some of the old features and the library are dropped; so if you rely on the library nature of CrackNum, do not upgrade. For other users who merely use crackNum as an executable, the new version is strongly recommended.
Version 2.4, 2020-09-05
- Changes required to compile cleanly with GHC 8.10.2
Version 2.3, 2018-11-17
- Remove dependency on the ieee754 and reinterpret-cast packages. The goal is to remove any FFI dependencies. We now define and export the required utilities directly in the CrackNum package.
Version 2.2, 2018-09-01
- Instead of data-binary-ieee754, use reinterpret-cast package. According to documents, the former is deprecated.
Version 2.1, 2018-07-20
- Support for vi-editor bindings. See the file “crackNum.vim” in the distribution or in the github repo You can put “so ~/.vim/crackNum.vim” (use the correct path!) and have vi crack numbers directly from inside your editor. Simply locate your cursor on a binary/hex stream of digits and type “:CrackNum”. See the “crackNum.vim” file for binding details.
Version 2.0, 2018-03-17
- Import FloatingHex qualified to avoid GHC 8.4.1 compilation issue
Version 1.9, 2017-01-22
- Minor fix to printing of +/-0
Version 1.8, 2017-01-15
- Bump up FloatingHex dependency to >0.4, this enables proper support for large doubles
Version 1.7, 2017-01-14
- Fix a snafu in reading hexadecimal floats
Version 1.6, 2017-01-14
- Add support for hexadecimal-floats. These now work both in toIEEE option as input, and also when printing the values out. (i.e., numbers of the form 0x1.abp-3, etc.)
Version 1.5, 2016-01-23
- Typo fixes; no functionality changes
Version 1.4, 2016-01-17
- Fix NaN nomenclature: Screaming->Signaling
- Add an example to README.md
Version 1.3, 2015-04-11
- Fix docs, github location
Version 1.2, 2015-04-11
- Fix the constant qnan values for SP/DP
- Add conversions from float/double. Much easier to use.
- Better handling of nan values.
Version 1.1, 2015-04-02
- Clean-up the API, examples etc.
Version 1.0, 2015-04-01
- First implementation. Supports HP/SP/DP and signed/unsigned numbers in 8/16/32/64 bits.