* [PATCH] Documentation/filesystems: add binderfs
@ 2019-01-10 23:13 Christian Brauner
2019-01-10 23:47 ` Jonathan Corbet
0 siblings, 1 reply; 5+ messages in thread
From: Christian Brauner @ 2019-01-10 23:13 UTC (permalink / raw)
To: corbet, linux-doc, linux-kernel; +Cc: Christian Brauner
This documents the Android binderfs filesystem used to dynamically add and
remove binder devices that are private to each instance.
Signed-off-by: Christian Brauner <christian.brauner@ubuntu.com>
---
Documentation/filesystems/binderfs.txt | 109 +++++++++++++++++++++++++
1 file changed, 109 insertions(+)
create mode 100644 Documentation/filesystems/binderfs.txt
diff --git a/Documentation/filesystems/binderfs.txt b/Documentation/filesystems/binderfs.txt
new file mode 100644
index 000000000000..9c47eb33dd6a
--- /dev/null
+++ b/Documentation/filesystems/binderfs.txt
@@ -0,0 +1,109 @@
+
+The Android binderfs Filesystem
+===============================
+
+Android binderfs is a filesystem for the Android binder IPC mechanism. It
+allows to dynamically add and remove binder devices at runtime. Binder devices
+located in a new binderfs instance are independent of binder devices located in
+other binderfs instances. Mounting a new binderfs instance makes it possible
+to get a set of private binder devices.
+
+Mounting binderfs
+-----------------
+
+Android binderfs can be mounted with:
+
+mkdir /dev/binderfs
+mount -t binder binder /dev/binderfs
+
+at which point a new instance of binderfs will show up at /dev/binderfs. In a
+fresh instance of binderfs no binder devices will be present. There will only
+be a binder-control device which serves as the request handler for binderfs.
+Mounting another binderfs instance at a different location will create a new
+and separate instance from all other binderfs mounts. This is identical to the
+behavior of e.g. devpts and tmpfs.
+The Android binderfs filesystem can be mounted in user namespaces.
+
+Options
+-------
+
+Android binderfs does currently not support mount options.
+
+Allocating binder Devices
+-------------------------
+
+To allocate a new binder device in a binderfs instance a request needs to be
+sent through the binder-control device node. A request is sent in the form of
+an ioctl(2). Here’s an example program:
+
+#define _GNU_SOURCE
+#include <errno.h>
+#include <fcntl.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/ioctl.h>
+#include <sys/stat.h>
+#include <sys/types.h>
+#include <unistd.h>
+#include <linux/android/binder_ctl.h>
+
+int main(int argc, char *argv[])
+{
+ int fd, ret, saved_errno;
+ size_t len;
+ struct binderfs_device device = { 0 };
+
+ if (argc != 3)
+ exit(EXIT_FAILURE);
+
+ len = strlen(argv[2]);
+ if (len > BINDERFS_MAX_NAME)
+ exit(EXIT_FAILURE);
+
+ memcpy(device.name, argv[2], len);
+
+ fd = open(argv[1], O_RDONLY | O_CLOEXEC);
+ if (fd < 0) {
+ printf("%s - Failed to open binder-control device\n",
+ strerror(errno));
+ exit(EXIT_FAILURE);
+ }
+
+ ret = ioctl(fd, BINDER_CTL_ADD, &device);
+ saved_errno = errno;
+ close(fd);
+ errno = saved_errno;
+ if (ret < 0) {
+ printf("%s - Failed to allocate new binder device\n",
+ strerror(errno));
+ exit(EXIT_FAILURE);
+ }
+
+ printf("Allocated new binder device with major %d, minor %d, and "
+ "name %s\n", device.major, device.minor,
+ device.name);
+
+ exit(EXIT_SUCCESS);
+}
+
+What this program simply does is to open the binder-control device node and
+sending a BINDER_CTL_ADD request to the kernel. Users of binderfs need to tell
+the kernel which name the new binder device should get. By default a name can
+only contain up to BINDERFS_MAX_NAME chars including the terminating zero byte.
+
+Once the request is made via an ioctl(2) passing a struct binder_device with
+the name to the kernel it will allocate a new binder device and return the
+major and minor number of the new device in the struct (This is necessary
+because binderfs allocates a major device number dynamically at boot.). After
+the ioctl(2) returns there will be a new binder device located under
+/dev/binderfs with the chosen name.
+
+Deleting binder Devices
+-----------------------
+
+Binderfs binder devices can be deleted via unlink(2). This means that the
+rm(1) tool can be used to delete them.
+Note that the binder-control device cannot be deleted since this would make the
+binderfs instance unuseable. The binder-control device will be deleted when
+the binderfs instance is unmounted and all references to it have been dropped.
--
2.19.1
^ permalink raw reply related [flat|nested] 5+ messages in thread
* Re: [PATCH] Documentation/filesystems: add binderfs
2019-01-10 23:13 [PATCH] Documentation/filesystems: add binderfs Christian Brauner
@ 2019-01-10 23:47 ` Jonathan Corbet
2019-01-10 23:56 ` Christian Brauner
0 siblings, 1 reply; 5+ messages in thread
From: Jonathan Corbet @ 2019-01-10 23:47 UTC (permalink / raw)
To: Christian Brauner; +Cc: linux-doc, linux-kernel
On Fri, 11 Jan 2019 00:13:09 +0100
Christian Brauner <christian@brauner.io> wrote:
> This documents the Android binderfs filesystem used to dynamically add and
> remove binder devices that are private to each instance.
>
> Signed-off-by: Christian Brauner <christian.brauner@ubuntu.com>
Seems like a worthwhile addition overall. I know nothing about binderfs,
so can't speak to the accuracy, of course. I do have a couple of
metacomments, though:
- Please consider doing this in RST and tying it into our documentation
tree. It's *almost* RST now, so the effort required will be almost
zero.
- It should probably have an SPDX line at the top.
- Is it worth putting the example program in the samples/ directory? Is
it something that would ever make any sense to run in its current form?
Thanks,
jon
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH] Documentation/filesystems: add binderfs
2019-01-10 23:47 ` Jonathan Corbet
@ 2019-01-10 23:56 ` Christian Brauner
2019-01-11 0:08 ` Jonathan Corbet
0 siblings, 1 reply; 5+ messages in thread
From: Christian Brauner @ 2019-01-10 23:56 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: linux-doc, linux-kernel
On Thu, Jan 10, 2019 at 04:47:03PM -0700, Jonathan Corbet wrote:
> On Fri, 11 Jan 2019 00:13:09 +0100
> Christian Brauner <christian@brauner.io> wrote:
>
> > This documents the Android binderfs filesystem used to dynamically add and
> > remove binder devices that are private to each instance.
> >
> > Signed-off-by: Christian Brauner <christian.brauner@ubuntu.com>
>
> Seems like a worthwhile addition overall. I know nothing about binderfs,
> so can't speak to the accuracy, of course. I do have a couple of
> metacomments, though:
>
> - Please consider doing this in RST and tying it into our documentation
> tree. It's *almost* RST now, so the effort required will be almost
> zero.
Oh sure. I simply didn't know. I was just going by the files under
Documentation/filesystems/. Is this a separate git tree? If so, where is
located? Or can I just place it as
Documentation/filesystems/binderfs.rst?
>
> - It should probably have an SPDX line at the top.
Yup, can add.
>
> - Is it worth putting the example program in the samples/ directory? Is
> it something that would ever make any sense to run in its current form?
Hm, I mean I can write a small binary that illustrates mounting and
allocating binder devices in binderfs.
Thanks!
Christian
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH] Documentation/filesystems: add binderfs
2019-01-10 23:56 ` Christian Brauner
@ 2019-01-11 0:08 ` Jonathan Corbet
2019-01-11 10:22 ` Christian Brauner
0 siblings, 1 reply; 5+ messages in thread
From: Jonathan Corbet @ 2019-01-11 0:08 UTC (permalink / raw)
To: Christian Brauner; +Cc: linux-doc, linux-kernel
On Fri, 11 Jan 2019 00:56:42 +0100
Christian Brauner <christian@brauner.io> wrote:
> > - Please consider doing this in RST and tying it into our documentation
> > tree. It's *almost* RST now, so the effort required will be almost
> > zero.
>
> Oh sure. I simply didn't know. I was just going by the files under
> Documentation/filesystems/. Is this a separate git tree? If so, where is
> located? Or can I just place it as
> Documentation/filesystems/binderfs.rst?
The latter - plus an entry in index.rst. Look at, say, path-lookup.rst in
that directory now.
> > - Is it worth putting the example program in the samples/ directory? Is
> > it something that would ever make any sense to run in its current form?
>
> Hm, I mean I can write a small binary that illustrates mounting and
> allocating binder devices in binderfs.
This was just a thought - I sure don't want to try to send you off on some
sort of project if it won't be useful! :)
Thanks,
jon
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH] Documentation/filesystems: add binderfs
2019-01-11 0:08 ` Jonathan Corbet
@ 2019-01-11 10:22 ` Christian Brauner
0 siblings, 0 replies; 5+ messages in thread
From: Christian Brauner @ 2019-01-11 10:22 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: linux-doc, linux-kernel
On Thu, Jan 10, 2019 at 05:08:11PM -0700, Jonathan Corbet wrote:
> On Fri, 11 Jan 2019 00:56:42 +0100
> Christian Brauner <christian@brauner.io> wrote:
>
> > > - Please consider doing this in RST and tying it into our documentation
> > > tree. It's *almost* RST now, so the effort required will be almost
> > > zero.
> >
> > Oh sure. I simply didn't know. I was just going by the files under
> > Documentation/filesystems/. Is this a separate git tree? If so, where is
> > located? Or can I just place it as
> > Documentation/filesystems/binderfs.rst?
>
> The latter - plus an entry in index.rst. Look at, say, path-lookup.rst in
> that directory now.
Good. Thanks!
>
> > > - Is it worth putting the example program in the samples/ directory? Is
> > > it something that would ever make any sense to run in its current form?
> >
> > Hm, I mean I can write a small binary that illustrates mounting and
> > allocating binder devices in binderfs.
>
> This was just a thought - I sure don't want to try to send you off on some
> sort of project if it won't be useful! :)
I mean it'll be useful and it's really not a lot of work to be honest.
It's just extending the program I put into the commit message for
binderfs itself. :)
Thanks!
Christian
^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2019-01-11 10:22 UTC | newest]
Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2019-01-10 23:13 [PATCH] Documentation/filesystems: add binderfs Christian Brauner
2019-01-10 23:47 ` Jonathan Corbet
2019-01-10 23:56 ` Christian Brauner
2019-01-11 0:08 ` Jonathan Corbet
2019-01-11 10:22 ` Christian Brauner
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).