[linux-block.git] / Documentation / filesystems / adfs.rst

.. SPDX-License-Identifier: GPL-2.0

===============================
Acorn Disc Filing System - ADFS
===============================

Filesystems supported by ADFS
-----------------------------

The ADFS module supports the following Filecore formats which have:

- new maps
- new directories or big directories

In terms of the named formats, this means we support:

- E and E+, with or without boot block
- F and F+

We fully support reading files from these filesystems, and writing to
existing files within their existing allocation.  Essentially, we do
not support changing any of the filesystem metadata.

This is intended to support loopback mounted Linux native filesystems
on a RISC OS Filecore filesystem, but will allow the data within files
to be changed.

If write support (ADFS_FS_RW) is configured, we allow rudimentary
directory updates, specifically updating the access mode and timestamp.

Mount options for ADFS
----------------------

  ============  ======================================================
  uid=nnn	All files in the partition will be owned by
		user id nnn.  Default 0 (root).
  gid=nnn	All files in the partition will be in group
		nnn.  Default 0 (root).
  ownmask=nnn	The permission mask for ADFS 'owner' permissions
		will be nnn.  Default 0700.
  othmask=nnn	The permission mask for ADFS 'other' permissions
		will be nnn.  Default 0077.
  ftsuffix=n	When ftsuffix=0, no file type suffix will be applied.
		When ftsuffix=1, a hexadecimal suffix corresponding to
		the RISC OS file type will be added.  Default 0.
  ============  ======================================================

Mapping of ADFS permissions to Linux permissions
------------------------------------------------

  ADFS permissions consist of the following:

	- Owner read
	- Owner write
	- Other read
	- Other write

  (In older versions, an 'execute' permission did exist, but this
  does not hold the same meaning as the Linux 'execute' permission
  and is now obsolete).

  The mapping is performed as follows::

	Owner read				-> -r--r--r--
	Owner write				-> --w--w---w
	Owner read and filetype UnixExec	-> ---x--x--x
    These are then masked by ownmask, eg 700	-> -rwx------
	Possible owner mode permissions		-> -rwx------

	Other read				-> -r--r--r--
	Other write				-> --w--w--w-
	Other read and filetype UnixExec	-> ---x--x--x
    These are then masked by othmask, eg 077	-> ----rwxrwx
	Possible other mode permissions		-> ----rwxrwx

  Hence, with the default masks, if a file is owner read/write, and
  not a UnixExec filetype, then the permissions will be::

			-rw-------

  However, if the masks were ownmask=0770,othmask=0007, then this would
  be modified to::

			-rw-rw----

  There is no restriction on what you can do with these masks.  You may
  wish that either read bits give read access to the file for all, but
  keep the default write protection (ownmask=0755,othmask=0577)::

			-rw-r--r--

  You can therefore tailor the permission translation to whatever you
  desire the permissions should be under Linux.

RISC OS file type suffix
------------------------

  RISC OS file types are stored in bits 19..8 of the file load address.

  To enable non-RISC OS systems to be used to store files without losing
  file type information, a file naming convention was devised (initially
  for use with NFS) such that a hexadecimal suffix of the form ,xyz
  denoted the file type: e.g. BasicFile,ffb is a BASIC (0xffb) file.  This
  naming convention is now also used by RISC OS emulators such as RPCEmu.

  Mounting an ADFS disc with option ftsuffix=1 will cause appropriate file
  type suffixes to be appended to file names read from a directory.  If the
  ftsuffix option is zero or omitted, no file type suffixes will be added.
Commit	Line	Data
34873900 MCC	1	.. SPDX-License-Identifier: GPL-2.0
	2
	3	===============================
	4	Acorn Disc Filing System - ADFS
	5	===============================
	6
76ed99d1 RK	7	Filesystems supported by ADFS
	8	-----------------------------
	9
	10	The ADFS module supports the following Filecore formats which have:
	11
	12	- new maps
	13	- new directories or big directories
	14
	15	In terms of the named formats, this means we support:
	16
	17	- E and E+, with or without boot block
	18	- F and F+
	19
	20	We fully support reading files from these filesystems, and writing to
	21	existing files within their existing allocation. Essentially, we do
	22	not support changing any of the filesystem metadata.
	23
	24	This is intended to support loopback mounted Linux native filesystems
	25	on a RISC OS Filecore filesystem, but will allow the data within files
	26	to be changed.
	27
	28	If write support (ADFS_FS_RW) is configured, we allow rudimentary
	29	directory updates, specifically updating the access mode and timestamp.
	30
1da177e4 LT	31	Mount options for ADFS
	32	----------------------
	33
34873900	34	============ ======================================================
1da177e4 LT	35	uid=nnn All files in the partition will be owned by
1da177e4 LT	36	user id nnn. Default 0 (root).
4ae0edc2	37	gid=nnn All files in the partition will be in group
1da177e4 LT	38	nnn. Default 0 (root).
	39	ownmask=nnn The permission mask for ADFS 'owner' permissions
	40	will be nnn. Default 0700.
	41	othmask=nnn The permission mask for ADFS 'other' permissions
	42	will be nnn. Default 0077.
da23ef05 SS	43	ftsuffix=n When ftsuffix=0, no file type suffix will be applied.
	44	When ftsuffix=1, a hexadecimal suffix corresponding to
	45	the RISC OS file type will be added. Default 0.
34873900	46	============ ======================================================
1da177e4 LT	47
	48	Mapping of ADFS permissions to Linux permissions
	49	------------------------------------------------
	50
	51	ADFS permissions consist of the following:
	52
34873900 MCC	53	- Owner read
	54	- Owner write
	55	- Other read
	56	- Other write
1da177e4 LT	57
1da177e4 LT	58	(In older versions, an 'execute' permission did exist, but this
34873900 MCC	59	does not hold the same meaning as the Linux 'execute' permission
34873900 MCC	60	and is now obsolete).
1da177e4	61
34873900	62	The mapping is performed as follows::
1da177e4 LT	63
	64	Owner read -> -r--r--r--
	65	Owner write -> --w--w---w
	66	Owner read and filetype UnixExec -> ---x--x--x
	67	These are then masked by ownmask, eg 700 -> -rwx------
	68	Possible owner mode permissions -> -rwx------
	69
	70	Other read -> -r--r--r--
	71	Other write -> --w--w--w-
	72	Other read and filetype UnixExec -> ---x--x--x
	73	These are then masked by othmask, eg 077 -> ----rwxrwx
	74	Possible other mode permissions -> ----rwxrwx
	75
	76	Hence, with the default masks, if a file is owner read/write, and
34873900	77	not a UnixExec filetype, then the permissions will be::
1da177e4 LT	78
	79	-rw-------
	80
	81	However, if the masks were ownmask=0770,othmask=0007, then this would
34873900 MCC	82	be modified to::
34873900 MCC	83
1da177e4 LT	84	-rw-rw----
	85
	86	There is no restriction on what you can do with these masks. You may
	87	wish that either read bits give read access to the file for all, but
34873900	88	keep the default write protection (ownmask=0755,othmask=0577)::
1da177e4 LT	89
	90	-rw-r--r--
	91
	92	You can therefore tailor the permission translation to whatever you
	93	desire the permissions should be under Linux.
da23ef05 SS	94
	95	RISC OS file type suffix
	96	------------------------
	97
	98	RISC OS file types are stored in bits 19..8 of the file load address.
	99
	100	To enable non-RISC OS systems to be used to store files without losing
	101	file type information, a file naming convention was devised (initially
	102	for use with NFS) such that a hexadecimal suffix of the form ,xyz
	103	denoted the file type: e.g. BasicFile,ffb is a BASIC (0xffb) file. This
	104	naming convention is now also used by RISC OS emulators such as RPCEmu.
	105
	106	Mounting an ADFS disc with option ftsuffix=1 will cause appropriate file
	107	type suffixes to be appended to file names read from a directory. If the
	108	ftsuffix option is zero or omitted, no file type suffixes will be added.