docs: enhanced document readability with the help of ChatGPT

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

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.