From 3974d6c72f429af3205f799fafedfe53bfa2b93b Mon Sep 17 00:00:00 2001 From: wildlarva Date: Mon, 1 Jun 2020 18:27:49 +0900 Subject: [PATCH] Update docs to support Sphinx v3 --- README.md | 2 +- requirements.txt | 3 +- src_docs/README.rst | 91 ++++++++++++++++++++++++++++++++- src_docs/conf.py | 1 - src_docs/guides.rst | 2 +- src_docs/spec_mc_desc.rst | 11 +++- src_docs/spec_mcdecoder_api.rst | 16 +++--- 7 files changed, 110 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 5ad856d..78bbff9 100644 --- a/README.md +++ b/README.md @@ -67,7 +67,7 @@ python3.8 -m pip install . ## License -The mcdecoder uses MIT License. See [LICENSE](https://github.com/wildlarva/mcdecoder/blob/master/LICENSE) for more details. +The mcdecoder uses MIT License. See [LICENSE](LICENSE) for more details. ## More details about usage diff --git a/requirements.txt b/requirements.txt index c03aea4..1b96968 100644 --- a/requirements.txt +++ b/requirements.txt @@ -3,11 +3,10 @@ deprecation<2.1 Jinja2 jsonschema lark-parser -m2r numpy pytest PyYAML -Sphinx +Sphinx>=3 sphinx-argparse sphinx-jsonschema sphinx_rtd_theme diff --git a/src_docs/README.rst b/src_docs/README.rst index 97d4958..3218bae 100644 --- a/src_docs/README.rst +++ b/src_docs/README.rst @@ -1 +1,90 @@ -.. mdinclude:: ../README.md +README: mcdecoder +================= + +The mcdecoder (Machine Code Decoder) is a set of tools to implement a machine code decoder. It includes tools to: + +* Generate a decoder for a user-defined machine code specification +* Emulate a decoder for a binary data and show decoded result +* Check the integrity of a machine code specification +* etc. + +Quickstart +---------- + +#. Define your machine code specification + + .. code-block:: yaml + :caption: arm.yaml + + machine: + byteorder: little + instructions: + - name: add_immediate_a1 + format: xxxx:cond|00|1|0100|x:S|xxxx:Rn|xxxx:Rd|xxxx xxxx xxxx:imm12 + +#. Generate a decoder + + .. code-block:: bash + + mcdecoder generate arm.yaml + +#. Use the decoder from a client + + .. code-block:: c + + const uint8_t kMachineCodes[] = { 0x04, 0xB0, 0x8D, 0xE2, }; + DecodeRequest request; + DecodeResult result; + bool succeeded; + + request.codes = &kMachineCodes[0]; + succeeded = DecodeInstruction(&request, &result); + +For more details, follow Installation steps below and go on to :doc:`quickstart`. + +Who is mcdecoder for +-------------------- + +* Developers of a CPU emulator + + * To implement the decoder part of an emulator + +* Developers of a static analyzer for machine codes + + * To implement the decoder part of an analyzer + +* Learners of the basics about machine codes + + * Hands-on approach to learn: write and test actual machine codes + +Implementing and maintaining a decoder are tough and cumbersome. The mcdecoder soothes these pains by generating a decoder. +The mcdecoder was originally developed for `athrill `__, a CPU emulator. It will be independent from athrill and be a more general tool in the near future. + +Requirements +------------ + +* Python 3.8 (with pip) + +Installation +------------ + +.. code-block:: bash + + git clone https://github.com/wildlarva/mcdecoder.git + cd mcdecoder + python3.8 -m pip install . + +License +------- + +The mcdecoder uses MIT License. See `LICENSE `__ for more details. + +More details about usage +------------------------ + +See :doc:`documents for mcdecoder users `. + +For developers of mcdecoder +--------------------------- + +See :doc:`documents for mcdecoder developers `. diff --git a/src_docs/conf.py b/src_docs/conf.py index 498360f..f6d730e 100644 --- a/src_docs/conf.py +++ b/src_docs/conf.py @@ -31,7 +31,6 @@ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ - # 'm2r', 'sphinx.ext.autodoc', 'sphinx.ext.graphviz', 'sphinx-jsonschema', diff --git a/src_docs/guides.rst b/src_docs/guides.rst index 0698385..1099d81 100644 --- a/src_docs/guides.rst +++ b/src_docs/guides.rst @@ -6,6 +6,6 @@ User guides :maxdepth: 2 :caption: Contents: - README + README quickstart user_templates diff --git a/src_docs/spec_mc_desc.rst b/src_docs/spec_mc_desc.rst index 3010c84..83e7cc7 100644 --- a/src_docs/spec_mc_desc.rst +++ b/src_docs/spec_mc_desc.rst @@ -377,9 +377,16 @@ decoder.process_instruction_hook .. warning:: - This is an experimental feature. The name and forms of this attribute might be changed in the future release. + This is an experimental feature. The name and form of this attribute might be changed in the future release. -:code:`process_instruction_hook` defines the name of the hook function to to process user-specific information into a different form. +:code:`process_instruction_hook` defines the name of the hook function to process user-specific information for an instruction into a different form. +The hook function must be defined in the python config file named :code:`config.py`. Yoo must put the config file in the same directory as the MC description file. + +The signature of the hook function is + +.. code-block:: python + + def (instruction: InstructionDecoder) -> None: Here's an example of defining a hook function to process user-specific information. diff --git a/src_docs/spec_mcdecoder_api.rst b/src_docs/spec_mcdecoder_api.rst index be8cbac..95a0496 100644 --- a/src_docs/spec_mcdecoder_api.rst +++ b/src_docs/spec_mcdecoder_api.rst @@ -42,7 +42,7 @@ Here's an example of using :code:`DecodeInstruction` (without namespace). Types ********************************* -.. c:type:: struct DecodeRequest +.. c:struct:: DecodeRequest Decoding request @@ -50,7 +50,7 @@ Types Codes to be input -.. c:type:: struct DecodeResult +.. c:struct:: DecodeResult Decoding result @@ -58,7 +58,7 @@ Types Decoded instruction id - .. c:member:: unnamed union instruction + .. c:union:: instruction Decoding result for an instruction @@ -70,11 +70,11 @@ Types * : Instruction name -.. c:type:: enum InstructionId +.. c:enum:: InstructionId Instruction id to identify a decoded instruction - .. c:member:: InstructionId_k_ + .. c:enumerator:: InstructionId_k_ Id for @@ -82,11 +82,11 @@ Types * : Instruction name - .. c:member:: InstructionId_kUnknown + .. c:enumerator:: InstructionId_kUnknown Id for an unknown instruction -.. c:type:: struct InstructionDecodeResult_ +.. c:struct:: InstructionDecodeResult_ Decoding result for @@ -107,7 +107,7 @@ Types Macros ********************************* -.. c:macro:: InstructionId INSTRUCTION_ID_MAX +.. c:var:: InstructionId INSTRUCTION_ID_MAX Number of instruction ids