From 1a3effc692d5424b164a364fc07e0949dc7d27ae Mon Sep 17 00:00:00 2001 From: Thomas Harte Date: Sat, 2 Jan 2021 21:19:45 -0500 Subject: [PATCH] Modifies contract again. This is why I'm doing this now. --- Processors/Decoders/README.md | 8 +++++--- Processors/Decoders/x86/x86.hpp | 7 ++++--- 2 files changed, 9 insertions(+), 6 deletions(-) diff --git a/Processors/Decoders/README.md b/Processors/Decoders/README.md index c8975eef7..ca5bbcbfe 100644 --- a/Processors/Decoders/README.md +++ b/Processors/Decoders/README.md @@ -36,11 +36,13 @@ If instructions are a variable size, the decoder should maintain internal state A sample interface: - size_t decode(Instruction &target, word_type *stream, size_t length) { ... } + Instruction decode(word_type *stream, size_t length) { ... } -Returns either the number of further words necessary fully to decode, if known, or a negative number to indicate a generic sense of 'more needed'. A value of `0` means 'an instruction was fully decoded', and the instruction itself should be able to report its size. +The returned instruction has a size that is one of: +* a positive number, indicating a successful decoding that consumed that many `word_type`s; or +* a negative number, indicating the [negatived] minimum number of `word_type`s that the caller should try to get hold of before calling `decode` again. -`target` is populated only if an instruction is decoded; `stream` and `length` provide as much further instruction stream data as the caller currently possesses. +A caller is permitted to react in any way it prefers to negative numbers; they're a hint potentially to reduce calling overhead only. ## Tying Decoders into Instruction Executors diff --git a/Processors/Decoders/x86/x86.hpp b/Processors/Decoders/x86/x86.hpp index 9c692747b..4ddbe0d1a 100644 --- a/Processors/Decoders/x86/x86.hpp +++ b/Processors/Decoders/x86/x86.hpp @@ -101,9 +101,10 @@ struct Decoder { /*! @returns an @c Instruction with a positive size to indicate successful decoding; a - negative size specifies the number of further bytes required fully to decode, and - a zero size indicates that further bytes are required but the decoder does not yet - know exactly how many. + negative size specifies the [negatived] number of further bytes the caller should ideally + collect before calling again. The caller is free to call with fewer, but may not get a decoded + instruction in response, and the decoder may still not be able to complete decoding + even if given that number of bytes. */ Instruction decode(uint8_t *source, size_t length);