From edb0dae12703f685f192036ead384a2e6ba42092 Mon Sep 17 00:00:00 2001 From: DarkSharpness <2040703891@qq.com> Date: Tue, 23 Jul 2024 17:44:41 +0800 Subject: [PATCH] docs: enhanced document readability with the help of ChatGPT --- docs/help.md | 74 ++++++++++++++++++++++--------------------------- docs/mistake.md | 30 +++++++++----------- 2 files changed, 46 insertions(+), 58 deletions(-) diff --git a/docs/help.md b/docs/help.md index 5a9e1f1..8acaaab 100644 --- a/docs/help.md +++ b/docs/help.md @@ -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 = [®]() -> 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. diff --git a/docs/mistake.md b/docs/mistake.md index 151e2de..27011c0 100644 --- a/docs/mistake.md +++ b/docs/mistake.md @@ -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.