====== Cycle Level Modules ======

This page is an overall description of what is a module in a cycle-level simulator. If you want a step-by-step presentation of what is a module you can refer to [[https://unisim.org/tutorial/may_2007_tutorial/html/basics/Basics%20of%20UNISIM.html|this tutorial]]. The tutorial will details our choices on how a module is implemented, and guide you through building your first modules.

You can also have some details on the modules currently available in the repository here:
  * [[modules:cycle:interfaces:start|Modules interfaces]]: All the interfaces used for communication between modules, as the list of possible //data-signals//.
  * [[modules:cycle:start|List of Modules]]: The list of the cycle-level modules available in the library, with a detailed description of each module.

===== Defining a module =====

Cycle-level modules usually correspond to hardware components or hardware blocks composing the cycle-level simulator. A module can correspond to a single stage of an out-of-order pipeline, or to the whole pipeline of an in-order simulator.

Modules are defined as a C++ class, the **state** of the module being defined by the properties of the class. For a //stage register// for instance, the state will correspond to the value stored in the register.




===== Implementing actions within modules =====

Modules can also implements actions that will either access or modify the state values. Such actions are defined as **processes** defined as methods of the module. All the processes of a module will implement his overall behavior.










===== Modules interactions =====

Modules can communicate through a **port-based communication** scheme: 
The principle is to use ports and signals to communicate between different modules. Basically, each module can have input and output ports, and an output is linked with an input port through a signal. Passing values between modules consists in writing to/reading from input/output ports. 

{{ ab.png }}

For each process defined within a module, the user can specify the list of input signals the process is sensitive, definging the **sensitivity list** of a process. Module communication is implemented through processes accessing input and output ports.







===== Defining the 3 signals =====

To enhance reusability of cycle-level modules accross simulators, the centralized control was distributed to the different modules composing the simulator.
So control is both part of the module behavior implemented through processes, and part of the communication scheme.

A connection between two modules is composed of three different signals, as shown on the figure below.

{{ ab_3sig.png }}

The figure correspond to a //source module// ''A'' communicating with a //target module// ''B''. The three signals are the following:
  * The **data signal** (red) is sent from the source  to the target, it correspond the the data effectively sent along the datapath.
  * The **accept signal** (blue) is sent from the target to the source to either accept or refuse previously sent data. This is part of the control abstraction embedded in the ports which allow to implement stalls in a pipeline. A stalled module will reject new incoming data.
  * The **enable signal** (green) is sent from the source to the target to allow or prevent the usage of a previously sent and accepted data. This is part of the control abstraction embedded in the ports which allow to implement synchronization when a module is sending a data to several modules.

For details on those signals, please refer to [[https://unisim.org/tutorial/may_2007_tutorial/html/basics/Basics%20of%20UNISIM.html|this tutorial]]. 

===== The Clock signal =====

The **clock signal** is not a simple //data signal//, but implemented as a specific signal:
  * The clock signal carry no data
  * A process can either be sentitive to the raising edge of the clock or the falling edge of the clock, meaning being called at the very begging of the cycle or at the end of the cycle.