Re: [PATCH V2 1/2] Documentation: DT: Add binding documentation for NVIDIA ADMA

[Jon Hunter <jonathanh@nvidia.com>]

On 07/10/15 20:36, Stephen Warren wrote:
> On 10/07/2015 10:19 AM, Jon Hunter wrote:
>>
>> On 07/10/15 17:09, Stephen Warren wrote:
>>> On 10/07/2015 02:43 AM, Jon Hunter wrote:
>>>>
>>>> On 07/10/15 00:04, Stephen Warren wrote:
>>>>> On 10/05/2015 06:10 AM, Jon Hunter wrote:
>>>>>> Add device-tree binding documentation for the Tegra210 Audio DMA
>>>>>> controller.
>>>>>
>>>>>> diff --git a/Documentation/devicetree/bindings/dma/tegra210-adma.txt
>>>>>> b/Documentation/devicetree/bindings/dma/tegra210-adma.txt
>>>>>
>>>>>> +- #dma-cells : Must be <2>. The first cell denotes the transmit or
>>>>>> +  receive request number and should be between 1 and the maximum
>>>>>> number
>>>>>> +  of requests supported (see properties "dma-rx-requests" and
>>>>>> +  "dma-tx-requests"). This value corresponds to the
>>>>>> RX/TX_REQUEST_SELECT
>>>>>> +  fields in the ADMA_CHn_CTRL register. The second cell denotes
>>>>>> whether
>>>>>> +  the channel is a receive or transmit channel and must be either 2
>>>>>> for
>>>>>> +  a receive channel and 4 for a transmit channel. These values
>>>>>> correspond
>>>>>> +  to the TRANSFER_DIRECTION field of the ADMA_CHn_CTRL register.
>>>>>
>>>>> Is it typical to encode the direction into the dma cells? I would have
>>>>> thought the client would provide that information at run-time when
>>>>> requesting a DMA channel.
>>>>
>>>> I have seen other dma bindings that do [0]. If we don't put the
>>>> direction in the client binding, then it would appear as ...
>>>>
>>>> tegra_admaif: admaif@0x702d0000 {
>>>>       ...
>>>>       dmas = <&adma 1>, <&adma 1>, <&adma 2>, <&adma 2>,
>>>>              <&adma 3>, <&adma 3>, <&adma 4>, <&adma 4>,
>>>>              <&adma 5>, <&adma 5>, <&adma 6>, <&adma 6>,
>>>>              <&adma 7>, <&adma 7>, <&adma 8>, <&adma 8>,
>>>>              <&adma 9>, <&adma 9>, <&adma 10>, <&adma 10>;
>>>>       dma-names = "rx1", "tx1", "rx2", "tx2", "rx3", "tx3",
>>>>                   "rx4", "tx4", "rx5", "tx5", "rx6", "tx6",
>>>>                   "rx7", "tx7", "rx8", "tx8", "rx9", "tx9",
>>>>                   "rx10", "tx10";
>>>>       ...
>>>> };
>>>>
>>>> ... where "rxN" and "txN" appear to use the same request, but the
>>>> reality is that "rxN" is using rx-request-N and "txN" is using
>>>> tx-request-N. Arnd questioned this before. Obviously I can explain this
>>>> in the binding document if the above is preferred. However, given that
>>>> they are named "rx1", "rx2", etc, why not put the direction in the
>>>> binding?
>>>
>>> Why would we need to duplicate the request IDs? I'd expect to have the
>>> following property content:
>>>
>>> dmas = <&adma 1>, <&adma 2>, <&adma 3>, ...;
>>> dma-names = "1", "2", "3"...;
>>>
>>> *and* not have a cell to represent the direction in DT. After all, the
>>> direction of the channel is 100% implied by the use-case (and hence
>>> defined by the DMA client's own DT binding); it is known by the client
>>> driver and can be supplied at run-time.
>>
>> Right, but what does the 1, 2, 3, etc in the specifier represent?
> 
> Aren't they the ADMAIF FIFO IDs?

Yes.

> We know the set/number of ADMAIF FIFOs, and each FIFO needs a request
> selector ID. The list of those can be indexed by the identity of the
> FIFO that is accessed via DMA.

Right, but you have 10 RX FIFOs and 10 TX FIFOs. The FIFOs are
unidirectional. This means that instead of having 20 FIFOs from 1-20
(yes the FIFOs start from 1 and not 0), you have RX FIFOs from 1-10 and
TX FIFOs from 1-10.

> Thinking about this more, I think actually that the dmas/dma-names
> property example that you posted above is exactly what is required here.

Ok, good.

> The counter-example I wrote makes this assumption and hence is invalid.
> The ADMAIF binding should not assume that the RX and TX request selector
> IDs are identical. As such, dmas/dma-names should have both an RX and TX
> entry for each ADMAIF FIFO.

Yes.

> Still, there's no need to encode the DMA direction into the #dma-cells.
> The client code will know that if it wants to configure DMA into (TX to)
> FIFO ID 5, it must query dma-names entry "tx5", and simply use whatever
> is in the DT. When it passes that DMA specifier to the DMA API, the
> ADMAIF driver knows that it will be for TX, and can pass that
> information to the DMA code.

That's fine. From my perspective I don't have a strong objection either
way, however, I can see that given that the name indicates rx or tx,
then the direction in the binding could be seen as redundant.

So to confirm you are happy with the client bindings being as follows?

tegra_admaif: admaif@0x702d0000 {
      ...
     dmas = <&adma 1>, <&adma 1>, <&adma 2>, <&adma 2>,
            <&adma 3>, <&adma 3>, <&adma 4>, <&adma 4>,
            <&adma 5>, <&adma 5>, <&adma 6>, <&adma 6>,
            <&adma 7>, <&adma 7>, <&adma 8>, <&adma 8>,
            <&adma 9>, <&adma 9>, <&adma 10>, <&adma 10>;
     dma-names = "rx1", "tx1", "rx2", "tx2", "rx3", "tx3",
                 "rx4", "tx4", "rx5", "tx5", "rx6", "tx6",
                 "rx7", "tx7", "rx8", "tx8", "rx9", "tx9",
                 "rx10", "tx10";
     ...
};

Jon