HDLRuby 3.1.0 → 3.3.0

data/README.md

@@ -7,10 +7,35 @@ __Note__:
 
 If you are new to HDLRuby, it is recommended that you consult first the following tutorial (even if you are a hardware person):
 
- * [HDLRuby tutorial for software people](tuto/tutorial_sw.md)
+ * [HDLRuby tutorial for software people](tuto/tutorial_sw.md) [md]
+
+ * [HDLRuby tutorial for software people](tuto/tutorial_sw.html) [html]
 
 __What's new__
 
+For HDLRuby version 3.3.0:
+ 
+ * Remade the description of software components using the program construct.
+   Now the Code objects are deprecated.
+
+ * Added HW-SW co-simulation capability for Ruby and compiled C-compatible
+   software programs.
+
+ * Added a browser-based graphical interface simulating simulates a development board that interacts with the HDLRuby simulator.
+
+ * Updated the documentation and tutorial accordingly and fixed several typos.
+
+
+For HDLRuby version 3.2.0:
+
+ * Added component for declaring BRAM and BRAM-based stacks.
+   The goal is to allocate memories inside FPGAs efficiently.
+
+ * Inner code overhaul for preparing version 4.0.0
+
+ * Multiple bug fixes
+
+
 For HDLRuby version 3.1.0:
 
  * [Functions for sequencers](#sequencer-specific-function-std-sequencer_func-rb) supporting recursion;
@@ -36,7 +61,7 @@ For HDLRuby version 3.0.0:
 
 __Install__:
 
-The recommended installation method is from rubygem as follows:
+The recommended installation method is from rubygems as follows:
 
 ```
 gem install HDLRuby
@@ -51,7 +76,7 @@ git clone HDLRuby
 __Warning__: 
 
  - This is still preliminary work which may change before we release a stable version.
- - It is highly recommended to have both basic knowledges of the Ruby language and hardware description languages before using HDLRuby.
+ - It is highly recommended to have both basic knowledge of the Ruby language and hardware description languages before using HDLRuby.
 
 
 # Compiling HDLRuby descriptions
@@ -98,7 +123,7 @@ __Notes__:
 
 * If no top system is given, it is automatically looked for from the input file.
 * If no option is given, it simply checks the input file.
-* If you are new to HDLRuby, or if you want to see how new features work, we strongly encourage to get a local copy of the test HDLRuby sample using:  
+* If you are new to HDLRuby, or if you want to see how new features work, we strongly encourage you to get a local copy of the test HDLRuby sample using:  
     
   ```bash
   hdrcc --get-samples
@@ -155,7 +180,7 @@ hdrcc -I pry
 
 ## Using HDLRuby in interactive mode
 
-When running in interactive mode, the HDLRuby framework starts a REPL prompt and creates a working directory called 'HDLRubyWorkspace'. By default, the REPL is 'irb', but it can be set to 'pry'. Within this prompt, HDLRuby code can be written like in an HDLRuby description file. However, to process this code the following commands are added:
+When running in interactive mode, the HDLRuby framework starts a REPL prompt and creates a working directory called `HDLRubyWorkspace`. By default, the REPL is `irb`, but it can be set to `pry`. Within this prompt, HDLRuby code can be written like in an HDLRuby description file. However, to process this code the following commands are added:
 
 * Compile an HDLRuby module:
 
@@ -374,7 +399,7 @@ system :reg do |typ|
 end
 ```
 
-Wait... I have just realized that D-FF without any inverted output does not look very serious. So, let us extend the existing `dff` to provide an inverted output. There are three ways for doing this. First, inheritance can be used: a new system is built inheriting from `dff` as it is done in the following code.
+Wait... I have just realized that D-FF without any inverted output does not look very serious. So, let us extend the existing `dff` to provide an inverted output. There are three ways to do this. First, inheritance can be used: a new system is built inheriting from `dff` as it is done in the following code.
 
 ```ruby
 system :dff_full, dff do
@@ -432,7 +457,7 @@ system :shifter do |n|
 end
 ```
 
-As can be seen in the above examples, in HDLRuby, any construct is an object and therefore include methods. For instance, declaring a signal of a given `type` and direction (input, output, or inout) is done as follows so that `direction` is a method of the type, and the signal names are the arguments of this method (symbols or string are supported.)
+As can be seen in the above examples, in HDLRuby, any construct is an object and therefore includes methods. For instance, declaring a signal of a given `type` and direction (input, output, or inout) is done as follows so that `direction` is a method of the type, and the signal names are the arguments of this method (symbols or string are supported.)
 
 ```ruby
 <type>.<direction> <list of symbols representing the signal>
@@ -483,7 +508,7 @@ end
 In the code above, there are two generic parameters,
 `typ`, which indicates the data type of the circuit, and `coefs`, which is assumed to be an array of coefficients. Since the number of inputs depends on the number of provided coefficients, it is declared as an array of `width` bit signed whose size is equal to the number of coefficients.
 
-The description of the sum of products may be more difficult to understand for people not familiar with the Ruby language. The `each_with_index` method iterates over the coefficients adding their index as an iteration variable, the resulting operation (i.e., the iteration loop) is then modified by the `reduce` method that accumulates the code passed as arguments. This code, starting by `|sum,coef,i|` simply performs the addition of the current accumulation result (`sum`) with the product of the current coefficient (`coef`) and input (`ins[i]`, where `i` is the index) in the iteration. The argument `_b0` initializes the sum to `0`.
+The description of the sum of products may be more difficult to understand for people not familiar with the Ruby language. The `each_with_index` method iterates over the coefficients adding their index as an iteration variable, the resulting operation (i.e., the iteration loop) is then modified by the `reduce` method that accumulates the code passed as arguments. This code, starting by `|sum,coef,i|` performs the addition of the current accumulation result (`sum`) with the product of the current coefficient (`coef`) and input (`ins[i]`, where `i` is the index) in the iteration. The argument `_b0` initializes the sum to `0`.
 
 While slightly longer than the previous description, this description allows declaring a circuit implementing a sum of products with any bit width and any number of coefficients. For instance, the following code describes a signed 32-bit sum of products with  16 coefficients (just random numbers here).
 
@@ -491,7 +516,7 @@ While slightly longer than the previous description, this description allows dec
 sumprod(signed[32], [3,78,43,246, 3,67,1,8, 47,82,99,13, 5,77,2,4]).(:my_circuit)  
 ```
 
-As seen in the code above, when passing a generic argument for instantiating a generic system, the name of the instance is put between brackets for avoiding confusion.
+As seen in the code above, when passing a generic argument for instantiating a generic system, the name of the instance is put between brackets to avoid confusion.
 
 While the description `sumprod` is already usable in a wide range of cases, it still uses standard addition and multiplication. However, there are cases where specific components are to be used for these operations, either for the sake of performance, compliance with constraints, or because functionally different operations are required (e.g., saturated computations). This can be solved by using functions implementing such computation in place of operators, for example, as follows:
 
@@ -537,7 +562,7 @@ hdef :add do |max, x, y|
 end
 ```
 
-It would however be necessary to add this argument when invoking the function, e.g., `add(1000,sum,mult(...))`. While this argument is relevant for addition with saturation, it is not for the other kind of addition operations, and hence, the code of `sumprod` is no general purpose.
+It would however be necessary to add this argument when invoking the function, e.g., `add(1000,sum,mult(...))`. While this argument is relevant for addition with saturation, it is not for the other kinds of addition operations, and hence, the code of `sumprod` has no general purpose.
 
 HDLRuby provides two ways to address such issues. First, it is possible to pass code as an argument. In the case of `sumprod`, it would then be enough to add two arguments that perform the required addition and multiplication. The example is below:
 
@@ -582,7 +607,7 @@ sat16_1000.define_operator(:+) do |x,y|
 end
 ```
 
-In the code above, the first line defines the new type `sat16_1000` to be 16-bit signed and the remaining overloads (redefines) the `+` operator for this type (the same should be done for the `*` operator).
+In the code above, the first line defines the new type `sat16_1000` to be 16-bit signed, and the remaining overloads (redefines) the `+` operator for this type (the same should be done for the `*` operator).
 Then, the initial version of `sumprod` can be used with this type to achieve saturated computations as follows:
 
 ```ruby
@@ -658,7 +683,7 @@ Several constructs in HDLRuby are referred to by name, e.g., systems and signals
 After being declared, the construct can be referred to by using the name directly (i.e., without the `:` of Ruby symbols). For example, if a construct
 has been declared with `:hello` as the name, it will be afterward referred to by `hello`.
 
-## Systems and signals
+## Systems and Signals
 
 A system represents a digital system and corresponds to a Verilog HDL module. A system has an interface comprising input, output, and inout signals, and includes structural and behavioral descriptions.
 
@@ -666,7 +691,7 @@ A signal represents a state in a system. It has a data type and a value, the lat
 
 ### Declaring an empty system
 
-A system is declared using the keyword `system`. It must be given a Ruby symbol for its name and a block that describe its content. For instance, the following code describes an empty system named `box`:
+A system is declared using the keyword `system`. It must be given a Ruby symbol for its name and a block that describes its content. For instance, the following code describes an empty system named `box`:
 
 ```ruby
 system(:box) {}
@@ -674,7 +699,7 @@ system(:box) {}
 
 __Notes__:
 
-- Since this is Ruby code, the body can also be delimited by the `do` and `end` Ruby keywords (in which case the parentheses can be omitted) are as follows:
+- Since this is Ruby code, the body can also be delimited by the `do` and `end` Ruby keywords (in which case the parentheses can be omitted) as follows:
 
 ```ruby
 system :box does
@@ -850,7 +875,7 @@ end
 ### Initialization of signals
 <a name="initialization"></a>
 
-Output, inner and constant signals of a system can be initialized when declared using the following syntax in place of the usual name of the signal:
+Output, inner, and constant signals of a system can be initialized when declared using the following syntax in place of the usual name of the signal:
 
 ```ruby
 <signal name>: <intial value>
@@ -889,7 +914,7 @@ system :div2 do
    
 ```
 
-For robustness or, readability purpose, it is possible to add inner scope inside the existing scope using the `sub` keyword as follows:
+For robustness or, readability purposes, it is possible to add an inner scope inside the existing scope using the `sub` keyword as follows:
 
 ```ruby
 sub do
@@ -971,7 +996,7 @@ end
 ```
 
 In addition, it is possible to declare inner signals within an execution block.
-While such signals will be physically linked to the system, they are only accessible within the block they are declared into. This permits a tighter scope for signals, which improves the readability of the code and make it possible to declare several signals with identical names provided their respective scopes are different.
+While such signals will be physically linked to the system, they are only accessible within the block they are declared into. This permits a tighter scope for signals, which improves the readability of the code and makes it possible to declare several signals with identical names provided their respective scopes are different.
 
 An event represents a specific change in the state of a signal. 
 For example, a rising edge of a clock signal named `clk` will be represented by the event `clk.posedge`. In HDLRuby, events are obtained directly from
@@ -1014,7 +1039,7 @@ system :with_sequential_behavior do
 end
 ```
 
-A sub-block can also have a different execution mode if it is declared using `seq`, which will force sequential execution mode and `par` which will force parallel execution mode. For example, in the following code a parallel sub-block is declared within a sequential one:
+A sub-block can also have a different execution mode if it is declared using `seq`, which will force sequential execution mode, and `par` which will force parallel execution mode. For example, in the following code a parallel sub-block is declared within a sequential one:
 
 ```ruby
 system :with_sequential_behavior do
@@ -1123,7 +1148,7 @@ end
 ( a <= b+1 ).at(clk.posedge)
 ```
 
-For sake of consistency, this operator can also be applied to block statements as follows, but it is probably less readable than the standard declaration of behaviors:
+For the sake of consistency, this operator can also be applied to block statements as follows, but it is probably less readable than the standard declaration of behaviors:
 
 ```ruby
 ( seq do
@@ -1237,8 +1262,7 @@ __Note:__
 ## Statements
 
 Statements are the basic elements of a behavioral description. They are regrouped in blocks that specify their execution mode (parallel or sequential).
-There are four kinds of statements: the transmit statement which computes expressions and sends the result to the target signals, the control statement
-that changes the execution flow of the behavior, the block statement (described earlier), and the inner signal declaration.
+There are four kinds of statements: the transmit statement which computes expressions and sends the result to the target signals, the control statement which changes the execution flow of the behavior, the block statement (described earlier), and the inner signal declaration.
 
 __Note__:
 
@@ -1319,8 +1343,7 @@ end
 
 #### About loops
 
-HDLRuby does not include any hardware construct for describing loops. This might look poor compared to the other HDL, but it is important to understand
-that the current synthesis tools do not really synthesize hardware from such loops but instead preprocess them (e.g., unroll them) to synthesizable loopless hardware. In HDLRuby, such features are natively supported by the Ruby loop constructs (`for`, `while`, and so on), but also by advanced Ruby constructs like the enumerators (`each`, `times`, and so on).
+HDLRuby does not include any hardware construct for describing loops. This might look poor compared to the other HDL, but it is important to understand that the current synthesis tools do not synthesize hardware from such loops but instead preprocess them (e.g., unroll them) to synthesizable loopless hardware. In HDLRuby, such features are natively supported by the Ruby loop constructs (`for`, `while`, and so on), but also by advanced Ruby constructs like the enumerators (`each`, `times`, and so on).
 
 __Notes__:
 
@@ -1338,10 +1361,9 @@ __Notes__:
 ## Types
 <a name="types"></a>
 
-Each signal and each expression is associated with a data type that describes the kind of value it can represent.  In HDLRuby, the data types represent
-bit-vectors associated with the way they should be interpreted, i.e., as bit strings, unsigned values, signed values, or hierarchical contents.
+Each signal and each expression is associated with a data type that describes the kind of value it can represent.  In HDLRuby, the data types represent bit-vectors associated with the way they should be interpreted, i.e., as bit strings, unsigned values, signed values, or hierarchical contents.
 
-### Type construction
+### Type Construction
 
 There are five basic types, `bit`, `signed`, `unsigned`, `integer`, and `float` that represent respectively single bit logical values, single-bit unsigned values, single-bit signed values, Ruby integer values, and Ruby floating-point values (double precision). The first three types are HW and support four-valued logic, whereas the two last ones are SW (but are compatible with HW) and only support Boolean logic. Ruby integers can represent any element of **Z** (the mathematical integers) and have for that purpose a variable bit-width.
 
@@ -1444,9 +1466,9 @@ They include [immediate values](#immediate-values), [reference to signals](#refe
 
 ### Immediate values
 
-The immediate values of HDLRuby can represent vectors of `bit`, `unsigned`, and `signed`, and integer or floating-point numbers. They are prefixed by a `_` character and include a header that indicates the vector type and the base used for representing the value, followed by a numeral representing the value. The bit width of a value is obtained by default from the width of the numeral, but it is also possible to specify it in the header. In addition, the character `_` can be put anywhere in the number for increasing the readability, it will be ignored.
+The immediate values of HDLRuby can represent vectors of `bit`, `unsigned`, and `signed`, and integer or floating-point numbers. They are prefixed by a `_` character and include a header that indicates the vector type and the base used for representing the value, followed by a numeral representing the value. The bit width of a value is obtained by default from the width of the numeral, but it is also possible to specify it in the header. In addition, the character `_` can be put anywhere in the number to increase the readability, but it will be ignored.
 
-The vector type specifiers are the followings:
+The vector type specifiers are the following:
  
  - `b`: `bit` type, can be omitted,
   
@@ -1454,7 +1476,7 @@ The vector type specifiers are the followings:
 
  - `s`: `signed` type, the last figure is sign-extended if required by the binary, octal, and hexadecimal bases, but not for the decimal base.
 
-The base specifiers are the followings:
+The base specifiers are the following:
 
  - `b`: binary,
 
@@ -1500,8 +1522,7 @@ __Notes__:
 
 References are expressions used to designate signals or a part of signals.
 
-The simplest reference is simply the name of a signal. It designates the signal corresponding to this name in the current scope. For instance, in the
-following code, inner signal `sig0` is declared, and therefore the name *sig0* becomes a reference to designate this signal.
+The simplest reference is simply the name of a signal. It designates the signal corresponding to this name in the current scope. For instance, in the following code, inner signal `sig0` is declared, and therefore the name *sig0* becomes a reference to designate this signal.
 
 ```ruby
 # Declaration of signal sig0.
@@ -1593,7 +1614,7 @@ __Conversion operators:__
 | :to\_bit      | cast to bit vector            |
 | :to\_unsigned | cast to unsigned vector       |
 | :to\_signed   | cast to signed vector         |
-| :to\_big      | cast to big endian            |
+| :to\_big      | cast to big-endian            |
 | :to\_little   | cast to little endian         |
 | :reverse      | reverse the bit order         |
 | :ljust        | increase width from the left, preserves the sign  |
@@ -1605,7 +1626,7 @@ __Selection /concatenation operators:__
 
 | &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;symbol&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; | description&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; |
 | :---          | :---                          |
-| :[]           | sub vector selection          |
+| :[]           | sub-vector selection          |
 | :@[]          | concatenation operator        |
 | :.            | field selection               |
 
@@ -1683,8 +1704,8 @@ The type puns include `to_bit`, `to_unsigned`, and `to_signed` that convert expr
 sig.to_bit <= _b01010011
 ```
 
-The type casts change both the type and the value and are used to adjust the width of the types.  They can only be applied to vectors of `bit`, `signed`, or `unsinged` and can only increase the bit width (bit width can be truncated using the selection operator, please refer to the next section).
-These operators comprise the bit width conversions: `ljust`, `rjust`, `zext` and `sext`.
+The type casts change both the type and the value and are used to adjust the width of the types.  They can only be applied to vectors of `bit`, `signed`, or `unsigned` and can only increase the bit width (bit width can be truncated using the selection operator, please refer to the next section).
+These operators comprise the bit width conversions: `ljust`, `rjust`, `zext`, and `sext`.
 
 More precisely, the bit width conversions operate as follows:
 
@@ -1747,7 +1768,7 @@ Concatenation and selection are done using the `[]` operator as follows:
 #### Implicit conversions
 <a name="implicit"></a>
 
-When there is no ambiguity, HDLRuby will automatically insert conversion operators when two types are not compatible with one another.  The cases where such implicit conversions are applied are summarized in the following tables where:
+When there is no ambiguity, HDLRuby will automatically insert conversion operators when two types are not compatible with one another.  The cases where such implicit conversions are applied are summarized in the following tables, where:
 
  - `operator` is the operator in use
  - `result width` is the width of the result's type
@@ -1844,7 +1865,7 @@ __Notes__:
    function :one { 1 }
    ```
    
-- Functions can accept any kind of object as an argument, including variadic arguments or blocks of code as shown below with a function that applies the code passed as an argument to all the variadic arguments of `args`:
+- Functions can accept any object as an argument, including variadic arguments or blocks of code as shown below with a function that applies the code passed as an argument to all the variadic arguments of `args`:
 
    ```ruby
    function :apply do |*args, &code|
@@ -1852,7 +1873,7 @@ __Notes__:
    end
    ```
    
-   Such a function can be used for example for connecting a signal to a set of other signals as follows (where `sig` is connected to `x`, `y` and `z`):
+   Such a function can be used for example for connecting a signal to a set of other signals as follows (where `sig` is connected to `x`, `y`, and `z`):
    ```ruby
     apply(x,y,z) { |v| v <= sig }
    ```
@@ -1905,7 +1926,7 @@ As another example, the following function will add an alternative code that gen
 
 ```ruby
 def too_bad
-   helse { $rst <= 1 }
+   helse { rst <= 1 }
 end
 ```
 
@@ -1926,6 +1947,308 @@ end
 Ruby functions can be compared to the macros of the C languages: they are more flexible since they edit the code they are invoked in, but they are also dangerous to use. In general, it is not recommended to use them, unless when designing a library of generic code for HDLRuby.
 
 
+## Software code
+
+It is possible to describe hardware-software components in HDLRuby using the `program` construct that encapsulates some software code a provides an interface for communicating with the hardware. This interface is composed of three kinds of components:
+
+ * The activation events: 1-bit signal that triggers the execution of a given software function when the switch from 0 to 1 (or for negative ones, from 1 to 0).
+
+ * The reading ports: bit-vector signals that can be read from a software function.
+
+ * The writing ports: bit-vector signals that can be written from a software function.
+
+__Note:__
+
+The same signal can be used at the same time by multiple ports for both reading and writing, however, from the software point of view, it will correspond to two different ports.
+
+### Declaring a software component
+
+A software component is declared like a hardware process within a system. The syntax is the following:
+
+```ruby
+program(<programming language>, <function name>) do
+   <location of the software files and description of its interface>
+end
+```
+
+In the code above, `programming language` is a symbol representing the programming language used for the software. For now, only two languages are supported:
+
+ * `:ruby`: for programs in Ruby.
+
+ * `:c`: for programs in C. However, for this case, any language that can be compiled to a shared library linkable with C is supported.
+
+The `function name` parameter indicates which function is to be executed when an activation event occurs. There can be only one such function per program, but any number of programs can be declared inside the same module.
+
+The `location of the software files and description of its interface` part can include the following declaration statements:
+
+ * `actport <list of events>`: for declaring the list of events that activates the program, i.e., that will trigger the execution of the program's start function.
+
+ * `inport <list of port names associated with a signal>`: for declaring the list of ports that the software code of the program can read.
+
+ * `outport <list of port names associated with a signal>`: for declaring the list of ports that the software code of the program can write to.
+
+ * `code <list of filenames>`: for declaring the source code files.
+
+For example the following declares a program in the Ruby language whose start function is `echo` that is activated on the positive edge of signal `req`, has a read port called `inP` that is connected to signal `count` and a write port called `outP` that is connected to signal `val`, finally the code of this program is given in a file named `echo.rb`:
+
+```ruby
+system :my_system do
+   inner :req
+   [8].inner :count, :val
+ 
+   ...
+
+   program(:ruby,'echo') do
+      actport req.posedge
+      inport  inP:  count
+      outport outP: val
+      code "echo.rb"
+   end
+end
+```
+
+
+__Note:__
+
+The size of the input and output ports is one of the signals they give access to. However, from the software side, their values are converted to `long long` types.
+
+
+
+### About the software code used in HDLRuby programs
+
+#### Location and format of the files
+
+The file names indicating the software code to use must indicate the path to these files relative to where the HDLRuby tools are used. In the example above, that would mean that the `echo.rb` program must be in the same directory as the HDLRuby description. If this code were to be into a `ruby` directory under the current directory, the declaration would become: `code "ruby/echo.rb"`.
+For the Ruby language, any number of source files can be declared, and plain Ruby code can be used as is. However, for the C language, the software code must first be compiled, and it is the resulting file that must be declared in the code declaration. For example, if for the example above, C had to be used, then the program description would be the following:
+
+```ruby
+   program(:c, :echo) do
+      actport req.posedge
+      inport  inP:  count
+      outport outP: val
+      code "echo"
+   end
+```
+
+Then, for this program to work, the C code must be compiled to a file named `echo`. Please notice that, in the example, the extension is omitted, to allow the system to look for the valid file type (e.g., `.so` for a Linux shared library).
+
+__Note:__
+
+The same software file can be used for several different program constructs, however the functions it contains will be unique for the whole device.
+
+
+#### The hardware interface
+
+From the software point of view, the hardware interface consists only of a list of ports that can either be read or written. However, the implementation of this interface depends on the language.
+
+##### For Ruby
+
+For ruby, the interface is accessed by requiring the `rubyHDL` library. It gives provides the `RubyHDL` module that provides accessors to ports of the program.
+For example, the following program reads on port `inP` and writes the results on port `outP`:
+
+```ruby
+require 'rubyHDL'
+
+def echo
+   val = RubyHDL.inP
+   RubyHDL.outP = val
+end
+```
+
+__Note:__
+
+As long as a port has been declared in the HDLRuby description of the program, it will be available to the software as a module accessor without the need for any additional declaration or configuration.
+
+##### For C
+
+For C (and C-compatible compiled languages), the interface is accessed by including the `cHDL.h` file. This file must be generated using the following command:
+
+```bash
+hdrcc --ch <destination project>
+```
+
+In the command above, `<destination project>` is the directory where the C code is meant to be.
+
+
+Once generated, this file provides the three following C functions:
+
+ * `void* c_get_port(const char* name)`: returns a pointer to the port whose name is passed as argument.
+
+ * `int c_read_port(void* port)`: reads the port whose pointer is passed as argument and returns its value.
+
+ * `int c_write_port(void* port, int val)`: write the value `val` to the port passed as argument.
+
+For example, the following program reads on port `inP` and writes the results on port `outP`:
+
+```c
+#include "cHDL.h"
+
+void echo() {
+   void* inP = c_get_port("inP");
+   void* outP = c_get_port("outP");
+   int val;
+   
+   val = c_read_port(inP);
+   c_write_port(outP,val);
+}
+```
+
+__Note:__
+
+* The command for generating the C header file for using the HDLRuby hardware interface also generates files for helping to compile the source code. Please see [compile for simulation](#compiling-the-c-code).
+
+* **Important:** for windows, dynamically loaded functions must be declared with the following prefix: `__declspec(dllexport)`. If this prefix is not present before each function that is used as an HDLRuby program, the simulation will not work. For example, for Windows, the function echo *must* be written as follows:
+
+```c
+#include "cHDL.h"
+
+__declspec(dllexport) void echo() {
+   void* inP = c_get_port("inP");
+   void* outP = c_get_port("outP");
+   int val;
+   
+   val = c_read_port(inP);
+   c_write_port(outP,val);
+}
+```
+
+
+
+#### Hardware-software co-simulation
+
+As long as your programs a correctly described and the software files provided (and compiled in the case of C), the hardware-software co-simulation will be automatically performed when executing the HDLRuby simulator.
+
+##### Compiling the C code
+
+While programs in Ruby can be used directly, programs in C must be compiled first. For that purpose, the required files, including the hardware interface `cHDL.h`, must be generated. This is done by using the following HDLRruby command:
+
+```bash
+hdrcc --ch <destination project>
+```
+
+In the command above, `<destination project>` is both the directory where the C code is and the name of the resulting shared library.
+
+For example, if you want to compile the code located in the directory `echo` you need first to execute:
+
+```bash
+hdrcc --ch echo
+```
+
+Then, you will have to put your C files into the resulting directory and go inside it for compiling. If you have some specific needs for this compiling, or if you do not want to rely on the Ruby environment, you can compile your program there as a shared library like any other project. For example, if you are using GCC, you could type (after entering the `echo` directory):
+
+```bash
+gcc -shared -fPIC -undefined dynamic_lookup  -o c_program.so echo.c
+```
+
+The command above is for compiling a single file project on a Linux system.
+
+Otherwise, it may be easier to use the Ruby environment by first installing `rake-compiler` as follows:
+
+```bash
+gem install rake-compiler
+```
+
+And simply type the following command (after entering the `echo` directory):
+
+```bash
+rake compile
+```
+
+The rake tool will take care of everything for performing the compiling whatever your system may be.
+
+
+#### Hardware generation
+
+In the current stage, HDLRuby only generates the hardware part of a description. E.g., when generating Verilog, the programs are simply being ignored. It is therefore up to the user to provide additional code for implementing the hardware-software interface. The reason is that such interfaces are target-dependent, and often comprise licensed software and IP components that cannot be integrated into HDLruby. 
+
+This is less a limitation than it seems since it is possible to write program constructs that wrap such accesses so that the software and HDLRuby code can be used as is in the target system. As an illustration, you can consult the example given in the tutorial: [7.6. Hardware-software co-synthesis](tuto/tutorial_sw.md#7-6-hardware-software-co-synthesis). 
+
+
+### Extended co-simulation
+
+Since HDLRuby programs can support any compiled software, these components can also be used for executing any kind of application that is not specifically meant to be executed on the target CPU. For instance, some peripheral circuits like a keyboard or a monitor can be modeled using an HDLRuby program, as illustrated in the HDLRuby sample `with_program_ruby_cpu.rb`.
+
+
+
+### Development board simulation graphical interface
+
+HDLRuby provides a web browser-based GUI for the simulator as an extension of the co-design platform presented in this section. This GUI is to be declared as follows within a module:
+
+```ruby
+board(:<board name>,<server port>) do
+  actport <event>
+  <description of the GUI>
+end
+```
+
+In the code above, `board name` is the name of the board, `server port` is the local port the browser has to connect to for accessing the GUI (by default it is set to 8000), and `event` is the event (e.g., the rising edge of a clock) that activates the synchronization of the GUI with the simulator.
+
+Then the description of the GUI consists of a list of the following possible development board-oriented elements. Active elements are to be given a name and attached to a HDLRuby signal as follows:
+
+```ruby
+<element> <element name>: <HDLRuby signal>
+```
+
+The list of possible elements is as follows:
+
+ * `sw`: represents a set of slide switches, their number is set to match the bit-width of the attached signal.
+
+ * `bt`: represents a set of push buttons, their number is set to match the bit-width of the attached signal.
+
+ * `led`: represents a set of LEDs, their number is set to match the bit-width of the attached signal.
+
+ * `hexa`: represents a hexadecimal number display, its character width is set to match the width of the largest possible value of the attached signal.
+
+ * `digit`: represents a decimal number display, its character width is set to match the width of the largest possible positive or the smallest possible negative value of the attached signal.
+
+ * `scope`: represents an oscilloscope display, the vertical axis represents the value of the attached signal, its range is determined by its data type, and the horizontal axis represents the time is number of synchronization of the GUI.
+
+ * `row`: inserts a new line in the GUI.
+
+
+For example, for a GUI presenting an interface to an adder with input signals `x` and `y` and output signal `z` displayed as LEDs, a digit display, and an oscilloscope, the following description can be used:
+
+```ruby
+system :adder_with_gui do
+  [8].inner :x, :y, :z
+  
+  z <= x + y
+
+  inner :gui_sync
+  
+  board(:adder_gui) do
+    actport gui_sync.posedge
+    sw x: x
+    sw y: y
+    row
+    led z_led: z
+    digit z_digit: z
+    row
+    scope z_scope: z
+  end
+
+  timed do
+    clk <= 0
+    repeat(10000) do
+      !10.ns
+      clk <= ~clk
+    end
+  end
+end
+```
+
+With the code above, the GUI will show a row containing two sets of slide switches for input `x` and `y`, a row containing a set of LEDs and a digital display for showing `z`, and a row containing an oscilloscope for showing the evolution `z`.
+
+This code is simulated exactly like any other HDLRuby description, e.g., the following command will start the simulation and generate a VCD wave file:
+
+```bash
+hdrcc --sim --vcd my_adder.rb my_adder
+```
+
+However, the simulator will wait until a browser connects to it. For that, you can open a web browser, and go to the local url: `http://localhost:8000`. The simulation will then start and you can interact with the GUI.
+
+
+
 ## Time
 
 ### Time values
@@ -1968,7 +2291,7 @@ There are two kinds of such statements:
       !10.ns
    ```
 
- - The `repeat` statements: such a statement takes as argument a number of iteration and a block. The execution of the block is repeated the given number times.  For example, the following code executes 10 times the inversion of the `clk` signal every 10 nanoseconds:
+ - The `repeat` statements: such a statement takes as argument the number of iterations and a block. The execution of the block is repeated the given number of times.  For example, the following code executes 10 times the inversion of the `clk` signal every 10 nanoseconds:
 
    ```ruby
       repeat(10) do 
@@ -1992,7 +2315,7 @@ sequential blocks. The execution semantic is the following:
 
    1. Statements are grouped in sequence until a time statement is met.
 
-   2. The grouped sequence are executed in parallel.
+   2. The grouped sequences are executed in parallel.
 
    3. The time statement is executed.
 
@@ -2136,8 +2459,7 @@ In the code above, `some_sig` is a signal available in the current context. This
 
 #### Basics
 
-In HDLRuby, a system can inherit from the content of one or several other parent systems using the `include` command as follows: `include <list of
-systems>`.  Such an include can be put anywhere in the body of a system, but the resulting content will be accessible only after this command.
+In HDLRuby, a system can inherit from the content of one or several other parent systems using the `include` command as follows: `include <list of systems>`.  Such an include can be put anywhere in the body of a system, but the resulting content will be accessible only after this command.
 
 For example, the following code describes first a simple D-FF, and then uses it to describe a FF with an additional reversed output (`qb`):
 
@@ -2183,8 +2505,7 @@ __Note__:
 
 #### About inner signals and system instances
 
-By default, inner signals and instances of a parent system are not accessible by its child systems.  They can be made accessible using the `export` keyword as follows: `export <symbol 0>, <symbol 1>, ...` . For example, the following
-code exports signals `clk` and `rst` and instance `dff0` of system `exporter` so that they can be accessed in child system `importer`.
+By default, inner signals and instances of a parent system are not accessible by its child systems.  They can be made accessible using the `export` keyword as follows: `export <symbol 0>, <symbol 1>, ...`. For example, the following code exports signals `clk` and `rst` and instance `dff0` of system `exporter` so that they can be accessed in child system `importer`.
 
 ```ruby
 system :exporter do
@@ -2346,7 +2667,7 @@ end
 Please notice, that in the code above, the left value has been cast to a plain bit-vector to avoid the infinite recursive call of the `*` operator.
 
 Operators can also be overloaded with generic types. However, in such a case, the generic argument must also be present in the list of arguments of the overloaded operators.
-For instance, let us consider the following fixed-point type of variable width (and whose decimal point is set at half of its bit range):
+For instance, let us consider the following fixed-point type of variable width (whose decimal point is set at half of its bit range):
 
 ```ruby
 typedef(:fixed) do |width|
@@ -2392,22 +2713,6 @@ Several enumerators are also provided for accessing the internals of the current
 | `each_statement`  | statements of the current block      |
 | `each_inner`      | inner signals of the current block (or system if not within a block) |
 
-### Global signals
-
-HDLRuby allows the declaration of global signals the same way system's signals are declared but outside the scope of any system.  After being declared, these signals are accessible directly from within any hardware construct.
-
-To ease the design of standardized libraries, the following global signals are defined by default:
-
-| signal name | signal type | signal function                       |
-| :---        | :---        | :---                                  |
-| `$reset`    | bit         | global reset                          |
-| `$resetb`   | bit         | global reset complement               |
-| `$clk`      | bit         | global clock                          |
-
-__Note__:
- 
- - When not used, the global signals are discarded.
-
 
 
 ### Defining and executing Ruby methods within HDLRuby constructs
@@ -2487,7 +2792,7 @@ end
 While requiring caution, a properly designed method can be very useful for clean code reuse. For example, the following method allows to start the execution of a block after a given number of cycles:
 
 ```ruby
-def after(cycles,rst = $rst, &code)
+def after(cycles, rst, &code)
    sub do
       inner :count
       hif rst == 1 do
@@ -2507,34 +2812,28 @@ end
 
 In the code above: 
  
- - the default initialization of `rst` to `$rst` allows resetting the counter even if no such signal is provided as an argument.
-
  - `sub` ensures that the `count` signal does not conflict with another signal with the same name.
 
  - the `instance_eval` keyword is a standard Ruby method that executes the block passed as an argument in context.
 
-The following is an example that switches a LED on after 1000000 clock cycles using the previously defined `after` ruby method:
+The following is an example that switches an LED on after 1000000 clock cycles using the previously defined `after` ruby method:
 
 ```ruby
 system :led_after do
    output :led
-   input :clk
+   input :clk, :rst
 
    par(clk.posedge) do
-      (led <= 0).hif($rst)
-      after(100000) { led <= 1 }
+      (led <= 0).hif(rst)
+      after(100000,rst) { led <= 1 }
    end
 end
 ```
 
 __Note__:
 
- - Ruby's closure still applies in HDLRuby, hence, the block sent to `after` can use the signals and instances of the current block. Moreover, the signal declared in this method will not collide with them.
-
-
-### Dynamic description
+ - Ruby's closure still applies in HDLRuby, hence, the block sent to `after` can use the signals and instances of the current block. Moreover, the signals declared in this method will not collide with them.
 
-When describing a system, it is possible to disconnect or completely undefine a signal or an instance.
 
 
 ## Extending HDLRuby
@@ -2572,11 +2871,12 @@ The following table gives the class of each construct of HDLRuby.
 | transmit        | Transmit     |
 | hif             | If           |
 | hcase           | Case         |
+| program         | Program      |
 
 
 ### Extending HDLRuby constructs locally
 
-By local extension of a hardware construct, we mean that while the construct will be changed, all the other constructs will remain unchanged. This is achieved like in Ruby by accessing the Eigen class using the `singleton_class` method and extending it using the `class_eval` method.  For example, with the following code, only system `dff` will respond to method `interface_size`:
+By local extension of a hardware construct, we mean that while the construct will be changed, all the other constructs will remain unchanged. This is achieved like with Ruby by accessing the Eigen class using the `singleton_class` method and extending it using the `class_eval` method.  For example, with the following code, only system `dff` will respond to method `interface_size`:
 
 ```ruby
 dff.singleton_class.class_eval do
@@ -2681,7 +2981,7 @@ After the libraries are loaded, the module `Std` must be included as follows:
 include HDLRuby::High::Std
 ```
 
-> However, `hdrcc` loads the stable components of the standard library by default, so you do not need to require nor include anything more to use them. In the current version, the stable components are the followings:  
+> However, `hdrcc` loads the stable components of the standard library by default, so you do not need to require nor include anything more to use them. In the current version, the stable components are the following:  
   
   - `std/clocks.rb`  
 
@@ -2736,7 +3036,7 @@ Where:
  * `<clock>` is the clock to use, this argument can be omitted.
  * `<reset>` is the signal used to reset the counter used for waiting, this argument can be omitted.
 
-This statement can be used either inside or outside a clocked behavior. When used within a clocked behavior, the clock event of the behavior is used for the counter unless specified otherwise. When used outside such behavior, the clock is the global default clock `$clk`. In both cases, the reset is the global reset `$rst` unless specified otherwise.
+This statement can be used inside a clocked behavior where the clock event of the behavior is used for the counter unless specified otherwise. 
 
 The second construct is the `before` statement that activates a block until a given number of clock cycles is passed. Its syntax and usage are identical to the `after` statement.
 
@@ -2782,7 +3082,7 @@ A finite state machine can be declared anywhere in a system provided it is outsi
 fsm(<event>,<reset>,<mode>) <block>
 ```
 
-Where `event` is the event (rising or falling edge of a signal) activating the state transitions, `rst` is the reset signal, and `mode` is the default execution mode and `block` is the execution block describing the states of the FSM. This last parameter can be either `:sync` for synchronous (Moore type) or `:async` for asynchronous (Mealy type).
+Where `event` is the event (rising or falling edge of a signal) activating the state transitions, `rst` is the reset signal, `mode` is the default execution mode, and `block` is the execution block describing the states of the FSM. This last parameter can be either `:sync` for synchronous (Moore type) or `:async` for asynchronous (Mealy type).
 
 The states of an FSM are described as follows:
 
@@ -2790,12 +3090,12 @@ The states of an FSM are described as follows:
 <kind>(<name>) <block>
 ```
 
-Where `kind` is the kind of state, `name` is the name of the state, and `block` is the actions to execute for the corresponding state. The kinds of states are the followings:
+Where `kind` is the kind of state, `name` is the name of the state, and `block` is the actions to execute for the corresponding state. The kinds of states are the following:
 
  * reset: the state reached when resetting the FSM. This state can be forced to be asynchronous by setting the `name` argument to `:async` and forced to be synchronous by setting the `name` argument to `:sync`. By default, the `name` argument is to be omitted.
- * state: the default kind of state, it will be synchronous if the FSM is synchronous or asynchronous otherwise.
- * sync:  the synchronous kind of state, it will be synchronous whatever the kind of FSM is used.
- * async: the asynchronous kind of state, it will be asynchronous whatever the kind of FSM is used.
+ * state: the default kind of state, will be synchronous if the FSM is synchronous or asynchronous otherwise.
+ * sync:  the synchronous kind of state, will be synchronous whatever the kind of FSM is used.
+ * async: the asynchronous kind of state, will be asynchronous whatever the kind of FSM is used.
 
 In addition, it is possible to define a default action that will be executed whatever the state is using the following statement:
 
@@ -2843,7 +3143,7 @@ fsm(clk.posedge,rst,:sync) do
 end
 ```
 
-__Note__: the goto statements act globally, i.e., they are independent of the place where they are declared within the state. For example for both following statements, the next state will always be `st_a` whatever `cond` maybe:
+__Note__: the goto statements act globally, i.e., they are independent of the place where they are declared within the state. For example for both following statements, the next state will always be `st_a` whatever `cond` may be:
 
 ```ruby
    state(:st_0) do
@@ -3000,11 +3300,11 @@ The enumerators can be controlled using the following methods:
 
  - `type`: returns the type of the elements accessed by the enumerator.
 
- - `seach`: returns the current enumerator. If a block is given, performs the iteration instead of returning an enumerator.
+ - `seach`: returns the current enumerator. If a block is given, it performs the iteration instead of returning an enumerator.
 
- - `seach_with_index`: returns an enumerator over the elements of the current enumerator associated with their index position. If a block is given, performs the iteration instead of returning an enumerator.
+ - `seach_with_index`: returns an enumerator over the elements of the current enumerator associated with their index position. If a block is given, it performs the iteration instead of returning an enumerator.
 
- - `seach_with_object(<obj>)`: returns an enumerator over the elements of the current enumerator associated with object `obj` (any object, HDLRuby or not, can be used). If a block is given, performs the iteration instead of returning an enumerator.
+ - `seach_with_object(<obj>)`: returns an enumerator over the elements of the current enumerator associated with object `obj` (any object, HDLRuby or not, can be used). If a block is given, it performs the iteration instead of returning an enumerator.
 
  - `with_index`: identical to `seach_with_index`.
 
@@ -3026,7 +3326,7 @@ It is also possible to define a custom enumerator using the following command:
 <enum> = senumerator(<typ>,<size>) <block>
 ```
 
-Where `enum` is a Ruby variable referring to the enumerator, `typ` is the data type and `size` is the number of the elements to enumerate, and `block` is the block that implements the access to an element by index. For example, an enumerator on a memory could be defined as follows:
+Where `enum` is a Ruby variable referring to the enumerator, `typ` is the data type, `size` is the number of the elements to enumerate, and `block` is the block that implements the access to an element by index. For example, an enumerator on a memory could be defined as follows:
 
 ```ruby
     bit[8][-8].inner mem: [ _h01, _h02, _h03, _h04, _h30, _h30, _h30, _h30 ]
@@ -3125,7 +3425,7 @@ With this basis, several algorithms have been implemented using enumerators and
 
 #### Shared signals
 
-Like any other process, It is not possible for several sequencers to write to the same signal. This is because there would be race competition that may destroy physically the device if such operations were authorized. In standard RTL design, this limitation is overcome by implementing three-state buses, multiplexers, and arbiters. However, HDLRuby sequencers support another kind of signal called the *shared signals* that abstract the implementation details for avoiding race competition.
+Like any other process, several sequencers can't write to the same signal. This is because there would be race competition that may physically destroy the device if such operations were authorized. In standard RTL design, this limitation is overcome by implementing three-state buses, multiplexers, and arbiters. However, HDLRuby sequencers support another kind of signal called the *shared signals* that abstract the implementation details for avoiding race competition.
 
 The shared signals are declared like the other kind of signals from their type. The syntax is the following:
 
@@ -3139,14 +3439,14 @@ They can also have an initial (and default) value when declared as follows:
 <type>.shared <list of names with initialization>
 ```
 
-For example, the following code declares two 8-bit shared signals `x` and `y` and two signed 16-bit shared signals initialized to 0 `u` and `v`:
+For example, the following code declares two 8-bit shared signals `x` and `y`, and two signed 16-bit shared signals initialized to 0 `u` and `v`:
 
 ```ruby
 [8].shared :x, :y
 signed[8].shared u: 0, v: 0
 ```
 
-A shared signal can then be read and written to by any sequencer from anywhere in the subsequent code of the current scope. However, they cannot be written to outside a sequencer. For example, the following code is valid:
+A shared signal can then be read and written to by any sequencer from anywhere in the subsequent code of the current scope. However, they cannot be written outside a sequencer. For example, the following code is valid:
 
 ```ruby
 input :clk, :start
@@ -3181,7 +3481,7 @@ This default behavior of shared signal avoids race competition but is not very u
 <shared signal>.select
 ```
 
-The select value starts from 0 for the first sequencer writing to the shared signal, and is increased by one per writing sequencer. For example, in the first example, for selecting the second sequencer for writing to `x` the following code can be added after this signal is declared:
+The select value starts from 0 for the first sequencer writing to the shared signal and is increased by one per writing sequencer. For example, in the first example, for selecting the second sequencer for writing to `x` the following code can be added after this signal is declared:
 
 ```ruby
    x.select <= 1
@@ -3193,12 +3493,12 @@ This value can be changed at runtime too. For example, instead of setting the se
    par(clk.posedge) { x.select <= x.select + 1 }
 ```
 
-__Note__: this select sub signal is a standard RTL signal that has the same properties and limitations as the other ones, i.e., this is not a shared signal itself.
+__Note__: this select sub-signal is a standard RTL signal that has the same properties and limitations as the other ones, i.e., this is not a shared signal itself.
 
 
 #### Arbiters
 
-Usually, it is not the signals that we want to share, but the resources they drive. For example, in a CPU, it is an ALU that is shared as a whole rather than each of its inputs separately. In order to support such cases and ease the handling of shared signals, the library also provides the *arbiter* components. This component is instantiated like a standard module as follows, where `name` is the name of the arbiter instance:
+Usually, it is not the signals that we want to share, but the resources they drive. For example, with a CPU, it is the ALU that is shared as a whole rather than each of its inputs separately. To support such cases and ease the handling of shared signals, the library also provides the *arbiter* components. This component is instantiated like a standard module as follows, where `name` is the name of the arbiter instance:
 
 ```ruby
 arbiter(:<name>).(<list of shared signal>)
@@ -3237,7 +3537,7 @@ end
 In the example, both sequencers require access to signals `x` and `y` before accessing them and then releasing the access. 
 
 Requiring access does not guarantee that the access will be granted by the arbiter though. In the access is not granted, the write access will be ignored.
-The default access granting policy of an arbiter is the priority in the order of sequencer declaration. I.e., if several sequencers are requiring one at the same time, then the one declared the earliest in the code gains write access. For example, with the code given above, the first sequencer has to write access to `x` and `y`, and since after five write cycles it releases access, the second sequencer can then write to these signals. However, not obtaining write access does not block the execution of the sequencer, simply, its write access to the corresponding shared signals is simply ignored. In the example, the second sequencer will do its first five loop cycles without any effect and have only its five last ones that change the shared signals. To avoid such a behavior, it is possible to check if the write access is granted using arbiter sub signal `acquired`: if this signal is one in the current sequencer, that means the access is granted, otherwise it is 0. For example the following will increase signal `x` only if write access is granted:
+The default access granting policy of an arbiter is the priority in the order of sequencer declaration. I.e., if several sequencers are requiring one at the same time, then the one declared the earliest in the code gains write access. For example, with the code given above, the first sequencer has to write access to `x` and `y`, and since after five write cycles it releases access, the second sequencer can then write to these signals. However, not obtaining write access does not block the execution of the sequencer, simply, its write access to the corresponding shared signals is ignored. In the example, the second sequencer will do its first five loop cycles without any effect and have only its five last ones that change the shared signals. To avoid such a behavior, it is possible to check if the write access is granted using arbiter sub signal `acquired`: if this signal is one in the current sequencer, that means the access is granted, otherwise it is 0. For example the following will increase signal `x` only if write access is granted:
 
 ```ruby
 hif(ctrl_xy.acquired) { x <= x + 1 }
@@ -3249,7 +3549,7 @@ The policy of an arbiter can be changed using command policy. You can either pro
 ctrl_xy.policy([1,0])
 ```
 
-It is also possible to set a more complex policy by providing to the policy method a block of code whose argument is a vector indicating which sequencer is currently requiring write access to the shared signals and whose result will be the number of the sequencer to grant the access. This code will be executed each time write access is actually performed. For example, in the previous code, a policy switch priorities at each access can be implemented as follows:
+It is also possible to set a more complex policy by providing to the policy method a block of code whose argument is a vector indicating which sequencer is currently requiring write access to the shared signals and whose result will be the number of the sequencer to grant the access. This code will be executed each time write access is performed. For example, in the previous code, a policy switch priorities at each access can be implemented as follows:
 
 ```ruby
 inner priority_xy: 0
@@ -3272,7 +3572,7 @@ ctrl_xy.policy do |acq|
 end
 ```
 
-As seen in the code above, each bit of the `acq` vector is one when the corresponding sequencer required an access or 0 otherwise, bit 0 corresponds to sequencer 0, bit 1 to sequencer 1 and so on.
+As seen in the code above, each bit of the `acq` vector is one when the corresponding sequencer requires access or 0 otherwise, bit 0 corresponds to sequencer 0, bit 1 to sequencer 1, and so on.
 
 
 #### Monitors
@@ -3285,7 +3585,7 @@ The monitor component is instantiated like the arbiters as follows:
 monitor(:<name>).(<list of shared signals>)
 ```
 
-Monitors are used exactly the same ways as arbiters (including the write access granting policies) but block the execution of the sequencers that require write access until the access is granted. If we take the example of code with two sequencers given as an illustration of arbiter usage, replacing the arbiter with a monitor as follows will lock the second sequencer until it can write to shared variables `x` and `y` ensuring that all its loop cycles have the specified result:
+Monitors are used the same ways as arbiters (including the write access granting policies) but block the execution of the sequencers that require write access until the access is granted. If we take the example of code with two sequencers given as an illustration of arbiter usage, replacing the arbiter with a monitor as follows will lock the second sequencer until it can write to shared variables `x` and `y` ensuring that all its loop cycles have the specified result:
 
 ```ruby
 monitor(:ctrl_xy).(x,y)
@@ -3321,7 +3621,7 @@ end
 
 ### Sequencer-specific function: `std/sequencer_func.rb`
 
-HDLRuby function defined by `hdef` can be used in sequencer like any other HDLRuyby construct. But like the process constructs `hif` and so on, the body of these functions cannot include any sequencer-specific constructs.
+HDLRuby function defined by `hdef` can be used in a sequencer like any other HDLRuyby construct. But like the process constructs `hif` and so on, the body of these functions cannot include any sequencer-specific constructs.
 
 However, it is possible to define functions that do support the sequencer constructs using `sdef` instead of `hdef` as follows:
 
@@ -3344,7 +3644,7 @@ end
 
 As seen in the code above, a new construct `sreturn` can be used for returning a value from anywhere inside the function.
 
-When a recursion is present, HDLRuby automatically defines a stack for storing the return state and the arguments of the function. The size of the stack is heuristically set to the maximum number of bits of the arguments of the function when it is recursively called. For example, for the previous `fact` function, if when called, `n` is 16-bit, the stack will be able to hold 16 recursions. If this heuristic does not match the circuit's needs, the size can be forced as a second argument when defining the function. For example, the following code set the size to 32 whatever the arguments are:
+When a recursion is present, HDLRuby automatically defines a stack for storing the return state and the arguments of the function. The size of the stack is heuristically set to the maximum number of bits of the arguments of the function when it is recursively called. For example, for the previous `fact` function, if when called, `n` is 16-bit, the stack will be able to hold 16 recursions. If this heuristic does not match the circuit's needs, the size can be forced as a second argument when defining the function. For example, the following code sets the size to 32 whatever the arguments are:
 
 ```ruby
 sdef(:fact,32) do |n|
@@ -3623,7 +3923,7 @@ The naming convention of the samples is the following:
 * `<name>.rb`:       default type of sample.
 * `<name>_gen.rb`:   generic parameters are required for processing the sample.
 * `<name>_bench.rb`: sample including a simulation benchmark, these are the only samples that can be simulated using `hdrcc -S`. Please notice that such a sample cannot be converted to VHDL or Verilog HDL yet.
-* `with_<name>.rb`: sample illustrating a single aspect of HDLRuby or one of its library, usually includes a benchmark.
+* `with_<name>.rb`: sample illustrating a single aspect of HDLRuby or one of its libraries, usually includes a benchmark.
 
 
 # Contributing