Re: [PATCH v5 7/8] device-dax: ensure dev_dax->pgmap is valid for dynamic devices

[Joao Martins <joao.m.martins@oracle.com>]

On 11/17/21 10:37, Christoph Hellwig wrote:
>> +bool static_dev_dax(struct dev_dax *dev_dax)
>> +{
>> +	return is_static(dev_dax->region);
>> +}
>> +EXPORT_SYMBOL_GPL(static_dev_dax);
> 
> This function would massively benefit from documentic what a static
> DAX region is and why someone would want to care.  Because even as
> someone occasionally dabbling with the DAX code I have no idea at all
> what that means.
> 
Good idea.

Maybe something like this:

diff --git a/drivers/dax/bus.c b/drivers/dax/bus.c
index 19dd83d3f3ea..8be6ec1ba193 100644
--- a/drivers/dax/bus.c
+++ b/drivers/dax/bus.c
@@ -129,6 +129,19 @@ ATTRIBUTE_GROUPS(dax_drv);

 static int dax_bus_match(struct device *dev, struct device_driver *drv);

+/*
+ * Static dax regions (PMEM) are regions partitioned by an external entity like
+ * nvdimm where a single range is assigned and which boundaries are
+ * defined by NVDIMM Namespace boundaries (e.g. need to be contiguous).
+ * Dynamic dax regions (HMEM), the assigned region can be subdivided by dax
+ * core into multiple devices (i.e. "partitions") which are composed with 1 or
+ * more discontiguous ranges.
+ * When allocating a dax region, drivers must set whether it's static.
+ * On static dax devices, the @pgmap is pre-assigned to dax when calling
+ * devm_create_dev_dax(), whereas in dynamic dax devices it is allocated
+ * on device ->probe(). Care is needed to make sure that non static devices
+ * are killed with a cleared @pgmap field (see kill_dev_dax()).
+ */
 static bool is_static(struct dax_region *dax_region)
 {
        return (dax_region->res.flags & IORESOURCE_DAX_STATIC) != 0;