Re: [PATCH v4 1/8] accel/qaic: Add documentation for AIC100 accelerator driver

[Bagas Sanjaya <bagasdotme@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 10323 bytes --]

On Tue, Mar 21, 2023 at 03:52:11PM -0600, Jeffrey Hugo wrote:
> > > +
> > > +Request field descriptions:
> > > +
> > > +| req_id- request ID. A request FIFO element and a response FIFO element with
> > > +|         the same request ID refer to the same command.
> > > +
> > > +| seq_id- sequence ID within a request. Ignored by the DMA Bridge.
> > > +
> > > +| pcie_dma_cmd- describes the DMA element of this request.
> > > +| 	Bit(7) is the force msi flag, which overrides the DMA Bridge MSI logic
> > > +| 		and generates a MSI when this request is complete, and QSM
> > > +| 		configures the DMA Bridge to look at this bit.
> > > +| 	Bits(6:5) are reserved.
> > > +| 	Bit(4) is the completion code flag, and indicates that the DMA Bridge
> > > +| 		shall generate a response FIFO element when this request is
> > > +| 		complete.
> > > +| 	Bit(3) indicates if this request is a linked list transfer(0) or a bulk
> > > +| 		transfer(1).
> > > +| 	Bit(2) is reserved.
> > > +| 	Bits(1:0) indicate the type of transfer. No transfer(0), to device(1),
> > > +| 		from device(2). Value 3 is illegal.
> > > +
> > > +| pcie_dma_source_addr- source address for a bulk transfer, or the address of
> > > +|         the linked list.
> > > +
> > > +| pcie_dma_dest_addr- destination address for a bulk transfer.
> > > +
> > > +| pcie_dma_len- length of the bulk transfer. Note that the size of this field
> > > +| 	limits transfers to 4G in size.
> > > +
> > > +| doorbell_addr- address of the doorbell to ring when this request is complete.
> > > +
> > > +| doorbell_attr- doorbell attributes.
> > > +| 	Bit(7) indicates if a write to a doorbell is to occur.
> > > +| 	Bits(6:2) are reserved.
> > > +| 	Bits(1:0) contain the encoding of the doorbell length. 0 is 32-bit,
> > > +| 		1 is 16-bit, 2 is 8-bit, 3 is reserved. The doorbell address
> > > +| 		must be naturally aligned to the specified length.
> > > +
> > > +| doorbell_data- data to write to the doorbell. Only the bits corresponding to
> > > +| 	the doorbell length are valid.
> > > +
> > > +| sem_cmdN- semaphore command.
> > > +| 	Bit(31) indicates this semaphore command is enabled.
> > > +| 	Bit(30) is the to-device DMA fence. Block this request until all
> > > +| 		to-device DMA transfers are complete.
> > > +| 	Bit(29) is the from-device DMA fence. Block this request until all
> > > +| 		from-device DMA transfers are complete.
> > > +| 	Bits(28:27) are reserved.
> > > +| 	Bits(26:24) are the semaphore command. 0 is NOP. 1 is init with the
> > > +| 		specified value. 2 is increment. 3 is decrement. 4 is wait
> > > +| 		until the semaphore is equal to the specified value. 5 is wait
> > > +| 		until the semaphore is greater or equal to the specified value.
> > > +| 		6 is "P", wait until semaphore is greater than 0, then
> > > +| 		decrement by 1. 7 is reserved.
> > > +| 	Bit(23) is reserved.
> > > +| 	Bit(22) is the semaphore sync. 0 is post sync, which means that the
> > > +| 		semaphore operation is done after the DMA transfer. 1 is
> > > +| 		presync, which gates the DMA transfer. Only one presync is
> > > +| 		allowed per request.
> > > +| 	Bit(21) is reserved.
> > > +| 	Bits(20:16) is the index of the semaphore to operate on.
> > > +| 	Bits(15:12) are reserved.
> > > +| 	Bits(11:0) are the semaphore value to use in operations.
> > 
> > What about bullet lists?
> 
> It doesn't feel like the above fits into a bullet list structure.  Do you
> have an example reference, or can you transform a small section of the above
> to illustrate what you are thinking?
> 

Oops, sorry for suggesting the wrong construct.

Definition lists fit in this case, since there are request fields along
with their individual descriptions. For bit lists, bullet lists should
suffice.

Here is the illustration diff:

diff --git a/Documentation/accel/qaic/aic100.rst b/Documentation/accel/qaic/aic100.rst
index 7ed95bb164bbeb..4d438fd8121451 100644
--- a/Documentation/accel/qaic/aic100.rst
+++ b/Documentation/accel/qaic/aic100.rst
@@ -308,67 +308,79 @@ A request FIFO element has the following structure:
 
 Request field descriptions:
 
-| req_id- request ID. A request FIFO element and a response FIFO element with
-|         the same request ID refer to the same command.
+  req_id
+      request ID. A request FIFO element and a response FIFO element with
+      the same request ID refer to the same command.
 
-| seq_id- sequence ID within a request. Ignored by the DMA Bridge.
+  seq_id
+      sequence ID within a request. Ignored by the DMA Bridge.
 
-| pcie_dma_cmd- describes the DMA element of this request.
-| 	Bit(7) is the force msi flag, which overrides the DMA Bridge MSI logic
-| 		and generates a MSI when this request is complete, and QSM
-| 		configures the DMA Bridge to look at this bit.
-| 	Bits(6:5) are reserved.
-| 	Bit(4) is the completion code flag, and indicates that the DMA Bridge
-| 		shall generate a response FIFO element when this request is
-| 		complete.
-| 	Bit(3) indicates if this request is a linked list transfer(0) or a bulk
-| 		transfer(1).
-| 	Bit(2) is reserved.
-| 	Bits(1:0) indicate the type of transfer. No transfer(0), to device(1),
-| 		from device(2). Value 3 is illegal.
+  pcie_dma_cmd
+      describes the DMA element of this request.
 
-| pcie_dma_source_addr- source address for a bulk transfer, or the address of
-|         the linked list.
+      * Bit(7) is the force msi flag, which overrides the DMA Bridge MSI logic
+        and generates a MSI when this request is complete, and QSM
+        configures the DMA Bridge to look at this bit.
+      * Bits(6:5) are reserved.
+      * Bit(4) is the completion code flag, and indicates that the DMA Bridge
+        shall generate a response FIFO element when this request is
+        complete.
+      * Bit(3) indicates if this request is a linked list transfer(0) or a bulk
+      * transfer(1).
+      * Bit(2) is reserved.
+      * Bits(1:0) indicate the type of transfer. No transfer(0), to device(1),
+      * from device(2). Value 3 is illegal.
 
-| pcie_dma_dest_addr- destination address for a bulk transfer.
+  pcie_dma_source_addr
+      source address for a bulk transfer, or the address of  the linked list.
 
-| pcie_dma_len- length of the bulk transfer. Note that the size of this field
-| 	limits transfers to 4G in size.
+  pcie_dma_dest_addr
+      destination address for a bulk transfer.
 
-| doorbell_addr- address of the doorbell to ring when this request is complete.
+  pcie_dma_len
+      length of the bulk transfer. Note that the size of this field
+      limits transfers to 4G in size.
 
-| doorbell_attr- doorbell attributes.
-| 	Bit(7) indicates if a write to a doorbell is to occur.
-| 	Bits(6:2) are reserved.
-| 	Bits(1:0) contain the encoding of the doorbell length. 0 is 32-bit,
-| 		1 is 16-bit, 2 is 8-bit, 3 is reserved. The doorbell address
-| 		must be naturally aligned to the specified length.
+  doorbell_addr
+      address of the doorbell to ring when this request is complete.
 
-| doorbell_data- data to write to the doorbell. Only the bits corresponding to
-| 	the doorbell length are valid.
+  doorbell_attr
+      doorbell attributes.
 
-| sem_cmdN- semaphore command.
-| 	Bit(31) indicates this semaphore command is enabled.
-| 	Bit(30) is the to-device DMA fence. Block this request until all
-| 		to-device DMA transfers are complete.
-| 	Bit(29) is the from-device DMA fence. Block this request until all
-| 		from-device DMA transfers are complete.
-| 	Bits(28:27) are reserved.
-| 	Bits(26:24) are the semaphore command. 0 is NOP. 1 is init with the
-| 		specified value. 2 is increment. 3 is decrement. 4 is wait
-| 		until the semaphore is equal to the specified value. 5 is wait
-| 		until the semaphore is greater or equal to the specified value.
-| 		6 is "P", wait until semaphore is greater than 0, then
-| 		decrement by 1. 7 is reserved.
-| 	Bit(23) is reserved.
-| 	Bit(22) is the semaphore sync. 0 is post sync, which means that the
-| 		semaphore operation is done after the DMA transfer. 1 is
-| 		presync, which gates the DMA transfer. Only one presync is
-| 		allowed per request.
-| 	Bit(21) is reserved.
-| 	Bits(20:16) is the index of the semaphore to operate on.
-| 	Bits(15:12) are reserved.
-| 	Bits(11:0) are the semaphore value to use in operations.
+      * Bit(7) indicates if a write to a doorbell is to occur.
+      * Bits(6:2) are reserved.
+      * Bits(1:0) contain the encoding of the doorbell length. 0 is 32-bit,
+        1 is 16-bit, 2 is 8-bit, 3 is reserved. The doorbell address
+        must be naturally aligned to the specified length.
+
+  doorbell_data
+      data to write to the doorbell. Only the bits corresponding to
+      the doorbell length are valid.
+
+  sem_cmdN
+      semaphore command.
+
+      * Bit(31) indicates this semaphore command is enabled.
+      * Bit(30) is the to-device DMA fence. Block this request until all
+        to-device DMA transfers are complete.
+      * Bit(29) is the from-device DMA fence. Block this request until all
+        from-device DMA transfers are complete.
+      * Bits(28:27) are reserved.
+        Bits(26:24) are the semaphore command. 0 is NOP. 1 is init with the
+        specified value. 2 is increment. 3 is decrement. 4 is wait
+        until the semaphore is equal to the specified value. 5 is wait
+        until the semaphore is greater or equal to the specified value.
+        6 is "P", wait until semaphore is greater than 0, then
+        decrement by 1. 7 is reserved.
+      * Bit(23) is reserved.
+      * Bit(22) is the semaphore sync. 0 is post sync, which means that the
+        semaphore operation is done after the DMA transfer. 1 is
+      * presync, which gates the DMA transfer. Only one presync is
+      * allowed per request.
+      * Bit(21) is reserved.
+      * Bits(20:16) is the index of the semaphore to operate on.
+      * Bits(15:12) are reserved.
+      * Bits(11:0) are the semaphore value to use in operations.
 
 Overall, a request is processed in 4 steps:
 

Thanks.

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]