docs: update wording

Signed-off-by: Jagoda Szwedyk <jszwedyk@antmicro.com>

docs/source/ci_queues.md

@@ -13,32 +13,32 @@ Controller Interface queues consist of:
 Controller Interface queues are depth-configurable with the [I3C Configuration](config.md#configuring-the-i3c-core).
 
 Queues generate several status indicators that will be used to trigger appropriate interrupts:
-  * `*_fifo_empty_` - no elements are enqueued in corresponding FIFO.
+  * `*_fifo_empty_` - no elements are enqueued in the corresponding FIFO.
   * `*_fifo_full_` - `*_FIFO_DEPTH` are enqueued in the corresponding FIFO.
   * `*_fifo_apch_thld_` - the user-defined threshold has been reached. <!-- TODO: name will be changed -->
 
 ## Queue threshold
-Command and response queue thresholds are controlled via [QUEUE_THLD_CTRL](https://github.com/chipsalliance/i3c-core-rdl/blob/4028ed29254aefdbe9c805e8bfaa275e200994ba/src/rdl/pio_registers.rdl#L44) register.
+Command and response queue thresholds are controlled via the [QUEUE_THLD_CTRL](https://github.com/chipsalliance/i3c-core-rdl/blob/4028ed29254aefdbe9c805e8bfaa275e200994ba/src/rdl/pio_registers.rdl#L44) register.
 RX and TX data queue thresholds are controlled via [DATA_BUFFER_THLD_CTRL](https://github.com/chipsalliance/i3c-core-rdl/blob/4028ed29254aefdbe9c805e8bfaa275e200994ba/src/rdl/pio_registers.rdl#L75).
 
 ### Command queue threshold
-* The threshold for command queue is set by a write to the `QUEUE_THLD_CTRL` to the 8-bit `CMD_EMPTY_BUF_THLD` field.
-* The threshold `N` of range `<1, 255>` (inclusive) will cause an `CMD_QUEUE_READY_STAT` interrupt when there's `N` or more remaining empty entries left in the command queue.
-* If the `N` value is greater than the size of the command queue (`CMD_FIFO_DEPTH`) the full depth will be considered (the threshold will be set to `CMD_FIFO_DEPTH`).
+* The threshold for command queue is set by a write to the 8-bit `CMD_EMPTY_BUF_THLD` field of the `QUEUE_THLD_CTRL` register.
+* The `N` threshold of `<1, 255>` range (inclusive) will cause an `CMD_QUEUE_READY_STAT` interrupt when there's `N` or more remaining empty entries in the command queue.
+* If the `N` value is greater than the size of the command queue (`CMD_FIFO_DEPTH`), the full depth will be considered (the threshold will be set to `CMD_FIFO_DEPTH`).
 
-### Response  queue threshold
-* The threshold for response queue is set by a write to `QUEUE_THLD_CTRL` to the 8-bit `RESP_BUF_THLD` field.
-* The threshold `N` of range `<1, 255>` (inclusive) will cause an `RESP_READY_STAT` interrupt when there's `N` or more responses enqueued in the response queue.
-* If the `N` value is greater or equal than the size of the response queue (`RESP_FIFO_DEPTH`) the full depth will be considered (the threshold will be set to `RESP_FIFO_DEPTH - 1`)
+### Response queue threshold
+* The threshold for response queue is set by a write to the 8-bit `RESP_BUF_THLD` field of the `QUEUE_THLD_CTRL` register.
+* The `N` threshold of `<1, 255>` range (inclusive) will cause an `RESP_READY_STAT` interrupt when there's `N` or more responses enqueued in the response queue.
+* If the `N` value is greater or equal than the size of the response queue (`RESP_FIFO_DEPTH`), the full depth will be considered (the threshold will be set to `RESP_FIFO_DEPTH - 1`)
 
 ### TX queue threshold
-* The threshold for the TX queue is set by a write to `DATA_BUFFER_THLD_CTRL` to the 3-bit `TX_BUF_THLD` field.
-* The threshold `N` of range `<0, 7>` (inclusive) will trigger an `TX_THLD_STAT` interrupt when `2^(N+1)` (`2` to the power of `N+1`) `DWORD` empty entries are available in the TX queue.
-* The software must provide an `N` value that corresponds to the threshold less or equal than `TX_FIFO_DEPTH`, otherwise the `clog2(TX_FIFO_DEPTH) - 1` will be applied.
+* The threshold for the TX queue is set by a write to the 3-bit `TX_BUF_THLD` field of the `DATA_BUFFER_THLD_CTRL` register.
+* The `N` threshold of `<0, 7>` range (inclusive) will trigger an `TX_THLD_STAT` interrupt when `2^(N+1)` (`2` to the power of `N+1`) empty `DWORD` entries are available in the TX queue.
+* The software must provide an `N` value that corresponds to the threshold less or equal than `TX_FIFO_DEPTH`, otherwise `clog2(TX_FIFO_DEPTH) - 1` will be applied.
 
 ### RX queue threshold
-* The threshold for the RX queue is set by a write to `DATA_BUFFER_THLD_CTRL` to the 3-bit `RX_BUF_THLD` field.
-* The threshold `N` of range `<0, 7>` (inclusive) will trigger an `RX_THLD_STAT` interrupt when `2^(N+1)` (`2` to the power of `N+1`) `DWORD` entries are enqueued in the RX queue.
-* The software must provide an `N` value that corresponds to the threshold less than `RX_FIFO_DEPTH`, otherwise the `clog2(RX_FIFO_DEPTH) - 2` will be applied.
+* The threshold for the RX queue is set by a write to the 3-bit `RX_BUF_THLD` field of the `DATA_BUFFER_THLD_CTRL` register.
+* The `N` threshold of `<0, 7>` range (inclusive) will trigger an `RX_THLD_STAT` interrupt when `2^(N+1)` (`2` to the power of `N+1`) `DWORD` entries are enqueued in the RX queue.
+* The software must provide an `N` value that corresponds to the threshold less than `RX_FIFO_DEPTH`, otherwise `clog2(RX_FIFO_DEPTH) - 2` will be applied.
 
-All queues utilize [caliptra_prim_fifo_sync.sv](https://github.com/chipsalliance/caliptra-rtl/blob/9c815c335a92901b27458271a885b2128e51e687/src/caliptra_prim/rtl/caliptra_prim_fifo_sync.sv#L9) fifo implementation.
+All queues utilize the [caliptra_prim_fifo_sync.sv](https://github.com/chipsalliance/caliptra-rtl/blob/9c815c335a92901b27458271a885b2128e51e687/src/caliptra_prim/rtl/caliptra_prim_fifo_sync.sv#L9) FIFO implementation.

docs/source/dv.md

@@ -1,8 +1,8 @@
 # Design verification
 
-This chapter presents available models and tools, which are used for I3C verification.
-The core is verified with [the Cocotb/Verilator + unit tests](../../verification/block) and [the UVM test suite](../../verification/uvm_i3c/).
+This chapter presents the available models and tools which are used for I3C verification.
+The core is verified with [the Cocotb/Verilator + unit tests](../../verification/cocotb/block) and [the UVM test suite](../../verification/uvm_i3c).
 
 ## Verification plan
 
-The verification plan is [here](../../verification/uvm_i3c/testplan.hjson).
+The verification plans can be found [here](../../verification/uvm_i3c).

docs/source/introduction.md

@@ -1,6 +1,6 @@
 # Introduction
 
-This document describes the open-source I3C Basic controller.
+This document describes the open source I3C Basic controller.
 The scope of the project includes:
 * Secondary Controller Mode
 * Active Controller Mode
@@ -10,15 +10,15 @@ The scope of the project includes:
 Secondary Controller Mode with generic TX/RX transfers can serve the same role as an I3C Target Device with support for Legacy I2C communication.
 ```
 
-The I3C Core provides a Controller Interface, which is developed in compliance with:
+The I3C Core provides a Controller Interface which is developed in compliance with:
 * <a name="spec-i3c-basic"></a>MIPI Alliance Specification for I3C Basic, Version 1.1.1
 * <a name="spec-i3c-hci"></a>MIPI Alliance Specification for I3C HCI, Version 1.2
 * <a name="spec-i3c-tcri"></a>MIPI Alliance Specification for I3C TCRI, Version 1.0
 
-Specification documents can be obtained directly from [MIPI website](https://www.mipi.org/specifications/i3c-hci), however, a login with MIPI Alliance account is required.
+The specification documents can be obtained directly from the [MIPI website](https://www.mipi.org/specifications/i3c-hci), however, a login with a MIPI Alliance account is required.
 
 Some terminology of the MIPI Alliance Specifications carry over to this documentation and requires additional context:
-* `Active Controller Mode` is the mode, in which the I3C Core initiates transfers on the I3C bus and is primarily responsible for bus initialization and management
+* `Active Controller Mode` is the mode in which the I3C Core initiates transfers on the I3C bus and is primarily responsible for bus initialization and management
 * `Secondary Controller Mode` is the mode, in which the I3C Core joins the I3C Bus as a Target Device and is conditionally responsible for specific bus management tasks
 * `Secondary Controller Mode` and `Standby Controller Mode` are used interchangeably
 * `Controller Interface` and `Host Controller Interface` are used interchangeably

docs/source/timings.md

@@ -2,13 +2,13 @@
 
 In this chapter we present:
   * the SoC Management Interface
-  * implemented oversampling of the I3C signals
-  * implemented driver
+  * the implemented oversampling of the I3C signals
+  * the implemented drivers
 
 The I3C Core exposes control over the electrical and timing configurations via [the SoC Management Interface](../../src/rdl/soc_management_interface.rdl).
 
 ```{note}
-Current numbers are not final and subject to change. Reserved for future.
+Current numbers are not final and are subject to change. Reserved for future.
 ```
 
 ## Clock speed and oversampling
@@ -31,20 +31,20 @@ In Active Controller Mode:
 
 ## Open-drain vs Push-pull configuration
 
-The I3C controller uses both Open-Drain and Push-Pull drivers and different timings are used for them.
+The I3C controller uses both Open-Drain and Push-Pull drivers, and different timings are used for them.
 The Open-Drain and Push-Pull drivers are both used within one I3C Frame.
 
 ## Rise and fall times
 
 Driver strength can be adjusted by setting correct values in the I3C Pad Attribute Configuration Register.
-The minimum allowed rise/fall times are: `150e6*bus_period`, which is 12 ns for the 12.5 MHz bus.
-When calculating timings it is worth to include all falling edges in the LOW state.
+The minimum allowed rise/fall times are `150e6*bus_period`, which is 12 ns for the 12.5 MHz bus.
+When calculating timings, it is worth including all falling edges in the LOW state.
 Similarly, all the rising edges are part of the HIGH state.
 This is because we will flip the bit in the internal implementation at the start of t{sub}`CR,CF` and then the actual rise/fall time will occur naturally.
 
 ## Timing control registers
 
-The SoC Management Interface defines the following registers, which can be used for timing control:
+The SoC Management Interface defines the following registers which can be used for timing control:
    * `T_R_REG`
    * `T_F_REG`
    * `T_SU_DAT_REG`
@@ -58,9 +58,9 @@ The SoC Management Interface defines the following registers, which can be used
    * `T_AVAL_REG`
    * `T_IDLE_REG`
 
-Value of each of these registers expresses time delay, expressed in the I3C clock period.
-Default values are provided for the 500MHz clock.
-A python script [timing.py](../../tools/timing/timing.py) is provided to recalculate values for higher clock frequencies.
+The value of each of these registers expresses time delay, expressed in the I3C clock period.
+The default values are provided for the 500MHz clock.
+The [timing.py](../../tools/timing/timing.py) Python script is provided to recalculate values for higher clock frequencies.
 
 ### Rise/fall Time Register
 ### Setup Time Register