Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
IronPort-SDR: MYSFU5FmslppLimdMQk5NMyyBuI3BAs1awINqShTEP89umAH4srJtsrAY2vGHAriIRBxdbws+a
 AX+jncSKmM6281B8nTWixl63ZawgjF+NYgM3YS99Bhbjd4EB95yknL/Z0N9an9FEkirG69gqo+
 I6RnGbT7hqfPmzdkYi+eyQ23hFyzPf4xGdLkUyuDnIz6MX2znRzP1U3NuFd+1KA0jl1D2PKRWx
 /KEpzmuSYriwLjLvVcQBE32vv2ddZYwFTdgnNOXCVLBjEqBJ+vD1CHWFXoGW7ixu6f6NavOMY6
 8RFASDcThgrWb04aEW2SNeL4
IronPort-SDR: pi4fgVJl1XcqeikW6TDWrVroUY+lhot7Eu/uMHEFa+6jNmJyhQUvfBy7hUhspPlvb769lLkTxV
 OTYOomHnFkVUp/FD51qYt9fnc7eW0uQFydOsF1M0Cy6CK337UQXoIU9hg1dnAXjVNk8Gv2JJz8
 w+AtP+iLpE93fGL+KvNPyzaMJmYs9Skp3cSaHS4ecIy28WUkmuvq1wwP3E6Byvl4LbQ5VPFx8Y
 QopXfXxR16OAUwpx7p3U9GAxjHZk5Sq0ujj6XB4ZTWePpfz8SpRgDQuZblQchcIuNa0zMWyJ3q
 468=
WDCIronportException: Internal
Message-ID: <f560ca8b-d921-d228-64f0-74e320f8af67@opensource.wdc.com>
Date:   Sat, 18 Jun 2022 15:52:28 +0900
MIME-Version: 1.0
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:91.0) Gecko/20100101
 Thunderbird/91.10.0
Subject: Re: [PATCH v4 12/23] ata: libahci: Extend port-cmd flags set with
 port capabilities
Content-Language: en-US
To:     Serge Semin <fancer.lancer@gmail.com>
Cc:     Serge Semin <Sergey.Semin@baikalelectronics.ru>,
        Hans de Goede <hdegoede@redhat.com>,
        Jens Axboe <axboe@kernel.dk>, Hannes Reinecke <hare@suse.de>,
        Alexey Malahov <Alexey.Malahov@baikalelectronics.ru>,
        Pavel Parkhomenko <Pavel.Parkhomenko@baikalelectronics.ru>,
        Rob Herring <robh+dt@kernel.org>, linux-ide@vger.kernel.org,
        linux-kernel@vger.kernel.org, devicetree@vger.kernel.org
References: <20220610081801.11854-1-Sergey.Semin@baikalelectronics.ru>
 <20220610081801.11854-13-Sergey.Semin@baikalelectronics.ru>
 <d06e9910-527e-cfa2-f2df-737fb4799fe5@opensource.wdc.com>
 <20220615205819.uiqptkqm5qfdvrbj@mobilestation>
 <903e273a-9dc5-f0df-5391-e96e63318323@opensource.wdc.com>
 <20220617203100.jg2o7ponolaenf6r@mobilestation>
From:   Damien Le Moal <damien.lemoal@opensource.wdc.com>
Organization: Western Digital Research
In-Reply-To: <20220617203100.jg2o7ponolaenf6r@mobilestation>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit
Precedence: bulk

On 6/18/22 05:31, Serge Semin wrote:
> On Thu, Jun 16, 2022 at 09:28:18AM +0900, Damien Le Moal wrote:
>> On 2022/06/16 5:58, Serge Semin wrote:
>>> On Tue, Jun 14, 2022 at 05:32:41PM +0900, Damien Le Moal wrote:
>>>> On 6/10/22 17:17, Serge Semin wrote:
>>>>> Currently not all of the Port-specific capabilities listed in the
>>>>
>>>> s/listed/are listed
>>>>
>>>>> PORT_CMD-enumeration. Let's extend that set with the Cold Presence
>>>>> Detection and Mechanical Presence Switch attached to the Port flags [1] so
>>>>> to closeup the set of the platform-specific port-capabilities flags.  Note
>>>>> these flags are supposed to be set by the platform firmware if there is
>>>>> one. Alternatively as we are about to do they can be set by means of the
>>>>> OF properties.
>>>>>
>>>>> While at it replace PORT_IRQ_DEV_ILCK with PORT_IRQ_DMPS and fix the
>>>>> comment there. In accordance with [2] that IRQ flag is supposed to
>>>>> indicate the state of the signal coming from the Mechanical Presence
>>>>> Switch.
>>>>>
>>>>> [1] Serial ATA AHCI 1.3.1 Specification, p.27
>>>>> [2] Serial ATA AHCI 1.3.1 Specification, p.24, p.88
>>>>>
>>>>> Signed-off-by: Serge Semin <Sergey.Semin@baikalelectronics.ru>
>>>>> Reviewed-by: Hannes Reinecke <hare@suse.de>
>>>>>
>>>>> ---
>>>>>
>>>>> Changelog v4:
>>>>> - Fix the DMPS macros name in the patch log. (@Sergei Shtylyov)
>>>>> ---
>>>>>  drivers/ata/ahci.h | 7 ++++++-
>>>>>  1 file changed, 6 insertions(+), 1 deletion(-)
>>>>>
>>>>> diff --git a/drivers/ata/ahci.h b/drivers/ata/ahci.h
>>>>> index 7d834deefeb9..f501531bd1b3 100644
>>>>> --- a/drivers/ata/ahci.h
>>>>> +++ b/drivers/ata/ahci.h
>>>>> @@ -138,7 +138,7 @@ enum {
>>>>>  	PORT_IRQ_BAD_PMP	= (1 << 23), /* incorrect port multiplier */
>>>>>  
>>>>>  	PORT_IRQ_PHYRDY		= (1 << 22), /* PhyRdy changed */
>>>>> -	PORT_IRQ_DEV_ILCK	= (1 << 7), /* device interlock */
>>>>> +	PORT_IRQ_DMPS		= (1 << 7), /* mechanical presence status */
>>>>>  	PORT_IRQ_CONNECT	= (1 << 6), /* port connect change status */
>>>>>  	PORT_IRQ_SG_DONE	= (1 << 5), /* descriptor processed */
>>>>>  	PORT_IRQ_UNK_FIS	= (1 << 4), /* unknown FIS rx'd */
>>>>> @@ -166,6 +166,8 @@ enum {
>>>>>  	PORT_CMD_ATAPI		= (1 << 24), /* Device is ATAPI */
>>>>>  	PORT_CMD_FBSCP		= (1 << 22), /* FBS Capable Port */
>>>>>  	PORT_CMD_ESP		= (1 << 21), /* External Sata Port */
>>>>> +	PORT_CMD_CPD		= (1 << 20), /* Cold Presence Detection */
>>>>> +	PORT_CMD_MPSP		= (1 << 19), /* Mechanical Presence Switch */
>>>>>  	PORT_CMD_HPCP		= (1 << 18), /* HotPlug Capable Port */
>>>>>  	PORT_CMD_PMP		= (1 << 17), /* PMP attached */
>>>>>  	PORT_CMD_LIST_ON	= (1 << 15), /* cmd list DMA engine running */
>>>>> @@ -181,6 +183,9 @@ enum {
>>>>>  	PORT_CMD_ICC_PARTIAL	= (0x2 << 28), /* Put i/f in partial state */
>>>>>  	PORT_CMD_ICC_SLUMBER	= (0x6 << 28), /* Put i/f in slumber state */
>>>>>  
>>>>> +	PORT_CMD_CAP		= PORT_CMD_HPCP | PORT_CMD_MPSP |
>>>>> +				  PORT_CMD_CPD | PORT_CMD_ESP | PORT_CMD_FBSCP,
>>>>
>>>
>>>> What is this one for ? A comment above it would be nice.
>>>
>>> Isn't it obviously inferrable from the definition and the item name?
>>
> 
>> I am guessing from the name. Am I guessing OK ? A comment would still be nice.
>> Why just these bits ? There are more cap/support indicator bits in that port cmd
>> bitfield. So why this particular set of bits ? What do they mean all together ?
> 
> Normally the variable/constant name should be self-content (as the
> kernel coding style doc states and what the common sense suggests). So
> the reader could correctly guess its purpose/content/value. In this
> case PORT_CMD_CAP - means PORT CMD capabilities mask. All of the
> possible flags have been set in that mask. There are no more
> capabilities in the PORT CMD register left undeclared. That's why the
> name is selected the way it is and why I haven't added any comment in
> here (what the kernel coding style says about the over-commenting the
> code).

Yes, I understood from the name what it is. What I do NOT understand is
why all the feature bits are not there. Why this subset only ? A comment
about that would be nice so that the reason for it is not lost.

> 
>>
>> Sure I can go and read the specs to figure it out. But again, a comment would
>> avoid readers of the code to have to decrypt all that.
> 
> If you still insist on having an additional comment. I can add
> something like "/* PORT_CMD capabilities mask */". Are you ok with it?

That does not help on its own. The macro name says that already. I would
like a note about why only these features are selected.

> 
> -Sergey
> 
>>
>>>
>>> -Sergey
>>>
>>>>
>>>>> +
>>>>>  	/* PORT_FBS bits */
>>>>>  	PORT_FBS_DWE_OFFSET	= 16, /* FBS device with error offset */
>>>>>  	PORT_FBS_ADO_OFFSET	= 12, /* FBS active dev optimization offset */
>>>>
>>>>
>>>> -- 
>>>> Damien Le Moal
>>>> Western Digital Research
>>
>>
>> -- 
>> Damien Le Moal
>> Western Digital Research


-- 
Damien Le Moal
Western Digital Research