docs/nvdimm: add example on persistent backend setup
diff mbox series

Message ID 20190724070307.12568-1-richardw.yang@linux.intel.com
State New
Headers show
Series
  • docs/nvdimm: add example on persistent backend setup
Related show

Commit Message

Wei Yang July 24, 2019, 7:03 a.m. UTC
Persistent backend setup requires some knowledge about nvdimm and ndctl
tool. Some users report they may struggle to gather these knowledge and
have difficulty to setup it properly.

Here we provide two examples for persistent backend and gives the link
to ndctl. By doing so, user could try it directly and do more
investigation on persistent backend setup with ndctl.

Signed-off-by: Wei Yang <richardw.yang@linux.intel.com>
---
 docs/nvdimm.txt | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

Comments

Pankaj Gupta July 24, 2019, 7:28 a.m. UTC | #1
> 
> Persistent backend setup requires some knowledge about nvdimm and ndctl
> tool. Some users report they may struggle to gather these knowledge and
> have difficulty to setup it properly.
> 
> Here we provide two examples for persistent backend and gives the link
> to ndctl. By doing so, user could try it directly and do more
> investigation on persistent backend setup with ndctl.
> 
> Signed-off-by: Wei Yang <richardw.yang@linux.intel.com>
> ---
>  docs/nvdimm.txt | 28 ++++++++++++++++++++++++++++
>  1 file changed, 28 insertions(+)
> 
> diff --git a/docs/nvdimm.txt b/docs/nvdimm.txt
> index b531cacd35..baba7a940d 100644
> --- a/docs/nvdimm.txt
> +++ b/docs/nvdimm.txt
> @@ -171,6 +171,32 @@ guest software that this vNVDIMM device contains a
> region that cannot
>  accept persistent writes. In result, for example, the guest Linux
>  NVDIMM driver, marks such vNVDIMM device as read-only.
>  
> +Backend File Setup Example
> +..........................
> +
> +Here is two examples for how to setup these persistent backend on
> +linux, which leverages the tool ndctl [3].
> +
> +It is easy to setup DAX device backend file.
> +
> +A. DAX device
> +
> +    ndctl create-namespace -f -e namespace0.0 -m devdax
> +
> +The /dev/dax0.0 could be used directly in "mem-path" option.
> +
> +For DAX file, it is more than creating the proper namespace. The
> +block device should be partitioned and mounted (with dax option).
> +
> +B. DAX file
> +
> +    ndctl create-namespace -f -e namespace0.0 -m fsdax
> +    (partition /dev/pmem0 with name pmem0p1)
> +    mount -o dax /dev/pmem0p1 /mnt
> +    (dd a file with proper size in /mnt)

This namespace is for filesystem DAX? What if user wants to create namespace for
device DAX to be used as persistent backend?

Does this makes sense to mention about by default namespace created on persistent
backend?

Thanks,
Pankaj

> +
> +Then the new file in /mnt could be used in "mem-path" option.
> +
>  NVDIMM Persistence
>  ------------------
>  
> @@ -212,3 +238,5 @@ References
>      https://www.snia.org/sites/default/files/technical_work/final/NVMProgrammingModel_v1.2.pdf
>  [2] Persistent Memory Development Kit (PMDK), formerly known as NVML
>  project, home page:
>      http://pmem.io/pmdk/
> +[3] ndctl-create-namespace - provision or reconfigure a namespace
> +    http://pmem.io/ndctl/ndctl-create-namespace.html
> --
> 2.17.1
> 
> 
>
Wei Yang July 24, 2019, 8:53 a.m. UTC | #2
On Wed, Jul 24, 2019 at 03:28:22AM -0400, Pankaj Gupta wrote:
>
>> 
>> Persistent backend setup requires some knowledge about nvdimm and ndctl
>> tool. Some users report they may struggle to gather these knowledge and
>> have difficulty to setup it properly.
>> 
>> Here we provide two examples for persistent backend and gives the link
>> to ndctl. By doing so, user could try it directly and do more
>> investigation on persistent backend setup with ndctl.
>> 
>> Signed-off-by: Wei Yang <richardw.yang@linux.intel.com>
>> ---
>>  docs/nvdimm.txt | 28 ++++++++++++++++++++++++++++
>>  1 file changed, 28 insertions(+)
>> 
>> diff --git a/docs/nvdimm.txt b/docs/nvdimm.txt
>> index b531cacd35..baba7a940d 100644
>> --- a/docs/nvdimm.txt
>> +++ b/docs/nvdimm.txt
>> @@ -171,6 +171,32 @@ guest software that this vNVDIMM device contains a
>> region that cannot
>>  accept persistent writes. In result, for example, the guest Linux
>>  NVDIMM driver, marks such vNVDIMM device as read-only.
>>  
>> +Backend File Setup Example
>> +..........................
>> +
>> +Here is two examples for how to setup these persistent backend on
>> +linux, which leverages the tool ndctl [3].
>> +
>> +It is easy to setup DAX device backend file.
>> +
>> +A. DAX device
>> +
>> +    ndctl create-namespace -f -e namespace0.0 -m devdax
>> +
>> +The /dev/dax0.0 could be used directly in "mem-path" option.
>> +
>> +For DAX file, it is more than creating the proper namespace. The
>> +block device should be partitioned and mounted (with dax option).
>> +
>> +B. DAX file
>> +
>> +    ndctl create-namespace -f -e namespace0.0 -m fsdax
>> +    (partition /dev/pmem0 with name pmem0p1)
>> +    mount -o dax /dev/pmem0p1 /mnt
>> +    (dd a file with proper size in /mnt)
>

Hi, Pankaj

Thanks for your comment.

>This namespace is for filesystem DAX? What if user wants to create namespace for
>device DAX to be used as persistent backend?
>

User could choose the type (devdax/fsdax) in ndctl command line with -m
option.

>Does this makes sense to mention about by default namespace created on persistent
>backend?
>

I don't get your point. Here is an example to let user know how to create
persistent backend. In case they want to get more control about the backend,
they can refer to the ndctl link. 

You mean it is not proper to mention the backend setup example in the
document? We found many users come to us for how to setup it, so we decide to
add this section.

Do you have other option?

>Thanks,
>Pankaj
>
>> +
>> +Then the new file in /mnt could be used in "mem-path" option.
>> +
>>  NVDIMM Persistence
>>  ------------------
>>  
>> @@ -212,3 +238,5 @@ References
>>      https://www.snia.org/sites/default/files/technical_work/final/NVMProgrammingModel_v1.2.pdf
>>  [2] Persistent Memory Development Kit (PMDK), formerly known as NVML
>>  project, home page:
>>      http://pmem.io/pmdk/
>> +[3] ndctl-create-namespace - provision or reconfigure a namespace
>> +    http://pmem.io/ndctl/ndctl-create-namespace.html
>> --
>> 2.17.1
>> 
>> 
>>
Pankaj Gupta July 24, 2019, 10:08 a.m. UTC | #3
> >
> >> 
> >> Persistent backend setup requires some knowledge about nvdimm and ndctl
> >> tool. Some users report they may struggle to gather these knowledge and
> >> have difficulty to setup it properly.
> >> 
> >> Here we provide two examples for persistent backend and gives the link
> >> to ndctl. By doing so, user could try it directly and do more
> >> investigation on persistent backend setup with ndctl.
> >> 
> >> Signed-off-by: Wei Yang <richardw.yang@linux.intel.com>
> >> ---
> >>  docs/nvdimm.txt | 28 ++++++++++++++++++++++++++++
> >>  1 file changed, 28 insertions(+)
> >> 
> >> diff --git a/docs/nvdimm.txt b/docs/nvdimm.txt
> >> index b531cacd35..baba7a940d 100644
> >> --- a/docs/nvdimm.txt
> >> +++ b/docs/nvdimm.txt
> >> @@ -171,6 +171,32 @@ guest software that this vNVDIMM device contains a
> >> region that cannot
> >>  accept persistent writes. In result, for example, the guest Linux
> >>  NVDIMM driver, marks such vNVDIMM device as read-only.
> >>  
> >> +Backend File Setup Example
> >> +..........................
> >> +
> >> +Here is two examples for how to setup these persistent backend on
> >> +linux, which leverages the tool ndctl [3].
> >> +
> >> +It is easy to setup DAX device backend file.
> >> +
> >> +A. DAX device
> >> +
> >> +    ndctl create-namespace -f -e namespace0.0 -m devdax
> >> +
> >> +The /dev/dax0.0 could be used directly in "mem-path" option.
> >> +
> >> +For DAX file, it is more than creating the proper namespace. The
> >> +block device should be partitioned and mounted (with dax option).
> >> +
> >> +B. DAX file
> >> +
> >> +    ndctl create-namespace -f -e namespace0.0 -m fsdax
> >> +    (partition /dev/pmem0 with name pmem0p1)
> >> +    mount -o dax /dev/pmem0p1 /mnt
> >> +    (dd a file with proper size in /mnt)
> >
> 
> Hi, Pankaj
> 
> Thanks for your comment.
> 
> >This namespace is for filesystem DAX? What if user wants to create namespace
> >for
> >device DAX to be used as persistent backend?
> >
> 
> User could choose the type (devdax/fsdax) in ndctl command line with -m
> option.

yes.

> 
> >Does this makes sense to mention about by default namespace created on
> >persistent
> >backend?
> >
> 
> I don't get your point. Here is an example to let user know how to create
> persistent backend. In case they want to get more control about the backend,
> they can refer to the ndctl link.

I agree this is helpful for users. 

> 
> You mean it is not proper to mention the backend setup example in the
> document? We found many users come to us for how to setup it, so we decide to
> add this section.

Sorry! For some reason I ignored devicedax namespace information in patch.
The patch looks good to me and I agree its helpful for the users.
   

Thanks,
Pankaj

> 
> Do you have other option?
> 
> >Thanks,
> >Pankaj
> >
> >> +
> >> +Then the new file in /mnt could be used in "mem-path" option.
> >> +
> >>  NVDIMM Persistence
> >>  ------------------
> >>  
> >> @@ -212,3 +238,5 @@ References
> >>      https://www.snia.org/sites/default/files/technical_work/final/NVMProgrammingModel_v1.2.pdf
> >>  [2] Persistent Memory Development Kit (PMDK), formerly known as NVML
> >>  project, home page:
> >>      http://pmem.io/pmdk/
> >> +[3] ndctl-create-namespace - provision or reconfigure a namespace
> >> +    http://pmem.io/ndctl/ndctl-create-namespace.html
> >> --
> >> 2.17.1
> >> 
> >> 
> >> 
> 
> --
> Wei Yang
> Help you, Help me
> 
>
Pankaj Gupta July 24, 2019, 10:17 a.m. UTC | #4
> 
> Persistent backend setup requires some knowledge about nvdimm and ndctl
> tool. Some users report they may struggle to gather these knowledge and
> have difficulty to setup it properly.
> 
> Here we provide two examples for persistent backend and gives the link
> to ndctl. By doing so, user could try it directly and do more
> investigation on persistent backend setup with ndctl.
> 
> Signed-off-by: Wei Yang <richardw.yang@linux.intel.com>
> ---
>  docs/nvdimm.txt | 28 ++++++++++++++++++++++++++++
>  1 file changed, 28 insertions(+)
> 
> diff --git a/docs/nvdimm.txt b/docs/nvdimm.txt
> index b531cacd35..baba7a940d 100644
> --- a/docs/nvdimm.txt
> +++ b/docs/nvdimm.txt
> @@ -171,6 +171,32 @@ guest software that this vNVDIMM device contains a
> region that cannot
>  accept persistent writes. In result, for example, the guest Linux
>  NVDIMM driver, marks such vNVDIMM device as read-only.
>  
> +Backend File Setup Example
> +..........................
> +
> +Here is two examples for how to setup these persistent backend on
> +linux, which leverages the tool ndctl [3].
> +
> +It is easy to setup DAX device backend file.
> +
> +A. DAX device
> +
> +    ndctl create-namespace -f -e namespace0.0 -m devdax
> +
> +The /dev/dax0.0 could be used directly in "mem-path" option.
> +
> +For DAX file, it is more than creating the proper namespace. The
> +block device should be partitioned and mounted (with dax option).
> +
> +B. DAX file
> +
> +    ndctl create-namespace -f -e namespace0.0 -m fsdax
> +    (partition /dev/pmem0 with name pmem0p1)
> +    mount -o dax /dev/pmem0p1 /mnt
> +    (dd a file with proper size in /mnt)

This is not clear to me. why 'dd' file is required in /mnt?
You mean for creating a backend file?

> +
> +Then the new file in /mnt could be used in "mem-path" option.
> +
>  NVDIMM Persistence
>  ------------------
>  
> @@ -212,3 +238,5 @@ References
>      https://www.snia.org/sites/default/files/technical_work/final/NVMProgrammingModel_v1.2.pdf
>  [2] Persistent Memory Development Kit (PMDK), formerly known as NVML
>  project, home page:
>      http://pmem.io/pmdk/
> +[3] ndctl-create-namespace - provision or reconfigure a namespace
> +    http://pmem.io/ndctl/ndctl-create-namespace.html
> --

Looks good to me. Just a small comment above. 
Other than that: Reviewed-by: Pankaj Gupta <pagupta@redhat.com>

> 2.17.1
> 
> 
>
Wei Yang July 24, 2019, 2:52 p.m. UTC | #5
On Wed, Jul 24, 2019 at 06:17:31AM -0400, Pankaj Gupta wrote:
>
>> 
>> Persistent backend setup requires some knowledge about nvdimm and ndctl
>> tool. Some users report they may struggle to gather these knowledge and
>> have difficulty to setup it properly.
>> 
>> Here we provide two examples for persistent backend and gives the link
>> to ndctl. By doing so, user could try it directly and do more
>> investigation on persistent backend setup with ndctl.
>> 
>> Signed-off-by: Wei Yang <richardw.yang@linux.intel.com>
>> ---
>>  docs/nvdimm.txt | 28 ++++++++++++++++++++++++++++
>>  1 file changed, 28 insertions(+)
>> 
>> diff --git a/docs/nvdimm.txt b/docs/nvdimm.txt
>> index b531cacd35..baba7a940d 100644
>> --- a/docs/nvdimm.txt
>> +++ b/docs/nvdimm.txt
>> @@ -171,6 +171,32 @@ guest software that this vNVDIMM device contains a
>> region that cannot
>>  accept persistent writes. In result, for example, the guest Linux
>>  NVDIMM driver, marks such vNVDIMM device as read-only.
>>  
>> +Backend File Setup Example
>> +..........................
>> +
>> +Here is two examples for how to setup these persistent backend on
>> +linux, which leverages the tool ndctl [3].
>> +
>> +It is easy to setup DAX device backend file.
>> +
>> +A. DAX device
>> +
>> +    ndctl create-namespace -f -e namespace0.0 -m devdax
>> +
>> +The /dev/dax0.0 could be used directly in "mem-path" option.
>> +
>> +For DAX file, it is more than creating the proper namespace. The
>> +block device should be partitioned and mounted (with dax option).
>> +
>> +B. DAX file
>> +
>> +    ndctl create-namespace -f -e namespace0.0 -m fsdax
>> +    (partition /dev/pmem0 with name pmem0p1)
>> +    mount -o dax /dev/pmem0p1 /mnt
>> +    (dd a file with proper size in /mnt)
>
>This is not clear to me. why 'dd' file is required in /mnt?
>You mean for creating a backend file?
>

Yes, create a backend file. You need to give a file instead of a directory to
qemu command line.

>> +
>> +Then the new file in /mnt could be used in "mem-path" option.
>> +
>>  NVDIMM Persistence
>>  ------------------
>>  
>> @@ -212,3 +238,5 @@ References
>>      https://www.snia.org/sites/default/files/technical_work/final/NVMProgrammingModel_v1.2.pdf
>>  [2] Persistent Memory Development Kit (PMDK), formerly known as NVML
>>  project, home page:
>>      http://pmem.io/pmdk/
>> +[3] ndctl-create-namespace - provision or reconfigure a namespace
>> +    http://pmem.io/ndctl/ndctl-create-namespace.html
>> --
>
>Looks good to me. Just a small comment above. 
>Other than that: Reviewed-by: Pankaj Gupta <pagupta@redhat.com>
>

Thanks

>> 2.17.1
>> 
>> 
>>
Pankaj Gupta July 25, 2019, 4:43 a.m. UTC | #6
> >
> >> 
> >> Persistent backend setup requires some knowledge about nvdimm and ndctl
> >> tool. Some users report they may struggle to gather these knowledge and
> >> have difficulty to setup it properly.
> >> 
> >> Here we provide two examples for persistent backend and gives the link
> >> to ndctl. By doing so, user could try it directly and do more
> >> investigation on persistent backend setup with ndctl.
> >> 
> >> Signed-off-by: Wei Yang <richardw.yang@linux.intel.com>
> >> ---
> >>  docs/nvdimm.txt | 28 ++++++++++++++++++++++++++++
> >>  1 file changed, 28 insertions(+)
> >> 
> >> diff --git a/docs/nvdimm.txt b/docs/nvdimm.txt
> >> index b531cacd35..baba7a940d 100644
> >> --- a/docs/nvdimm.txt
> >> +++ b/docs/nvdimm.txt
> >> @@ -171,6 +171,32 @@ guest software that this vNVDIMM device contains a
> >> region that cannot
> >>  accept persistent writes. In result, for example, the guest Linux
> >>  NVDIMM driver, marks such vNVDIMM device as read-only.
> >>  
> >> +Backend File Setup Example
> >> +..........................
> >> +
> >> +Here is two examples for how to setup these persistent backend on
> >> +linux, which leverages the tool ndctl [3].
> >> +
> >> +It is easy to setup DAX device backend file.
> >> +
> >> +A. DAX device
> >> +
> >> +    ndctl create-namespace -f -e namespace0.0 -m devdax
> >> +
> >> +The /dev/dax0.0 could be used directly in "mem-path" option.
> >> +
> >> +For DAX file, it is more than creating the proper namespace. The
> >> +block device should be partitioned and mounted (with dax option).
> >> +
> >> +B. DAX file
> >> +
> >> +    ndctl create-namespace -f -e namespace0.0 -m fsdax
> >> +    (partition /dev/pmem0 with name pmem0p1)
> >> +    mount -o dax /dev/pmem0p1 /mnt
> >> +    (dd a file with proper size in /mnt)
> >
> >This is not clear to me. why 'dd' file is required in /mnt?
> >You mean for creating a backend file?
> >
> 
> Yes, create a backend file. You need to give a file instead of a directory to
> qemu command line.
o.k

Thanks,
Pankaj 
> 
> >> +
> >> +Then the new file in /mnt could be used in "mem-path" option.
> >> +
> >>  NVDIMM Persistence
> >>  ------------------
> >>  
> >> @@ -212,3 +238,5 @@ References
> >>      https://www.snia.org/sites/default/files/technical_work/final/NVMProgrammingModel_v1.2.pdf
> >>  [2] Persistent Memory Development Kit (PMDK), formerly known as NVML
> >>  project, home page:
> >>      http://pmem.io/pmdk/
> >> +[3] ndctl-create-namespace - provision or reconfigure a namespace
> >> +    http://pmem.io/ndctl/ndctl-create-namespace.html
> >> --
> >
> >Looks good to me. Just a small comment above.
> >Other than that: Reviewed-by: Pankaj Gupta <pagupta@redhat.com>
> >
> 
> Thanks
> 
> >> 2.17.1
> >> 
> >> 
> >> 
> 
> --
> Wei Yang
> Help you, Help me
> 
>
Pankaj Gupta July 25, 2019, 4:46 a.m. UTC | #7
> 
> Persistent backend setup requires some knowledge about nvdimm and ndctl
> tool. Some users report they may struggle to gather these knowledge and
> have difficulty to setup it properly.
> 
> Here we provide two examples for persistent backend and gives the link
> to ndctl. By doing so, user could try it directly and do more
> investigation on persistent backend setup with ndctl.
> 
> Signed-off-by: Wei Yang <richardw.yang@linux.intel.com>
> ---
>  docs/nvdimm.txt | 28 ++++++++++++++++++++++++++++
>  1 file changed, 28 insertions(+)
> 
> diff --git a/docs/nvdimm.txt b/docs/nvdimm.txt
> index b531cacd35..baba7a940d 100644
> --- a/docs/nvdimm.txt
> +++ b/docs/nvdimm.txt
> @@ -171,6 +171,32 @@ guest software that this vNVDIMM device contains a
> region that cannot
>  accept persistent writes. In result, for example, the guest Linux
>  NVDIMM driver, marks such vNVDIMM device as read-only.
>  
> +Backend File Setup Example
> +..........................
> +
> +Here is two examples for how to setup these persistent backend on
> +linux, which leverages the tool ndctl [3].
> +
> +It is easy to setup DAX device backend file.
> +
> +A. DAX device
> +
> +    ndctl create-namespace -f -e namespace0.0 -m devdax
> +
> +The /dev/dax0.0 could be used directly in "mem-path" option.
> +
> +For DAX file, it is more than creating the proper namespace. The
> +block device should be partitioned and mounted (with dax option).
> +
> +B. DAX file
> +
> +    ndctl create-namespace -f -e namespace0.0 -m fsdax
> +    (partition /dev/pmem0 with name pmem0p1)
> +    mount -o dax /dev/pmem0p1 /mnt
> +    (dd a file with proper size in /mnt)
> +
> +Then the new file in /mnt could be used in "mem-path" option.
> +
>  NVDIMM Persistence
>  ------------------
>  
> @@ -212,3 +238,5 @@ References
>      https://www.snia.org/sites/default/files/technical_work/final/NVMProgrammingModel_v1.2.pdf
>  [2] Persistent Memory Development Kit (PMDK), formerly known as NVML
>  project, home page:
>      http://pmem.io/pmdk/
> +[3] ndctl-create-namespace - provision or reconfigure a namespace
> +    http://pmem.io/ndctl/ndctl-create-namespace.html
> --

Reviewed-by: Pankaj Gupta <pagupta@redhat.com>

> 2.17.1
> 
> 
>
Stefan Hajnoczi July 29, 2019, 1:58 p.m. UTC | #8
On Wed, Jul 24, 2019 at 03:03:07PM +0800, Wei Yang wrote:
> Persistent backend setup requires some knowledge about nvdimm and ndctl
> tool. Some users report they may struggle to gather these knowledge and
> have difficulty to setup it properly.
> 
> Here we provide two examples for persistent backend and gives the link
> to ndctl. By doing so, user could try it directly and do more
> investigation on persistent backend setup with ndctl.
> 
> Signed-off-by: Wei Yang <richardw.yang@linux.intel.com>
> ---
>  docs/nvdimm.txt | 28 ++++++++++++++++++++++++++++
>  1 file changed, 28 insertions(+)
> 
> diff --git a/docs/nvdimm.txt b/docs/nvdimm.txt
> index b531cacd35..baba7a940d 100644
> --- a/docs/nvdimm.txt
> +++ b/docs/nvdimm.txt
> @@ -171,6 +171,32 @@ guest software that this vNVDIMM device contains a region that cannot
>  accept persistent writes. In result, for example, the guest Linux
>  NVDIMM driver, marks such vNVDIMM device as read-only.
>  
> +Backend File Setup Example
> +..........................

For consistency with the rest of the document please use '-' instead of
'.'.

> +
> +Here is two examples for how to setup these persistent backend on
> +linux, which leverages the tool ndctl [3].

Small grammar tweaks:

  Here are two examples showing how to set up persistent backends on
  Linux using the tool ndctl [3].

> +
> +It is easy to setup DAX device backend file.

Please move this into the "A. DAX device" section and use it as an
introduction to explain what this section is about:

  Use the following command to set up /dev/dax0.0 so that the entirety
  of namespace0.0 can be exposed as an emulated NVDIMM to the guest:

> +
> +A. DAX device
> +
> +    ndctl create-namespace -f -e namespace0.0 -m devdax
> +
> +The /dev/dax0.0 could be used directly in "mem-path" option.
> +
> +For DAX file, it is more than creating the proper namespace. The
> +block device should be partitioned and mounted (with dax option).

Please move this into "B. DAX file":

  Individual files on a DAX host file system can be exposed as emulated
  NVDIMMS.  First an fsdax block device is created, partitioned, and
  then mounted with the "dax" mount option:

> +
> +B. DAX file
> +
> +    ndctl create-namespace -f -e namespace0.0 -m fsdax
> +    (partition /dev/pmem0 with name pmem0p1)
> +    mount -o dax /dev/pmem0p1 /mnt
> +    (dd a file with proper size in /mnt)

"dd a file" could be "create or copy a disk image file with qemu-img(1),
cp(1), or dd(1) in /mnt".
Wei Yang July 30, 2019, 12:51 a.m. UTC | #9
Hi, Stefan

Thanks for your comments :-)

On Mon, Jul 29, 2019 at 02:58:59PM +0100, Stefan Hajnoczi wrote:
>On Wed, Jul 24, 2019 at 03:03:07PM +0800, Wei Yang wrote:
>> Persistent backend setup requires some knowledge about nvdimm and ndctl
>> tool. Some users report they may struggle to gather these knowledge and
>> have difficulty to setup it properly.
>> 
>> Here we provide two examples for persistent backend and gives the link
>> to ndctl. By doing so, user could try it directly and do more
>> investigation on persistent backend setup with ndctl.
>> 
>> Signed-off-by: Wei Yang <richardw.yang@linux.intel.com>
>> ---
>>  docs/nvdimm.txt | 28 ++++++++++++++++++++++++++++
>>  1 file changed, 28 insertions(+)
>> 
>> diff --git a/docs/nvdimm.txt b/docs/nvdimm.txt
>> index b531cacd35..baba7a940d 100644
>> --- a/docs/nvdimm.txt
>> +++ b/docs/nvdimm.txt
>> @@ -171,6 +171,32 @@ guest software that this vNVDIMM device contains a region that cannot
>>  accept persistent writes. In result, for example, the guest Linux
>>  NVDIMM driver, marks such vNVDIMM device as read-only.
>>  
>> +Backend File Setup Example
>> +..........................

Here I use '-' because I want to say this is a sub-section of "Guest Data
Persistence".

Actually, I struggled a little to pick up a proper character. Do you think '-'
is the proper one?

>
>For consistency with the rest of the document please use '-' instead of
>'.'.
>
>> +
>> +Here is two examples for how to setup these persistent backend on
>> +linux, which leverages the tool ndctl [3].
>
>Small grammar tweaks:
>
>  Here are two examples showing how to set up persistent backends on
>  Linux using the tool ndctl [3].
>
>> +
>> +It is easy to setup DAX device backend file.
>
>Please move this into the "A. DAX device" section and use it as an
>introduction to explain what this section is about:
>
>  Use the following command to set up /dev/dax0.0 so that the entirety
>  of namespace0.0 can be exposed as an emulated NVDIMM to the guest:
>
>> +
>> +A. DAX device
>> +
>> +    ndctl create-namespace -f -e namespace0.0 -m devdax
>> +
>> +The /dev/dax0.0 could be used directly in "mem-path" option.
>> +
>> +For DAX file, it is more than creating the proper namespace. The
>> +block device should be partitioned and mounted (with dax option).
>
>Please move this into "B. DAX file":
>
>  Individual files on a DAX host file system can be exposed as emulated
>  NVDIMMS.  First an fsdax block device is created, partitioned, and
>  then mounted with the "dax" mount option:
>
>> +
>> +B. DAX file
>> +
>> +    ndctl create-namespace -f -e namespace0.0 -m fsdax
>> +    (partition /dev/pmem0 with name pmem0p1)
>> +    mount -o dax /dev/pmem0p1 /mnt
>> +    (dd a file with proper size in /mnt)
>
>"dd a file" could be "create or copy a disk image file with qemu-img(1),
>cp(1), or dd(1) in /mnt".
Stefan Hajnoczi July 30, 2019, 6:03 a.m. UTC | #10
On Tue, Jul 30, 2019 at 1:52 AM Wei Yang <richardw.yang@linux.intel.com> wrote:
>
> Hi, Stefan
>
> Thanks for your comments :-)
>
> On Mon, Jul 29, 2019 at 02:58:59PM +0100, Stefan Hajnoczi wrote:
> >On Wed, Jul 24, 2019 at 03:03:07PM +0800, Wei Yang wrote:
> >> Persistent backend setup requires some knowledge about nvdimm and ndctl
> >> tool. Some users report they may struggle to gather these knowledge and
> >> have difficulty to setup it properly.
> >>
> >> Here we provide two examples for persistent backend and gives the link
> >> to ndctl. By doing so, user could try it directly and do more
> >> investigation on persistent backend setup with ndctl.
> >>
> >> Signed-off-by: Wei Yang <richardw.yang@linux.intel.com>
> >> ---
> >>  docs/nvdimm.txt | 28 ++++++++++++++++++++++++++++
> >>  1 file changed, 28 insertions(+)
> >>
> >> diff --git a/docs/nvdimm.txt b/docs/nvdimm.txt
> >> index b531cacd35..baba7a940d 100644
> >> --- a/docs/nvdimm.txt
> >> +++ b/docs/nvdimm.txt
> >> @@ -171,6 +171,32 @@ guest software that this vNVDIMM device contains a region that cannot
> >>  accept persistent writes. In result, for example, the guest Linux
> >>  NVDIMM driver, marks such vNVDIMM device as read-only.
> >>
> >> +Backend File Setup Example
> >> +..........................
>
> Here I use '-' because I want to say this is a sub-section of "Guest Data
> Persistence".
>
> Actually, I struggled a little to pick up a proper character. Do you think '-'
> is the proper one?

This is a .txt file without syntax.  Whatever you choose might be
confusing to someone.  If you use a separate '-' section like the rest
of the document then that avoids confusion.

Stefan
Wei Yang Aug. 1, 2019, 12:35 a.m. UTC | #11
On Tue, Jul 30, 2019 at 07:03:45AM +0100, Stefan Hajnoczi wrote:
>On Tue, Jul 30, 2019 at 1:52 AM Wei Yang <richardw.yang@linux.intel.com> wrote:
>>
>> Hi, Stefan
>>
>> Thanks for your comments :-)
>>
>> On Mon, Jul 29, 2019 at 02:58:59PM +0100, Stefan Hajnoczi wrote:
>> >On Wed, Jul 24, 2019 at 03:03:07PM +0800, Wei Yang wrote:
>> >> Persistent backend setup requires some knowledge about nvdimm and ndctl
>> >> tool. Some users report they may struggle to gather these knowledge and
>> >> have difficulty to setup it properly.
>> >>
>> >> Here we provide two examples for persistent backend and gives the link
>> >> to ndctl. By doing so, user could try it directly and do more
>> >> investigation on persistent backend setup with ndctl.
>> >>
>> >> Signed-off-by: Wei Yang <richardw.yang@linux.intel.com>
>> >> ---
>> >>  docs/nvdimm.txt | 28 ++++++++++++++++++++++++++++
>> >>  1 file changed, 28 insertions(+)
>> >>
>> >> diff --git a/docs/nvdimm.txt b/docs/nvdimm.txt
>> >> index b531cacd35..baba7a940d 100644
>> >> --- a/docs/nvdimm.txt
>> >> +++ b/docs/nvdimm.txt
>> >> @@ -171,6 +171,32 @@ guest software that this vNVDIMM device contains a region that cannot
>> >>  accept persistent writes. In result, for example, the guest Linux
>> >>  NVDIMM driver, marks such vNVDIMM device as read-only.
>> >>
>> >> +Backend File Setup Example
>> >> +..........................
>>
>> Here I use '-' because I want to say this is a sub-section of "Guest Data
>> Persistence".
>>
>> Actually, I struggled a little to pick up a proper character. Do you think '-'
>> is the proper one?
>
>This is a .txt file without syntax.  Whatever you choose might be
>confusing to someone.  If you use a separate '-' section like the rest
>of the document then that avoids confusion.
>

Sure, let me change it. Thanks :)

>Stefan

Patch
diff mbox series

diff --git a/docs/nvdimm.txt b/docs/nvdimm.txt
index b531cacd35..baba7a940d 100644
--- a/docs/nvdimm.txt
+++ b/docs/nvdimm.txt
@@ -171,6 +171,32 @@  guest software that this vNVDIMM device contains a region that cannot
 accept persistent writes. In result, for example, the guest Linux
 NVDIMM driver, marks such vNVDIMM device as read-only.
 
+Backend File Setup Example
+..........................
+
+Here is two examples for how to setup these persistent backend on
+linux, which leverages the tool ndctl [3].
+
+It is easy to setup DAX device backend file.
+
+A. DAX device
+
+    ndctl create-namespace -f -e namespace0.0 -m devdax
+
+The /dev/dax0.0 could be used directly in "mem-path" option.
+
+For DAX file, it is more than creating the proper namespace. The
+block device should be partitioned and mounted (with dax option).
+
+B. DAX file
+
+    ndctl create-namespace -f -e namespace0.0 -m fsdax
+    (partition /dev/pmem0 with name pmem0p1)
+    mount -o dax /dev/pmem0p1 /mnt
+    (dd a file with proper size in /mnt)
+
+Then the new file in /mnt could be used in "mem-path" option.
+
 NVDIMM Persistence
 ------------------
 
@@ -212,3 +238,5 @@  References
     https://www.snia.org/sites/default/files/technical_work/final/NVMProgrammingModel_v1.2.pdf
 [2] Persistent Memory Development Kit (PMDK), formerly known as NVML project, home page:
     http://pmem.io/pmdk/
+[3] ndctl-create-namespace - provision or reconfigure a namespace
+    http://pmem.io/ndctl/ndctl-create-namespace.html