doc: documentation proofreading

a4c7b3ed · Dimitris Lampridis · e5ee2536 · a4c7b3ed · a4c7b3ed · a4c7b3ed
Commit a4c7b3ed authored May 09, 2019 by Dimitris Lampridis
25 changed files
--- a/README.rst
+++ b/README.rst
@@ -4,26 +4,24 @@
 Introduction
 ============
-The Mock Turtle is a framework to develop embedded systems on FPGA.
+Mock Turtle is a framework to develop embedded systems on FPGA.
 The need for this framework comes from the fact that in some contexts
 the development of a gateware core is more complex than writing a
-software application. Software takes more computation time than a
+software application. Typically, software takes more computation time
-custom-designed gateware core; but on the other hand, the development
+than a custom-designed gateware core; but on the other hand, the
-and support efforts are significantly reduced. Mock Turtle is a solution
+development and support efforts are significantly reduced. By using Mock
-for such problem. The gateware core complexity is moved to the software
+Turtle, the gateware core complexity is moved to the software domain
-domain within the Mock Turtle boundaries, without sacrificing
+within the Mock Turtle boundaries, without sacrificing determinism.
-determinism.
 The Mock Turtle framework provides an infrastructure on which you can
 build an FPGA-based embedded system. The basic ingredient of this
-framework is a soft-cpu multi-core environment that can be used to write
+framework is a soft-CPU multi-core environment that can be used to write
 firmware to control/monitor gateware cores. In other words, you can
 connect Mock Turtle to your gateware cores and control them with the
-firmware running on the soft-cpu. In addition, the Mock Turtle framework
+firmware running on the soft-CPU. In addition, the Mock Turtle framework
-provides a communication channel between the firmware and the
+provides a communication channel between the firmware and the host
-host applications which can be used to configure or control the
+applications which can be used to configure or control the firmware.
-firmware.
 The Mock Turtle framework focuses mainly on the determinism of the
 firmware running in it. Indeed, Mock Turtle does not support any kind of
@@ -50,7 +48,7 @@ The Mock Turtle framework includes the following components:
   -  the Mock Turtle firmware framework to develop firmware
-If the Mock Turtle is used within a Linux host system, the user can take
+If Mock Turtle is used within a Linux host system, the user can take
 advantage of a number of software components which run on the host and
 support Mock Turtle:
@@ -65,13 +63,13 @@ support Mock Turtle:
 Use Cases
 ==========
-The focus on the high determinism of the soft-cpus makes the Mock Turtle
+The focus on the high determinism of its soft-CPUs makes Mock Turtle
-a very good candidate to implement rtc systems and control
+a very good candidate to implement (typically real-time) control systems.
-systems (which are, typically, rtc applications).
-To make clear the system architecture differences let’s take the
+To demonstrate the system architecture and benefits of Mock Turtle,
-classical control system from the control theory: the heating system. We
+let’s take the classical control system example from control theory: the
-have a thermometer sensor, and an actuator to adjust the temperature.
+heating system. We have a thermometer sensor, and an actuator to adjust
+the temperature.
 The following figures show the control system architecture with and
 without Mock Turtle.
@@ -92,33 +90,32 @@ without Mock Turtle.
-In the scenario without Mock-Turtle in figure the
+In the scenario without Mock-Turtle, the user is responsible for the
-user is responsible for the entire development. On the other hands, with
+entire development. On the other hand, with Mock Turtle, the user will
-Mock Turtle, the user will be responsible of the development only of
+be responsible only for the development of the application-specific
-your business logic. This will limit your gateware development to the
+control logic, which is moved to the software domain.  The user does not
-essential blocks, and move the control logic to the software domain. You
+have to care about the communication with the host system or the
-do not have to care about the communication with the host system or the
 external world because it’s already part of the Mock Turtle framework.
 .. _introduction:when-do-not-consider-mock-turtle:
-When To Not Consider Mock Turtle
+When Not To Consider Mock Turtle
 --------------------------------
-The Mock Turtle soft-CPUs have limited computation power, this precludes
+Since the Mock Turtle soft-CPUs have limited computation power, this
-some applications like: dsp.
+precludes using it for applications like Digital Signal Processing
+(DSP).
 If you really want to use Mock Turtle for dsp analysis, please consider
-the development of a dedicated gateware core to perform the dsp analysis
+the development of a dedicated gateware core to perform the DSP analysis
-and to use the Mock Turtle as a control system for the dsp gateware
+and to use Mock Turtle as a control system for the DSP gateware core.
-core.
 Where To Get Mock Turtle
 ========================
 Mock Turtle is officially hosted on the `Open Hardware Repository`_:
-`Mock Turtle`_. This project is distributed as a git repository which can
+`Mock Turtle`_. This project is distributed as a git repository which
-be cloned using the following command::
+can be cloned using the following command::
    git clone https://ohwr.org/project/mock-turtle.git

--- a/doc/architecture.rst
+++ b/doc/architecture.rst
@@ -4,34 +4,33 @@
 The Mock Turtle Architecture
 ===============================
-The Mock Turtle is a framework to develop embedded systems on FPGA. This
+The Mock Turtle framework offers a complete and integrated stack from
-framework offers a complete and integrated stack from the HDL core to
+the HDL core to the software application.
-the software application.
-The following figure shows an overview over the Mock Turtle architecture.
+The following figure shows an overview of the Mock Turtle architecture.
 .. figure:: img/mock-turtle-overview.svg
   :align: center
   Mock Turtle Architecture Overview.
-Mock Turtle Architecture Overview. The blue and orange blocks are
+The blue and orange blocks are Mock Turtle components (respectively
-Mock Turtle components (respectively software and gateware cores).
+software and gateware cores).  Grey blocks are external components
-Grey blocks are external components (gateware cores or software)
+(gateware cores or software) developed by the user. Purple represents
-developed by the user. In purple any external world communication
+any communication to the external world over the network.
-over the network.
-This document tries to provide a big overview of what Mock Turtle offers
+This chapter tries to provide an overview of what Mock Turtle offers and
-and what is important to know when designing a Mock Turtle application.
+what is important to know when designing a Mock Turtle application.
-For more information read the dedicated chapters for the different parts.
+For more information, please read the dedicated chapters for the
+different parts.
 Mock Turtle Core
 ==================
-Mock Turtle can have one or more cores. A single core is made of the following
+Mock Turtle can have one or more cores. A single core is made of the
-components: soft-CPU, Serial console and message queues.
+following components: soft-CPU, Serial console and message queues.
 Soft-CPU
 ---------
@@ -46,7 +45,7 @@ The memory size for code and data is :ref:`configurable at synthesis time <hdl:c
 .. _uRV processor: https://www.ohwr.org/project/urv-core
 .. _`RISC-V`: https://riscv.org/
-For more information about how to handle cores from software, please read:
+For more information on how to handle cores from software, please read:
 - :ref:`Linux Library - Cores Management<sw:lnx:lib:cpu>`
@@ -55,7 +54,7 @@ Serial Console
 Each core has a serial console connected to the host system. This link is
 unidirectional from core to host. Whenever there is a pending character in
-a serial buffer, Mock Turtle raises an interrupt for the host.
+a serial buffer, Mock Turtle raises an interrupt to the host.
 .. graphviz::
   :align: center
@@ -75,23 +74,28 @@ a serial buffer, Mock Turtle raises an interrupt for the host.
      fw3 -> "Serial 3" -> host;
   }
-This is used to send string messages from the running firmware to the host system:
+This is used to send string messages from the running firmware to the
+host system.
+For more information on how to access the serial console from the
+firmware, please read:
 - :ref:`Firmware Library - Serial Interface<sw:fw:lib:uart>`
 Message Queue
 ----------------
-Mock Turtle firmware can communicate with external agents using
+Firmware running on Mock Turtle can communicate with external agents using
-*message queues*; as the name suggests, this is a message queue with
+*message queues*; as the name suggests, these are message queues with
 FIFO priority. Each soft-CPU has two sets of private message queues:
 one set is for host communication (*host message queue*), the other one is
-for external communication (*remote message queue*). Each message queue
+for external communication (*remote message queue*). All message queues
-is bidirectional (one queue per direction).
+are bidirectional (one queue per direction).
-A message queue entry is split in two fixed size buffers: header and payload.
+A message queue entry is split in two fixed size buffers: header and
-Header should be used to store a protocol header, while payload should be
+payload.  The header buffer should be used to store a protocol header,
-used to store the message content to be exchanged.
+while the payload buffer should be used to store the message content to
+be exchanged.
 .. figure:: img/mock-turtle-mq.svg
   :align: center
@@ -112,30 +116,35 @@ input and output queues:
   - maximum header size
   - maximum payload size
-Host message queues are connected to the host system. The host receives an
+Host message queues are connected to the host system. The host receives
-interrupt whenever an input queue contains at least one message; while
+an interrupt whenever an input queue contains at least one message;
-for output it receives an interrupt when a queue has at least one free entry.
+while for output it receives an interrupt when a queue has at least one
+free entry.
 Remote message queues are not handled by the host system. They must be
-connected to an *end-point* that provides a connection to the external world.
+connected to an *end-point* that provides a connection to the external
-Their task is to pack and unpack messages according to the type of network to
+world.  Their task is to pack and unpack messages according to the type
-which are connected. The end-point implementation is application specific and
+of network they are connected to. The end-point implementation is
-outside the Mock Turtle scope. Mock Turtle offers a set of generic end-points
+application specific and outside the scope of Mock Turtle. Mock Turtle
-that you can use.
+offers a set of generic end-points that you can use.
-For more information about how to access it from software, please read:
+For more information on how to access message queues from the firmware,
+please read:
 - :ref:`Firmware Library - Message Queue<sw:fw:lib:mq>`
+For more information on how to access message queues from user space,
+please read:
 - :ref:`Linux Library - Message Queue<sw:lnx:lib:hmq>`
 Shared Memory
 ================
-Mock Turtle offers a *shared memory* block accessible from the host system as
+Mock Turtle offers a *shared memory* block, accessible from the host
-well as from soft-CPU cores. This can be used to share data among all actors.
+system as well as from soft-CPU cores. This can be used to share data
-Access to the shared memory is serialized, this means that an intensive use of it
+among all actors.  Since access to the shared memory is serialized, an
-can affect the determinism.
+intensive use of it can affect the determinism.
 .. graphviz::
   :align: center
@@ -156,13 +165,16 @@ can affect the determinism.
 The shared memory size can be :ref:`configured at synthesis time <hdl:cfg>`
-but it cannot exceed 64KiB.
+but it cannot exceed 64KiB.  Its address space is mirrored into multiple
-Its address space is mirrored into multiple address ranges (contiguous),
+address ranges (contiguous), each responsible for a single atomic
-each responsible for a single atomic operation; for more information about
+operation.
-how to access it from software read:
+For more information on how to access the shared memory from the firmware, please read:
 - :ref:`Firmware Library - Shared Memory<sw:fw:lib:shm>`
+For more information on how to access the shared memory from user space, please read:
 - :ref:`Linux Library - Shared Memory<sw:lnx:lib:shm>`
 .. _`arch:dp`:
@@ -170,11 +182,17 @@ how to access it from software read:
 Device Peripherals
 ==================
-Device peripherals are external components connected to a Mock Turtle core.
+Device peripherals are external components connected to a Mock Turtle
-What they do, how many they are and how they are connected is application
+core over a Wishbone interface.  What they do, how many they are and how
-specific: Mock Turtle just offers connections to cores.
+they are connected is application specific: Mock Turtle just offers
-From the core on which the device is connected, the firmware must be able
+connections to cores.
-to address the device.
+Once a device peripheral is connected to a Mock Turtle core, firmware
+running on that core can access the peripheral by performing
+reads/writes over Wishbone.
+Note that device peripherals are not directly accessible from user
+space. Only the firmware can access them.
 .. graphviz::
   :align: center
@@ -200,6 +218,7 @@ to address the device.
     {rank=same; "Custom Logic"; "I2C master"; "SPI master"}
   }
-For more information about how to access it from software, please read:
+For more information about how to access device peripherals from the
+firmware, please read:
 - :ref:`Firmware Library - Memory Location<sw:fw:lib:mem>`
--- a/doc/demos/fmc-spec-carrier.rst
+++ b/doc/demos/fmc-spec-carrier.rst
+.. _`demo:spec`:
 ===================
 The *FMC SPEC* Demo
 ===================
@@ -9,7 +11,7 @@ application. Apart from the board itself, no other hardware is necessary to
 run the demo.
 The main aim of this demo is to handle the SPEC LEDs and buttons. The LEDs
-can be turned *on* and *off*. Buttuns' status can be read.
+can be turned *on* and *off* and the status of the buttons can be read.
 HDL Code
 ==========
@@ -98,7 +100,7 @@ The expected output from the simulation is::
 Software
 =========
-This demo has two firmware. One is named *blinker* (fw-01), the other
+This demo uses two firmware programs. One is named *blinker* (fw-01), the other
 *controller* (fw-02).
 The *blinker* firmware runs autonomously without any communication with the host
@@ -116,9 +118,8 @@ the following things:
 The *controller* firmware gives you the possibility to control the *blinker*.
 This firmware does the following things:
- it exportes as :ref:`sw:fw:frm:var` the blinking mode (it's on the shared
+- it exports as a shared memory :ref:`variable <sw:fw:frm:var>` the blinking mode;
-  memory);
+- it exports as a shared memory :ref:`variable <sw:fw:frm:var>` the buttons' actions;
- it exportes as :ref:`sw:fw:frm:var` the buttons actions (it's on the shared memory);
 .. highlight:: c
 .. literalinclude:: ../../demos/fmc-spec-carrier/software/firmware/fw-02/fw-spec.c

--- a/doc/demos/fmc-svec-carrier.rst
+++ b/doc/demos/fmc-svec-carrier.rst
+.. _`demo:svec`:
 ====================
 The *FMC SVEC* Demo
 ====================
@@ -105,7 +107,7 @@ The expected output from the simulation is::
 Software
 =========
-This demo has two firmware. One is named *autosvec* (fw-01), the other
+This demo uses two firmware programs. One is named *autosvec* (fw-01), the other
 *manualsvec* (fw-02).
 The *autosvec* firmware runs autonomously without any communication with the host
@@ -114,7 +116,7 @@ It does not use :ref:`sw:fw:frm` but only :ref:`sw:fw:lib`. This firmware does
 the following things:
 - it turns *on* and *off* all the LEDs one after the other;
- it reproduce on LEMO connector 2 whatever state is on LEMO connector 1
+- it reproduces on LEMO connector 2 whatever state is on LEMO connector 1
 - it generates square signals on LEMO connectors 3
 - it generates square signals on LEMO connectors 4
 - it periodically prints messages on the console with the GPIO status (LEDs
@@ -126,37 +128,37 @@ the following things:
 The *manualsvec* firmware offers a manual control of all LEDs and LEMOs.
 It does use :ref:`sw:fw:frm`. This firmware does the following things:
- it exportes as :ref:`sw:fw:frm:var` the device peripheral registers
+- it exports as :ref:`variables <sw:fw:frm:var>` the device peripheral registers
  to configure LEDs and LEMOs
- to exports a local :ref:`sw:fw:frm:buf` where the user can read and write
+- it exports a local :ref:`buffer <sw:fw:frm:buf>` where the user can read and write
  (it is not used)
 - it exports a local :ref:`variable <sw:fw:frm:var>` that can be used to
  stop/start an *autosvec* firmware running on a different core.
 .. note::
-   Rembember that the SVEC connects LEMO 3 and LEMO 4 to the same GPIO port.
+   Remember that the SVEC connects LEMO 3 and LEMO 4 to the same GPIO port.
   This means that they must have the same direction (both input, or both
   output)
 .. highlight:: c
 .. literalinclude:: ../../demos/fmc-svec-carrier/software/firmware/fw-02/fw-svec.c
-This firmware has also a support layer on the host side. This is not really
+This firmware also provides a support layer to the host side. This is not really
-necessary because you can always uses the generic Mock Turtle tools
+necessary because you can always use the generic Mock Turtle tools
 to :ref:`read/write variables <tools:mockturtle-variable>` and
 to :ref:`read/write buffers <tools:mockturtle-buffer>`; but for the sake of
-make this demos as complete as possible we added an host support layer which is
+making this demo as complete as possible we added a host support layer which is
-made of a C library and a C program. A part from the standard operations to open
+made of a C library and a C program. Apart from the standard operations to open
-and close a device, the library exports an API to handle the LEDs and LEMOs
+and close a device, the library exports an API to handle the status of the LEDs and LEMOs
-status and functions to set/get a dummy data structure. This library is mainly a
+and to set/get a dummy data structure. This library is mainly a
 wrapper around the Mock Turtle one.
 .. highlight:: c
 .. literalinclude:: ../../demos/fmc-svec-carrier/software/lib/libsvec.c
-At the end, the host program. This program is a command line tool that uses the
+Last but not least, there is the host program. This program is a command line tool that uses the
 svec library described above to handle the SVEC board. Again, it gives users
-the possibility to play with LEDs and LEMOs status.
+the possibility to play with the status of the LEDs and LEMOs.
 .. highlight:: c
 .. literalinclude:: ../../demos/fmc-svec-carrier/software/tools/mockturtle-svec.c

--- a/doc/demos/hello-world.rst
+++ b/doc/demos/hello-world.rst
@@ -3,7 +3,7 @@ The *Hello World* Demo
 ==========================
 The *Hello World* demo is a firmware program that prints
-over the serial interface the string ``"Hello World"`` and exit.
+over the serial interface the string ``"Hello World"`` and exits.
 This program makes use of the :ref:`sw:fw:lib`.
@@ -16,8 +16,8 @@ This program makes use of the :ref:`sw:fw:lib`.
 .. literalinclude:: ../../demos/hello_world/firmware/fw-01/fw-hello.c
 There is also the *Hello World* demo based on the :ref:`sw:fw:frm`.
-This demo will print on the serial interface general informations
+This demo will print on the serial interface general information regarding
-about the firmware application.
+the firmware application.
 ::

--- a/doc/demos/index.rst
+++ b/doc/demos/index.rst
@@ -4,15 +4,15 @@
 The Demos
 ============
-This is a collection of demo applications which main purpose is to
+This is a collection of demo applications whose main purpose is to
 introduce the users to the Mock Turtle development. In the following
 demos you will find some example code to run and test the applications.
 Unless it is explicitly specified, these demos can run on **any** Mock Turtle
 instance, in other words they do not depends on a specific HDL or hardware
 design.
-You will notice the usage of environment variable; these variables, of
+You will notice the usage of environment variables; these variables, of
-course, depend of your environment. Here a list of used variable
+course, depend on your environment. Here is a list of used variables:
 TRTL
  This is the path to the root directory of the Mock Turtle project.
@@ -35,9 +35,9 @@ DEMO
  ``software/demos`` main directory.
 In principle you can compile all the demos by running *make* in the main
-directory. Then you can load the firmware using
+directory. Then you can load the firmware using the
-:ref:`tools:mockturtle-firmware-loader` and restart the CPU with
+:ref:`tools:mockturtle-firmware-loader` tool and restart the CPU with the
-:ref:`tools:mockturtle-cpu-restart`::
+:ref:`tools:mockturtle-cpu-restart` tool::
   # Compile
   make -C $DEMO
@@ -48,7 +48,7 @@ directory. Then you can load the firmware using
 .. toctree::
   :maxdepth: 2
-   :caption: Contents:
+   :caption: Contents
   hello-world
   data-generator

--- a/doc/glossary.rst
+++ b/doc/glossary.rst
@@ -5,73 +5,65 @@ Glossary
 .. glossary::
   Control System
-     It is a system that manage, commands, regulates the behaviour of a set
+     A system that manages, commands, regulates the behaviour of a set
     of devices.
   Digital Signal Processing
     The use of digital processing to perform a wide variety of signal
     processing operations.
-   CPU-Core
-      It is a soft-CPU in Mock Turtle
   Embedded System
-     It is an autonomus system made of software, hardware (and gateware),
+     An autonomus system made of software, hardware (and gateware),
     implementing dedicated functions
   End-Point
-     It is a gateware core connected to a Mock Turtle RMQ that provides
+     A gateware core connected to a Mock Turtle RMQ that provides
     connection to an external network.
   Firmware
-     It is an embedded software system running on the Mock Turtle cpu-core.
+     An embedded software system running on a Mock Turtle soft-CPU.
   Gateware
-     It is a bitstream which configures an FPGA, or the HDL sources
+     A bitstream which configures an FPGA, or the HDL sources
     from which it was generated.
   Gateware Core
-     It is an HDL component part of a more complex gateware design.
+     An HDL component part of a more complex gateware design.
   Hardware
-     It is a physical component.
+     A physical component.
   Host
     It is the system that hosts the hardware in use.
   Host Application
-     It is a user space program running on the host system.
+     A user space program running on the host system.
   HMQ
   Host Message Queue
-     It is a message queue that connects Mock Turtle to the host system.
+     A message queue that connects Mock Turtle to the host system.
   MQ
   Message Queue
-     It is a communication system based on queues with FIFO policy. Messages are
+     A communication system based on queues with FIFO policy. Messages are
     put on the queue and they are sent to the programmed destination. Each
-     message queue has two direction: input and output.
+     message queue has two directions: input and output.
     Mock Turtle supports two message queues: host and remote.
-   RTC
-   Real-Time Computing
-     It is an hardware and software system subject to time constraints.
   RMQ
   Remote Message Queue
-     It is a message queue that connects the Mock Turtle to a network.
+     A message queue that connects the Mock Turtle to a network.
   SHM
   Shared Memory
-     It is a memory shared among soft-CPUs and the host system.
+     A memory shared among soft-CPUs and the host system.
   Soft CPU
-   soft-cpu
+     An HDL implementation of a CPU running on an FPGA.
-     It is an HDL implementation of a CPU running on an FPGA.
   MQ Entry
-     It is a single element in the MQ.
+     A single element in the MQ.
   User Space
-     It is a software running on the host and it is not in kernel mode.
+     A software running on the host, but not in kernel mode.
     This includes libraries and programs.
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -8,7 +8,7 @@ Welcome to Mock Turtle's documentation!
 .. toctree::
   :maxdepth: 1
-   :caption: Contents:
+   :caption: Contents
   introduction
   architecture

--- a/doc/software/firmware-framework.rst
+++ b/doc/software/firmware-framework.rst
@@ -6,17 +6,17 @@
 The Mock Turtle Firmware Framework
 ==================================
-Mock Turtle firmware framework guides users development by
+The Mock Turtle firmware framework guides users' development by
-keeping them focused only on the core logic without the need to deal
+keeping them focused on the core logic without the need to deal
 with Mock Turtle architectural details.
-This API is available by including ``mockturtle-framework.h`` in your source file.::
+This API is available by including ``mockturtle-framework.h`` in your source file::
      #include <mockturtle-framework.h>
 We recommend this framework to develop Mock Turtle firmware. You should
-consider alternatives if you see that it’s consuming too much memory or
+consider alternatives if you see that it is consuming too much memory or
-the performances are not enough for your application.
+that the performance is not enough for your application.
 .. note::
@@ -26,13 +26,13 @@ the performances are not enough for your application.
 Application
 ===========
-Firmwares developed with this framework need to be described by
+Firmware developed with this framework needs to be described by
-:c:type:`trtl_fw_application`. Firmware applications develop with this
+:c:type:`trtl_fw_application`. Firmware applications developed with this
-framework does not have a ``main()``. The ``main()`` is implemented within the
+framework do not have a ``main()``. The ``main()`` is implemented within the
-framework itself. What you should do is to declare a new
+framework itself. What you should do instead is to declare a new
 :c:type:`trtl_fw_application` named **app** and implement the operations
 *init*, *main* and *exit*. These operations are all optional, it means that if
-you do not implement them nothing will be executed.
+you do not implement them, nothing will be executed.
 .. graphviz::
   :align: center
@@ -45,7 +45,7 @@ you do not implement them nothing will be executed.
-Here an example.::
+Here is a minimal example of a firmware using the framework::
    #include <mockturtle-framework.h>
@@ -83,7 +83,7 @@ Here an example.::
    };
-The Mock Turtle is FPGA based, this means that the firmware are
+Since the Mock Turtle is FPGA-based, the firmware is
 typically loaded by the host. The procedure is error prone, so it may
 happen to load the wrong firmware with unpredictable consequences. To
 limit the damage, the ``fpga_id_compat`` can be used to declare a
@@ -102,23 +102,24 @@ not provide a compatibility list (like in the example above).
 Actions
 ========
-The *action* is s function that get executed when a special message
+The *action* is a function that gets executed when a special message
-arrives through a mq slot. In order words, an action is similar to an RPC.
+arrives through a message queue. In order words, an action is similar to a
+remote procedure call (RPC).
 The firmware framework relies on the :ref:`sw:proto:hmq` to make this work.
 The mechanism is quite simple. The Mock Turtle message header has a
 dedicated flag to mark a message as an RPC call
 :c:macro:`TRTL_HMQ_HEADER_FLAG_RPC`. When this flag is set, the firmware
 framework interprets the header’s message-id as action-id. Thus, the
-correspondent function get executed.
+corresponding function gets executed.
-This framework support up to :c:macro:`__TRTL_MSG_ID_MAX` actions.
+This framework supports up to :c:macro:`__TRTL_MSG_ID_MAX` actions.
 Part of it (:c:macro:`__TRTL_MSG_ID_MAX_TRTL`) is reserved for internal use,
 the rest (:c:macro:`__TRTL_MSG_ID_MAX_USER`) can be used to implement new
 actions. The reserved IDs are at the end of the number space and they are
 defined in :c:type:`trtl_msg_id`.
-The declaration of a new user action consists in 4 steps:
+The declaration of a new user action consists of 4 steps:
 #. enumerate the action IDs, share it with host;
@@ -133,7 +134,9 @@ The declaration of a new user action consists in 4 steps:
 The framework does not execute actions automatically. Once the actions
 are declared, the user must ask the framework to dispatch incoming actions.
 This is performed by :c:func:`trtl_fw_mq_action_dispatch`, which listens for
-RPC messages on a given mq. Here an example.::
+RPC messages on a given mq.
+Here is an example of declaring and using an action::
    #include <mockturtle-framework.h>
@@ -192,10 +195,10 @@ Variables
 The firmware framework offers the possibility to export local variables
 to the host system. Variables must be declared using the
-:c:type:`trtl_fw_variable` and then exported in your
+:c:type:`trtl_fw_variable` and then exported by your
 :c:type:`trtl_fw_application`.
-The mean of variable in this context is extended to any memory location:
+The meaning of a variable in this context is extended to any memory location:
 local variable, Mock Turtle registers, device peripheral registers
 and so on.
@@ -269,12 +272,12 @@ From the host you can read/write the variable by using the
 .. highlight:: c
-In chapter :ref:`sw:lnx:lib:hmq` you can find the correspondent host API,
+In chapter :ref:`sw:lnx:lib:hmq` you can find the corresponding host API,
-which in few words consists in two function: :c:func:`trtl_fw_variable_set`
+which consists of two functions: :c:func:`trtl_fw_variable_set`
 and :c:func:`trtl_fw_variable_get`.
-What we have seen until now it is handled automatically by this framework.
+All of the above is handled automatically by the framework.
-The user can send, asynchronously, variables of choice using the function
+The user can also send, asynchronously, variables of choice using the function
 :c:func:`trtl_fw_mq_send_buf`.
 .. doxygenfunction:: trtl_fw_mq_send_uint32
@@ -286,11 +289,11 @@ Buffers
 The firmware framework offers the possibility to export local buffers to
 the host system. The buffers must be declared using the
-:c:type:`trtl_fw_buffer` and then exported in your
+:c:type:`trtl_fw_buffer` and then exported by your
 :c:type:`trtl_fw_application`.
-The meaning of buffer in this context is extended to any contiguous memory
+The meaning of a buffer in this context is extended to any contiguous
-location.
+memory location.
 The framework handles the buffer exchange as a special action.
 Internally, the framework defines actions to write and to read buffers.
@@ -357,20 +360,20 @@ From the host you can read/write the buffer by using the
 .. highlight:: c
-In chapter :ref:`sw:lnx:lib:hmq` you can find the correspondent host API;
+In chapter :ref:`sw:lnx:lib:hmq` you can find the corresponding host
-in a few words consists of two function: :c:func:`trtl_fw_buffer_set`
+API, which consists of two functions: :c:func:`trtl_fw_buffer_set` and
-and :c:func:`trtl_fw_buffer_get`.
+:c:func:`trtl_fw_buffer_get`.
-What we have seen until now it is handled automatically by this framework.
+All of the above is handled automatically by the framework.  The user
-The user can send, asynchronously, buffer of choice using the function
+can also send, asynchronously, buffers of choice using the function
 :c:func:`trtl_fw_mq_send_buf`.
 .. doxygenfunction:: trtl_fw_mq_send_buf
-Utilities
+Miscellaneous
-=========
+=============
-This is a collection of miscellaneous functions that can be of some helpers.
+The following is a list of miscellaneous, helper functions.
 .. doxygenfunction:: trtl_fw_time

--- a/doc/software/firmware-library.rst
+++ b/doc/software/firmware-library.rst
@@ -17,7 +17,7 @@ Turtle firmware.
 .. warning::
-   Any firmware develop without this library will not receive any kind
+   Any firmware developed without this library will not receive any kind
   of support.
 .. _`sw:fw:lib:mem`:
@@ -25,11 +25,13 @@ Turtle firmware.
 Read And Write Memory Locations
 ===============================
-This firmware library offers a set of function to read/write memory locations.
+This firmware library offers a set of functions to read/write memory locations.
-You can access local register with :c:func:`lr_readl()` and
+You can access local registers with :c:func:`lr_readl()` and
 :c:func:`lr_writel()`.
 You can access device peripherals with :c:func:`dp_readl()` and
-:c:func:`dp_writel()`.::
+:c:func:`dp_writel()`::
      #include <mockturtle-rt.h>
@@ -107,7 +109,7 @@ All these functions are based on the generic :c:func:`readl()` and
 .. _`sw:fw:lib:mq`:
-Message Queue
+Message Queues
 ================
 Mock Turtle cores' main communication mechanism is the message queues.
@@ -115,18 +117,18 @@ The API is almost identical for both remote and host because most of these
 functions have the *message queue type* argument to distinguish them.
 You can handle the message queue with the commands: *claim*, *send*,
-*discard*, *purge*. For each of these command there is a function that
+*discard*, *purge*. For each of these commands there is a function that
 you can call to execute that command: :c:func:`mq_claim`, :c:func:`mq_send`,
-:c:func:`mq_discard`, :c:func:`mq_purge`. A part from performing active
+:c:func:`mq_discard`, :c:func:`mq_purge`. Apart from performing active
 actions on the message queue, sometimes we are interested only in their
-status, expecialy we want to know if the message queue input channel is
+status, expecialy when we want to know if the message queue input channel is
 *not empty* (it means that there is something to read) or the output channel
 is *not full* (it means that there space for writing). You can check the queue
 status with :c:func:`mq_poll_in` and :c:func:`mq_poll_out`.
 The API usage is different for input and for output.
-The typical procedure to send (output) messages over is the following.
+The typical procedure to send (output) messages is the following.
 #. *poll* the mq to see if there is at least an empty entry;
@@ -140,7 +142,7 @@ The typical procedure to send (output) messages over is the following.
 #. *send* the data, which will also release the mq slot;
-Here the output example.::
+Here is an example of how to send a message::
    #define HMQ_NUM 0
    struct trtl_fw_msg msg;
@@ -168,7 +170,7 @@ The typical procedure to receive (input) messages is the following.
 #. *discard* the slot, which will erase the data and point to the next
   one;
-Here the input example.::
+Here is an example on how to receive a message::
    #define HMQ_NUM 0
    struct trtl_fw_msg msg;
@@ -184,8 +186,10 @@ Here the input example.::
    mq_discard(TRTL_HMQ, HMQ_NUM);
 The library does not perform any validation on the data you write in
-the message. Any kind of overflow control is up to the user who can take
+the message. Any kind of overflow control is up to the user.
-the payload size from the configuration rom using :c:func:`trtl_config_rom_get`.
+The size of the payload can be retrieved from the configuration rom using
+:c:func:`trtl_config_rom_get`.
 On the host you can read the messages using the tool :ref:`tools:mockturtle-messages`
@@ -212,7 +216,7 @@ On the host you can read the messages using the tool :ref:`tools:mockturtle-mess
 These functions are enough to send and receive messages with both HMQ and RMQ.
-Following a list of lower level functions which actually are used to implement
+The remaining functions listed below are actually used to implement
 the ones above.
 .. note::
@@ -235,7 +239,7 @@ the ones above.
 Shared Memory
 =============
-This is a collection of functions and macros which purposes are:
+This is a collection of functions and macros whose purpose is:
 - to read/write the Mock Turtle shared memory
@@ -265,7 +269,7 @@ Then you can use a shared memory variable as a normal variable::
 The shared memory provides a set of atomic operations, to avoid race conditions
 while different cores are writing. There is a dedicated API for such operations.
-Here an example that uses all operations.::
+Here is an example that uses all of the available operations::
      #include <mockturtle-rt.h>
@@ -301,7 +305,7 @@ Here an example that uses all operations.::
 Serial Interface
 =================
-Over the serial interface you can print formatted string messages.
+You can user the serial interface to print formatted string messages.
 .. note::
   Even if it is potentially possible to use the serial interface to
@@ -311,7 +315,7 @@ Over the serial interface you can print formatted string messages.
 This API is based on :c:func:`pp_printf` and its different flavors:
 :c:func:`pr_error`, :c:func:`pr_debug`.
-Here an example::
+Here is an example on how to print over the serial interface::
      #include <mockturtle-rt.h>
@@ -348,7 +352,7 @@ Host Notification
 Mock Turtle has a mechanism that allows firmware to send arbitrary interrupts
 to the host system. This mechanism is used by Mock Turtle software to deliver
 special notifications; but this mechanism can be used as well by the user to
-deliver custum notifications to their support layer.
+deliver custom notifications to their support layer.
 The Mock Turtle notifications are enumerated
 by :c:type:`trtl_cpu_notification`. The user must start their enumeration
@@ -357,8 +361,8 @@ after the value *__TRTL_CPU_NOTIFY_MAX*.
 .. doxygenenum:: trtl_cpu_notification
 Mock Turtle will deliver a notification to the host when the firmware calls
-:c:func:`trtl_notify()` or, suggested for user's notification,
+:c:func:`trtl_notify()` or :c:func:`trtl_notify_user()`. The latter is
-:c:func:`trtl_notify_user()`.
+suggested for users' notifications.
 .. doxygenfunction:: trtl_notify
@@ -367,7 +371,7 @@ Mock Turtle will deliver a notification to the host when the firmware calls
 Miscellaneous
 ==============
-At the end, this chapter is a collection of helpers
+The following is a list of miscellaneous, helper functions.
 .. doxygenfunction:: delay

--- a/doc/software/index-fw.rst
+++ b/doc/software/index-fw.rst
@@ -30,15 +30,15 @@ resources and to external gateware cores. This will help mainly in
 firmware development.
 It is recommended to use the framework because it guides you in the
-development by keeping you focused only on your core logic without the
+development by keeping you focused on your core logic without the
 need to deal with Mock Turtle architecture details.
-The framework usage, rather than precluding the user to use library
+The framework usage, rather than precluding the user from using library
 functions, is complementary to the library.
 Of course, this framework provides more features and features cost space
 and computation time. If you need more space (and you can't allocate more
-memory) or you need much better performances: don't use this framework.
+memory) or you need much better performance: don't use this framework.
 All the Mock Turtle firmware source code can be found in the directory
 ``/path/to/mockturtle/software/firmware/``.
@@ -63,7 +63,7 @@ Here the list of supported TBuild variables
 OBJS
    (Mandatory) List of object files to generate from sources with
-    the same name. The default is an empty variable, this mean that it
+    the same name. The default is an empty variable, this means that it
    will not compile any source file.
 OUTPUT
@@ -104,7 +104,7 @@ configuration of the target Mock Turtle instance.
   please write your own linker script file and pass it to the build system
   by using ``TRTL_LD_SCRIPT``.
-You can build such firmware application by calling ``make`` from the
+You can build such a firmware application by calling ``make`` from the
 application directory (where the ``TBuild`` file is) like this::
  make -C <path-to-mockturtle-project>/software/firmware M=$PWD
@@ -142,8 +142,8 @@ Configuration options are not documented here. For more details
 use the help messages from Kconfig: run ``make menuconfig``
 from your firmware directory.
-Mock Turtle is using the *RISC-V* ISA, this means that your code must be
+Mock Turtle is using the *RISC-V* ISA, which means that your code must be
-compiled for this instruction-set. Mock Turtle uses the environment variable
+compiled for this instruction set. Mock Turtle uses the environment variable
 ``CROSS_COMPILE_TARGET`` to provide the path to the cross-compilation
 toolchain. By default, Mock Turtle expects the cross-compilation toolchain
 to be installed on your system and visible in ``PATH``. If this is not
@@ -154,7 +154,7 @@ the case you have to overwrite this variable.::
 At this point you can call ``make(1)`` to build your firmware.
 .. note:: If you do not know how to get the cross-compilation toolchain
-   or you need to build your own one, please have a look at the
+   or you need to build your own, please have a look at the
   `soft-cpu toolchain`_ project on the `OHWR`_.
 .. _`OHWR`: https://www.ohwr.org/
@@ -163,7 +163,7 @@ At this point you can call ``make(1)`` to build your firmware.
 .. toctree::
   :maxdepth: 2
-   :caption: Contents:
+   :caption: Contents
   firmware-library
   firmware-framework
--- a/doc/software/index-lnx.rst
+++ b/doc/software/index-lnx.rst
@@ -4,14 +4,14 @@
 Linux Development
 ====================
-It includes an explaination about the host development (libraries or
+This section provides details regarding host development (libraries or
-applications) and the Mock Turtle API on a Linux host. Any future reference
+applications) and the Mock Turtle API on a Linux host. References to a
-to host in this section will assume a Linux host because it is the only
+"host" in this section will assume a Linux host because it is the only
 supported platform for the time being.
-Mock Turtle offers 3 interfaces: a Pyhton module, a C library and
+Mock Turtle offers 3 interfaces: a Python module, a C library and a
-a Linux kernel interface. Mock Turtle users are not supposed to use
+Linux kernel interface. Users are expected to use either the Python
-the driver interface directly.
+module or the C library.
 .. graphviz::
   :align: center

--- a/doc/software/index.rst
+++ b/doc/software/index.rst
@@ -4,36 +4,36 @@
 The Software
 ==============
-This section explains the Mock Turtle software architecture as well as
+This chapter explains the Mock Turtle software architecture as well as
 the necessary steps to develop software layers on top of the Mock Turtle
 ones.
-The software integration discussion will assume that you have a general
+The following discussion assumes that the reader already has a general
 understanding of :ref:`arch`
-The Mock Turtle software stack consists in two main development domains:
+The Mock Turtle software stack consists of two main development domains:
-the :ref:`sw:fw` and the :ref:`sw:lnx`
+:ref:`sw:fw` and :ref:`sw:lnx`
 (libraries or applications).
-The Mock Turtle software stack is made of different layers which main
+The main objectives of the Mock Turtle software stack are:
-objectives are:
-  to manage the Mock Turtle cores from the host
+-  to allow managing of the Mock Turtle cores from the host
 -  to allow firmware to access Mock Turtle resources
 -  to provide a communication infrastructure between firmware and host
-  to provide a communication infrastructure with remote nodes
+-  to provide a communication infrastructure between remote nodes
-The development of a firmware is necessary to make the system work. In
+:ref:`sw:fw` is necessary to make any Mock Turtle based system to work. In
-the section :ref:`sw:fw` you will learn how to write a firmware using
+the :ref:`sw:fw` section you will learn how to write a firmware using
-Mock Turtle API.
+the provided Mock Turtle API.
-On the other hand, the development of a software support layer on the
+On the other hand, :ref:`sw:lnx` on the
-host depends on your needs. If you need a custumized control/monitor
+host depends on your needs. If you need a customized control/monitor
 infrastructure for firmware, then it is recommended to develop
 your software support layer(s) on top of the Mock Turtle ones.
 Keep in mind that :ref:`tools` can be used for basic control/monitor
 operations. This means that for basic requirements you can directly use
 the tools without developing any support layer.
@@ -41,12 +41,9 @@ the tools without developing any support layer.
 We strongly recommend you to start the develpment of a new Mock Turtle
 project by using the :ref:`tools:mockturtle-project-creator`.
-Following a list of generic topics which are not specific to Linux or firmware
-development.
 .. toctree::
   :maxdepth: 1
-   :caption: Contents:
+   :caption: Contents
   protocol
   index-lnx

--- a/doc/software/linux-driver.rst
+++ b/doc/software/linux-driver.rst
@@ -16,17 +16,17 @@ Requirements
 ==============
 The Mock Turtle device driver has been developed and tested on Linux
-3.6. Other Linux versions might work as well but it is not guaranteed.
+3.6, 3.10 and 4.14. Other Linux versions might work as well but it is
+not guaranteed.
 The FPGA address space must be visible on the host system. This requires
-a driver for the FPGA carrier that export the FPGA address space to the
+a driver for the FPGA carrier that exports the FPGA address space to the
 host.
 Compile And Install
 ====================
-The Mock Turtle device driver compilation and installation requires only
+The compile and install the Mock Turtle device driver simply execute ``make``::
-to execute ``make``.::
      $ cd /path/to/mockturtle/software/kernel
      $ export LINUX=/path/to/linux/sources
@@ -36,13 +36,13 @@ to execute ``make``.::
 Load Driver
 =============
-The Mock Turtle device driver module needs to be loaded in order to be
+The Mock Turtle device driver module needs to be loaded in order for it to be
-used.::
+used::
      $ cd /path/to/mockturtle/software/kernel
      $ sudo insmod mock-turtle.ko
-Following the list of module parameters that can be used to custumize
+The following table lists the module parameters that can be used to customize
 the driver instance.
 .. list-table::
@@ -60,12 +60,12 @@ the driver instance.
 Load Gateware
 ================
-Of course, a Mock Turtle instance must exist on your FPGA in order to be able
+A Mock Turtle instance must already exist on the FPGA in order to be
-to drive it. Loading the gateware bitstream depends on the FPGA carrier in use.
+able to drive it. Loading the gateware bitstream depends on the FPGA
-Just keep in mind that you must load the bitstream **before** adding a
+carrier in use.  Therefore, the bitstream must be loaded to the FPGA
-Mock Turtle device instance in the Linux kernel. If you do not do so, you will
+**before** adding a Mock Turtle device instance in the Linux kernel. If
-get crashes because the device driver will try to access something that does
+not, the host will crash because the device driver will try to access
-not exist yet.
+something that does not exist yet.
 .. _integration:software:host:linux:platform:
@@ -73,11 +73,11 @@ Load Device
 =============
 The Mock Turtle device driver is based on the platform Linux subsystem
-[1]_ . This means that you need a mechanism to load a platform device that
+[1]_ . This means that you need a mechanism to load a platform device
-describes a Mock Turtle device. Typically, this mechanism involves the
+that describes a Mock Turtle device. Typically, this mechanism involves
-development of a Linux module or the DeviceTree.
+the development of a Linux module or a Device Tree Structure.
-This driver handles all platform_device instances which name is one of
+This driver handles all platform_device instances whose name is one of
 the following: "mock-turtle", "mockturtle".
 The Mock Turtle device driver expects five ``resources`` from the platform
@@ -110,7 +110,7 @@ In */dev/mockturtle* you will have devices named *trtl-%04x*
 .. doxygendefine:: TRTL_IOCTL_SMEM_IO
   :outline:
-You can find the cores *sysfs* attributes at::
+You can find the *sysfs* attributes for each instance of Mock Turtle at::
  /sys/class/mockturtle/trtl-%04x/
@@ -135,11 +135,14 @@ You can find the cores *sysfs* attributes at::
 Mock Turtle Cores
 -----------------
-The Mock Turtle driver exports a *char device* for each Mock Turtle core.
+The Mock Turtle driver exports a *char device* for each Mock Turtle
-All core instances will appear as child of a :ref:`sw:drv:dev`; in
+core.  All core instances will appear as children of a
-*/dev/mockturtle* you will have devices named *trtl-%04x-%02d``*
+:ref:`sw:drv:dev`; in */dev/mockturtle* you will have devices named
-(trtl-<device-id>-<cpu-index>). The main purpose of this interface is to
+*trtl-%04x-%02d``* (trtl-<device-id>-<cpu-index>). The main purpose of
-program (or rarely useful dump) firmware into cores. These devices are
+this interface is to program firmware into cores, or, dump the firmware
+that is already loaded.
+These devices are
 bidirectional, so you can: ``write(2)`` to program a firmware, ``read(2)``
 to dump a firmware; ``lseek(2)`` to move to different memory locations.
@@ -148,14 +151,14 @@ tools.::
    dd if=firmware.bin of=/dev/mockturtle/trtl-0001-00
-The same command can be used also to dump the memory content.::
+The same command can also be used to dump the memory contents::
    dd if=/dev/mockturtle/trtl-0001-00 of=firmwaredump.bin
 In both cases (loading and dumping) the driver automatically puts the core
 in *reset* state.
 This means that after your operation you need to *unreset* the
-core in order to make it running again.::
+core in order to make it running again::
    echo 0 > /sys/class/mockturtle/trtl-0001-00/reset
@@ -178,7 +181,7 @@ For example::
   words whatever the firmware application writes is replicated on this
   interface.
-You can find the cores *sysfs* attributes at::
+You can find the *sysfs* attributes for each core at::
  /sys/class/mockturtle/trtl-%04x/trtl-%04x-%02d-%02d
@@ -204,11 +207,13 @@ Host Message Queue
 --------------------
 The Mock Turtle driver exports a *char device* for each Mock Turtle HMQ.
-All HMQ instances will appear as child of a :ref:`sw:drv:core`; in
+All HMQ instances will appear as childred of a :ref:`sw:drv:core`; in
 */dev/mockturtle/* you will have devices named ``trtl-%04x-%02d-%02d``
 (trtl-<device-id>-<cpu-index>-<hmq-index>). The main purpose of this
-interface is to exchange messages. These devices are bidirectional,
+interface is to exchange messages.
-so you can: ``write(2)`` to send messaged; ``read(2)`` to receive messages;
+These devices are bidirectional,
+so you can: ``write(2)`` to send messages; ``read(2)`` to receive messages;
 ``poll(2)`` or ``select(2)`` to wait for the interface to become accessible.
 This *char device* provides a set of ``ioctl(2)`` commands:
@@ -253,17 +258,18 @@ You can find the HMQ *sysfs* attributes at::
 Debugging Interface
 -------------------
-The driver exports on debugfs a file in YAML format which contains internal
+The driver exports on debugfs a file in YAML format which contains
-information about the driver: variable values, register values. This file is named as
+internal information about the driver: variable values, register
-the Mock Turtle instance that represents "trtl-%04x".::
+values. This file is named as the Mock Turtle instance that it
+represents ("trtl-%04x")::
    mount -t debugfs none /sys/kernel/debug
    cat /sys/kernel/debug/trtl-0001/info
 This is typically used by driver developers for debugging purposes.
-.. warning:: Its content it is not stable and it may change at anytime.
+.. warning:: The contents of the YAML file are not stable and may
-   Do not consider this as a stable interface.
+   change at any time. Do not consider this as a stable interface.
 Then, there is a debugfs file for each Mock Turtle instance that can be
 used to access the CPU debug registers. These files are named using the

--- a/doc/software/linux-library.rst
+++ b/doc/software/linux-library.rst
@@ -7,13 +7,13 @@ The Mock Turtle Linux Library
 ==============================
 The Mock Turtle Library for host system development handles all the Mock
-Turtle features and it makes them available to any user. The Mock Turtle
+Turtle features and it makes them available to the user. The aim of the
-library mandate is to export all the Mock Turtle driver features to
+Mock Turtle library is to export all the Mock Turtle driver features to
 user-space programs in a more user-friendly way without paying much in
 terms of the flexibility that the driver offers.
 The library layer covers all the driver features; for this reason, the
-user should use only the library or the Python module. The user can
+user should only use the library or the Python module. The user can
 still access the Mock Turtle driver directly but it is strongly
 discouraged.
@@ -62,12 +62,12 @@ While in the compilation command you have to provide the following options
 The example above assumes that you are compiling from the Mock Turtle
 git repository or a copy of it; if on your environment libraries and header
-files are in different locations, then fix the above code accordingly.
+files are in different locations, please adjust the above example accordingly.
 Initialization
 ==============
-The library initialization is done with function :c:func:`trtl_init()`.
+The library initialization is done with the function :c:func:`trtl_init()`.
 You must initialize the library before calling any library function.
 .. doxygenfunction:: trtl_init
@@ -103,7 +103,7 @@ Mock Turtle Cores Management
 ============================
 Library support for cores' management is limited to the firmware loading
-(dumping) and core enable/disable.
+(and dumping) and enabling/disabling of the cores.
 The typical use of these functions is to load an executable file into
 the soft-CPU. The following listing shows an example
@@ -153,14 +153,14 @@ side so that the complete flush happens synchronously.
 .. doxygenfunction:: trtl_hmq_flush
-Then, there are the functions to exchange messages with firmware
+Furthermore, there are the functions to exchange messages with firmware
-running on Mock Turtle. This API offers a minimum set of function
+running on Mock Turtle. This API offers a set of functions
 to allow users to send/receive synchronous/asynchronous messages.
-This library does not have any knowledge about the message content,
+This library does not have any knowledge about the message content.
-it processes the header but the payload is transfered as is.
+It processes the header but the payload is transfered as is.
-Any processing on the payload is left to the user. This is the rule
+Any processing of the payload is left to the user. This is the rule
-for most messages, anyway Mock Turtle offers a set of special messages
+for most messages, but Mock Turtle also offers a set of special messages
-which are completely handled by Mock Turtle.
+which are completely handled internally by Mock Turtle, including their payload.
 .. doxygenstruct:: polltrtl
   :members:
@@ -176,7 +176,7 @@ which are completely handled by Mock Turtle.
 Mock Turtle offers a set of special messages which can be used in
 combination with the firmware framework to ease the development.
 The idea behind these special messages is to offer an API for the most
-common operation that you will perform with Mock Turtle. Of course,
+common operations that you will perform with Mock Turtle. Of course,
 you are always free to use the basic message exchange mechanism and
 build on top of them your high level API.
@@ -200,9 +200,9 @@ Shared Memory
 The Mock Turtle shared memory is accessible also from the host.
-In some cases accessing the shared memory from host is necessary, but
+Even though In some cases it is necessary to access the shared memory from the host,
-this is not really encouraged as *normal usage* because it may affect
+this is not really encouraged because it may affect
-the Mock Turtle determinism. This API is limited to the basic function
+the Mock Turtle determinism. This API is limited to the basic functions
 to read and write: :c:func:`trtl_smem_write()`, :c:func:`trtl_smem_write()`.
 .. doxygenfunction:: trtl_smem_read

--- a/doc/software/linux-python.rst
+++ b/doc/software/linux-python.rst
@@ -39,7 +39,8 @@ You can use the Makefile to install PyMockTurtle module::
    cd /path/to/mockturtle/software/lib/PyMockTurtle
    make install
-Alternatively, you can use the *distutil* script that takes care of the module installation in your Python environment::
+Alternatively, you can use the *distutil* script that takes care of the
+module installation in your Python environment::
    cd /path/to/mockturtle/software/lib/PyMockTurtle
    python setup.py install
@@ -74,7 +75,7 @@ corresponding to the version declared in the setup.py script.
 .. _`sw:lnx:py:use`:
-The PyMockTurlte Basic Usage
+PyMockTurtle Basic Usage
 ============================
 The usage of this module is quite straight forward. The first thing
@@ -83,7 +84,7 @@ you have to to do is to create an instance for
 The instantiation process will autoconfigure the new object using the
 information from the configuration ROM. This means that all the cores
 (:py:class:`PyMockTurtle.TrtlCpu`) and the respective host message queues
-(:py:class:`PyMockTurtle.TrtlHmq`) will be instanciated automaticaly.::
+(:py:class:`PyMockTurtle.TrtlHmq`) will be instantiated automaticaly::
  import PyMockTurtle

--- a/doc/software/protocol.rst
+++ b/doc/software/protocol.rst
@@ -32,9 +32,9 @@ with different APIs, by both host system and firmware.
 Host Message Queue Protocol
 ==============================
-A protocol in necessary in order to exchange messages between two entities.
+A protocol is necessary in order to exchange messages between two entities.
 Any Mock Turtle message queue has a header part and a payload part. It is
-within the header part that users put the information to handle the choosen
+within the header part that users put the information to handle the chosen
 protocol.
 In order to standardize the message exchange between host and firmware
@@ -68,10 +68,12 @@ two end-points of Host Message Queue communication channel.
 Remote Message Queue Protocol
 -------------------------------
-Within this project we have defined a protocol for the communication with
+Mock Turtle only defines a protocol for the communication of the cores with
 the host system. How to handle the communication with remote nodes is left
-to the user who can chose among dozen of existing protocols (for example UDP).
+to the user who can choose among existing protocols (for example UDP).
-Also for remote queues a message is made of header and payload; whatever is
-your choosen protocol, its header will lay in the header part and the payload
+A remote queue message is also made of a header and a payload; whatever is
-the payload part. End-points can use the header part to configure them selves
+the chosen protocol, its header will lay in the header part and the payload
+the payload part. End-points can use the header part to configure themselves
 with user parameters.
--- a/doc/tools/mockturtle-buffer.rst
+++ b/doc/tools/mockturtle-buffer.rst
@@ -3,6 +3,6 @@
 Mock Turtle Buffer
 ------------------
-The Mock Turtle buffer application(\ *mockturtle-buffer*) allows the
+The Mock Turtle buffer application (*mockturtle-buffer*) allows the
-user to read/write the buffers that a firmware exports. The tool works
+user to read/write the buffers that a firmware exports. The tool only
-only with those firmware developed using :ref:`sw:fw:frm`.
+works with firmware developed using :ref:`sw:fw:frm`.
--- a/doc/tools/mockturtle-cpu-restart.rst
+++ b/doc/tools/mockturtle-cpu-restart.rst
@@ -5,5 +5,5 @@ Mock Turtle CPU Restart
 =========================
 The Mock Turtle CPU Restart application (*mockturtle-cpu-restart*) is
-used to restart a soft-cpu. This will stop the firmware execution and
+used to restart a soft-CPU. This will stop the firmware execution and
 start it again from the ``main()`` function.
--- a/doc/tools/mockturtle-firmware-loader.rst
+++ b/doc/tools/mockturtle-firmware-loader.rst
@@ -5,5 +5,5 @@ Mock Turtle Firmware Loader
 ==============================
 The Mock Turtle Loader application (*mockturtle-firmware-loader*) allows
-the user to load a firmware in a soft-cpu. It gives also the possibility
+the user to load a firmware in a soft-CPU. It gives also the possibility
-to dump the RAM content from a soft-cpu.
+to dump the RAM content from a soft-CPU.
--- a/doc/tools/mockturtle-messages.rst
+++ b/doc/tools/mockturtle-messages.rst
@@ -5,5 +5,5 @@ Mock Turtle Messages
 ======================
 The Mock Turtle Messages application (*mockturtle-messages*) can be used
-to sniff the traffic over a hmq or to access the serial console of a
+to sniff the traffic over a HMQ or to access the serial console of a
-soft-cpu.
+soft-CPU.
--- a/doc/tools/mockturtle-ping.rst
+++ b/doc/tools/mockturtle-ping.rst
@@ -7,5 +7,5 @@ Mock Turtle Ping
 The purpose of the Mock Turtle Ping application (*mockturtle-ping*) is
 to be able to verify that a firmware is running. In addition, the
 mockturtle-ping application provides information about the firmware
-version running on a Mock Turtle soft-cpu. The tool works only with
+version running on a Mock Turtle soft-CPU. The tool only works with
-those firmware developed using :ref:`sw:fw:frm`.
+firmware developed using :ref:`sw:fw:frm`.
--- a/doc/tools/mockturtle-project-creator.rst
+++ b/doc/tools/mockturtle-project-creator.rst
@@ -6,7 +6,7 @@ Mock Turtle Project Creator
 The process of setting up a new Mock Turtle project can takes hours the
 first time if you do not know already what it is expected from the user.
-Fortunatelly, this process can be automated and there is not much
+Fortunately, this process can be automated and there is not much
 knowledge in it.
 The Mock Turtle Project Creator (*mockturtle-project-creator*) is a

--- a/doc/tools/mockturtle-smem.rst
+++ b/doc/tools/mockturtle-smem.rst
@@ -5,5 +5,5 @@ Mock Turtle Shared Memory
 =============================
 The Mock Turtle Shared Memory application (*mockturtle-smem*) provides
-access to the Mock Turtle shm. The user can read/write any location of
+access to the Mock Turtle shared memory. The user can read/write any location of
-the shm using different access modes.
+the shared memory using different access modes.
--- a/doc/tools/mockturtle-variable.rst
+++ b/doc/tools/mockturtle-variable.rst
@@ -4,6 +4,6 @@
 Mock Turtle Variable
 =====================
-The Mock Turtle variable application(\ *mockturtle-variable*) allows the
+The Mock Turtle variable application (*mockturtle-variable*) allows the
-user to read/write the variables that a firmware exports. The tool works
+user to read/write the variables that a firmware exports. The tool only
-only with those firmware developed using :ref:`sw:fw:frm`.
+works with firmware developed using :ref:`sw:fw:frm`.