bump version to 0.0.5 update documentation some0.0.5

add some keywords to the crate. this is a first for yaxpeax

3 files changed, 57 insertions, 5 deletions

diff --git a/CHANGELOG b/CHANGELOG
index c9ec754..1a32078 100644
--- a/CHANGELOG
+++ b/CHANGELOG
@@ -1,3 +1,31 @@
+## 0.0.5
+* add thumb/thumb2 decoders
+
+these decoders are considered "mostly correct" and "mostly complete". notably,
+system instructions are less well-tested (particularly `mrs`, `cps`, and
+similar), and the NEON extensions are still unsupported. NEON in particular
+yield `DecodeError::Incomplete`. if you, the user, see `Incomplete`, that is a
+`yaxpeax-arm` error!
+
+`yaxpeax-arm` differs from the ARM manual's assembly syntax in a few ways:
+* `.w` suffixes are best-effort.
+* `addw`/`subw` are written `add.w`/`sub.w` for consistency with other wide instructions.
+* `adr` with added/subtracted offset are shown as `add`/`sub`
+* testing is not as exhaustive as is possible for ARM; errors may yet exist
+
+at this time, if-then instructions (`IT`) are decoded, but the decoder has no
+notion of "in an `IT` block or not", so following conditional instructions are
+not yet conditional.
+
+this all said, for armv4/thumb decoding, the implementation here is probably
+close to correct. for armv6+/thumb2, aside from these notes, the implementation
+here is ... hopefully ... close to correct.
+
+* add clear rules by which `yaxpeax-arm` will be versioned 0.1 or 1.0. (see README)
+
+## 0.0.4
+* bump yaxpeax-arch, no functional change
+
 ## 0.0.3
 `Instruction`, `Opcode`, and `Operand` are now a useful model of decoded
 operations.
diff --git a/Cargo.toml b/Cargo.toml
index 851f884..c3dd94c 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,11 +1,12 @@
 [package]
 
 name = "yaxpeax-arm"
-version = "0.0.4"
+version = "0.0.5"
 authors = [ "iximeow <me@iximeow.net>" ]
 license = "0BSD"
 repository = "http://git.iximeow.net/yaxpeax-arm/"
 description = "arm decoders for the yaxpeax project"
+keywords = ["disassembler", "decoder", "armv7", "armv8"]
 
 [dependencies]
 yaxpeax-arch = { version = "0.0.4", default-features = false, features = [] }
@@ -17,10 +18,6 @@ bitvec = "0.19"
 name = "test"
 path = "test/test.rs"
 
-[[bench]]
-name = "bench"
-path = "test/test.rs"
-
 [features]
 default = ["use-serde"]
 
diff --git a/README.md b/README.md
index 80044de..9185389 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,32 @@
 ## yaxpeax-arm
 
+`yaxpeax-arm` provides implementations of decoders for the armv7, v7/thumb, v7/thumb2, and aarch64/a64 instruction sets.
+
+the entrypoint to begin decoding is either `armv7::InstDecoder` (`ARMv7::Decoder::default()`) or `armv8::InstDecoder` (`ARMv8::Decoder::default()`). `default` for both decoders is to decode in ARM mode. `default` will try to decode as permissively as possible, even attempting to produce some kind of instruction for `UNPREDICTABLE` patterns, where possible. for armv7 and below, `default_thumb` produces a similarly permissive set of rules, but for decoding thumb/thumb2 instructions.
+
+ARMv7 and thumb mode instructions decode to the same structure: `armv7::Instruction`. this is not known to introduce ambiguities, and if you must discern thumb vs non-thumb origins, `armv7::Instruction::thumb` will reflect the decoder state when decoding the instruction of interest. additionally, `armv7::Instruction::w` reports if the instruction was a wide (32-bit) thum instruction.
+
+for all ARMv7 instructions, `armv7::Instruction::s()` reports if the instruction will update status flags. if `s` is in error, that is a decoder bug, please report it.
+
+
+## stability
+0.1 and 1.0 versions are considered significant indicators of feature-completeness and stability. the specific guidelines by which `yaxpeax-arm` will be considered stable are listed below.
+
+### 0.1 checklist
+[ ] support `NEON`
+[ ] adjust `yaxpeax-arch` so `min_length` can be contingent on the mode of `InstDecoder`
+  - currently `min_length` is always 4, which is incorrect for `Thumb` modes.
+    conversely, selecting "2" would be flagrantly wrong for `ARM` modes.
+[ ] address all in-tree TODO
+
+### 1.0 checklist
+[ ] support per-version decode flags, so decoding an armv4, armv5, or armv7 instruction
+[ ] fully support `should_is_must` to control how pedantic decoding should be
+[ ] fully support reporting `unpredictable` encodings as `DecodeError::Unpredictable` if required
+[ ] exhaustively test armv7 and armv8 instructions against other decoders
+  - existing thumb test suite is derived from enumerating thumb instructions,
+    but is missing some
+
 ### ! user beware !
 * armv7 NEON support is still nonexistent