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?
> +
> +.. 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.
--
An old man doll... just what I always wanted! - Clara
Attachment:
signature.asc
Description: PGP signature
