Re: [PATCH 01/20] mm: Add msharefs filesystem

[Anthony Yznaga <anthony.yznaga@oracle.com>]

On 2/3/25 5:52 PM, Bagas Sanjaya wrote:
> On Fri, Jan 24, 2025 at 03:54:35PM -0800, Anthony Yznaga wrote:
>> diff --git a/Documentation/filesystems/msharefs.rst b/Documentation/filesystems/msharefs.rst
>> new file mode 100644
>> index 000000000000..c3c7168aa18f
>> --- /dev/null
>> +++ b/Documentation/filesystems/msharefs.rst
>> @@ -0,0 +1,107 @@
>> +.. SPDX-License-Identifier: GPL-2.0
>> +
>> +=====================================================
>> +msharefs - a filesystem to support shared page tables
>> +=====================================================
>> +
>> +msharefs is a ram-based filesystem that allows multiple processes to
>> +share page table entries for shared pages. To enable support for
>> +msharefs the kernel must be compiled with CONFIG_MSHARE set.
>> +
>> +msharefs is typically mounted like this::
>> +
>> +	mount -t msharefs none /sys/fs/mshare
>> +
>> +A file created on msharefs creates a new shared region where all
>> +processes mapping that region will map it using shared page table
>> +entries. ioctls are used to initialize or retrieve the start address
>> +and size of a shared region and to map objects in the shared
>> +region. It is important to note that an msharefs file is a control
>> +file for the shared region and does not contain the contents
>> +of the region itself.
>> +
>> +Here are the basic steps for using mshare::
>> +
>> +1. Mount msharefs on /sys/fs/mshare::
>> +
>> +	mount -t msharefs msharefs /sys/fs/mshare
>> +
>> +2. mshare regions have alignment and size requirements. Start
>> +   address for the region must be aligned to an address boundary and
>> +   be a multiple of fixed size. This alignment and size requirement
>> +   can be obtained by reading the file ``/sys/fs/mshare/mshare_info``
>> +   which returns a number in text format. mshare regions must be
>> +   aligned to this boundary and be a multiple of this size.
>> +
>> +3. For the process creating an mshare region::
>> +
>> +a. Create a file on /sys/fs/mshare, for example:
> Should the creating mshare region sublist be nested list?
Can you expand on that? Do you mean create an mshare region as a 
directory and populate it with files representing the mappings that are 
created in the region?
>
>> +
>> +.. code-block:: c
>> +
>> +	fd = open("/sys/fs/mshare/shareme",
>> +			O_RDWR|O_CREAT|O_EXCL, 0600);
>> +
>> +b. Establish the starting address and size of the region:
>> +
>> +.. code-block:: c
>> +
>> +	struct mshare_info minfo;
>> +
>> +	minfo.start = TB(2);
>> +	minfo.size = BUFFER_SIZE;
>> +	ioctl(fd, MSHAREFS_SET_SIZE, &minfo);
>> +
>> +c. Map some memory in the region:
>> +
>> +.. code-block:: c
>> +
>> +	struct mshare_create mcreate;
>> +
>> +	mcreate.addr = TB(2);
>> +	mcreate.size = BUFFER_SIZE;
>> +	mcreate.offset = 0;
>> +	mcreate.prot = PROT_READ | PROT_WRITE;
>> +	mcreate.flags = MAP_ANONYMOUS | MAP_SHARED | MAP_FIXED;
>> +	mcreate.fd = -1;
>> +
>> +	ioctl(fd, MSHAREFS_CREATE_MAPPING, &mcreate);
>> +
>> +d. Map the mshare region into the process:
>> +
>> +.. code-block:: c
>> +
>> +	mmap((void *)TB(2), BUF_SIZE,
>> +		PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0);
>> +
>> +e. Write and read to mshared region normally.
>> +
>> +
>> +4. For processes attaching an mshare region::
>> +
>> +a. Open the file on msharefs, for example:
>> +
>> +.. code-block:: c
>> +
>> +	fd = open("/sys/fs/mshare/shareme", O_RDWR);
>> +
>> +b. Get information about mshare'd region from the file:
>> +
>> +.. code-block:: c
>> +
>> +	struct mshare_info minfo;
>> +
>> +	ioctl(fd, MSHAREFS_GET_SIZE, &minfo);
>> +
>> +c. Map the mshare'd region into the process:
>> +
>> +.. code-block:: c
>> +
>> +	mmap(minfo.start, minfo.size,
>> +		PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0);
>> +
>> +5. To delete the mshare region:
>> +
>> +.. code-block:: c
>> +
>> +		unlink("/sys/fs/mshare/shareme");
> Sphinx reports htmldocs warnings:
>
> Documentation/filesystems/msharefs.rst:25: WARNING: Literal block expected; none found. [docutils]
> Documentation/filesystems/msharefs.rst:38: WARNING: Literal block expected; none found. [docutils]
> Documentation/filesystems/msharefs.rst:82: WARNING: Literal block expected; none found. [docutils]

Thanks. Will fix this.


Anthony


>
> Thanks.
>