Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::3:6 as permitted sender) client-ip=2620:137:e000::3:6;
Date:   Wed, 13 Dec 2023 16:50:52 +0000
From:   Jonathan Cameron <Jonathan.Cameron@Huawei.com>
To:     Vishal Verma <vishal.l.verma@intel.com>
CC:     Dan Williams <dan.j.williams@intel.com>,
        Dave Jiang <dave.jiang@intel.com>,
        <linux-kernel@vger.kernel.org>, <nvdimm@lists.linux.dev>,
        <linux-cxl@vger.kernel.org>, David Hildenbrand <david@redhat.com>,
        Dave Hansen <dave.hansen@linux.intel.com>,
        Huang Ying <ying.huang@intel.com>
Subject: Re: [PATCH v4 1/3] Documentatiion/ABI: Add ABI documentation for
 sys-bus-dax
Message-ID: <20231213165052.00007d74@Huawei.com>
In-Reply-To: <20231212-vv-dax_abi-v4-1-1351758f0c92@intel.com>
References: <20231212-vv-dax_abi-v4-0-1351758f0c92@intel.com>
        <20231212-vv-dax_abi-v4-1-1351758f0c92@intel.com>
Organization: Huawei Technologies Research and Development (UK) Ltd.
MIME-Version: 1.0
Content-Type: text/plain; charset="US-ASCII"
Content-Transfer-Encoding: 7bit
Precedence: bulk

On Tue, 12 Dec 2023 12:08:30 -0700
Vishal Verma <vishal.l.verma@intel.com> wrote:

> Add the missing sysfs ABI documentation for the device DAX subsystem.
> Various ABI attributes under this have been present since v5.1, and more
> have been added over time. In preparation for adding a new attribute,
> add this file with the historical details.
> 
> Cc: Dan Williams <dan.j.williams@intel.com>
> Signed-off-by: Vishal Verma <vishal.l.verma@intel.com>

Hi Vishal,  One editorial suggestions.

I don't know the interface well enough to do a good review of the content
so leaving that for Dan or others.

> +What:		/sys/bus/dax/devices/daxX.Y/mapping[0..N]/start
> +Date:		October, 2020
> +KernelVersion:	v5.10
> +Contact:	nvdimm@lists.linux.dev
> +Description:
> +		(RO) A dax device may have multiple constituent discontiguous
> +		address ranges. These are represented by the different
> +		'mappingX' subdirectories. The 'start' attribute indicates the
> +		start physical address for the given range.

A common option for these files is to have a single entry with two What:
lines.  Here that would avoid duplication of majority of this text across
the start, end  and page_offset entries.  Alternatively you could do an
entry for the mapping[0..N] directory with the shared text then separate
entries for the 3 files under there.


> +
> +What:		/sys/bus/dax/devices/daxX.Y/mapping[0..N]/end
> +Date:		October, 2020
> +KernelVersion:	v5.10
> +Contact:	nvdimm@lists.linux.dev
> +Description:
> +		(RO) A dax device may have multiple constituent discontiguous
> +		address ranges. These are represented by the different
> +		'mappingX' subdirectories. The 'end' attribute indicates the
> +		end physical address for the given range.
> +
> +What:		/sys/bus/dax/devices/daxX.Y/mapping[0..N]/page_offset
> +Date:		October, 2020
> +KernelVersion:	v5.10
> +Contact:	nvdimm@lists.linux.dev
> +Description:
> +		(RO) A dax device may have multiple constituent discontiguous
> +		address ranges. These are represented by the different
> +		'mappingX' subdirectories. The 'page_offset' attribute indicates the
> +		offset of the current range in the dax device.