ZYM/RISC-V-Simulator
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: enhanced document readability with the help of ChatGPT

Browse Source
This commit is contained in:
DarkSharpness
2024-07-23 17:44:41 +08:00
parent d3572cc9dc
commit edb0dae127
2 changed files with 46 additions and 58 deletions
Download Patch File Download Diff File Expand all files Collapse all files

74
docs/help.md
View File

@ -1,74 +1,68 @@
# How to use
# How to Use
You need to keep in mind that all the value types just
behave like normal integers, except that we have a similar
bit-width matching check as the verilog integers.
(e.g. 4-bit register can only be assigned from a 4-bit value)
When using this library, it's important to note that all the value types behave like regular integers, with the exception that we have a similar bit-width matching check as with Verilog integers.
(e.g. a 4-bit register can only be assigned from a 4-bit value)
Also, you should use the recommended way to perform the auto-synchronization,
which can (hope so) save you from writing a lot of duplicated code.
Additionally, it is recommended to use the provided method for auto-synchronization, which can potentially save you from writing a lot of duplicated code.
## Requirements
`g++-12` or later, with flags `-std=c++20`.
You will need `g++-12` or later, with the flags `-std=c++20`.
e.g. `g++ -std=c++20 ...`
Example: `g++ -std=c++20 ...`
Your code may still run on `g++-11` or earlier, but we do not guarantee that.
Your code may still run on `g++-11` or earlier, but we do not guarantee it.
## Include the library
## Including the Library
This is a header-only library, which means you just need to include all your required headers in your project.
This is a header-only library, which means you simply need to include all the required headers in your project.
We strongly recommend you to include `include/tools.h` to simply include all the headers.
We strongly recommend including `include/tools.h` to easily include all the headers.
```cpp
#include "include/tools.h"
```
## Debug mode
## Debug Mode
We provide a debug mode, which will perform more checks in the code. To enable that,
just define the macro `_DEBUG` before including the headers.
You may also pass `-D _DEBUG` to the compiler to define the macro,
or just define it in your code.
We provide a debug mode, which performs additional checks in the code. To enable this, simply define the macro `_DEBUG` before including the headers.
You can also pass `-D _DEBUG` to the compiler to define the macro, or define it directly in your code.
```cpp
#define _DEBUG
```
We **strongly recommend** you to enable the debug mode when you are developing your project.
We **strongly recommend** enabling the debug mode when developing your project.
e.g. `g++ -std=c++20 -D _DEBUG ...`
Example: `g++ -std=c++20 -D _DEBUG ...`
## Value types
## Value Types
You may at first treat all these types as the verilog integers.
You may assume all the types below support basic arithmetic operations,
and will **clip** the value just as the verilog integers operations.
Initially, you can treat all these types as Verilog integers.
You can assume that all the types below support basic arithmetic operations and will **clip** the value just like Verilog integer operations.
### Register
Registers are just like the registers in the verilog.
Registers are similar to those in Verilog.
To simulate the registers, a `Register` is only allowed to be assigned once in a cycle.
To simulate registers, a `Register` is only allowed to be assigned once in a cycle.
```cpp
// Declare a 32-bit register
// The maximum bit-width depends on the max_size_t
// Currently, the max_size_t is std::uint32_t
Register<32> reg;
reg <= reg + 1; // OK, allow to assign from some value with the same bit-width
reg <= reg + 1; // OK, allows assignment from a value with the same bit-width
Register<16> reg2;
reg <= reg2 * reg2; // Compile error, the bit-width is different (32 vs 16)
```
### Wire
Wires are also similar to the wires in the verilog.
Wires are also similar to those in Verilog.
It should be assigned exactly once before reading.
It can accept a function-like input (function pointers/lambdas) to extract the value.
They should be assigned exactly once before reading.
They can accept a function-like input (function pointers/lambdas) to extract the value.
```cpp
// Declare a 4-bit wire
@ -87,14 +81,14 @@ Wire <4> wire2 = [&reg]() -> auto & { return reg; };
// Ill formed! The wire is assigned twice
wire = []() { return 0b11010; };
// Ill formed! Wire can not accept a value
// with different bit-width
// Ill formed! Wire cannot accept a value
// with a different bit-width
Wire <5> wire3 = [&]() -> auto & { return reg + 4; };
```
### Bit
Bit is an intermediate type, which can be used to represent an integer with some bit_width.
Bit is an intermediate type, which can be used to represent an integer with a specific bit width.
```cpp
Bit <5> b = 0b111111; // Clipped to 0b11111
@ -107,20 +101,18 @@ Bit <4> d = b.slice <4> (1); // Copy 4 bits from bit 1 (bit 4, 3, 2, 1) to d
Bit <1> e = d[0]; // Get the 0-th bit of d
Bit f = { b + 3, c, d }; // Concatenate b + 3, c, d from high to low
```
## Synchronization
We support a feature of auto synchronization, which means that you can
easily synchronize all the members of a class by simply calling the `sync_member` function.
We support a feature of auto synchronization, which means that you can easily synchronize all the members of a class by simply calling the `sync_member` function.
We support 4 types of synchronization:
1. Register / Wire type synchronization.
2. An array (only std::array is supported) of synchronizable objects.
3. A class which contains only synchronizable objects, and satisfies std::is_aggregate.
4. A class which has some basis which are synchronizable objects, and has a special tag.
3. A class which contains only synchronizable objects and satisfies std::is_aggregate.
4. A class which has some basis that are synchronizable objects, and has a special tag.
We will show some examples of 3 and 4.
@ -162,10 +154,10 @@ void demo() {
}
```
## Common mistakes
## Common Mistakes
Turn to the [mistake](mistake.md) page to see some common mistakes.
Refer to the [mistake](mistake.md) page to see some common mistakes.
## Examples
See demo folder for more examples.
See the demo folder for more examples.

30
docs/mistake.md
View File

@ -1,9 +1,9 @@
# Some common mistakes
# Some Common Mistakes
## Bit-width mismatch
## Bit-width Mismatch
That is, the bit-width of the LHS and RHS of an assignment operation are different.
For example, the following code will result in compile error:
This occurs when the bit-width of the left-hand side (LHS) and right-hand side (RHS) of an assignment operation are different.
For example, the following code will result in a compile error:
```cpp
Register <8> r1;
@ -11,32 +11,28 @@ Register <16> r2;
r1 <= r2; // Error: bit-width mismatch
```
## Register/Wire passed by value
## Register/Wire Passed by Value
Register/Wire can be only passed by reference. We forbid
the copy/move constructor for Register/Wire to avoid misuse.
Register/Wire can only be passed by reference. We forbid the copy/move constructor for Register/Wire to prevent misuse.
This may cause some error in the lambda function of a wire.
This may cause errors in the lambda function of a wire.
```cpp
Register <8> r1;
Wire <8> w1 = [&]() { return r1; };
```
To fix this issue, you may return by reference,
or use + operator to convert the value to bit type.
To fix this issue, you may return by reference or use the + operator to convert the value to a bit type.
```cpp
Register <8> r1;
Wire <8> w1 = [&]() -> auto & { return r1; };
Wire <8> w2 = [&]() { return +r1; };
Wire <8> w2 = [&]() { return +r1; }; // +r1 will return Bit<8>b
```
## C-array as member variable
## C-array as Member Variable
We do not support C-array as member variable for synchronization.
Our C++ static reflection library do not support parsing
C-array as member variable currently.
We do not support C-arrays as member variables for synchronization. Our C++ static reflection library does not currently support parsing C-arrays as member variables.
Always use `std::array` instead.
@ -47,6 +43,6 @@ struct NeedToSync {
};
```
## Some others
## Others
If you encounter some other issues, please feel free to open an issue.
If you encounter other issues, please feel free to open an issue.