From 14a19fa5cf759ea18bc7d692cd8fe326af3c4d0a Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 17 Feb 2020 17:11:58 +0100 Subject: docs: filesystems: convert dlmfs.txt to ReST - Add a SPDX header; - Use copyright symbol; - Adjust document title; - Some whitespace fixes and new line breaks; - Mark literal blocks as such; - Add table markups; - Add it to filesystems/index.rst. Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/efc9e59925723e17d1a4741b11049616c221463e.1581955849.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet --- Documentation/filesystems/dlmfs.rst | 140 ++++++++++++++++++++++++++++++++++++ Documentation/filesystems/dlmfs.txt | 130 --------------------------------- Documentation/filesystems/index.rst | 1 + 3 files changed, 141 insertions(+), 130 deletions(-) create mode 100644 Documentation/filesystems/dlmfs.rst delete mode 100644 Documentation/filesystems/dlmfs.txt diff --git a/Documentation/filesystems/dlmfs.rst b/Documentation/filesystems/dlmfs.rst new file mode 100644 index 000000000000..68daaa7facf9 --- /dev/null +++ b/Documentation/filesystems/dlmfs.rst @@ -0,0 +1,140 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: + +===== +DLMFS +===== + +A minimal DLM userspace interface implemented via a virtual file +system. + +dlmfs is built with OCFS2 as it requires most of its infrastructure. + +:Project web page: http://ocfs2.wiki.kernel.org +:Tools web page: https://github.com/markfasheh/ocfs2-tools +:OCFS2 mailing lists: http://oss.oracle.com/projects/ocfs2/mailman/ + +All code copyright 2005 Oracle except when otherwise noted. + +Credits +======= + +Some code taken from ramfs which is Copyright |copy| 2000 Linus Torvalds +and Transmeta Corp. + +Mark Fasheh + +Caveats +======= +- Right now it only works with the OCFS2 DLM, though support for other + DLM implementations should not be a major issue. + +Mount options +============= +None + +Usage +===== + +If you're just interested in OCFS2, then please see ocfs2.txt. The +rest of this document will be geared towards those who want to use +dlmfs for easy to setup and easy to use clustered locking in +userspace. + +Setup +===== + +dlmfs requires that the OCFS2 cluster infrastructure be in +place. Please download ocfs2-tools from the above url and configure a +cluster. + +You'll want to start heartbeating on a volume which all the nodes in +your lockspace can access. The easiest way to do this is via +ocfs2_hb_ctl (distributed with ocfs2-tools). Right now it requires +that an OCFS2 file system be in place so that it can automatically +find its heartbeat area, though it will eventually support heartbeat +against raw disks. + +Please see the ocfs2_hb_ctl and mkfs.ocfs2 manual pages distributed +with ocfs2-tools. + +Once you're heartbeating, DLM lock 'domains' can be easily created / +destroyed and locks within them accessed. + +Locking +======= + +Users may access dlmfs via standard file system calls, or they can use +'libo2dlm' (distributed with ocfs2-tools) which abstracts the file +system calls and presents a more traditional locking api. + +dlmfs handles lock caching automatically for the user, so a lock +request for an already acquired lock will not generate another DLM +call. Userspace programs are assumed to handle their own local +locking. + +Two levels of locks are supported - Shared Read, and Exclusive. +Also supported is a Trylock operation. + +For information on the libo2dlm interface, please see o2dlm.h, +distributed with ocfs2-tools. + +Lock value blocks can be read and written to a resource via read(2) +and write(2) against the fd obtained via your open(2) call. The +maximum currently supported LVB length is 64 bytes (though that is an +OCFS2 DLM limitation). Through this mechanism, users of dlmfs can share +small amounts of data amongst their nodes. + +mkdir(2) signals dlmfs to join a domain (which will have the same name +as the resulting directory) + +rmdir(2) signals dlmfs to leave the domain + +Locks for a given domain are represented by regular inodes inside the +domain directory. Locking against them is done via the open(2) system +call. + +The open(2) call will not return until your lock has been granted or +an error has occurred, unless it has been instructed to do a trylock +operation. If the lock succeeds, you'll get an fd. + +open(2) with O_CREAT to ensure the resource inode is created - dlmfs does +not automatically create inodes for existing lock resources. + +============ =========================== +Open Flag Lock Request Type +============ =========================== +O_RDONLY Shared Read +O_RDWR Exclusive +============ =========================== + + +============ =========================== +Open Flag Resulting Locking Behavior +============ =========================== +O_NONBLOCK Trylock operation +============ =========================== + +You must provide exactly one of O_RDONLY or O_RDWR. + +If O_NONBLOCK is also provided and the trylock operation was valid but +could not lock the resource then open(2) will return ETXTBUSY. + +close(2) drops the lock associated with your fd. + +Modes passed to mkdir(2) or open(2) are adhered to locally. Chown is +supported locally as well. This means you can use them to restrict +access to the resources via dlmfs on your local node only. + +The resource LVB may be read from the fd in either Shared Read or +Exclusive modes via the read(2) system call. It can be written via +write(2) only when open in Exclusive mode. + +Once written, an LVB will be visible to other nodes who obtain Read +Only or higher level locks on the resource. + +See Also +======== +http://opendlm.sourceforge.net/cvsmirror/opendlm/docs/dlmbook_final.pdf + +For more information on the VMS distributed locking API. diff --git a/Documentation/filesystems/dlmfs.txt b/Documentation/filesystems/dlmfs.txt deleted file mode 100644 index fcf4d509d118..000000000000 --- a/Documentation/filesystems/dlmfs.txt +++ /dev/null @@ -1,130 +0,0 @@ -dlmfs -================== -A minimal DLM userspace interface implemented via a virtual file -system. - -dlmfs is built with OCFS2 as it requires most of its infrastructure. - -Project web page: http://ocfs2.wiki.kernel.org -Tools web page: https://github.com/markfasheh/ocfs2-tools -OCFS2 mailing lists: http://oss.oracle.com/projects/ocfs2/mailman/ - -All code copyright 2005 Oracle except when otherwise noted. - -CREDITS -======= - -Some code taken from ramfs which is Copyright (C) 2000 Linus Torvalds -and Transmeta Corp. - -Mark Fasheh - -Caveats -======= -- Right now it only works with the OCFS2 DLM, though support for other - DLM implementations should not be a major issue. - -Mount options -============= -None - -Usage -===== - -If you're just interested in OCFS2, then please see ocfs2.txt. The -rest of this document will be geared towards those who want to use -dlmfs for easy to setup and easy to use clustered locking in -userspace. - -Setup -===== - -dlmfs requires that the OCFS2 cluster infrastructure be in -place. Please download ocfs2-tools from the above url and configure a -cluster. - -You'll want to start heartbeating on a volume which all the nodes in -your lockspace can access. The easiest way to do this is via -ocfs2_hb_ctl (distributed with ocfs2-tools). Right now it requires -that an OCFS2 file system be in place so that it can automatically -find its heartbeat area, though it will eventually support heartbeat -against raw disks. - -Please see the ocfs2_hb_ctl and mkfs.ocfs2 manual pages distributed -with ocfs2-tools. - -Once you're heartbeating, DLM lock 'domains' can be easily created / -destroyed and locks within them accessed. - -Locking -======= - -Users may access dlmfs via standard file system calls, or they can use -'libo2dlm' (distributed with ocfs2-tools) which abstracts the file -system calls and presents a more traditional locking api. - -dlmfs handles lock caching automatically for the user, so a lock -request for an already acquired lock will not generate another DLM -call. Userspace programs are assumed to handle their own local -locking. - -Two levels of locks are supported - Shared Read, and Exclusive. -Also supported is a Trylock operation. - -For information on the libo2dlm interface, please see o2dlm.h, -distributed with ocfs2-tools. - -Lock value blocks can be read and written to a resource via read(2) -and write(2) against the fd obtained via your open(2) call. The -maximum currently supported LVB length is 64 bytes (though that is an -OCFS2 DLM limitation). Through this mechanism, users of dlmfs can share -small amounts of data amongst their nodes. - -mkdir(2) signals dlmfs to join a domain (which will have the same name -as the resulting directory) - -rmdir(2) signals dlmfs to leave the domain - -Locks for a given domain are represented by regular inodes inside the -domain directory. Locking against them is done via the open(2) system -call. - -The open(2) call will not return until your lock has been granted or -an error has occurred, unless it has been instructed to do a trylock -operation. If the lock succeeds, you'll get an fd. - -open(2) with O_CREAT to ensure the resource inode is created - dlmfs does -not automatically create inodes for existing lock resources. - -Open Flag Lock Request Type ---------- ----------------- -O_RDONLY Shared Read -O_RDWR Exclusive - -Open Flag Resulting Locking Behavior ---------- -------------------------- -O_NONBLOCK Trylock operation - -You must provide exactly one of O_RDONLY or O_RDWR. - -If O_NONBLOCK is also provided and the trylock operation was valid but -could not lock the resource then open(2) will return ETXTBUSY. - -close(2) drops the lock associated with your fd. - -Modes passed to mkdir(2) or open(2) are adhered to locally. Chown is -supported locally as well. This means you can use them to restrict -access to the resources via dlmfs on your local node only. - -The resource LVB may be read from the fd in either Shared Read or -Exclusive modes via the read(2) system call. It can be written via -write(2) only when open in Exclusive mode. - -Once written, an LVB will be visible to other nodes who obtain Read -Only or higher level locks on the resource. - -See Also -======== -http://opendlm.sourceforge.net/cvsmirror/opendlm/docs/dlmbook_final.pdf - -For more information on the VMS distributed locking API. diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst index ab3b656bbe60..c6885c7ef781 100644 --- a/Documentation/filesystems/index.rst +++ b/Documentation/filesystems/index.rst @@ -58,6 +58,7 @@ Documentation for filesystem implementations. ceph cramfs debugfs + dlmfs fuse overlayfs virtiofs -- cgit v1.2.3