[PATCH v4 1/8] accel/qaic: Add documentation for AIC100 accelerator driver
Jeffrey Hugo
quic_jhugo at quicinc.com
Wed Mar 22 15:22:13 UTC 2023
On 3/21/2023 10:39 PM, Bagas Sanjaya wrote:
> 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.
Ok. This is making sense to me. Thanks for the clarification. I'll
give this a try.
-Jeff
More information about the dri-devel
mailing list