* Re: [PATCH v2] Documentation/security-bugs: provide more information about linux-distros
From: Sasha Levin @ 2019-07-19 0:39 UTC (permalink / raw)
To: Kees Cook
Cc: corbet, solar, will, peterz, gregkh, tyhicks, linux-doc,
linux-kernel
In-Reply-To: <201907181457.D61AC061C@keescook>
On Thu, Jul 18, 2019 at 03:00:55PM -0700, Kees Cook wrote:
>On Wed, Jul 17, 2019 at 07:11:03PM -0400, Sasha Levin wrote:
>> Provide more information about how to interact with the linux-distros
>> mailing list for disclosing security bugs.
>>
>> Reference the linux-distros list policy and clarify that the reporter
>> must read and understand those policies as they differ from
>> security@kernel.org's policy.
>>
>> Suggested-by: Solar Designer <solar@openwall.com>
>> Signed-off-by: Sasha Levin <sashal@kernel.org>
>
>Sorry, but NACK, see below...
>
>> ---
>>
>> Changes in v2:
>> - Focus more on pointing to the linux-distros wiki and policies.
>
>I think this is already happening in the text. What specifically do you
>want described differently?
The main issue was that there isn't anything pointing to the
linux-distros policies. The current text outlines a few of them ("add
[vs]", and "there should be an embargo period"), but it effectively just
gives out the linux-distros mailing address and tells the reporter to
contact it.
>> - Remove explicit linux-distros email.
>
>I don't like this because we had past trouble with notifications going
>to the distros@ list and leaking Linux-only flaws to the BSDs. As there
>isn't a separate linux-distros wiki, the clarification of WHICH list is
>needed.
Why would removing the explicit linux-distros email encourage people to
send reports to it?
I also don't understand what you mean by "there isn't a separate
linux-distros wiki"? There is one, and I want to point the reporter
there.
>> - Remove various explanations of linux-distros policies.
>
>I don't think there's value in removing the Tue-Thu comment, nor
>providing context for why distros need time. This has been a regular
>thing we've had to explain to researchers that aren't familiar with
>update procedures and publication timing.
To be fair, the Tue-Thu comment is listed in the section describing how
to do coordination with linux-distros, and linux-distros don't have a
Tue-Thu policy. If it's a security@kernel.org policy then let's list it
elsewhere.
If you feel that there is a consensus around Tue-Thu let's just add it
to the linux-distros policy wiki, there's no point in listing random
policies from that wiki.
--
Thanks,
Sasha
^ permalink raw reply
* Re: [PATCH v2] Documentation/security-bugs: provide more information about linux-distros
From: Kees Cook @ 2019-07-19 1:51 UTC (permalink / raw)
To: Sasha Levin
Cc: corbet, solar, will, peterz, gregkh, tyhicks, linux-doc,
linux-kernel
In-Reply-To: <20190719003919.GC4240@sasha-vm>
On Thu, Jul 18, 2019 at 08:39:19PM -0400, Sasha Levin wrote:
> On Thu, Jul 18, 2019 at 03:00:55PM -0700, Kees Cook wrote:
> > On Wed, Jul 17, 2019 at 07:11:03PM -0400, Sasha Levin wrote:
> > > Provide more information about how to interact with the linux-distros
> > > mailing list for disclosing security bugs.
> > >
> > > Reference the linux-distros list policy and clarify that the reporter
> > > must read and understand those policies as they differ from
> > > security@kernel.org's policy.
> > >
> > > Suggested-by: Solar Designer <solar@openwall.com>
> > > Signed-off-by: Sasha Levin <sashal@kernel.org>
> >
> > Sorry, but NACK, see below...
> >
> > > ---
> > >
> > > Changes in v2:
> > > - Focus more on pointing to the linux-distros wiki and policies.
> >
> > I think this is already happening in the text. What specifically do you
> > want described differently?
>
> The main issue was that there isn't anything pointing to the
> linux-distros policies. The current text outlines a few of them ("add
> [vs]", and "there should be an embargo period"), but it effectively just
> gives out the linux-distros mailing address and tells the reporter to
> contact it.
The current text includes the wiki link, but yes, the anchor tag is not
present at the wiki anymore. I would agree that's due for updating.
I think reinforcing information to avoid past mistakes is appropriate
here. Reports have regularly missed the "[vs]" detail or suggested
embargoes that ended on Fridays, etc.
> > > - Remove explicit linux-distros email.
> >
> > I don't like this because we had past trouble with notifications going
> > to the distros@ list and leaking Linux-only flaws to the BSDs. As there
> > isn't a separate linux-distros wiki, the clarification of WHICH list is
> > needed.
>
> Why would removing the explicit linux-distros email encourage people to
> send reports to it?
What? No, I'm saying we should _keep_ linux-distros@... in our text so
that people don't send to the wrong list.
> I also don't understand what you mean by "there isn't a separate
> linux-distros wiki"? There is one, and I want to point the reporter
> there.
That URL is a combined page for two lists. The very fact that it's
not obvious that there are two lists described there is exactly why I
think we need to keep an explicit mention of which to use. There are
two mailing lists described at the wiki URL:
distros@lists.openwall.com
linux-distros@lists.openwall.com
Sending to the distros@ list risks exposing Linux-only flaws to non-Linux
distros. This has caused leaks in the past, and we do not want people
guessing at which list they should use.
Also note that nowhere on the openwall wiki is the email address
actually spelled out; this is another reason to spell it out in our
documentation: no misunderstanding.
(And historically there WAS a specific linux-distros wiki:
https://oss-security.openwall.org/wiki/mailing-lists/linux-distros
but it redirects to the combined one now...)
> > > - Remove various explanations of linux-distros policies.
> >
> > I don't think there's value in removing the Tue-Thu comment, nor
> > providing context for why distros need time. This has been a regular
> > thing we've had to explain to researchers that aren't familiar with
> > update procedures and publication timing.
>
> To be fair, the Tue-Thu comment is listed in the section describing how
> to do coordination with linux-distros, and linux-distros don't have a
> Tue-Thu policy. If it's a security@kernel.org policy then let's list it
> elsewhere.
It's a distro preference. Many researchers aren't thinking about the
larger Linux ecosystem that has to consume fixes. It's not a _policy_,
but it makes the researchers understand how to construct better embargoes.
> If you feel that there is a consensus around Tue-Thu let's just add it
> to the linux-distros policy wiki, there's no point in listing random
> policies from that wiki.
I think it'd be a good idea to add that note also to the wiki, but I
don't want it removed from our text because I have had to repeat that
information regularly in the past.
--
Kees Cook
^ permalink raw reply
* Re: [PATCH v2 2/2] f2fs: Support case-insensitive file name lookups
From: Chao Yu @ 2019-07-19 2:01 UTC (permalink / raw)
To: Daniel Rosenberg, Jaegeuk Kim, Jonathan Corbet, linux-f2fs-devel
Cc: linux-kernel, linux-doc, linux-fsdevel, kernel-team
In-Reply-To: <4ef17922-d1e9-1b83-9e89-d332ea6fb7ae@google.com>
On 2019/7/19 5:31, Daniel Rosenberg wrote:
>
> On 7/17/19 3:11 AM, Chao Yu wrote:
>> We need to add one more entry f2fs_fsflags_map[] to map F2FS_CASEFOLD_FL to
>> FS_CASEFOLD_FL correctly and adapt F2FS_GETTABLE_FS_FL/F2FS_SETTABLE_FS_FL as well.
>
> I don't see FS_CASEFOLD_FL. It would make sense for it to exist, but unless it's in some recent patch I don't think that's currently in the kernel. Or are you suggesting adding it in this patch?
Yeah, I think we can use a separated patch to propose uplifting the flag to a
common one in fs.h, and then adjust
f2fs_fsflags_map/F2FS_GETTABLE_FS_FL/F2FS_SETTABLE_FS_FL mapping. Otherwise we
will fail to set CASEFOLD flag to inode.
Thanks,
>
> .
>
^ permalink raw reply
* Re: [PATCH v3 2/2] f2fs: Support case-insensitive file name lookups
From: Chao Yu @ 2019-07-19 2:11 UTC (permalink / raw)
To: Daniel Rosenberg, Jaegeuk Kim, Jonathan Corbet, linux-f2fs-devel
Cc: linux-kernel, linux-doc, linux-fsdevel, kernel-team
In-Reply-To: <20190719000322.106163-3-drosen@google.com>
On 2019/7/19 8:03, Daniel Rosenberg wrote:
> Modeled after commit b886ee3e778e ("ext4: Support case-insensitive file
> name lookups")
>
> """
> This patch implements the actual support for case-insensitive file name
> lookups in f2fs, based on the feature bit and the encoding stored in the
> superblock.
>
> A filesystem that has the casefold feature set is able to configure
> directories with the +F (F2FS_CASEFOLD_FL) attribute, enabling lookups
> to succeed in that directory in a case-insensitive fashion, i.e: match
> a directory entry even if the name used by userspace is not a byte per
> byte match with the disk name, but is an equivalent case-insensitive
> version of the Unicode string. This operation is called a
> case-insensitive file name lookup.
>
> The feature is configured as an inode attribute applied to directories
> and inherited by its children. This attribute can only be enabled on
> empty directories for filesystems that support the encoding feature,
> thus preventing collision of file names that only differ by case.
>
> * dcache handling:
>
> For a +F directory, F2Fs only stores the first equivalent name dentry
> used in the dcache. This is done to prevent unintentional duplication of
> dentries in the dcache, while also allowing the VFS code to quickly find
> the right entry in the cache despite which equivalent string was used in
> a previous lookup, without having to resort to ->lookup().
>
> d_hash() of casefolded directories is implemented as the hash of the
> casefolded string, such that we always have a well-known bucket for all
> the equivalencies of the same string. d_compare() uses the
> utf8_strncasecmp() infrastructure, which handles the comparison of
> equivalent, same case, names as well.
>
> For now, negative lookups are not inserted in the dcache, since they
> would need to be invalidated anyway, because we can't trust missing file
> dentries. This is bad for performance but requires some leveraging of
> the vfs layer to fix. We can live without that for now, and so does
> everyone else.
>
> * on-disk data:
>
> Despite using a specific version of the name as the internal
> representation within the dcache, the name stored and fetched from the
> disk is a byte-per-byte match with what the user requested, making this
> implementation 'name-preserving'. i.e. no actual information is lost
> when writing to storage.
>
> DX is supported by modifying the hashes used in +F directories to make
> them case/encoding-aware. The new disk hashes are calculated as the
> hash of the full casefolded string, instead of the string directly.
> This allows us to efficiently search for file names in the htree without
> requiring the user to provide an exact name.
>
> * Dealing with invalid sequences:
>
> By default, when a invalid UTF-8 sequence is identified, ext4 will treat
> it as an opaque byte sequence, ignoring the encoding and reverting to
> the old behavior for that unique file. This means that case-insensitive
> file name lookup will not work only for that file. An optional bit can
> be set in the superblock telling the filesystem code and userspace tools
> to enforce the encoding. When that optional bit is set, any attempt to
> create a file name using an invalid UTF-8 sequence will fail and return
> an error to userspace.
>
> * Normalization algorithm:
>
> The UTF-8 algorithms used to compare strings in f2fs is implemented
> in fs/unicode, and is based on a previous version developed by
> SGI. It implements the Canonical decomposition (NFD) algorithm
> described by the Unicode specification 12.1, or higher, combined with
> the elimination of ignorable code points (NFDi) and full
> case-folding (CF) as documented in fs/unicode/utf8_norm.c.
>
> NFD seems to be the best normalization method for F2FS because:
>
> - It has a lower cost than NFC/NFKC (which requires
> decomposing to NFD as an intermediary step)
> - It doesn't eliminate important semantic meaning like
> compatibility decompositions.
>
> Although:
>
> - This implementation is not completely linguistic accurate, because
> different languages have conflicting rules, which would require the
> specialization of the filesystem to a given locale, which brings all
> sorts of problems for removable media and for users who use more than
> one language.
> """
>
> Signed-off-by: Daniel Rosenberg <drosen@google.com>
> ---
> fs/f2fs/dir.c | 126 +++++++++++++++++++++++++++++++++++++++++++----
> fs/f2fs/f2fs.h | 15 ++++--
> fs/f2fs/file.c | 9 ++++
> fs/f2fs/hash.c | 35 ++++++++++++-
> fs/f2fs/inline.c | 4 +-
> fs/f2fs/inode.c | 4 +-
> fs/f2fs/namei.c | 21 ++++++++
> fs/f2fs/super.c | 6 +++
> 8 files changed, 203 insertions(+), 17 deletions(-)
>
> diff --git a/fs/f2fs/dir.c b/fs/f2fs/dir.c
> index 85a1528f319f2..2913483473f30 100644
> --- a/fs/f2fs/dir.c
> +++ b/fs/f2fs/dir.c
> @@ -8,6 +8,7 @@
> #include <linux/fs.h>
> #include <linux/f2fs_fs.h>
> #include <linux/sched/signal.h>
> +#include <linux/unicode.h>
> #include "f2fs.h"
> #include "node.h"
> #include "acl.h"
> @@ -81,7 +82,8 @@ static unsigned long dir_block_index(unsigned int level,
> return bidx;
> }
>
> -static struct f2fs_dir_entry *find_in_block(struct page *dentry_page,
> +static struct f2fs_dir_entry *find_in_block(struct inode *dir,
> + struct page *dentry_page,
> struct fscrypt_name *fname,
> f2fs_hash_t namehash,
> int *max_slots,
> @@ -93,7 +95,7 @@ static struct f2fs_dir_entry *find_in_block(struct page *dentry_page,
>
> dentry_blk = (struct f2fs_dentry_block *)page_address(dentry_page);
>
> - make_dentry_ptr_block(NULL, &d, dentry_blk);
> + make_dentry_ptr_block(dir, &d, dentry_blk);
> de = f2fs_find_target_dentry(fname, namehash, max_slots, &d);
> if (de)
> *res_page = dentry_page;
> @@ -101,6 +103,39 @@ static struct f2fs_dir_entry *find_in_block(struct page *dentry_page,
> return de;
> }
>
> +#ifdef CONFIG_UNICODE
> +/*
> + * Test whether a case-insensitive directory entry matches the filename
> + * being searched for.
> + *
> + * Returns: 0 if the directory entry matches, more than 0 if it
> + * doesn't match or less than zero on error.
> + */
> +int f2fs_ci_compare(const struct inode *parent, const struct qstr *name,
> + const struct qstr *entry)
> +{
> + const struct f2fs_sb_info *sbi = F2FS_SB(parent->i_sb);
> + const struct unicode_map *um = sbi->s_encoding;
> + int ret;
> +
> + ret = utf8_strncasecmp(um, name, entry);
> + if (ret < 0) {
> + /* Handle invalid character sequence as either an error
> + * or as an opaque byte sequence.
> + */
> + if (f2fs_has_strict_mode(sbi))
> + return -EINVAL;
> +
> + if (name->len != entry->len)
> + return 1;
> +
> + return !!memcmp(name->name, entry->name, name->len);
> + }
> +
> + return ret;
> +}
> +#endif
> +
> struct f2fs_dir_entry *f2fs_find_target_dentry(struct fscrypt_name *fname,
> f2fs_hash_t namehash, int *max_slots,
> struct f2fs_dentry_ptr *d)
> @@ -108,6 +143,9 @@ struct f2fs_dir_entry *f2fs_find_target_dentry(struct fscrypt_name *fname,
> struct f2fs_dir_entry *de;
> unsigned long bit_pos = 0;
> int max_len = 0;
> +#ifdef CONFIG_UNICODE
> + struct qstr entry;
> +#endif
>
> if (max_slots)
> *max_slots = 0;
> @@ -119,16 +157,28 @@ struct f2fs_dir_entry *f2fs_find_target_dentry(struct fscrypt_name *fname,
> }
>
> de = &d->dentry[bit_pos];
> +#ifdef CONFIG_UNICODE
> + entry.name = d->filename[bit_pos];
> + entry.len = de->name_len;
> +#endif
>
> if (unlikely(!de->name_len)) {
> bit_pos++;
> continue;
> }
> + if (de->hash_code == namehash) {
> +#ifdef CONFIG_UNICODE
> + if (F2FS_SB(d->inode->i_sb)->s_encoding &&
> + IS_CASEFOLDED(d->inode) &&
> + !f2fs_ci_compare(d->inode,
> + fname->usr_fname, &entry))
> + goto found;
>
> - if (de->hash_code == namehash &&
> - fscrypt_match_name(fname, d->filename[bit_pos],
> - le16_to_cpu(de->name_len)))
> - goto found;
> +#endif
> + if (fscrypt_match_name(fname, d->filename[bit_pos],
> + le16_to_cpu(de->name_len)))
> + goto found;
> + }
>
> if (max_slots && max_len > *max_slots)
> *max_slots = max_len;
> @@ -157,7 +207,7 @@ static struct f2fs_dir_entry *find_in_level(struct inode *dir,
> struct f2fs_dir_entry *de = NULL;
> bool room = false;
> int max_slots;
> - f2fs_hash_t namehash = f2fs_dentry_hash(&name, fname);
> + f2fs_hash_t namehash = f2fs_dentry_hash(dir, &name, fname);
>
> nbucket = dir_buckets(level, F2FS_I(dir)->i_dir_level);
> nblock = bucket_blocks(level);
> @@ -179,8 +229,8 @@ static struct f2fs_dir_entry *find_in_level(struct inode *dir,
> }
> }
>
> - de = find_in_block(dentry_page, fname, namehash, &max_slots,
> - res_page);
> + de = find_in_block(dir, dentry_page, fname, namehash,
> + &max_slots, res_page);
> if (de)
> break;
>
> @@ -250,6 +300,14 @@ struct f2fs_dir_entry *f2fs_find_entry(struct inode *dir,
> struct fscrypt_name fname;
> int err;
>
> +#ifdef CONFIG_UNICODE
> + if (f2fs_has_strict_mode(F2FS_I_SB(dir)) && IS_CASEFOLDED(dir) &&
> + utf8_validate(F2FS_I_SB(dir)->s_encoding, child)) {
> + *res_page = ERR_PTR(-EINVAL);
> + return NULL;
> + }
> +#endif
> +
> err = fscrypt_setup_filename(dir, child, 1, &fname);
> if (err) {
> if (err == -ENOENT)
> @@ -504,7 +562,7 @@ int f2fs_add_regular_entry(struct inode *dir, const struct qstr *new_name,
>
> level = 0;
> slots = GET_DENTRY_SLOTS(new_name->len);
> - dentry_hash = f2fs_dentry_hash(new_name, NULL);
> + dentry_hash = f2fs_dentry_hash(dir, new_name, NULL);
>
> current_depth = F2FS_I(dir)->i_current_depth;
> if (F2FS_I(dir)->chash == dentry_hash) {
> @@ -943,3 +1001,51 @@ const struct file_operations f2fs_dir_operations = {
> .compat_ioctl = f2fs_compat_ioctl,
> #endif
> };
> +
> +#ifdef CONFIG_UNICODE
> +static int f2fs_d_compare(const struct dentry *dentry, unsigned int len,
> + const char *str, const struct qstr *name)
> +{
> + struct qstr qstr = {.name = str, .len = len };
> +
> + if (!IS_CASEFOLDED(dentry->d_parent->d_inode)) {
> + if (len != name->len)
> + return -1;
> + return memcmp(str, name, len);
> + }
> +
> + return f2fs_ci_compare(dentry->d_parent->d_inode, name, &qstr);
> +}
> +
> +static int f2fs_d_hash(const struct dentry *dentry, struct qstr *str)
> +{
> + struct f2fs_sb_info *sbi = F2FS_SB(dentry->d_sb);
> + const struct unicode_map *um = sbi->s_encoding;
> + unsigned char *norm;
> + int len, ret = 0;
> +
> + if (!IS_CASEFOLDED(dentry->d_inode))
> + return 0;
> +
> + norm = f2fs_kmalloc(sbi, PATH_MAX, GFP_ATOMIC);
> + if (!norm)
> + return -ENOMEM;
> +
> + len = utf8_casefold(um, str, norm, PATH_MAX);
> + if (len < 0) {
> + if (f2fs_has_strict_mode(sbi))
> + ret = -EINVAL;
> + goto out;
> + }
> + str->hash = full_name_hash(dentry, norm, len);
> +out:
> + kvfree(norm);
> + return ret;
> +}
> +
> +const struct dentry_operations f2fs_dentry_ops = {
> + .d_hash = f2fs_d_hash,
> + .d_compare = f2fs_d_compare,
> +};
> +#endif
> +
> diff --git a/fs/f2fs/f2fs.h b/fs/f2fs/f2fs.h
> index c6c7904572d0d..31fd2a268ba14 100644
> --- a/fs/f2fs/f2fs.h
> +++ b/fs/f2fs/f2fs.h
> @@ -2364,10 +2364,12 @@ static inline void f2fs_change_bit(unsigned int nr, char *addr)
> #define F2FS_INDEX_FL 0x00001000 /* hash-indexed directory */
> #define F2FS_DIRSYNC_FL 0x00010000 /* dirsync behaviour (directories only) */
> #define F2FS_PROJINHERIT_FL 0x20000000 /* Create with parents projid */
> +#define F2FS_CASEFOLD_FL 0x40000000 /* Casefolded file */
>
> /* Flags that should be inherited by new inodes from their parent. */
> #define F2FS_FL_INHERITED (F2FS_SYNC_FL | F2FS_NODUMP_FL | F2FS_NOATIME_FL | \
> - F2FS_DIRSYNC_FL | F2FS_PROJINHERIT_FL)
> + F2FS_DIRSYNC_FL | F2FS_PROJINHERIT_FL | \
> + F2FS_CASEFOLD_FL)
>
> /* Flags that are appropriate for regular files (all but dir-specific ones). */
> #define F2FS_REG_FLMASK (~(F2FS_DIRSYNC_FL | F2FS_PROJINHERIT_FL))
> @@ -2930,6 +2932,10 @@ int f2fs_update_extension_list(struct f2fs_sb_info *sbi, const char *name,
> bool hot, bool set);
> struct dentry *f2fs_get_parent(struct dentry *child);
>
> +extern int f2fs_ci_compare(const struct inode *parent,
> + const struct qstr *name,
> + const struct qstr *entry);
> +
> /*
> * dir.c
> */
> @@ -2993,8 +2999,8 @@ int f2fs_sanity_check_ckpt(struct f2fs_sb_info *sbi);
> /*
> * hash.c
> */
> -f2fs_hash_t f2fs_dentry_hash(const struct qstr *name_info,
> - struct fscrypt_name *fname);
> +f2fs_hash_t f2fs_dentry_hash(const struct inode *dir,
> + const struct qstr *name_info, struct fscrypt_name *fname);
>
> /*
> * node.c
> @@ -3437,6 +3443,9 @@ static inline void f2fs_destroy_root_stats(void) { }
> #endif
>
> extern const struct file_operations f2fs_dir_operations;
> +#ifdef CONFIG_UNICODE
> +extern const struct dentry_operations f2fs_dentry_ops;
> +#endif
> extern const struct file_operations f2fs_file_operations;
> extern const struct inode_operations f2fs_file_inode_operations;
> extern const struct address_space_operations f2fs_dblock_aops;
> diff --git a/fs/f2fs/file.c b/fs/f2fs/file.c
> index f8d46df8fa9ee..7adef2d8dbc47 100644
> --- a/fs/f2fs/file.c
> +++ b/fs/f2fs/file.c
> @@ -1660,7 +1660,16 @@ static int f2fs_setflags_common(struct inode *inode, u32 iflags, u32 mask)
> return -EPERM;
>
> oldflags = fi->i_flags;
> + if ((iflags ^ oldflags) & F2FS_CASEFOLD_FL) {
> + if (!f2fs_sb_has_casefold(F2FS_I_SB(inode)))
> + return -EOPNOTSUPP;
> +
> + if (!S_ISDIR(inode->i_mode))
> + return -ENOTDIR;
>
> + if (!f2fs_empty_dir(inode))
> + return -ENOTEMPTY;
> + }
> if ((iflags ^ oldflags) & (F2FS_APPEND_FL | F2FS_IMMUTABLE_FL))
> if (!capable(CAP_LINUX_IMMUTABLE))
> return -EPERM;
> diff --git a/fs/f2fs/hash.c b/fs/f2fs/hash.c
> index cc82f142f811f..b7bd0ddbbdf01 100644
> --- a/fs/f2fs/hash.c
> +++ b/fs/f2fs/hash.c
> @@ -14,6 +14,7 @@
> #include <linux/f2fs_fs.h>
> #include <linux/cryptohash.h>
> #include <linux/pagemap.h>
> +#include <linux/unicode.h>
>
> #include "f2fs.h"
>
> @@ -67,7 +68,7 @@ static void str2hashbuf(const unsigned char *msg, size_t len,
> *buf++ = pad;
> }
>
> -f2fs_hash_t f2fs_dentry_hash(const struct qstr *name_info,
> +static f2fs_hash_t __f2fs_dentry_hash(const struct qstr *name_info,
> struct fscrypt_name *fname)
> {
> __u32 hash;
> @@ -103,3 +104,35 @@ f2fs_hash_t f2fs_dentry_hash(const struct qstr *name_info,
> f2fs_hash = cpu_to_le32(hash & ~F2FS_HASH_COL_BIT);
> return f2fs_hash;
> }
> +
> +f2fs_hash_t f2fs_dentry_hash(const struct inode *dir,
> + const struct qstr *name_info, struct fscrypt_name *fname)
> +{
> +#ifdef CONFIG_UNICODE
> + struct f2fs_sb_info *sbi = F2FS_SB(dir->i_sb);
> + const struct unicode_map *um = sbi->s_encoding;
> + int r, dlen;
> + unsigned char *buff;
> + struct qstr *folded;
> +
> + if (name_info->len && IS_CASEFOLDED(dir)) {
> + buff = f2fs_kzalloc(sbi, sizeof(char) * PATH_MAX, GFP_KERNEL);
> + if (!buff)
> + return -ENOMEM;
> +
> + dlen = utf8_casefold(um, name_info, buff, PATH_MAX);
> + if (dlen < 0) {
> + kfree(buff);
kvfree()
> + goto opaque_seq;
> + }
> + folded->name = buff;
> + folded->len = dlen;
> + r = __f2fs_dentry_hash(folded, fname);
> +
> + kvfree(buff);
> + return r;
> + }
> +opaque_seq:
> +#endif
> + return __f2fs_dentry_hash(name_info, fname);
> +}
> diff --git a/fs/f2fs/inline.c b/fs/f2fs/inline.c
> index 3613efca8c00c..354f71cf9e6ba 100644
> --- a/fs/f2fs/inline.c
> +++ b/fs/f2fs/inline.c
> @@ -320,7 +320,7 @@ struct f2fs_dir_entry *f2fs_find_in_inline_dir(struct inode *dir,
> return NULL;
> }
>
> - namehash = f2fs_dentry_hash(&name, fname);
> + namehash = f2fs_dentry_hash(dir, &name, fname);
>
> inline_dentry = inline_data_addr(dir, ipage);
>
> @@ -580,7 +580,7 @@ int f2fs_add_inline_entry(struct inode *dir, const struct qstr *new_name,
>
> f2fs_wait_on_page_writeback(ipage, NODE, true, true);
>
> - name_hash = f2fs_dentry_hash(new_name, NULL);
> + name_hash = f2fs_dentry_hash(dir, new_name, NULL);
> f2fs_update_dentry(ino, mode, &d, new_name, name_hash, bit_pos);
>
> set_page_dirty(ipage);
> diff --git a/fs/f2fs/inode.c b/fs/f2fs/inode.c
> index a33d7a849b2df..9a1f0d6616577 100644
> --- a/fs/f2fs/inode.c
> +++ b/fs/f2fs/inode.c
> @@ -46,9 +46,11 @@ void f2fs_set_inode_flags(struct inode *inode)
> new_fl |= S_DIRSYNC;
> if (file_is_encrypt(inode))
> new_fl |= S_ENCRYPTED;
> + if (flags & F2FS_CASEFOLD_FL)
> + new_fl |= S_CASEFOLD;
> inode_set_flags(inode, new_fl,
> S_SYNC|S_APPEND|S_IMMUTABLE|S_NOATIME|S_DIRSYNC|
> - S_ENCRYPTED);
> + S_ENCRYPTED|S_CASEFOLD);
> }
>
> static void __get_inode_rdev(struct inode *inode, struct f2fs_inode *ri)
> diff --git a/fs/f2fs/namei.c b/fs/f2fs/namei.c
> index c5b99042e6f2b..727de2f8620f2 100644
> --- a/fs/f2fs/namei.c
> +++ b/fs/f2fs/namei.c
> @@ -489,6 +489,17 @@ static struct dentry *f2fs_lookup(struct inode *dir, struct dentry *dentry,
> goto out_iput;
> }
> out_splice:
> +#ifdef CONFIG_UNICODE
> + if (!inode && IS_CASEFOLDED(dir)) {
> + /* Eventually we want to call d_add_ci(dentry, NULL)
> + * for negative dentries in the encoding case as
> + * well. For now, prevent the negative dentry
> + * from being cached.
> + */
> + trace_f2fs_lookup_end(dir, dentry, ino, err);
> + return NULL;
> + }
> +#endif
> new = d_splice_alias(inode, dentry);
> err = PTR_ERR_OR_ZERO(new);
> trace_f2fs_lookup_end(dir, dentry, ino, err);
> @@ -537,6 +548,16 @@ static int f2fs_unlink(struct inode *dir, struct dentry *dentry)
> goto fail;
> }
> f2fs_delete_entry(de, page, dir, inode);
> +#ifdef CONFIG_UNICODE
> + /* VFS negative dentries are incompatible with Encoding and
> + * Case-insensitiveness. Eventually we'll want avoid
> + * invalidating the dentries here, alongside with returning the
> + * negative dentries at f2fs_lookup(), when it is better
> + * supported by the VFS for the CI case.
> + */
> + if (IS_CASEFOLDED(dir))
> + d_invalidate(dentry);
> +#endif
> f2fs_unlock_op(sbi);
>
> if (IS_DIRSYNC(dir))
> diff --git a/fs/f2fs/super.c b/fs/f2fs/super.c
> index 82f7da93c3ed1..9c522d1abcb6d 100644
> --- a/fs/f2fs/super.c
> +++ b/fs/f2fs/super.c
> @@ -3115,6 +3115,7 @@ static int f2fs_setup_casefold(struct f2fs_sb_info *sbi)
> return -EINVAL;
> }
> #endif
> + return 0;
It needs to relocate this line to PATCH 1/2
> }
>
> static void f2fs_tuning_parameters(struct f2fs_sb_info *sbi)
> @@ -3410,6 +3411,11 @@ static int f2fs_fill_super(struct super_block *sb, void *data, int silent)
> goto free_node_inode;
> }
>
> +#ifdef CONFIG_UNICODE
> + if (sbi->s_encoding)
> + sb->s_d_op = &f2fs_dentry_ops;
> +#endif
How about moving this to f2fs_setup_casefold()?
Thanks,
> +
> sb->s_root = d_make_root(root); /* allocate root dentry */
> if (!sb->s_root) {
> err = -ENOMEM;
>
^ permalink raw reply
* Re: [PATCH v3 1/2] f2fs: include charset encoding information in the superblock
From: Chao Yu @ 2019-07-19 2:03 UTC (permalink / raw)
To: Daniel Rosenberg, Jaegeuk Kim, Jonathan Corbet, linux-f2fs-devel
Cc: linux-kernel, linux-doc, linux-fsdevel, kernel-team
In-Reply-To: <20190719000322.106163-2-drosen@google.com>
On 2019/7/19 8:03, Daniel Rosenberg wrote:
> Add charset encoding to f2fs to support casefolding. It is modeled after
> the same feature introduced in commit c83ad55eaa91 ("ext4: include charset
> encoding information in the superblock")
>
> Currently this is not compatible with encryption, similar to the current
> ext4 imlpementation. This will change in the future.
>
>>From the ext4 patch:
> """
> The s_encoding field stores a magic number indicating the encoding
> format and version used globally by file and directory names in the
> filesystem. The s_encoding_flags defines policies for using the charset
> encoding, like how to handle invalid sequences. The magic number is
> mapped to the exact charset table, but the mapping is specific to ext4.
> Since we don't have any commitment to support old encodings, the only
> encoding I am supporting right now is utf8-12.1.0.
>
> The current implementation prevents the user from enabling encoding and
> per-directory encryption on the same filesystem at the same time. The
> incompatibility between these features lies in how we do efficient
> directory searches when we cannot be sure the encryption of the user
> provided fname will match the actual hash stored in the disk without
> decrypting every directory entry, because of normalization cases. My
> quickest solution is to simply block the concurrent use of these
> features for now, and enable it later, once we have a better solution.
> """
>
> Signed-off-by: Daniel Rosenberg <drosen@google.com>
> ---
> fs/f2fs/f2fs.h | 6 +++
> fs/f2fs/super.c | 94 +++++++++++++++++++++++++++++++++++++++++
> fs/f2fs/sysfs.c | 23 ++++++++++
> include/linux/f2fs_fs.h | 9 +++-
> 4 files changed, 131 insertions(+), 1 deletion(-)
>
> diff --git a/fs/f2fs/f2fs.h b/fs/f2fs/f2fs.h
> index 17382da7f0bd9..c6c7904572d0d 100644
> --- a/fs/f2fs/f2fs.h
> +++ b/fs/f2fs/f2fs.h
> @@ -153,6 +153,7 @@ struct f2fs_mount_info {
> #define F2FS_FEATURE_LOST_FOUND 0x0200
> #define F2FS_FEATURE_VERITY 0x0400 /* reserved */
> #define F2FS_FEATURE_SB_CHKSUM 0x0800
> +#define F2FS_FEATURE_CASEFOLD 0x1000
>
> #define __F2FS_HAS_FEATURE(raw_super, mask) \
> ((raw_super->feature & cpu_to_le32(mask)) != 0)
> @@ -1169,6 +1170,10 @@ struct f2fs_sb_info {
> int valid_super_block; /* valid super block no */
> unsigned long s_flag; /* flags for sbi */
> struct mutex writepages; /* mutex for writepages() */
> +#ifdef CONFIG_UNICODE
> + struct unicode_map *s_encoding;
> + __u16 s_encoding_flags;
> +#endif
>
> #ifdef CONFIG_BLK_DEV_ZONED
> unsigned int blocks_per_blkz; /* F2FS blocks per zone */
> @@ -3562,6 +3567,7 @@ F2FS_FEATURE_FUNCS(quota_ino, QUOTA_INO);
> F2FS_FEATURE_FUNCS(inode_crtime, INODE_CRTIME);
> F2FS_FEATURE_FUNCS(lost_found, LOST_FOUND);
> F2FS_FEATURE_FUNCS(sb_chksum, SB_CHKSUM);
> +F2FS_FEATURE_FUNCS(casefold, CASEFOLD);
>
> #ifdef CONFIG_BLK_DEV_ZONED
> static inline bool f2fs_blkz_is_seq(struct f2fs_sb_info *sbi, int devi,
> diff --git a/fs/f2fs/super.c b/fs/f2fs/super.c
> index 6de6cda440315..82f7da93c3ed1 100644
> --- a/fs/f2fs/super.c
> +++ b/fs/f2fs/super.c
> @@ -23,6 +23,7 @@
> #include <linux/f2fs_fs.h>
> #include <linux/sysfs.h>
> #include <linux/quota.h>
> +#include <linux/unicode.h>
>
> #include "f2fs.h"
> #include "node.h"
> @@ -222,6 +223,36 @@ void f2fs_printk(struct f2fs_sb_info *sbi, const char *fmt, ...)
> va_end(args);
> }
>
> +#ifdef CONFIG_UNICODE
> +static const struct f2fs_sb_encodings {
> + __u16 magic;
> + char *name;
> + char *version;
> +} f2fs_sb_encoding_map[] = {
> + {F2FS_ENC_UTF8_12_1, "utf8", "12.1.0"},
> +};
> +
> +static int f2fs_sb_read_encoding(const struct f2fs_super_block *sb,
> + const struct f2fs_sb_encodings **encoding,
> + __u16 *flags)
> +{
> + __u16 magic = le16_to_cpu(sb->s_encoding);
> + int i;
> +
> + for (i = 0; i < ARRAY_SIZE(f2fs_sb_encoding_map); i++)
> + if (magic == f2fs_sb_encoding_map[i].magic)
> + break;
> +
> + if (i >= ARRAY_SIZE(f2fs_sb_encoding_map))
> + return -EINVAL;
> +
> + *encoding = &f2fs_sb_encoding_map[i];
> + *flags = le16_to_cpu(sb->s_encoding_flags);
> +
> + return 0;
> +}
> +#endif
> +
> static inline void limit_reserve_root(struct f2fs_sb_info *sbi)
> {
> block_t limit = min((sbi->user_block_count << 1) / 1000,
> @@ -798,6 +829,13 @@ static int parse_options(struct super_block *sb, char *options)
> return -EINVAL;
> }
> #endif
> +#ifndef CONFIG_UNICODE
> + if (f2fs_sb_has_casefold(sbi)) {
> + f2fs_err(sbi,
> + "Filesystem with casefold feature cannot be mounted without CONFIG_UNICODE");
> + return -EINVAL;
> + }
> +#endif
>
> if (F2FS_IO_SIZE_BITS(sbi) && !test_opt(sbi, LFS)) {
> f2fs_err(sbi, "Should set mode=lfs with %uKB-sized IO",
> @@ -1089,6 +1127,9 @@ static void f2fs_put_super(struct super_block *sb)
> destroy_percpu_info(sbi);
> for (i = 0; i < NR_PAGE_TYPE; i++)
> kvfree(sbi->write_io[i]);
> +#ifdef CONFIG_UNICODE
> + utf8_unload(sbi->s_encoding);
> +#endif
> kvfree(sbi);
> }
>
> @@ -3031,6 +3072,51 @@ static int f2fs_scan_devices(struct f2fs_sb_info *sbi)
> return 0;
> }
>
> +static int f2fs_setup_casefold(struct f2fs_sb_info *sbi)
> +{
> +#ifdef CONFIG_UNICODE
> + if (f2fs_sb_has_casefold(sbi) && !sbi->s_encoding) {
> + const struct f2fs_sb_encodings *encoding_info;
> + struct unicode_map *encoding;
> + __u16 encoding_flags;
> +
> + if (f2fs_sb_has_encrypt(sbi)) {
> + f2fs_err(sbi,
> + "Can't mount with encoding and encryption");
> + return -EINVAL;
> + }
> +
> + if (f2fs_sb_read_encoding(sbi->raw_super, &encoding_info,
> + &encoding_flags)) {
> + f2fs_err(sbi,
> + "Encoding requested by superblock is unknown");
> + return -EINVAL;
> + }
> +
> + encoding = utf8_load(encoding_info->version);
> + if (IS_ERR(encoding)) {
> + f2fs_err(sbi,
> + "can't mount with superblock charset: %s-%s "
> + "not supported by the kernel. flags: 0x%x.",
> + encoding_info->name, encoding_info->version,
> + encoding_flags);
> + return PTR_ERR(encoding);
> + }
> + f2fs_info(sbi, "Using encoding defined by superblock: "
> + "%s-%s with flags 0x%hx", encoding_info->name,
> + encoding_info->version?:"\b", encoding_flags);
> +
> + sbi->s_encoding = encoding;
> + sbi->s_encoding_flags = encoding_flags;
> + }
> +#else
> + if (f2fs_sb_has_casefold(sbi)) {
> + f2fs_err(sbi, "Filesystem with casefold feature cannot be mounted without CONFIG_UNICODE");
> + return -EINVAL;
> + }
> +#endif
> +}
> +
> static void f2fs_tuning_parameters(struct f2fs_sb_info *sbi)
> {
> struct f2fs_sm_info *sm_i = SM_I(sbi);
> @@ -3127,6 +3213,10 @@ static int f2fs_fill_super(struct super_block *sb, void *data, int silent)
> le32_to_cpu(raw_super->log_blocksize);
> sb->s_max_links = F2FS_LINK_MAX;
>
> + err = f2fs_setup_casefold(sbi);
> + if (err)
> + goto free_options;
> +
> #ifdef CONFIG_QUOTA
> sb->dq_op = &f2fs_quota_operations;
> sb->s_qcop = &f2fs_quotactl_ops;
> @@ -3477,6 +3567,10 @@ static int f2fs_fill_super(struct super_block *sb, void *data, int silent)
> free_bio_info:
> for (i = 0; i < NR_PAGE_TYPE; i++)
> kvfree(sbi->write_io[i]);
> +
> +#ifdef CONFIG_UNICODE
> + utf8_unload(sbi->s_encoding);
> +#endif
> free_options:
> #ifdef CONFIG_QUOTA
> for (i = 0; i < MAXQUOTAS; i++)
> diff --git a/fs/f2fs/sysfs.c b/fs/f2fs/sysfs.c
> index 3aeacd0aacfd2..f9fcca695db9f 100644
> --- a/fs/f2fs/sysfs.c
> +++ b/fs/f2fs/sysfs.c
> @@ -10,6 +10,7 @@
> #include <linux/proc_fs.h>
> #include <linux/f2fs_fs.h>
> #include <linux/seq_file.h>
> +#include <linux/unicode.h>
>
> #include "f2fs.h"
> #include "segment.h"
> @@ -81,6 +82,19 @@ static ssize_t unusable_show(struct f2fs_attr *a,
> (unsigned long long)unusable);
> }
>
> +static ssize_t encoding_show(struct f2fs_attr *a,
> + struct f2fs_sb_info *sbi, char *buf)
> +{
> +#ifdef CONFIG_UNICODE
> + if (f2fs_sb_has_casefold(sbi))
> + return snprintf(buf, PAGE_SIZE, "%s (%d.%d.%d)\n",
> + sbi->s_encoding->charset,
> + (sbi->s_encoding->version >> 16) & 0xff,
> + (sbi->s_encoding->version >> 8) & 0xff,
> + sbi->s_encoding->version & 0xff);
> +#endif
> + return snprintf(buf, PAGE_SIZE, "(none)");
> +}
>
> static ssize_t lifetime_write_kbytes_show(struct f2fs_attr *a,
> struct f2fs_sb_info *sbi, char *buf)
> @@ -134,6 +148,9 @@ static ssize_t features_show(struct f2fs_attr *a,
> if (f2fs_sb_has_sb_chksum(sbi))
> len += snprintf(buf + len, PAGE_SIZE - len, "%s%s",
> len ? ", " : "", "sb_checksum");
> + if (f2fs_sb_has_casefold(sbi))
> + len += snprintf(buf + len, PAGE_SIZE - len, "%s%s",
> + len ? ", " : "", "casefold");
> len += snprintf(buf + len, PAGE_SIZE - len, "\n");
> return len;
> }
> @@ -365,6 +382,7 @@ enum feat_id {
> FEAT_INODE_CRTIME,
> FEAT_LOST_FOUND,
> FEAT_SB_CHECKSUM,
> + FEAT_CASEFOLD,
> };
>
> static ssize_t f2fs_feature_show(struct f2fs_attr *a,
> @@ -382,6 +400,7 @@ static ssize_t f2fs_feature_show(struct f2fs_attr *a,
> case FEAT_INODE_CRTIME:
> case FEAT_LOST_FOUND:
> case FEAT_SB_CHECKSUM:
> + case FEAT_CASEFOLD:
> return snprintf(buf, PAGE_SIZE, "supported\n");
> }
> return 0;
> @@ -455,6 +474,7 @@ F2FS_GENERAL_RO_ATTR(lifetime_write_kbytes);
> F2FS_GENERAL_RO_ATTR(features);
> F2FS_GENERAL_RO_ATTR(current_reserved_blocks);
> F2FS_GENERAL_RO_ATTR(unusable);
> +F2FS_GENERAL_RO_ATTR(encoding);
>
> #ifdef CONFIG_FS_ENCRYPTION
> F2FS_FEATURE_RO_ATTR(encryption, FEAT_CRYPTO);
> @@ -471,6 +491,7 @@ F2FS_FEATURE_RO_ATTR(quota_ino, FEAT_QUOTA_INO);
> F2FS_FEATURE_RO_ATTR(inode_crtime, FEAT_INODE_CRTIME);
> F2FS_FEATURE_RO_ATTR(lost_found, FEAT_LOST_FOUND);
> F2FS_FEATURE_RO_ATTR(sb_checksum, FEAT_SB_CHECKSUM);
> +F2FS_FEATURE_RO_ATTR(casefold, FEAT_CASEFOLD);
>
> #define ATTR_LIST(name) (&f2fs_attr_##name.attr)
> static struct attribute *f2fs_attrs[] = {
> @@ -515,6 +536,7 @@ static struct attribute *f2fs_attrs[] = {
> ATTR_LIST(features),
> ATTR_LIST(reserved_blocks),
> ATTR_LIST(current_reserved_blocks),
> + ATTR_LIST(encoding),
Let's document this entry in f2fs.txt and sysfs-fs-f2fs.
Thanks,
> NULL,
> };
> ATTRIBUTE_GROUPS(f2fs);
> @@ -535,6 +557,7 @@ static struct attribute *f2fs_feat_attrs[] = {
> ATTR_LIST(inode_crtime),
> ATTR_LIST(lost_found),
> ATTR_LIST(sb_checksum),
> + ATTR_LIST(casefold),
> NULL,
> };
> ATTRIBUTE_GROUPS(f2fs_feat);
> diff --git a/include/linux/f2fs_fs.h b/include/linux/f2fs_fs.h
> index 65559900d4d76..b7c9c7f721339 100644
> --- a/include/linux/f2fs_fs.h
> +++ b/include/linux/f2fs_fs.h
> @@ -36,6 +36,11 @@
>
> #define F2FS_MAX_QUOTAS 3
>
> +#define F2FS_ENC_UTF8_12_1 1
> +#define F2FS_ENC_STRICT_MODE_FL (1 << 0)
> +#define f2fs_has_strict_mode(sbi) \
> + (sbi->s_encoding_flags & F2FS_ENC_STRICT_MODE_FL)
> +
> #define F2FS_IO_SIZE(sbi) (1 << F2FS_OPTION(sbi).write_io_size_bits) /* Blocks */
> #define F2FS_IO_SIZE_KB(sbi) (1 << (F2FS_OPTION(sbi).write_io_size_bits + 2)) /* KB */
> #define F2FS_IO_SIZE_BYTES(sbi) (1 << (F2FS_OPTION(sbi).write_io_size_bits + 12)) /* B */
> @@ -109,7 +114,9 @@ struct f2fs_super_block {
> struct f2fs_device devs[MAX_DEVICES]; /* device list */
> __le32 qf_ino[F2FS_MAX_QUOTAS]; /* quota inode numbers */
> __u8 hot_ext_count; /* # of hot file extension */
> - __u8 reserved[310]; /* valid reserved region */
> + __le16 s_encoding; /* Filename charset encoding */
> + __le16 s_encoding_flags; /* Filename charset encoding flags */
> + __u8 reserved[306]; /* valid reserved region */
> __le32 crc; /* checksum of superblock */
> } __packed;
>
>
^ permalink raw reply
* Re: Using rst2pdf for PDF output - Was: Re: [PATCH 0/5] PDF output fixes
From: Mauro Carvalho Chehab @ 2019-07-19 2:44 UTC (permalink / raw)
To: Markus Heiser; +Cc: Jonathan Corbet, linux-doc
In-Reply-To: <04a1a65f-c96c-1f4a-d987-d8b9e605d7c1@darmarit.de>
Em Thu, 18 Jul 2019 19:56:57 +0200
Markus Heiser <markus.heiser@darmarit.de> escreveu:
> Am 18.07.19 um 19:46 schrieb Mauro Carvalho Chehab:
> > Em Sat, 13 Jul 2019 00:41:25 -0300
> > Mauro Carvalho Chehab <mchehab+samsung@kernel.org> escreveu:
> >
> >> Em Fri, 12 Jul 2019 19:27:05 -0300
> >> Mauro Carvalho Chehab <mchehab+samsung@kernel.org> escreveu:
> >>
> >>> Em Fri, 12 Jul 2019 14:19:21 -0600
> >>> Jonathan Corbet <corbet@lwn.net> escreveu:
> >>>
> >>>> Can't you just make rst2pdf work instead? :)
> >>>
> >>> Well, we can try.
>
> Thanks a lot for your investigation on this. I also checked the rst2pdf sources
> a while ago, for me it was crap with crap requirements [1] .. my tip: don't
> waste to much time on it.
>
> [1] https://github.com/mchehab/rst2pdf/blob/master/requirements.txt#L31
>
Yeah, a simple test shows that this upstream rst2pdf + latest reportlab has
some issues.
Running this:
$ rst2pdf Documentation/process/license-rules.rst
causes an error with reportlab-3.5.23. It has to be downgraded to version
3.4 in order to avoid this error:
File "/devel/v4l/docs_temp/sphinx_2.0.1/lib/python3.7/site-packages/reportlab/platypus/doctemplate.py", line 651, in handle_pageEnd
raise LayoutError(ident)
reportlab.platypus.doctemplate.LayoutError: More than 10 pages generated without content - halting layout. Likely that a flowable is too large for any frame.
Another solution would be to do this:
diff --git a/Documentation/process/license-rules.rst b/Documentation/process/license-rules.rst
index 2ef44ada3f11..19a480ebd69a 100644
--- a/Documentation/process/license-rules.rst
+++ b/Documentation/process/license-rules.rst
@@ -452,7 +452,10 @@ _`MODULE_LICENSE`
module source is dual licensed under a
GPL v2 variant and MIT license. Please do
not use in new code.
+ ============================= =============================================
+
+ ============================= =============================================
"Dual MIT/GPL" The correct way of expressing that the
module is dual licensed under a GPL v2
variant or MIT license choice.
But it sucks needing to break long tables because reportlab's handling
for big tables is broken.
Thanks,
Mauro
^ permalink raw reply related
* Re: [PATCH v2] Documentation/security-bugs: provide more information about linux-distros
From: Sasha Levin @ 2019-07-19 3:41 UTC (permalink / raw)
To: Kees Cook
Cc: corbet, solar, will, peterz, gregkh, tyhicks, linux-doc,
linux-kernel
In-Reply-To: <201907181833.EF0D93C@keescook>
On Thu, Jul 18, 2019 at 06:51:07PM -0700, Kees Cook wrote:
>On Thu, Jul 18, 2019 at 08:39:19PM -0400, Sasha Levin wrote:
>> On Thu, Jul 18, 2019 at 03:00:55PM -0700, Kees Cook wrote:
>> > On Wed, Jul 17, 2019 at 07:11:03PM -0400, Sasha Levin wrote:
>> > > Provide more information about how to interact with the linux-distros
>> > > mailing list for disclosing security bugs.
>> > >
>> > > Reference the linux-distros list policy and clarify that the reporter
>> > > must read and understand those policies as they differ from
>> > > security@kernel.org's policy.
>> > >
>> > > Suggested-by: Solar Designer <solar@openwall.com>
>> > > Signed-off-by: Sasha Levin <sashal@kernel.org>
>> >
>> > Sorry, but NACK, see below...
>> >
>> > > ---
>> > >
>> > > Changes in v2:
>> > > - Focus more on pointing to the linux-distros wiki and policies.
>> >
>> > I think this is already happening in the text. What specifically do you
>> > want described differently?
>>
>> The main issue was that there isn't anything pointing to the
>> linux-distros policies. The current text outlines a few of them ("add
>> [vs]", and "there should be an embargo period"), but it effectively just
>> gives out the linux-distros mailing address and tells the reporter to
>> contact it.
>
>The current text includes the wiki link, but yes, the anchor tag is not
>present at the wiki anymore. I would agree that's due for updating.
>
>I think reinforcing information to avoid past mistakes is appropriate
>here. Reports have regularly missed the "[vs]" detail or suggested
>embargoes that ended on Fridays, etc.
Right, but this is a sign that the reporter didn't read the wiki.
Explaining things like this encourages reporters to skip reading the
wiki and just send their report out.
>> > > - Remove explicit linux-distros email.
>> >
>> > I don't like this because we had past trouble with notifications going
>> > to the distros@ list and leaking Linux-only flaws to the BSDs. As there
>> > isn't a separate linux-distros wiki, the clarification of WHICH list is
>> > needed.
>>
>> Why would removing the explicit linux-distros email encourage people to
>> send reports to it?
>
>What? No, I'm saying we should _keep_ linux-distros@... in our text so
>that people don't send to the wrong list.
But doesn't this just encourage mails being sent to linux-distros@
without the policies being followed? That was Alexander's concern at
least.
>> I also don't understand what you mean by "there isn't a separate
>> linux-distros wiki"? There is one, and I want to point the reporter
>> there.
>
>That URL is a combined page for two lists. The very fact that it's
>not obvious that there are two lists described there is exactly why I
>think we need to keep an explicit mention of which to use. There are
>two mailing lists described at the wiki URL:
>
> distros@lists.openwall.com
> linux-distros@lists.openwall.com
>
>Sending to the distros@ list risks exposing Linux-only flaws to non-Linux
>distros. This has caused leaks in the past, and we do not want people
>guessing at which list they should use.
>
>Also note that nowhere on the openwall wiki is the email address
>actually spelled out; this is another reason to spell it out in our
>documentation: no misunderstanding.
>
>(And historically there WAS a specific linux-distros wiki:
>https://oss-security.openwall.org/wiki/mailing-lists/linux-distros
>but it redirects to the combined one now...)
>
>> > > - Remove various explanations of linux-distros policies.
>> >
>> > I don't think there's value in removing the Tue-Thu comment, nor
>> > providing context for why distros need time. This has been a regular
>> > thing we've had to explain to researchers that aren't familiar with
>> > update procedures and publication timing.
>>
>> To be fair, the Tue-Thu comment is listed in the section describing how
>> to do coordination with linux-distros, and linux-distros don't have a
>> Tue-Thu policy. If it's a security@kernel.org policy then let's list it
>> elsewhere.
>
>It's a distro preference. Many researchers aren't thinking about the
>larger Linux ecosystem that has to consume fixes. It's not a _policy_,
>but it makes the researchers understand how to construct better embargoes.
If it's an accepted preference then we should just document it in a few
other places like the linux-distros@ wiki. My concern with this is that
it's not, and it's actually one of the only things Alexander pointed out
in this document as surprising.
--
Thanks,
Sasha
>> If you feel that there is a consensus around Tue-Thu let's just add it
>> to the linux-distros policy wiki, there's no point in listing random
>> policies from that wiki.
>
>I think it'd be a good idea to add that note also to the wiki, but I
>don't want it removed from our text because I have had to repeat that
>information regularly in the past.
>
>--
>Kees Cook
^ permalink raw reply
* Re: [PATCH v2] Documentation/security-bugs: provide more information about linux-distros
From: Solar Designer @ 2019-07-19 8:42 UTC (permalink / raw)
To: Kees Cook
Cc: Sasha Levin, corbet, will, peterz, gregkh, tyhicks, linux-doc,
linux-kernel
In-Reply-To: <201907181833.EF0D93C@keescook>
On Thu, Jul 18, 2019 at 06:51:07PM -0700, Kees Cook wrote:
> On Thu, Jul 18, 2019 at 08:39:19PM -0400, Sasha Levin wrote:
> > On Thu, Jul 18, 2019 at 03:00:55PM -0700, Kees Cook wrote:
> > > On Wed, Jul 17, 2019 at 07:11:03PM -0400, Sasha Levin wrote:
> > > > Provide more information about how to interact with the linux-distros
> > > > mailing list for disclosing security bugs.
> > > >
> > > > Reference the linux-distros list policy and clarify that the reporter
> > > > must read and understand those policies as they differ from
> > > > security@kernel.org's policy.
> > > >
> > > > Suggested-by: Solar Designer <solar@openwall.com>
> > > > Signed-off-by: Sasha Levin <sashal@kernel.org>
> > >
> > > Sorry, but NACK, see below...
I like Sasha's PATCH v2 better, but if Kees insists on NACK'ing it then
I suggest that we apply Sasha's first revision of the patch instead.
I think either revision is an improvement on the status quo.
> I think reinforcing information to avoid past mistakes is appropriate
> here.
Maybe, but from my perspective common past issues with Linux kernel bugs
reported to linux-distros were:
- The reporter having been directed to post from elsewhere (and I
suspect this documentation file) without being aware of list policy.
- The reporter not mentioning (and sometimes not replying even when
asked) whether they're also coordinating with security@k.o or whether
they want someone on linux-distros to help coordinate with security@k.o.
(Maybe this is something we want to write about here.)
- The Linux kernel bug having been introduced too recently to be of much
interest to distros.
> Reports have regularly missed the "[vs]" detail or suggested
> embargoes that ended on Fridays, etc.
This happens too. Regarding missing the "[vs]" detail, technically
there are also a number of other conditions that also let the message
through, but those are changing and are deliberately not advertised.
> Sending to the distros@ list risks exposing Linux-only flaws to non-Linux
> distros.
Right.
> This has caused leaks in the past
Do you mean leaks to *BSD security teams or to the public? I'm not
aware of past leaks to the public via the non-Linux distros present on
the distros@ list. Are you?
Alexander
^ permalink raw reply
* Re: [PATCH 1/4] block: elevator.c: Remove now unused elevator= argument
From: Hannes Reinecke @ 2019-07-19 13:36 UTC (permalink / raw)
To: Marcos Paulo de Souza, linux-kernel; +Cc: linux-block, linux-doc, Jens Axboe
In-Reply-To: <20190714053453.1655-2-marcos.souza.org@gmail.com>
On 7/14/19 7:34 AM, Marcos Paulo de Souza wrote:
> Since the inclusion of blk-mq, elevator argument was not being
> considered anymore, and it's utility died long with the legacy IO path,
> now removed too.
>
> Signed-off-by: Marcos Paulo de Souza <marcos.souza.org@gmail.com>
> ---
> block/elevator.c | 14 --------------
> 1 file changed, 14 deletions(-)
>
> diff --git a/block/elevator.c b/block/elevator.c
> index 2f17d66d0e61..f56d9c7d5cbc 100644
> --- a/block/elevator.c
> +++ b/block/elevator.c
> @@ -135,20 +135,6 @@ static struct elevator_type *elevator_get(struct request_queue *q,
> return e;
> }
>
> -static char chosen_elevator[ELV_NAME_MAX];
> -
> -static int __init elevator_setup(char *str)
> -{
> - /*
> - * Be backwards-compatible with previous kernels, so users
> - * won't get the wrong elevator.
> - */
> - strncpy(chosen_elevator, str, sizeof(chosen_elevator) - 1);
> - return 1;
> -}
> -
> -__setup("elevator=", elevator_setup);
> -
> static struct kobj_type elv_ktype;
>
> struct elevator_queue *elevator_alloc(struct request_queue *q,
>
Reviewed-by: Hannes Reinecke <hare@suse.com>
Cheers,
Hannes
--
Dr. Hannes Reinecke Teamlead Storage & Networking
hare@suse.de +49 911 74053 688
SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg
GF: Felix Imendörffer, Mary Higgins, Sri Rasiah
HRB 21284 (AG Nürnberg)
^ permalink raw reply
* Re: [PATCH 2/4] kernel-parameters.txt: Remove elevator argument
From: Hannes Reinecke @ 2019-07-19 13:36 UTC (permalink / raw)
To: Marcos Paulo de Souza, linux-kernel
Cc: linux-block, linux-doc, Jonathan Corbet, Thomas Gleixner,
Kees Cook, Andrew Morton, Ingo Molnar, Mauro Carvalho Chehab,
Paul E. McKenney, Josh Poimboeuf, Logan Gunthorpe, Lu Baolu,
Andy Lutomirski
In-Reply-To: <20190714053453.1655-3-marcos.souza.org@gmail.com>
On 7/14/19 7:34 AM, Marcos Paulo de Souza wrote:
> This argument was not being used since the legacy IO path was removed,
> when blk-mq was enabled by default. So removed it from the kernel
> parameters documentation.
>
> Signed-off-by: Marcos Paulo de Souza <marcos.souza.org@gmail.com>
> ---
> Documentation/admin-guide/kernel-parameters.txt | 6 ------
> 1 file changed, 6 deletions(-)
>
Reviewed-by: Hannes Reinecke <hare@suse.com>
Cheers,
Hannes
--
Dr. Hannes Reinecke Teamlead Storage & Networking
hare@suse.de +49 911 74053 688
SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg
GF: Felix Imendörffer, Mary Higgins, Sri Rasiah
HRB 21284 (AG Nürnberg)
^ permalink raw reply
* Re: [PATCH 3/4] Documenation: switching-sched: Remove notes about elevator argument
From: Hannes Reinecke @ 2019-07-19 13:37 UTC (permalink / raw)
To: Marcos Paulo de Souza, linux-kernel
Cc: linux-block, linux-doc, Jonathan Corbet, Jens Axboe,
Andreas Herrmann
In-Reply-To: <20190714053453.1655-4-marcos.souza.org@gmail.com>
On 7/14/19 7:34 AM, Marcos Paulo de Souza wrote:
> This argument was ignored since blk-mq was set as default, so remove it
> from documentation.
>
> Signed-off-by: Marcos Paulo de Souza <marcos.souza.org@gmail.com>
> ---
> Documentation/block/switching-sched.txt | 4 ----
> 1 file changed, 4 deletions(-)
>
> diff --git a/Documentation/block/switching-sched.txt b/Documentation/block/switching-sched.txt
> index 7977f6fb8b20..431d56471227 100644
> --- a/Documentation/block/switching-sched.txt
> +++ b/Documentation/block/switching-sched.txt
> @@ -1,7 +1,3 @@
> -To choose IO schedulers at boot time, use the argument 'elevator=deadline'.
> -'noop' and 'cfq' (the default) are also available. IO schedulers are assigned
> -globally at boot time only presently.
> -
> Each io queue has a set of io scheduler tunables associated with it. These
> tunables control how the io scheduler works. You can find these entries
> in:
>
Reviewed-by: Hannes Reinecke <hare@suse.com>
Cheers,
Hannes
--
Dr. Hannes Reinecke Teamlead Storage & Networking
hare@suse.de +49 911 74053 688
SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg
GF: Felix Imendörffer, Mary Higgins, Sri Rasiah
HRB 21284 (AG Nürnberg)
^ permalink raw reply
* Re: [PATCH 4/4] Documentation:kernel-per-CPU-kthreads.txt: Remove reference to elevator=
From: Hannes Reinecke @ 2019-07-19 13:37 UTC (permalink / raw)
To: Marcos Paulo de Souza, linux-kernel
Cc: linux-block, linux-doc, Jonathan Corbet
In-Reply-To: <20190714053453.1655-5-marcos.souza.org@gmail.com>
On 7/14/19 7:34 AM, Marcos Paulo de Souza wrote:
> This argument was not being considered since blk-mq was set by default,
> so removed this documentation to avoid confusion.
>
> Signed-off-by: Marcos Paulo de Souza <marcos.souza.org@gmail.com>
> ---
> Documentation/kernel-per-CPU-kthreads.txt | 8 +++-----
> 1 file changed, 3 insertions(+), 5 deletions(-)
>
Reviewed-by: Hannes Reinecke <hare@suse.com>
Cheers,
Hannes
--
Dr. Hannes Reinecke Teamlead Storage & Networking
hare@suse.de +49 911 74053 688
SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg
GF: Felix Imendörffer, Mary Higgins, Sri Rasiah
HRB 21284 (AG Nürnberg)
^ permalink raw reply
* Re: [PATCH v2 08/11] kbuild: create *.mod with full directory path and remove MODVERDIR
From: Masahiro Yamada @ 2019-07-20 5:09 UTC (permalink / raw)
To: Joe Lawrence
Cc: Linux Kbuild mailing list, Sam Ravnborg, Nicolas Pitre,
open list:DOCUMENTATION, Jonathan Corbet,
Linux Kernel Mailing List, Michal Marek
In-Reply-To: <f1222c8a-9301-1e76-981d-a36e8687a29f@redhat.com>
Hi Joe,
On Fri, Jul 19, 2019 at 5:18 AM Joe Lawrence <joe.lawrence@redhat.com> wrote:
> > Perhaps, adding a new field
> > to *.mod files might be cleaner.
>
> I can look into that. By "field" you mean a new row in the file?
Yes.
--
Best Regards
Masahiro Yamada
^ permalink raw reply
* [PATCH v6 3/7] of/platform: Add functional dependency link from DT bindings
From: Saravana Kannan @ 2019-07-20 6:16 UTC (permalink / raw)
To: Rob Herring, Mark Rutland, Greg Kroah-Hartman, Rafael J. Wysocki,
Frank Rowand, Jonathan Corbet
Cc: Saravana Kannan, devicetree, linux-kernel, David Collins,
kernel-team, linux-doc
In-Reply-To: <20190720061647.234852-1-saravanak@google.com>
Add device-links after the devices are created (but before they are
probed) by looking at common DT bindings like clocks and
interconnects.
Automatically adding device-links for functional dependencies at the
framework level provides the following benefits:
- Optimizes device probe order and avoids the useless work of
attempting probes of devices that will not probe successfully
(because their suppliers aren't present or haven't probed yet).
For example, in a commonly available mobile SoC, registering just
one consumer device's driver at an initcall level earlier than the
supplier device's driver causes 11 failed probe attempts before the
consumer device probes successfully. This was with a kernel with all
the drivers statically compiled in. This problem gets a lot worse if
all the drivers are loaded as modules without direct symbol
dependencies.
- Supplier devices like clock providers, interconnect providers, etc
need to keep the resources they provide active and at a particular
state(s) during boot up even if their current set of consumers don't
request the resource to be active. This is because the rest of the
consumers might not have probed yet and turning off the resource
before all the consumers have probed could lead to a hang or
undesired user experience.
Some frameworks (Eg: regulator) handle this today by turning off
"unused" resources at late_initcall_sync and hoping all the devices
have probed by then. This is not a valid assumption for systems with
loadable modules. Other frameworks (Eg: clock) just don't handle
this due to the lack of a clear signal for when they can turn off
resources. This leads to downstream hacks to handle cases like this
that can easily be solved in the upstream kernel.
By linking devices before they are probed, we give suppliers a clear
count of the number of dependent consumers. Once all of the
consumers are active, the suppliers can turn off the unused
resources without making assumptions about the number of consumers.
By default we just add device-links to track "driver presence" (probe
succeeded) of the supplier device. If any other functionality provided
by device-links are needed, it is left to the consumer/supplier
devices to change the link when they probe.
Signed-off-by: Saravana Kannan <saravanak@google.com>
---
.../admin-guide/kernel-parameters.txt | 5 +
drivers/of/platform.c | 158 ++++++++++++++++++
2 files changed, 163 insertions(+)
diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
index 138f6664b2e2..109b4310844f 100644
--- a/Documentation/admin-guide/kernel-parameters.txt
+++ b/Documentation/admin-guide/kernel-parameters.txt
@@ -3141,6 +3141,11 @@
This can be set from sysctl after boot.
See Documentation/sysctl/vm.txt for details.
+ of_devlink [KNL] Make device links from common DT bindings. Useful
+ for optimizing probe order and making sure resources
+ aren't turned off before the consumer devices have
+ probed.
+
ohci1394_dma=early [HW] enable debugging via the ohci1394 driver.
See Documentation/debugging-via-ohci1394.txt for more
info.
diff --git a/drivers/of/platform.c b/drivers/of/platform.c
index 04ad312fd85b..88a2086e26fa 100644
--- a/drivers/of/platform.c
+++ b/drivers/of/platform.c
@@ -509,6 +509,163 @@ int of_platform_default_populate(struct device_node *root,
}
EXPORT_SYMBOL_GPL(of_platform_default_populate);
+bool of_link_is_valid(struct device_node *con, struct device_node *sup)
+{
+ of_node_get(sup);
+ /*
+ * Don't allow linking a device node as a consumer of one of its
+ * descendant nodes. By definition, a child node can't be a functional
+ * dependency for the parent node.
+ */
+ while (sup) {
+ if (sup == con) {
+ of_node_put(sup);
+ return false;
+ }
+ sup = of_get_next_parent(sup);
+ }
+ return true;
+}
+
+static int of_link_to_phandle(struct device *dev, struct device_node *sup_np)
+{
+ struct platform_device *sup_dev;
+ u32 dl_flags = DL_FLAG_AUTOPROBE_CONSUMER;
+ int ret = 0;
+
+ /*
+ * Since we are trying to create device links, we need to find
+ * the actual device node that owns this supplier phandle.
+ * Often times it's the same node, but sometimes it can be one
+ * of the parents. So walk up the parent till you find a
+ * device.
+ */
+ while (sup_np && !of_find_property(sup_np, "compatible", NULL))
+ sup_np = of_get_next_parent(sup_np);
+ if (!sup_np)
+ return 0;
+
+ if (!of_link_is_valid(dev->of_node, sup_np)) {
+ of_node_put(sup_np);
+ return 0;
+ }
+ sup_dev = of_find_device_by_node(sup_np);
+ of_node_put(sup_np);
+ if (!sup_dev)
+ return -ENODEV;
+ if (!device_link_add(dev, &sup_dev->dev, dl_flags))
+ ret = -ENODEV;
+ put_device(&sup_dev->dev);
+ return ret;
+}
+
+static struct device_node *parse_prop_cells(struct device_node *np,
+ const char *prop, int i,
+ const char *binding,
+ const char *cell)
+{
+ struct of_phandle_args sup_args;
+
+ if (!i && strcmp(prop, binding))
+ return NULL;
+
+ if (of_parse_phandle_with_args(np, binding, cell, i, &sup_args))
+ return NULL;
+
+ return sup_args.np;
+}
+
+static struct device_node *parse_clocks(struct device_node *np,
+ const char *prop, int i)
+{
+ return parse_prop_cells(np, prop, i, "clocks", "#clock-cells");
+}
+
+static struct device_node *parse_interconnects(struct device_node *np,
+ const char *prop, int i)
+{
+ return parse_prop_cells(np, prop, i, "interconnects",
+ "#interconnect-cells");
+}
+
+static int strcmp_suffix(const char *str, const char *suffix)
+{
+ unsigned int len, suffix_len;
+
+ len = strlen(str);
+ suffix_len = strlen(suffix);
+ if (len <= suffix_len)
+ return -1;
+ return strcmp(str + len - suffix_len, suffix);
+}
+
+static struct device_node *parse_regulators(struct device_node *np,
+ const char *prop, int i)
+{
+ if (i || strcmp_suffix(prop, "-supply"))
+ return NULL;
+
+ return of_parse_phandle(np, prop, 0);
+}
+
+/**
+ * struct supplier_bindings - Information for parsing supplier DT binding
+ *
+ * @parse_prop: If the function cannot parse the property, return NULL.
+ * Otherwise, return the phandle listed in the property
+ * that corresponds to index i.
+ */
+struct supplier_bindings {
+ struct device_node *(*parse_prop)(struct device_node *np,
+ const char *name, int i);
+};
+
+struct supplier_bindings bindings[] = {
+ { .parse_prop = parse_clocks, },
+ { .parse_prop = parse_interconnects, },
+ { .parse_prop = parse_regulators, },
+ { },
+};
+
+static bool of_link_property(struct device *dev, struct device_node *con_np,
+ const char *prop)
+{
+ struct device_node *phandle;
+ struct supplier_bindings *s = bindings;
+ unsigned int i = 0;
+ bool done = true;
+
+ while (!i && s->parse_prop) {
+ while ((phandle = s->parse_prop(con_np, prop, i))) {
+ i++;
+ if (of_link_to_phandle(dev, phandle))
+ done = false;
+ }
+ s++;
+ }
+ return done ? 0 : -ENODEV;
+}
+
+static bool of_devlink;
+core_param(of_devlink, of_devlink, bool, 0);
+
+static int of_link_to_suppliers(struct device *dev)
+{
+ struct property *p;
+ bool done = true;
+
+ if (!of_devlink)
+ return 0;
+ if (unlikely(!dev->of_node))
+ return 0;
+
+ for_each_property_of_node(dev->of_node, p)
+ if (of_link_property(dev, dev->of_node, p->name))
+ done = false;
+
+ return done ? 0 : -ENODEV;
+}
+
#ifndef CONFIG_PPC
static const struct of_device_id reserved_mem_matches[] = {
{ .compatible = "qcom,rmtfs-mem" },
@@ -524,6 +681,7 @@ static int __init of_platform_default_populate_init(void)
if (!of_have_populated_dt())
return -ENODEV;
+ platform_bus_type.add_links = of_link_to_suppliers;
/*
* Handle certain compatibles explicitly, since we don't want to create
* platform_devices for every node in /reserved-memory with a
--
2.22.0.657.g960e92d24f-goog
^ permalink raw reply related
* [PATCH] Documentation: filesystem: fix "Removed Sysctls" table
From: Sheriff Esseson @ 2019-07-20 17:29 UTC (permalink / raw)
To: skhan
Cc: linux-kernel-mentees, Darrick J. Wong, linux-xfs, Jonathan Corbet,
open list:DOCUMENTATION, open list
the "Removed Sysctls" section is a table - bring it alive with ReST.
Signed-off-by: Sheriff Esseson <sheriffesseson@gmail.com>
---
Documentation/admin-guide/xfs.rst | 5 +++--
1 file changed, 3 insertions(+), 2 deletions(-)
diff --git a/Documentation/admin-guide/xfs.rst b/Documentation/admin-guide/xfs.rst
index e76665a8f2f2..fb5b39f73059 100644
--- a/Documentation/admin-guide/xfs.rst
+++ b/Documentation/admin-guide/xfs.rst
@@ -337,11 +337,12 @@ None at present.
Removed Sysctls
===============
+============================= =======
Name Removed
- ---- -------
+============================= =======
fs.xfs.xfsbufd_centisec v4.0
fs.xfs.age_buffer_centisecs v4.0
-
+============================= =======
Error handling
==============
--
2.22.0
^ permalink raw reply related
* [PATCH 05/22] docs: ipmb: place it at driver-api and convert to ReST
From: Mauro Carvalho Chehab @ 2019-07-22 11:07 UTC (permalink / raw)
Cc: Mauro Carvalho Chehab, Jonathan Corbet, linux-doc
In-Reply-To: <cover.1563792333.git.mchehab+samsung@kernel.org>
No new doc should be added at the main Documentation/ directory.
Instead, new docs should be added as ReST files, within the
Kernel documentation body.
Fixes: 51bd6f291583 ("Add support for IPMB driver")
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/driver-api/index.rst | 1 +
1 file changed, 1 insertion(+)
diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst
index 37ac052ded85..38e638abe3eb 100644
--- a/Documentation/driver-api/index.rst
+++ b/Documentation/driver-api/index.rst
@@ -76,6 +76,7 @@ available subsections can be seen below.
dell_rbu
edid
eisa
+ ipmb
isa
isapnp
generic-counter
--
2.21.0
^ permalink raw reply related
* [PATCH 08/22] docs: README.buddha: convert to ReST and add to m68k book
From: Mauro Carvalho Chehab @ 2019-07-22 11:07 UTC (permalink / raw)
Cc: Mauro Carvalho Chehab, Jonathan Corbet, linux-doc
In-Reply-To: <cover.1563792333.git.mchehab+samsung@kernel.org>
Adjust the file for it to be properly parsed by Sphinx, adding
it to the index of the book it belongs.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
.../m68k/{README.buddha => buddha-driver.rst} | 95 +++++++++----------
Documentation/m68k/index.rst | 1 +
2 files changed, 48 insertions(+), 48 deletions(-)
rename Documentation/m68k/{README.buddha => buddha-driver.rst} (73%)
diff --git a/Documentation/m68k/README.buddha b/Documentation/m68k/buddha-driver.rst
similarity index 73%
rename from Documentation/m68k/README.buddha
rename to Documentation/m68k/buddha-driver.rst
index 3ea9827ba3c7..20e401413991 100644
--- a/Documentation/m68k/README.buddha
+++ b/Documentation/m68k/buddha-driver.rst
@@ -1,3 +1,6 @@
+=====================================
+Amiga Buddha and Catweasel IDE Driver
+=====================================
The Amiga Buddha and Catweasel IDE Driver (part of ide.c) was written by
Geert Uytterhoeven based on the following specifications:
@@ -12,12 +15,12 @@ described in their manuals, no tricks have been used (for
example leaving some address lines out of the equations...).
If you want to configure the board yourself (for example let
a Linux kernel configure the card), look at the Commodore
-Docs. Reading the nibbles should give this information:
+Docs. Reading the nibbles should give this information::
-Vendor number: 4626 ($1212)
-product number: 0 (42 for Catweasel Z-II)
-Serial number: 0
-Rom-vector: $1000
+ Vendor number: 4626 ($1212)
+ product number: 0 (42 for Catweasel Z-II)
+ Serial number: 0
+ Rom-vector: $1000
The card should be a Z-II board, size 64K, not for freemem
list, Rom-Vektor is valid, no second Autoconfig-board on the
@@ -34,6 +37,7 @@ otherwise your chance is only 1:16 to find the board :-).
The local memory-map is even active when mapped to $e8:
+============== ===========================================
$0-$7e Autokonfig-space, see Z-II docs.
$80-$7fd reserved
@@ -50,50 +54,51 @@ $a00-$aff IDE-Select 2 (Port 1, Register set 0)
$b00-$bff IDE-Select 3 (Port 1, Register set 1)
$c00-$cff IDE-Select 4 (Port 2, Register set 0,
- Catweasel only!)
+ Catweasel only!)
$d00-$dff IDE-Select 5 (Port 3, Register set 1,
- Catweasel only!)
+ Catweasel only!)
-$e00-$eff local expansion port, on Catweasel Z-II the
+$e00-$eff local expansion port, on Catweasel Z-II the
Catweasel registers are also mapped here.
Never touch, use multidisk.device!
-
-$f00 read only, Byte-access: Bit 7 shows the
- level of the IRQ-line of IDE port 0.
+
+$f00 read only, Byte-access: Bit 7 shows the
+ level of the IRQ-line of IDE port 0.
$f01-$f3f mirror of $f00
-$f40 read only, Byte-access: Bit 7 shows the
- level of the IRQ-line of IDE port 1.
+$f40 read only, Byte-access: Bit 7 shows the
+ level of the IRQ-line of IDE port 1.
$f41-$f7f mirror of $f40
-$f80 read only, Byte-access: Bit 7 shows the
- level of the IRQ-line of IDE port 2.
+$f80 read only, Byte-access: Bit 7 shows the
+ level of the IRQ-line of IDE port 2.
(Catweasel only!)
$f81-$fbf mirror of $f80
$fc0 write-only: Writing any value to this
- register enables IRQs to be passed from the
- IDE ports to the Zorro bus. This mechanism
- has been implemented to be compatible with
+ register enables IRQs to be passed from the
+ IDE ports to the Zorro bus. This mechanism
+ has been implemented to be compatible with
harddisks that are either defective or have
- a buggy firmware and pull the IRQ line up
- while starting up. If interrupts would
- always be passed to the bus, the computer
- might not start up. Once enabled, this flag
- can not be disabled again. The level of the
- flag can not be determined by software
+ a buggy firmware and pull the IRQ line up
+ while starting up. If interrupts would
+ always be passed to the bus, the computer
+ might not start up. Once enabled, this flag
+ can not be disabled again. The level of the
+ flag can not be determined by software
(what for? Write to me if it's necessary!).
$fc1-$fff mirror of $fc0
$1000-$ffff Buddha-Rom with offset $1000 in the rom
- chip. The addresses $0 to $fff of the rom
+ chip. The addresses $0 to $fff of the rom
chip cannot be read. Rom is Byte-wide and
mapped to even addresses.
+============== ===========================================
The IDE ports issue an INT2. You can read the level of the
IRQ-lines of the IDE-ports by reading from the three (two
@@ -128,7 +133,8 @@ must always be set to 1 to be compatible with later Buddha
versions (if I'll ever update this one). I presume that
I'll never use the lower four bits, but they have to be set
to 1 by definition.
- The values in this table have to be shifted 5 bits to the
+
+The values in this table have to be shifted 5 bits to the
left and or'd with $1f (this sets the lower 5 bits).
All the timings have in common: Select and IOR/IOW rise at
@@ -138,44 +144,36 @@ values are no multiple of 71. One clock-cycle is 71ns long
(exactly 70,5 at 14,18 Mhz on PAL systems).
value 0 (Default after reset)
-
-497ns Select (7 clock cycles) , IOR/IOW after 172ns (2 clock cycles)
-(same timing as the Amiga 1200 does on it's IDE port without
-accelerator card)
+ 497ns Select (7 clock cycles) , IOR/IOW after 172ns (2 clock cycles)
+ (same timing as the Amiga 1200 does on it's IDE port without
+ accelerator card)
value 1
-
-639ns Select (9 clock cycles), IOR/IOW after 243ns (3 clock cycles)
+ 639ns Select (9 clock cycles), IOR/IOW after 243ns (3 clock cycles)
value 2
-
-781ns Select (11 clock cycles), IOR/IOW after 314ns (4 clock cycles)
+ 781ns Select (11 clock cycles), IOR/IOW after 314ns (4 clock cycles)
value 3
-
-355ns Select (5 clock cycles), IOR/IOW after 101ns (1 clock cycle)
+ 355ns Select (5 clock cycles), IOR/IOW after 101ns (1 clock cycle)
value 4
-
-355ns Select (5 clock cycles), IOR/IOW after 172ns (2 clock cycles)
+ 355ns Select (5 clock cycles), IOR/IOW after 172ns (2 clock cycles)
value 5
-
-355ns Select (5 clock cycles), IOR/IOW after 243ns (3 clock cycles)
+ 355ns Select (5 clock cycles), IOR/IOW after 243ns (3 clock cycles)
value 6
-
-1065ns Select (15 clock cycles), IOR/IOW after 314ns (4 clock cycles)
+ 1065ns Select (15 clock cycles), IOR/IOW after 314ns (4 clock cycles)
value 7
-
-355ns Select, (5 clock cycles), IOR/IOW after 101ns (1 clock cycle)
+ 355ns Select, (5 clock cycles), IOR/IOW after 101ns (1 clock cycle)
When accessing IDE registers with A6=1 (for example $84x),
the timing will always be mode 0 8-bit compatible, no matter
what you have selected in the speed register:
-781ns select, IOR/IOW after 4 clock cycles (=314ns) aktive.
+781ns select, IOR/IOW after 4 clock cycles (=314ns) aktive.
All the timings with a very short select-signal (the 355ns
fast accesses) depend on the accelerator card used in the
@@ -204,7 +202,8 @@ always shows a "no IRQ here" on the Buddha, and accesses to
the third IDE port are going into data's Nirwana on the
Buddha.
- Jens Schönfeld february 19th, 1997
- updated may 27th, 1997
- eMail: sysop@nostlgic.tng.oche.de
+Jens Schönfeld february 19th, 1997
+updated may 27th, 1997
+
+eMail: sysop@nostlgic.tng.oche.de
diff --git a/Documentation/m68k/index.rst b/Documentation/m68k/index.rst
index 3a5ba7fe1703..b89cb6a86d9b 100644
--- a/Documentation/m68k/index.rst
+++ b/Documentation/m68k/index.rst
@@ -8,6 +8,7 @@ m68k Architecture
:maxdepth: 2
kernel-options
+ buddha-driver
.. only:: subproject and html
--
2.21.0
^ permalink raw reply related
* [PATCH 11/22] docs: isdn: convert to ReST and add to kAPI bookset
From: Mauro Carvalho Chehab @ 2019-07-22 11:07 UTC (permalink / raw)
Cc: Mauro Carvalho Chehab, Jonathan Corbet, Karsten Keil,
Greg Kroah-Hartman, linux-doc, netdev, devel
In-Reply-To: <cover.1563792333.git.mchehab+samsung@kernel.org>
The ISDN documentation is a mix of admin guide, uAPI and kAPI.
Ideally, it should be split. Yet, not sure if it would worth
the troble. Anyway, we have the same kind of mix on several
drivers specific documentation. So, just like the others, keep
the directory at the root Documentation/ tree, just adding a
pointer to it at the kAPI section, as the documentation was
written with the Kernel developers in mind.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/index.rst | 1 +
.../isdn/{README.avmb1 => avmb1.rst} | 231 ++++++++------
Documentation/isdn/{CREDITS => credits.rst} | 7 +-
.../isdn/{README.gigaset => gigaset.rst} | 290 +++++++++++-------
.../isdn/{README.hysdn => hysdn.rst} | 125 ++++----
Documentation/isdn/index.rst | 24 ++
.../{INTERFACE.CAPI => interface_capi.rst} | 182 +++++++----
.../isdn/{README.mISDN => m_isdn.rst} | 5 +-
drivers/staging/isdn/hysdn/Kconfig | 2 +-
9 files changed, 536 insertions(+), 331 deletions(-)
rename Documentation/isdn/{README.avmb1 => avmb1.rst} (50%)
rename Documentation/isdn/{CREDITS => credits.rst} (96%)
rename Documentation/isdn/{README.gigaset => gigaset.rst} (74%)
rename Documentation/isdn/{README.hysdn => hysdn.rst} (80%)
create mode 100644 Documentation/isdn/index.rst
rename Documentation/isdn/{INTERFACE.CAPI => interface_capi.rst} (75%)
rename Documentation/isdn/{README.mISDN => m_isdn.rst} (89%)
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 5583b2e64692..c0132ad9c4d9 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -106,6 +106,7 @@ needed).
hid/index
i2c/index
iio/index
+ isdn/index
infiniband/index
leds/index
media/index
diff --git a/Documentation/isdn/README.avmb1 b/Documentation/isdn/avmb1.rst
similarity index 50%
rename from Documentation/isdn/README.avmb1
rename to Documentation/isdn/avmb1.rst
index 9e075484ef1e..de3961e67553 100644
--- a/Documentation/isdn/README.avmb1
+++ b/Documentation/isdn/avmb1.rst
@@ -1,4 +1,6 @@
-Driver for active AVM Controller.
+================================
+Driver for active AVM Controller
+================================
The driver provides a kernel capi2.0 Interface (kernelcapi) and
on top of this a User-Level-CAPI2.0-interface (capi)
@@ -11,25 +13,28 @@ The command avmcapictrl is part of the isdn4k-utils.
t4-files can be found at ftp://ftp.avm.de/cardware/b1/linux/firmware
Currently supported cards:
- B1 ISA (all versions)
- B1 PCI
- T1/T1B (HEMA card)
- M1
- M2
- B1 PCMCIA
+
+ - B1 ISA (all versions)
+ - B1 PCI
+ - T1/T1B (HEMA card)
+ - M1
+ - M2
+ - B1 PCMCIA
Installing
----------
You need at least /dev/capi20 to load the firmware.
-mknod /dev/capi20 c 68 0
-mknod /dev/capi20.00 c 68 1
-mknod /dev/capi20.01 c 68 2
-.
-.
-.
-mknod /dev/capi20.19 c 68 20
+::
+
+ mknod /dev/capi20 c 68 0
+ mknod /dev/capi20.00 c 68 1
+ mknod /dev/capi20.01 c 68 2
+ .
+ .
+ .
+ mknod /dev/capi20.19 c 68 20
Running
-------
@@ -38,45 +43,58 @@ To use the card you need the t4-files to download the firmware.
AVM GmbH provides several t4-files for the different D-channel
protocols (b1.t4 for Euro-ISDN). Install these file in /lib/isdn.
-if you configure as modules load the modules this way:
-
-insmod /lib/modules/current/misc/capiutil.o
-insmod /lib/modules/current/misc/b1.o
-insmod /lib/modules/current/misc/kernelcapi.o
-insmod /lib/modules/current/misc/capidrv.o
-insmod /lib/modules/current/misc/capi.o
-
-if you have an B1-PCI card load the module b1pci.o
-insmod /lib/modules/current/misc/b1pci.o
-and load the firmware with
-avmcapictrl load /lib/isdn/b1.t4 1
+if you configure as modules load the modules this way::
+
+ insmod /lib/modules/current/misc/capiutil.o
+ insmod /lib/modules/current/misc/b1.o
+ insmod /lib/modules/current/misc/kernelcapi.o
+ insmod /lib/modules/current/misc/capidrv.o
+ insmod /lib/modules/current/misc/capi.o
+
+if you have an B1-PCI card load the module b1pci.o::
+
+ insmod /lib/modules/current/misc/b1pci.o
+
+and load the firmware with::
+
+ avmcapictrl load /lib/isdn/b1.t4 1
if you have an B1-ISA card load the module b1isa.o
-and add the card by calling
-avmcapictrl add 0x150 15
-and load the firmware by calling
-avmcapictrl load /lib/isdn/b1.t4 1
+and add the card by calling::
+
+ avmcapictrl add 0x150 15
+
+and load the firmware by calling::
+
+ avmcapictrl load /lib/isdn/b1.t4 1
if you have an T1-ISA card load the module t1isa.o
-and add the card by calling
-avmcapictrl add 0x450 15 T1 0
-and load the firmware by calling
-avmcapictrl load /lib/isdn/t1.t4 1
+and add the card by calling::
+
+ avmcapictrl add 0x450 15 T1 0
+
+and load the firmware by calling::
+
+ avmcapictrl load /lib/isdn/t1.t4 1
if you have an PCMCIA card (B1/M1/M2) load the module b1pcmcia.o
before you insert the card.
Leased Lines with B1
--------------------
+
Init card and load firmware.
+
For an D64S use "FV: 1" as phone number
+
For an D64S2 use "FV: 1" and "FV: 2" for multilink
or "FV: 1,2" to use CAPI channel bundling.
/proc-Interface
-----------------
-/proc/capi:
+/proc/capi::
+
dr-xr-xr-x 2 root root 0 Jul 1 14:03 .
dr-xr-xr-x 82 root root 0 Jun 30 19:08 ..
-r--r--r-- 1 root root 0 Jul 1 14:03 applications
@@ -91,84 +109,124 @@ or "FV: 1,2" to use CAPI channel bundling.
/proc/capi/applications:
applid level3cnt datablkcnt datablklen ncci-cnt recvqueuelen
- level3cnt: capi_register parameter
- datablkcnt: capi_register parameter
- ncci-cnt: current number of nccis (connections)
- recvqueuelen: number of messages on receive queue
- for example:
-1 -2 16 2048 1 0
-2 2 7 2048 1 0
+ level3cnt:
+ capi_register parameter
+ datablkcnt:
+ capi_register parameter
+ ncci-cnt:
+ current number of nccis (connections)
+ recvqueuelen:
+ number of messages on receive queue
+
+ for example::
+
+ 1 -2 16 2048 1 0
+ 2 2 7 2048 1 0
/proc/capi/applstats:
applid recvctlmsg nrecvdatamsg nsentctlmsg nsentdatamsg
- recvctlmsg: capi messages received without DATA_B3_IND
- recvdatamsg: capi DATA_B3_IND received
- sentctlmsg: capi messages sent without DATA_B3_REQ
- sentdatamsg: capi DATA_B3_REQ sent
- for example:
-1 2057 1699 1721 1699
+ recvctlmsg:
+ capi messages received without DATA_B3_IND
+ recvdatamsg:
+ capi DATA_B3_IND received
+ sentctlmsg:
+ capi messages sent without DATA_B3_REQ
+ sentdatamsg:
+ capi DATA_B3_REQ sent
+
+ for example::
+
+ 1 2057 1699 1721 1699
/proc/capi/capi20: statistics of capi.o (/dev/capi20)
minor nopen nrecvdropmsg nrecvctlmsg nrecvdatamsg sentctlmsg sentdatamsg
- minor: minor device number of capi device
- nopen: number of calls to devices open
- nrecvdropmsg: capi messages dropped (messages in recvqueue in close)
- nrecvctlmsg: capi messages received without DATA_B3_IND
- nrecvdatamsg: capi DATA_B3_IND received
- nsentctlmsg: capi messages sent without DATA_B3_REQ
- nsentdatamsg: capi DATA_B3_REQ sent
+ minor:
+ minor device number of capi device
+ nopen:
+ number of calls to devices open
+ nrecvdropmsg:
+ capi messages dropped (messages in recvqueue in close)
+ nrecvctlmsg:
+ capi messages received without DATA_B3_IND
+ nrecvdatamsg:
+ capi DATA_B3_IND received
+ nsentctlmsg:
+ capi messages sent without DATA_B3_REQ
+ nsentdatamsg:
+ capi DATA_B3_REQ sent
- for example:
-1 2 18 0 16 2
+ for example::
+
+ 1 2 18 0 16 2
/proc/capi/capidrv: statistics of capidrv.o (capi messages)
nrecvctlmsg nrecvdatamsg sentctlmsg sentdatamsg
- nrecvctlmsg: capi messages received without DATA_B3_IND
- nrecvdatamsg: capi DATA_B3_IND received
- nsentctlmsg: capi messages sent without DATA_B3_REQ
- nsentdatamsg: capi DATA_B3_REQ sent
+ nrecvctlmsg:
+ capi messages received without DATA_B3_IND
+ nrecvdatamsg:
+ capi DATA_B3_IND received
+ nsentctlmsg:
+ capi messages sent without DATA_B3_REQ
+ nsentdatamsg:
+ capi DATA_B3_REQ sent
+
for example:
-2780 2226 2256 2226
+ 2780 2226 2256 2226
/proc/capi/controller:
controller drivername state cardname controllerinfo
- for example:
-1 b1pci running b1pci-e000 B1 3.07-01 0xe000 19
-2 t1isa running t1isa-450 B1 3.07-01 0x450 11 0
-3 b1pcmcia running m2-150 B1 3.07-01 0x150 5
+
+ for example::
+
+ 1 b1pci running b1pci-e000 B1 3.07-01 0xe000 19
+ 2 t1isa running t1isa-450 B1 3.07-01 0x450 11 0
+ 3 b1pcmcia running m2-150 B1 3.07-01 0x150 5
/proc/capi/contrstats:
controller nrecvctlmsg nrecvdatamsg sentctlmsg sentdatamsg
- nrecvctlmsg: capi messages received without DATA_B3_IND
- nrecvdatamsg: capi DATA_B3_IND received
- nsentctlmsg: capi messages sent without DATA_B3_REQ
- nsentdatamsg: capi DATA_B3_REQ sent
- for example:
-1 2845 2272 2310 2274
-2 2 0 2 0
-3 2 0 2 0
+ nrecvctlmsg:
+ capi messages received without DATA_B3_IND
+ nrecvdatamsg:
+ capi DATA_B3_IND received
+ nsentctlmsg:
+ capi messages sent without DATA_B3_REQ
+ nsentdatamsg:
+ capi DATA_B3_REQ sent
+
+ for example::
+
+ 1 2845 2272 2310 2274
+ 2 2 0 2 0
+ 3 2 0 2 0
/proc/capi/driver:
drivername ncontroller
- for example:
-b1pci 1
-t1isa 1
-b1pcmcia 1
-b1isa 0
+
+ for example::
+
+ b1pci 1
+ t1isa 1
+ b1pcmcia 1
+ b1isa 0
/proc/capi/ncci:
apllid ncci winsize sendwindow
- for example:
-1 0x10101 8 0
+
+ for example::
+
+ 1 0x10101 8 0
/proc/capi/users: kernelmodules that use the kernelcapi.
name
- for example:
-capidrv
-capi20
+
+ for example::
+
+ capidrv
+ capi20
Questions
---------
+
Check out the FAQ (ftp.isdn4linux.de) or subscribe to the
linux-avmb1@calle.in-berlin.de mailing list by sending
a mail to majordomo@calle.in-berlin.de with
@@ -178,9 +236,10 @@ in the body.
German documentation and several scripts can be found at
ftp://ftp.avm.de/cardware/b1/linux/
-Bugs
+Bugs
----
-If you find any please let me know.
+
+If you find any please let me know.
Enjoy,
diff --git a/Documentation/isdn/CREDITS b/Documentation/isdn/credits.rst
similarity index 96%
rename from Documentation/isdn/CREDITS
rename to Documentation/isdn/credits.rst
index c1679e913fca..319323f2091f 100644
--- a/Documentation/isdn/CREDITS
+++ b/Documentation/isdn/credits.rst
@@ -1,3 +1,7 @@
+=======
+Credits
+=======
+
I want to thank all who contributed to this project and especially to:
(in alphabetical order)
@@ -19,7 +23,7 @@ Matthias Hessler (hessler@isdn4linux.de)
For creating and maintaining the FAQ.
Bernhard Hailer (Bernhard.Hailer@lrz.uni-muenchen.de)
- For creating the FAQ, and the leafsite HOWTO.
+ For creating the FAQ, and the leafsite HOWTO.
Michael 'Ghandi' Herold (michael@abadonna.franken.de)
For contribution of the vbox answering machine.
@@ -67,4 +71,3 @@ Gerhard 'Fido' Schneider (fido@wuff.mayn.de)
Thomas Uhl (uhl@think.de)
For distributing the cards.
For pushing me to work ;-)
-
diff --git a/Documentation/isdn/README.gigaset b/Documentation/isdn/gigaset.rst
similarity index 74%
rename from Documentation/isdn/README.gigaset
rename to Documentation/isdn/gigaset.rst
index f6184b637182..98b4ec521c51 100644
--- a/Documentation/isdn/README.gigaset
+++ b/Documentation/isdn/gigaset.rst
@@ -1,33 +1,36 @@
+==========================
GigaSet 307x Device Driver
==========================
1. Requirements
- ------------
+=================
+
1.1. Hardware
- --------
+-------------
+
This driver supports the connection of the Gigaset 307x/417x family of
ISDN DECT bases via Gigaset M101 Data, Gigaset M105 Data or direct USB
connection. The following devices are reported to be compatible:
Bases:
- Siemens Gigaset 3070/3075 isdn
- Siemens Gigaset 4170/4175 isdn
- Siemens Gigaset SX205/255
- Siemens Gigaset SX353
- T-Com Sinus 45 [AB] isdn
- T-Com Sinus 721X[A] [SE]
- Vox Chicago 390 ISDN (KPN Telecom)
+ - Siemens Gigaset 3070/3075 isdn
+ - Siemens Gigaset 4170/4175 isdn
+ - Siemens Gigaset SX205/255
+ - Siemens Gigaset SX353
+ - T-Com Sinus 45 [AB] isdn
+ - T-Com Sinus 721X[A] [SE]
+ - Vox Chicago 390 ISDN (KPN Telecom)
RS232 data boxes:
- Siemens Gigaset M101 Data
- T-Com Sinus 45 Data 1
+ - Siemens Gigaset M101 Data
+ - T-Com Sinus 45 Data 1
USB data boxes:
- Siemens Gigaset M105 Data
- Siemens Gigaset USB Adapter DECT
- T-Com Sinus 45 Data 2
- T-Com Sinus 721 data
- Chicago 390 USB (KPN)
+ - Siemens Gigaset M105 Data
+ - Siemens Gigaset USB Adapter DECT
+ - T-Com Sinus 45 Data 2
+ - T-Com Sinus 721 data
+ - Chicago 390 USB (KPN)
See also http://www.erbze.info/sinus_gigaset.htm
(archived at https://web.archive.org/web/20100717020421/http://www.erbze.info:80/sinus_gigaset.htm ) and
@@ -37,17 +40,21 @@ GigaSet 307x Device Driver
with SX 100 and CX 100 ISDN bases (only in unimodem mode, see section 2.5.)
If you have another device that works with our driver, please let us know.
- Chances of getting an USB device to work are good if the output of
- lsusb
- at the command line contains one of the following:
- ID 0681:0001
- ID 0681:0002
- ID 0681:0009
- ID 0681:0021
- ID 0681:0022
+ Chances of getting an USB device to work are good if the output of::
+
+ lsusb
+
+ at the command line contains one of the following::
+
+ ID 0681:0001
+ ID 0681:0002
+ ID 0681:0009
+ ID 0681:0021
+ ID 0681:0022
1.2. Software
- --------
+-------------
+
The driver works with the Kernel CAPI subsystem and can be used with any
software which is able to use CAPI 2.0 for ISDN connections (voice or data).
@@ -58,9 +65,11 @@ GigaSet 307x Device Driver
2. How to use the driver
- ---------------------
+==========================
+
2.1. Modules
- -------
+------------
+
For the devices to work, the proper kernel modules have to be loaded.
This normally happens automatically when the system detects the USB
device (base, M105) or when the line discipline is attached (M101). It
@@ -71,13 +80,17 @@ GigaSet 307x Device Driver
which uses the regular serial port driver to access the device, and must
therefore be attached to the serial device to which the M101 is connected.
The ldattach(8) command (included in util-linux-ng release 2.14 or later)
- can be used for that purpose, for example:
+ can be used for that purpose, for example::
+
ldattach GIGASET_M101 /dev/ttyS1
+
This will open the device file, attach the line discipline to it, and
then sleep in the background, keeping the device open so that the line
discipline remains active. To deactivate it, kill the daemon, for example
- with
+ with::
+
killall ldattach
+
before disconnecting the device. To have this happen automatically at
system startup/shutdown on an LSB compatible system, create and activate
an appropriate LSB startup script /etc/init.d/gigaset. (The init name
@@ -86,9 +99,10 @@ GigaSet 307x Device Driver
The modules accept the following parameters:
- Module Parameter Meaning
+ =============== ========== ==========================================
+ Module Parameter Meaning
- gigaset debug debug level (see section 3.2.)
+ gigaset debug debug level (see section 3.2.)
startmode initial operation mode (see section 2.5.):
bas_gigaset ) 1=CAPI (default), 0=Unimodem
@@ -96,11 +110,14 @@ GigaSet 307x Device Driver
usb_gigaset ) cidmode initial Call-ID mode setting (see section
2.5.): 1=on (default), 0=off
+ =============== ========== ==========================================
+
Depending on your distribution you may want to create a separate module
configuration file like /etc/modprobe.d/gigaset.conf for these.
2.2. Device nodes for user space programs
- ------------------------------------
+-----------------------------------------
+
The device can be accessed from user space (eg. by the user space tools
mentioned in 1.2.) through the device nodes:
@@ -113,46 +130,56 @@ GigaSet 307x Device Driver
You can also set a "default device" for the user space tools to use when
no device node is given as parameter, by creating a symlink /dev/ttyG to
- one of them, eg.:
+ one of them, eg.::
ln -s /dev/ttyGB0 /dev/ttyG
The devices accept the following device specific ioctl calls
(defined in gigaset_dev.h):
- ioctl(int fd, GIGASET_REDIR, int *cmd);
+ ``ioctl(int fd, GIGASET_REDIR, int *cmd);``
+
If cmd==1, the device is set to be controlled exclusively through the
character device node; access from the ISDN subsystem is blocked.
+
If cmd==0, the device is set to be used from the ISDN subsystem and does
not communicate through the character device node.
- ioctl(int fd, GIGASET_CONFIG, int *cmd);
+ ``ioctl(int fd, GIGASET_CONFIG, int *cmd);``
+
(ser_gigaset and usb_gigaset only)
+
If cmd==1, the device is set to adapter configuration mode where commands
are interpreted by the M10x DECT adapter itself instead of being
forwarded to the base station. In this mode, the device accepts the
commands described in Siemens document "AT-Kommando Alignment M10x Data"
for setting the operation mode, associating with a base station and
querying parameters like field strengh and signal quality.
+
Note that there is no ioctl command for leaving adapter configuration
mode and returning to regular operation. In order to leave adapter
configuration mode, write the command ATO to the device.
- ioctl(int fd, GIGASET_BRKCHARS, unsigned char brkchars[6]);
+ ``ioctl(int fd, GIGASET_BRKCHARS, unsigned char brkchars[6]);``
+
(usb_gigaset only)
+
Set the break characters on an M105's internal serial adapter to the six
bytes stored in brkchars[]. Unused bytes should be set to zero.
ioctl(int fd, GIGASET_VERSION, unsigned version[4]);
Retrieve version information from the driver. version[0] must be set to
one of:
+
- GIGVER_DRIVER: retrieve driver version
- GIGVER_COMPAT: retrieve interface compatibility version
- GIGVER_FWBASE: retrieve the firmware version of the base
+
Upon return, version[] is filled with the requested version information.
2.3. CAPI
- ----
+---------
+
The devices will show up as CAPI controllers as soon as the
corresponding driver module is loaded, and can then be used with
CAPI 2.0 kernel and user space applications. For user space access,
@@ -165,21 +192,22 @@ GigaSet 307x Device Driver
driver.
2.5. Unimodem mode
- -------------
+------------------
+
In this mode the device works like a modem connected to a serial port
- (the /dev/ttyGU0, ... mentioned above) which understands the commands
+ (the /dev/ttyGU0, ... mentioned above) which understands the commands::
- ATZ init, reset
- => OK or ERROR
- ATD
- ATDT dial
- => OK, CONNECT,
- BUSY,
- NO DIAL TONE,
- NO CARRIER,
- NO ANSWER
- <pause>+++<pause> change to command mode when connected
- ATH hangup
+ ATZ init, reset
+ => OK or ERROR
+ ATD
+ ATDT dial
+ => OK, CONNECT,
+ BUSY,
+ NO DIAL TONE,
+ NO CARRIER,
+ NO ANSWER
+ <pause>+++<pause> change to command mode when connected
+ ATH hangup
You can use some configuration tool of your distribution to configure this
"modem" or configure pppd/wvdial manually. There are some example ppp
@@ -189,40 +217,52 @@ GigaSet 307x Device Driver
control lines. This means you must use "Stupid Mode" if you are using
wvdial or you should use the nocrtscts option of pppd.
You must also assure that the ppp_async module is loaded with the parameter
- flag_time=0. You can do this e.g. by adding a line like
+ flag_time=0. You can do this e.g. by adding a line like::
- options ppp_async flag_time=0
+ options ppp_async flag_time=0
- to an appropriate module configuration file, like
- /etc/modprobe.d/gigaset.conf.
+ to an appropriate module configuration file, like::
+
+ /etc/modprobe.d/gigaset.conf.
Unimodem mode is needed for making some devices [e.g. SX100] work which
do not support the regular Gigaset command set. If debug output (see
- section 3.2.) shows something like this when dialing:
- CMD Received: ERROR
- Available Params: 0
- Connection State: 0, Response: -1
- gigaset_process_response: resp_code -1 in ConState 0 !
- Timeout occurred
+ section 3.2.) shows something like this when dialing::
+
+ CMD Received: ERROR
+ Available Params: 0
+ Connection State: 0, Response: -1
+ gigaset_process_response: resp_code -1 in ConState 0 !
+ Timeout occurred
+
then switching to unimodem mode may help.
If you have installed the command line tool gigacontr, you can enter
- unimodem mode using
- gigacontr --mode unimodem
- You can switch back using
- gigacontr --mode isdn
+ unimodem mode using::
+
+ gigacontr --mode unimodem
+
+ You can switch back using::
+
+ gigacontr --mode isdn
You can also put the driver directly into Unimodem mode when it's loaded,
by passing the module parameter startmode=0 to the hardware specific
- module, e.g.
+ module, e.g.::
+
modprobe usb_gigaset startmode=0
- or by adding a line like
+
+ or by adding a line like::
+
options usb_gigaset startmode=0
- to an appropriate module configuration file, like
- /etc/modprobe.d/gigaset.conf
+
+ to an appropriate module configuration file, like::
+
+ /etc/modprobe.d/gigaset.conf
2.6. Call-ID (CID) mode
- ------------------
+-----------------------
+
Call-IDs are numbers used to tag commands to, and responses from, the
Gigaset base in order to support the simultaneous handling of multiple
ISDN calls. Their use can be enabled ("CID mode") or disabled ("Unimodem
@@ -238,6 +278,7 @@ GigaSet 307x Device Driver
During active operation, the driver switches to the necessary mode
automatically. However, for the reasons above, the mode chosen when
the device is not in use (idle) can be selected by the user.
+
- If you want to receive incoming calls, you can use the default
settings (CID mode).
- If you have several DECT data devices (M10x) which you want to use
@@ -247,25 +288,27 @@ GigaSet 307x Device Driver
If you want both of these at once, you are out of luck.
You can also use the tty class parameter "cidmode" of the device to
- change its CID mode while the driver is loaded, eg.
- echo 0 > /sys/class/tty/ttyGU0/cidmode
+ change its CID mode while the driver is loaded, eg.::
+
+ echo 0 > /sys/class/tty/ttyGU0/cidmode
2.7. Dialing Numbers
- ---------------
- The called party number provided by an application for dialing out must
+--------------------
+provided by an application for dialing out must
be a public network number according to the local dialing plan, without
any dial prefix for getting an outside line.
Internal calls can be made by providing an internal extension number
- prefixed with "**" (two asterisks) as the called party number. So to dial
- eg. the first registered DECT handset, give "**11" as the called party
- number. Dialing "***" (three asterisks) calls all extensions
+ prefixed with ``**`` (two asterisks) as the called party number. So to dial
+ eg. the first registered DECT handset, give ``**11`` as the called party
+ number. Dialing ``***`` (three asterisks) calls all extensions
simultaneously (global call).
Unimodem mode does not support internal calls.
2.8. Unregistered Wireless Devices (M101/M105)
- -----------------------------------------
+----------------------------------------------
+
The main purpose of the ser_gigaset and usb_gigaset drivers is to allow
the M101 and M105 wireless devices to be used as ISDN devices for ISDN
connections through a Gigaset base. Therefore they assume that the device
@@ -279,73 +322,91 @@ GigaSet 307x Device Driver
modes. See the gigacontr(8) manpage for details.
3. Troubleshooting
- ---------------
+====================
+
3.1. Solutions to frequently reported problems
- -----------------------------------------
+----------------------------------------------
+
Problem:
- You have a slow provider and isdn4linux gives up dialing too early.
+ You have a slow provider and isdn4linux gives up dialing too early.
Solution:
- Load the isdn module using the dialtimeout option. You can do this e.g.
- by adding a line like
+ Load the isdn module using the dialtimeout option. You can do this e.g.
+ by adding a line like::
- options isdn dialtimeout=15
+ options isdn dialtimeout=15
- to /etc/modprobe.d/gigaset.conf or a similar file.
+ to /etc/modprobe.d/gigaset.conf or a similar file.
Problem:
- The isdnlog program emits error messages or just doesn't work.
+ The isdnlog program emits error messages or just doesn't work.
Solution:
- Isdnlog supports only the HiSax driver. Do not attempt to use it with
+ Isdnlog supports only the HiSax driver. Do not attempt to use it with
other drivers such as Gigaset.
Problem:
- You have two or more DECT data adapters (M101/M105) and only the
- first one you turn on works.
+ You have two or more DECT data adapters (M101/M105) and only the
+ first one you turn on works.
Solution:
- Select Unimodem mode for all DECT data adapters. (see section 2.5.)
+ Select Unimodem mode for all DECT data adapters. (see section 2.5.)
Problem:
- Messages like this:
+ Messages like this::
+
usb_gigaset 3-2:1.0: Could not initialize the device.
+
appear in your syslog.
Solution:
Check whether your M10x wireless device is correctly registered to the
Gigaset base. (see section 2.7.)
3.2. Telling the driver to provide more information
- ----------------------------------------------
+---------------------------------------------------
Building the driver with the "Gigaset debugging" kernel configuration
option (CONFIG_GIGASET_DEBUG) gives it the ability to produce additional
information useful for debugging.
You can control the amount of debugging information the driver produces by
- writing an appropriate value to /sys/module/gigaset/parameters/debug, e.g.
- echo 0 > /sys/module/gigaset/parameters/debug
+ writing an appropriate value to /sys/module/gigaset/parameters/debug,
+ e.g.::
+
+ echo 0 > /sys/module/gigaset/parameters/debug
+
switches off debugging output completely,
- echo 0x302020 > /sys/module/gigaset/parameters/debug
+
+ ::
+
+ echo 0x302020 > /sys/module/gigaset/parameters/debug
+
enables a reasonable set of debugging output messages. These values are
bit patterns where every bit controls a certain type of debugging output.
See the constants DEBUG_* in the source file gigaset.h for details.
The initial value can be set using the debug parameter when loading the
- module "gigaset", e.g. by adding a line
- options gigaset debug=0
+ module "gigaset", e.g. by adding a line::
+
+ options gigaset debug=0
+
to your module configuration file, eg. /etc/modprobe.d/gigaset.conf
Generated debugging information can be found
- - as output of the command
- dmesg
+ - as output of the command::
+
+ dmesg
+
- in system log files written by your syslog daemon, usually
in /var/log/, e.g. /var/log/messages.
3.3. Reporting problems and bugs
- ---------------------------
+--------------------------------
If you can't solve problems with the driver on your own, feel free to
use one of the forums, bug trackers, or mailing lists on
- https://sourceforge.net/projects/gigaset307x
+
+ https://sourceforge.net/projects/gigaset307x
+
or write an electronic mail to the maintainers.
Try to provide as much information as possible, such as
+
- distribution
- kernel version (uname -r)
- gcc version (gcc --version)
@@ -362,7 +423,7 @@ GigaSet 307x Device Driver
appropriate forums and newsgroups.
3.4. Reporting problem solutions
- ---------------------------
+--------------------------------
If you solved a problem with our drivers, wrote startup scripts for your
distribution, ... feel free to contact us (using one of the places
mentioned in 3.3.). We'd like to add scripts, hints, documentation
@@ -370,34 +431,35 @@ GigaSet 307x Device Driver
4. Links, other software
- ---------------------
+==========================
+
- Sourceforge project developing this driver and associated tools
- https://sourceforge.net/projects/gigaset307x
+ https://sourceforge.net/projects/gigaset307x
- Yahoo! Group on the Siemens Gigaset family of devices
- https://de.groups.yahoo.com/group/Siemens-Gigaset
+ https://de.groups.yahoo.com/group/Siemens-Gigaset
- Siemens Gigaset/T-Sinus compatibility table
- http://www.erbze.info/sinus_gigaset.htm
+ http://www.erbze.info/sinus_gigaset.htm
(archived at https://web.archive.org/web/20100717020421/http://www.erbze.info:80/sinus_gigaset.htm )
5. Credits
- -------
+============
+
Thanks to
Karsten Keil
- for his help with isdn4linux
+ for his help with isdn4linux
Deti Fliegl
- for his base driver code
+ for his base driver code
Dennis Dietrich
- for his kernel 2.6 patches
+ for his kernel 2.6 patches
Andreas Rummel
- for his work and logs to get unimodem mode working
+ for his work and logs to get unimodem mode working
Andreas Degert
- for his logs and patches to get cx 100 working
+ for his logs and patches to get cx 100 working
Dietrich Feist
- for his generous donation of one M105 and two M101 cordless adapters
+ for his generous donation of one M105 and two M101 cordless adapters
Christoph Schweers
- for his generous donation of a M34 device
+ for his generous donation of a M34 device
and all the other people who sent logs and other information.
-
diff --git a/Documentation/isdn/README.hysdn b/Documentation/isdn/hysdn.rst
similarity index 80%
rename from Documentation/isdn/README.hysdn
rename to Documentation/isdn/hysdn.rst
index eeca11f00ccd..0a168d1cbffc 100644
--- a/Documentation/isdn/README.hysdn
+++ b/Documentation/isdn/hysdn.rst
@@ -1,4 +1,7 @@
-$Id: README.hysdn,v 1.3.6.1 2001/02/10 14:41:19 kai Exp $
+============
+Hysdn Driver
+============
+
The hysdn driver has been written by
Werner Cornelius (werner@isdn4linux.de or werner@titro.de)
for Hypercope GmbH Aachen Germany. Hypercope agreed to publish this driver
@@ -22,28 +25,28 @@ for Hypercope GmbH Aachen, Germany.
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
-Table of contents
-=================
+.. Table of contents
-1. About the driver
+ 1. About the driver
-2. Loading/Unloading the driver
+ 2. Loading/Unloading the driver
-3. Entries in the /proc filesystem
+ 3. Entries in the /proc filesystem
-4. The /proc/net/hysdn/cardconfX file
+ 4. The /proc/net/hysdn/cardconfX file
-5. The /proc/net/hysdn/cardlogX file
+ 5. The /proc/net/hysdn/cardlogX file
-6. Where to get additional info and help
+ 6. Where to get additional info and help
1. About the driver
+===================
- The drivers/isdn/hysdn subdir contains a driver for HYPERCOPEs active
+ The drivers/isdn/hysdn subdir contains a driver for HYPERCOPEs active
PCI isdn cards Champ, Ergo and Metro. To enable support for this cards
enable ISDN support in the kernel config and support for HYSDN cards in
- the active cards submenu. The driver may only be compiled and used if
+ the active cards submenu. The driver may only be compiled and used if
support for loadable modules and the process filesystem have been enabled.
These cards provide two different interfaces to the kernel. Without the
@@ -52,22 +55,23 @@ Table of contents
handlers for various protocols like ppp and others as well as config info
and firmware may be fetched from Hypercopes WWW-Site www.hypercope.de.
- With CAPI 2.0 support enabled, the card can also be used as a CAPI 2.0
- compliant devices with either CAPI 2.0 applications
+ With CAPI 2.0 support enabled, the card can also be used as a CAPI 2.0
+ compliant devices with either CAPI 2.0 applications
(check isdn4k-utils) or -using the capidrv module- as a regular
- isdn4linux device. This is done via the same mechanism as with the
+ isdn4linux device. This is done via the same mechanism as with the
active AVM cards and in fact uses the same module.
-
+
2. Loading/Unloading the driver
+===============================
The module has no command line parameters and auto detects up to 10 cards
in the id-range 0-9.
If a loaded driver shall be unloaded all open files in the /proc/net/hysdn
- subdir need to be closed and all ethernet interfaces allocated by this
+ subdir need to be closed and all ethernet interfaces allocated by this
driver must be shut down. Otherwise the module counter will avoid a module
unload.
-
+
If you are using the CAPI 2.0-interface, make sure to load/modprobe the
kernelcapi-module first.
@@ -76,52 +80,57 @@ Table of contents
any avm-specific modules).
3. Entries in the /proc filesystem
+==================================
- When the module has been loaded it adds the directory hysdn in the
- /proc/net tree. This directory contains exactly 2 file entries for each
+ When the module has been loaded it adds the directory hysdn in the
+ /proc/net tree. This directory contains exactly 2 file entries for each
card. One is called cardconfX and the other cardlogX, where X is the
- card id number from 0 to 9.
+ card id number from 0 to 9.
The cards are numbered in the order found in the PCI config data.
4. The /proc/net/hysdn/cardconfX file
+=====================================
- This file may be read to get by everyone to get info about the cards type,
+ This file may be read to get by everyone to get info about the cards type,
actual state, available features and used resources.
The first 3 entries (id, bus and slot) are PCI info fields, the following
type field gives the information about the cards type:
- 4 -> Ergo card (server card with 2 b-chans)
- 5 -> Metro card (server card with 4 or 8 b-chans)
- 6 -> Champ card (client card with 2 b-chans)
+ - 4 -> Ergo card (server card with 2 b-chans)
+ - 5 -> Metro card (server card with 4 or 8 b-chans)
+ - 6 -> Champ card (client card with 2 b-chans)
The following 3 fields show the hardware assignments for irq, iobase and the
dual ported memory (dp-mem).
+
The fields b-chans and fax-chans announce the available card resources of
this types for the user.
+
The state variable indicates the actual drivers state for this card with the
following assignments.
- 0 -> card has not been booted since driver load
- 1 -> card booting is actually in progess
- 2 -> card is in an error state due to a previous boot failure
- 3 -> card is booted and active
+ - 0 -> card has not been booted since driver load
+ - 1 -> card booting is actually in progess
+ - 2 -> card is in an error state due to a previous boot failure
+ - 3 -> card is booted and active
And the last field (device) shows the name of the ethernet device assigned
to this card. Up to the first successful boot this field only shows a -
to tell that no net device has been allocated up to now. Once a net device
has been allocated it remains assigned to this card, even if a card is
- rebooted and an boot error occurs.
+ rebooted and an boot error occurs.
- Writing to the cardconfX file boots the card or transfers config lines to
- the cards firmware. The type of data is automatically detected when the
+ Writing to the cardconfX file boots the card or transfers config lines to
+ the cards firmware. The type of data is automatically detected when the
first data is written. Only root has write access to this file.
The firmware boot files are normally called hyclient.pof for client cards
and hyserver.pof for server cards.
After successfully writing the boot file, complete config files or single
config lines may be copied to this file.
- If an error occurs the return value given to the writing process has the
+ If an error occurs the return value given to the writing process has the
following additional codes (decimal):
+ ==== ============================================
1000 Another process is currently bootng the card
1001 Invalid firmware header
1002 Boards dual-port RAM test failed
@@ -131,34 +140,39 @@ Table of contents
1006 Second boot stage failure
1007 Timeout waiting for card ready during boot
1008 Operation only allowed in booted state
- 1009 Config line too long
- 1010 Invalid channel number
+ 1009 Config line too long
+ 1010 Invalid channel number
1011 Timeout sending config data
+ ==== ============================================
- Additional info about error reasons may be fetched from the log output.
+ Additional info about error reasons may be fetched from the log output.
5. The /proc/net/hysdn/cardlogX file
-
- The cardlogX file entry may be opened multiple for reading by everyone to
+====================================
+
+ The cardlogX file entry may be opened multiple for reading by everyone to
get the cards and drivers log data. Card messages always start with the
- keyword LOG. All other lines are output from the driver.
- The driver log data may be redirected to the syslog by selecting the
+ keyword LOG. All other lines are output from the driver.
+ The driver log data may be redirected to the syslog by selecting the
appropriate bitmask. The cards log messages will always be send to this
interface but never to the syslog.
A root user may write a decimal or hex (with 0x) value t this file to select
- desired output options. As mentioned above the cards log dat is always
+ desired output options. As mentioned above the cards log dat is always
written to the cardlog file independent of the following options only used
to check and debug the driver itself:
- For example:
- echo "0x34560078" > /proc/net/hysdn/cardlog0
+ For example::
+
+ echo "0x34560078" > /proc/net/hysdn/cardlog0
+
to output the hex log mask 34560078 for card 0.
-
- The written value is regarded as an unsigned 32-Bit value, bit ored for
+
+ The written value is regarded as an unsigned 32-Bit value, bit ored for
desired output. The following bits are already assigned:
- 0x80000000 All driver log data is alternatively via syslog
+ ========== ============================================================
+ 0x80000000 All driver log data is alternatively via syslog
0x00000001 Log memory allocation errors
0x00000010 Firmware load start and close are logged
0x00000020 Log firmware record parser
@@ -171,25 +185,12 @@ Table of contents
0x00100000 Log all open and close actions to /proc/net/hysdn/card files
0x00200000 Log all actions from /proc file entries
0x00010000 Log network interface init and deinit
-
+ ========== ============================================================
+
6. Where to get additional info and help
+========================================
- If you have any problems concerning the driver or configuration contact
+ If you have any problems concerning the driver or configuration contact
the Hypercope support team (support@hypercope.de) and or the authors
Werner Cornelius (werner@isdn4linux or cornelius@titro.de) or
Ulrich Albrecht (ualbrecht@hypercope.de).
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/Documentation/isdn/index.rst b/Documentation/isdn/index.rst
new file mode 100644
index 000000000000..407e74b78372
--- /dev/null
+++ b/Documentation/isdn/index.rst
@@ -0,0 +1,24 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+====
+ISDN
+====
+
+.. toctree::
+ :maxdepth: 2
+
+ interface_capi
+
+ avmb1
+ gigaset
+ hysdn
+ m_isdn
+
+ credits
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/isdn/INTERFACE.CAPI b/Documentation/isdn/interface_capi.rst
similarity index 75%
rename from Documentation/isdn/INTERFACE.CAPI
rename to Documentation/isdn/interface_capi.rst
index 021aa9cf139d..01a4b5ade9a4 100644
--- a/Documentation/isdn/INTERFACE.CAPI
+++ b/Documentation/isdn/interface_capi.rst
@@ -1,7 +1,9 @@
+=========================================
Kernel CAPI Interface to Hardware Drivers
------------------------------------------
+=========================================
1. Overview
+===========
From the CAPI 2.0 specification:
COMMON-ISDN-API (CAPI) is an application programming interface standard used
@@ -22,6 +24,7 @@ This standard is freely available from https://www.capi.org.
2. Driver and Device Registration
+=================================
CAPI drivers optionally register themselves with Kernel CAPI by calling the
Kernel CAPI function register_capi_driver() with a pointer to a struct
@@ -50,6 +53,7 @@ callback functions by Kernel CAPI.
3. Application Registration and Communication
+=============================================
Kernel CAPI forwards registration requests from applications (calls to CAPI
operation CAPI_REGISTER) to an appropriate hardware driver by calling its
@@ -71,23 +75,26 @@ messages for that application may be passed to or from the device anymore.
4. Data Structures
+==================
4.1 struct capi_driver
+----------------------
This structure describes a Kernel CAPI driver itself. It is used in the
register_capi_driver() and unregister_capi_driver() functions, and contains
the following non-private fields, all to be set by the driver before calling
register_capi_driver():
-char name[32]
+``char name[32]``
the name of the driver, as a zero-terminated ASCII string
-char revision[32]
+``char revision[32]``
the revision number of the driver, as a zero-terminated ASCII string
-int (*add_card)(struct capi_driver *driver, capicardparams *data)
+``int (*add_card)(struct capi_driver *driver, capicardparams *data)``
a callback function pointer (may be NULL)
4.2 struct capi_ctr
+-------------------
This structure describes an ISDN device (controller) handled by a Kernel CAPI
driver. After registration via the attach_capi_ctr() function it is passed to
@@ -96,88 +103,109 @@ identify the controller to operate on.
It contains the following non-private fields:
-- to be set by the driver before calling attach_capi_ctr():
+to be set by the driver before calling attach_capi_ctr():
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-struct module *owner
+``struct module *owner``
pointer to the driver module owning the device
-void *driverdata
+``void *driverdata``
an opaque pointer to driver specific data, not touched by Kernel CAPI
-char name[32]
+``char name[32]``
the name of the controller, as a zero-terminated ASCII string
-char *driver_name
+``char *driver_name``
the name of the driver, as a zero-terminated ASCII string
-int (*load_firmware)(struct capi_ctr *ctrlr, capiloaddata *ldata)
+``int (*load_firmware)(struct capi_ctr *ctrlr, capiloaddata *ldata)``
(optional) pointer to a callback function for sending firmware and
configuration data to the device
+
The function may return before the operation has completed.
+
Completion must be signalled by a call to capi_ctr_ready().
+
Return value: 0 on success, error code on error
Called in process context.
-void (*reset_ctr)(struct capi_ctr *ctrlr)
+``void (*reset_ctr)(struct capi_ctr *ctrlr)``
(optional) pointer to a callback function for stopping the device,
releasing all registered applications
+
The function may return before the operation has completed.
+
Completion must be signalled by a call to capi_ctr_down().
+
Called in process context.
-void (*register_appl)(struct capi_ctr *ctrlr, u16 applid,
- capi_register_params *rparam)
-void (*release_appl)(struct capi_ctr *ctrlr, u16 applid)
- pointers to callback functions for registration and deregistration of
+``void (*register_appl)(struct capi_ctr *ctrlr, u16 applid, capi_register_params *rparam)``
+ pointers to callback function for registration of
applications with the device
+
+ Calls to these functions are serialized by Kernel CAPI so that only
+ one call to any of them is active at any time.
+
+``void (*release_appl)(struct capi_ctr *ctrlr, u16 applid)``
+ pointers to callback functions deregistration of
+ applications with the device
+
Calls to these functions are serialized by Kernel CAPI so that only
one call to any of them is active at any time.
-u16 (*send_message)(struct capi_ctr *ctrlr, struct sk_buff *skb)
+``u16 (*send_message)(struct capi_ctr *ctrlr, struct sk_buff *skb)``
pointer to a callback function for sending a CAPI message to the
device
+
Return value: CAPI error code
+
If the method returns 0 (CAPI_NOERROR) the driver has taken ownership
of the skb and the caller may no longer access it. If it returns a
non-zero (error) value then ownership of the skb returns to the caller
who may reuse or free it.
+
The return value should only be used to signal problems with respect
to accepting or queueing the message. Errors occurring during the
actual processing of the message should be signaled with an
appropriate reply message.
+
May be called in process or interrupt context.
+
Calls to this function are not serialized by Kernel CAPI, ie. it must
be prepared to be re-entered.
-char *(*procinfo)(struct capi_ctr *ctrlr)
+``char *(*procinfo)(struct capi_ctr *ctrlr)``
pointer to a callback function returning the entry for the device in
the CAPI controller info table, /proc/capi/controller
-const struct file_operations *proc_fops
+``const struct file_operations *proc_fops``
pointers to callback functions for the device's proc file
system entry, /proc/capi/controllers/<n>; pointer to the device's
capi_ctr structure is available from struct proc_dir_entry::data
which is available from struct inode.
-Note: Callback functions except send_message() are never called in interrupt
-context.
+Note:
+ Callback functions except send_message() are never called in interrupt
+ context.
-- to be filled in before calling capi_ctr_ready():
+to be filled in before calling capi_ctr_ready():
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-u8 manu[CAPI_MANUFACTURER_LEN]
+``u8 manu[CAPI_MANUFACTURER_LEN]``
value to return for CAPI_GET_MANUFACTURER
-capi_version version
+``capi_version version``
value to return for CAPI_GET_VERSION
-capi_profile profile
+``capi_profile profile``
value to return for CAPI_GET_PROFILE
-u8 serial[CAPI_SERIAL_LEN]
+``u8 serial[CAPI_SERIAL_LEN]``
value to return for CAPI_GET_SERIAL
4.3 SKBs
+--------
CAPI messages are passed between Kernel CAPI and the driver via send_message()
and capi_ctr_handle_message(), stored in the data portion of a socket buffer
@@ -192,6 +220,7 @@ instead of 30.
4.4 The _cmsg Structure
+-----------------------
(declared in <linux/isdn/capiutil.h>)
@@ -216,6 +245,7 @@ Members are named after the CAPI 2.0 standard names of the parameters they
represent. See <linux/isdn/capiutil.h> for the exact spelling. Member data
types are:
+=========== =================================================================
u8 for CAPI parameters of type 'byte'
u16 for CAPI parameters of type 'word'
@@ -235,6 +265,7 @@ _cmstruct alternative representation for CAPI parameters of type 'struct'
CAPI_COMPOSE: The parameter is present.
Subparameter values are stored individually in the corresponding
_cmsg structure members.
+=========== =================================================================
Functions capi_cmsg2message() and capi_message2cmsg() are provided to convert
messages between their transport encoding described in the CAPI 2.0 standard
@@ -244,51 +275,71 @@ sure it is big enough to accommodate the resulting CAPI message.
5. Lower Layer Interface Functions
+==================================
(declared in <linux/isdn/capilli.h>)
-void register_capi_driver(struct capi_driver *drvr)
-void unregister_capi_driver(struct capi_driver *drvr)
- register/unregister a driver with Kernel CAPI
-
-int attach_capi_ctr(struct capi_ctr *ctrlr)
-int detach_capi_ctr(struct capi_ctr *ctrlr)
- register/unregister a device (controller) with Kernel CAPI
-
-void capi_ctr_ready(struct capi_ctr *ctrlr)
-void capi_ctr_down(struct capi_ctr *ctrlr)
- signal controller ready/not ready
-
-void capi_ctr_suspend_output(struct capi_ctr *ctrlr)
-void capi_ctr_resume_output(struct capi_ctr *ctrlr)
- signal suspend/resume
-
-void capi_ctr_handle_message(struct capi_ctr * ctrlr, u16 applid,
- struct sk_buff *skb)
- pass a received CAPI message to Kernel CAPI
- for forwarding to the specified application
+::
+
+ void register_capi_driver(struct capi_driver *drvr)
+ void unregister_capi_driver(struct capi_driver *drvr)
+
+register/unregister a driver with Kernel CAPI
+
+::
+
+ int attach_capi_ctr(struct capi_ctr *ctrlr)
+ int detach_capi_ctr(struct capi_ctr *ctrlr)
+
+register/unregister a device (controller) with Kernel CAPI
+
+::
+
+ void capi_ctr_ready(struct capi_ctr *ctrlr)
+ void capi_ctr_down(struct capi_ctr *ctrlr)
+
+signal controller ready/not ready
+
+::
+
+ void capi_ctr_suspend_output(struct capi_ctr *ctrlr)
+ void capi_ctr_resume_output(struct capi_ctr *ctrlr)
+
+signal suspend/resume
+
+::
+
+ void capi_ctr_handle_message(struct capi_ctr * ctrlr, u16 applid,
+ struct sk_buff *skb)
+
+pass a received CAPI message to Kernel CAPI
+for forwarding to the specified application
6. Helper Functions and Macros
+==============================
Library functions (from <linux/isdn/capilli.h>):
-void capilib_new_ncci(struct list_head *head, u16 applid,
+::
+
+ void capilib_new_ncci(struct list_head *head, u16 applid,
u32 ncci, u32 winsize)
-void capilib_free_ncci(struct list_head *head, u16 applid, u32 ncci)
-void capilib_release_appl(struct list_head *head, u16 applid)
-void capilib_release(struct list_head *head)
-void capilib_data_b3_conf(struct list_head *head, u16 applid,
+ void capilib_free_ncci(struct list_head *head, u16 applid, u32 ncci)
+ void capilib_release_appl(struct list_head *head, u16 applid)
+ void capilib_release(struct list_head *head)
+ void capilib_data_b3_conf(struct list_head *head, u16 applid,
u32 ncci, u16 msgid)
-u16 capilib_data_b3_req(struct list_head *head, u16 applid,
+ u16 capilib_data_b3_req(struct list_head *head, u16 applid,
u32 ncci, u16 msgid)
Macros to extract/set element values from/in a CAPI message header
(from <linux/isdn/capiutil.h>):
+====================== ============================= ====================
Get Macro Set Macro Element (Type)
-
+====================== ============================= ====================
CAPIMSG_LEN(m) CAPIMSG_SETLEN(m, len) Total Length (u16)
CAPIMSG_APPID(m) CAPIMSG_SETAPPID(m, applid) ApplID (u16)
CAPIMSG_COMMAND(m) CAPIMSG_SETCOMMAND(m,cmd) Command (u8)
@@ -300,31 +351,31 @@ CAPIMSG_MSGID(m) CAPIMSG_SETMSGID(m, msgid) Message Number (u16)
CAPIMSG_CONTROL(m) CAPIMSG_SETCONTROL(m, contr) Controller/PLCI/NCCI
(u32)
CAPIMSG_DATALEN(m) CAPIMSG_SETDATALEN(m, len) Data Length (u16)
+====================== ============================= ====================
Library functions for working with _cmsg structures
(from <linux/isdn/capiutil.h>):
-unsigned capi_cmsg2message(_cmsg *cmsg, u8 *msg)
- Assembles a CAPI 2.0 message from the parameters in *cmsg, storing the
- result in *msg.
+``unsigned capi_cmsg2message(_cmsg *cmsg, u8 *msg)``
+ Assembles a CAPI 2.0 message from the parameters in ``*cmsg``,
+ storing the result in ``*msg``.
-unsigned capi_message2cmsg(_cmsg *cmsg, u8 *msg)
- Disassembles the CAPI 2.0 message in *msg, storing the parameters in
- *cmsg.
+``unsigned capi_message2cmsg(_cmsg *cmsg, u8 *msg)``
+ Disassembles the CAPI 2.0 message in ``*msg``, storing the parameters
+ in ``*cmsg``.
-unsigned capi_cmsg_header(_cmsg *cmsg, u16 ApplId, u8 Command, u8 Subcommand,
- u16 Messagenumber, u32 Controller)
- Fills the header part and address field of the _cmsg structure *cmsg
+``unsigned capi_cmsg_header(_cmsg *cmsg, u16 ApplId, u8 Command, u8 Subcommand, u16 Messagenumber, u32 Controller)``
+ Fills the header part and address field of the _cmsg structure ``*cmsg``
with the given values, zeroing the remainder of the structure so only
parameters with non-default values need to be changed before sending
the message.
-void capi_cmsg_answer(_cmsg *cmsg)
- Sets the low bit of the Subcommand field in *cmsg, thereby converting
- _REQ to _CONF and _IND to _RESP.
+``void capi_cmsg_answer(_cmsg *cmsg)``
+ Sets the low bit of the Subcommand field in ``*cmsg``, thereby
+ converting ``_REQ`` to ``_CONF`` and ``_IND`` to ``_RESP``.
-char *capi_cmd2str(u8 Command, u8 Subcommand)
+``char *capi_cmd2str(u8 Command, u8 Subcommand)``
Returns the CAPI 2.0 message name corresponding to the given command
and subcommand values, as a static ASCII string. The return value may
be NULL if the command/subcommand is not one of those defined in the
@@ -332,6 +383,7 @@ char *capi_cmd2str(u8 Command, u8 Subcommand)
7. Debugging
+============
The module kernelcapi has a module parameter showcapimsgs controlling some
debugging output produced by the module. It can only be set when the module is
diff --git a/Documentation/isdn/README.mISDN b/Documentation/isdn/m_isdn.rst
similarity index 89%
rename from Documentation/isdn/README.mISDN
rename to Documentation/isdn/m_isdn.rst
index cd8bf920e77b..9957de349e69 100644
--- a/Documentation/isdn/README.mISDN
+++ b/Documentation/isdn/m_isdn.rst
@@ -1,6 +1,9 @@
+============
+mISDN Driver
+============
+
mISDN is a new modular ISDN driver, in the long term it should replace
the old I4L driver architecture for passiv ISDN cards.
It was designed to allow a broad range of applications and interfaces
but only have the basic function in kernel, the interface to the user
space is based on sockets with a own address family AF_ISDN.
-
diff --git a/drivers/staging/isdn/hysdn/Kconfig b/drivers/staging/isdn/hysdn/Kconfig
index 1971ef850c9a..4c8a9283b9dd 100644
--- a/drivers/staging/isdn/hysdn/Kconfig
+++ b/drivers/staging/isdn/hysdn/Kconfig
@@ -5,7 +5,7 @@ config HYSDN
help
Say Y here if you have one of Hypercope's active PCI ISDN cards
Champ, Ergo and Metro. You will then get a module called hysdn.
- Please read the file <file:Documentation/isdn/README.hysdn> for more
+ Please read the file <file:Documentation/isdn/hysdn.rst> for more
information.
config HYSDN_CAPI
--
2.21.0
^ permalink raw reply related
* [PATCH 12/22] docs: fs: cifs: convert to ReST and add to admin-guide book
From: Mauro Carvalho Chehab @ 2019-07-22 11:07 UTC (permalink / raw)
Cc: Mauro Carvalho Chehab, Steve French, Jonathan Corbet, linux-cifs,
samba-technical, linux-doc
In-Reply-To: <cover.1563792333.git.mchehab+samsung@kernel.org>
The filenames for cifs documentation is not using the same
convention as almost all Kernel documents is using. So,
rename them to a more appropriate name. Then, manually convert
the documentation files for CIFS to ReST.
By doing a manual conversion, we can preserve the original
author's style, while making it to look more like the other
Kernel documents.
Most of the conversion here is trivial. The most complex one was
the README file (which was renamed to usage.rst).
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
.../AUTHORS => admin-guide/cifs/authors.rst} | 64 +-
.../CHANGES => admin-guide/cifs/changes.rst} | 4 +
Documentation/admin-guide/cifs/index.rst | 21 +
.../cifs/introduction.rst} | 8 +
.../cifs/TODO => admin-guide/cifs/todo.rst} | 87 +--
.../README => admin-guide/cifs/usage.rst} | 560 +++++++++++-------
.../cifs/winucase_convert.pl | 0
Documentation/admin-guide/index.rst | 1 +
MAINTAINERS | 2 +-
9 files changed, 460 insertions(+), 287 deletions(-)
rename Documentation/{filesystems/cifs/AUTHORS => admin-guide/cifs/authors.rst} (60%)
rename Documentation/{filesystems/cifs/CHANGES => admin-guide/cifs/changes.rst} (91%)
create mode 100644 Documentation/admin-guide/cifs/index.rst
rename Documentation/{filesystems/cifs/cifs.txt => admin-guide/cifs/introduction.rst} (98%)
rename Documentation/{filesystems/cifs/TODO => admin-guide/cifs/todo.rst} (58%)
rename Documentation/{filesystems/cifs/README => admin-guide/cifs/usage.rst} (72%)
rename Documentation/{filesystems => admin-guide}/cifs/winucase_convert.pl (100%)
diff --git a/Documentation/filesystems/cifs/AUTHORS b/Documentation/admin-guide/cifs/authors.rst
similarity index 60%
rename from Documentation/filesystems/cifs/AUTHORS
rename to Documentation/admin-guide/cifs/authors.rst
index 75865da2ce14..b02d6dd6c070 100644
--- a/Documentation/filesystems/cifs/AUTHORS
+++ b/Documentation/admin-guide/cifs/authors.rst
@@ -1,5 +1,10 @@
+=======
+Authors
+=======
+
Original Author
-===============
+---------------
+
Steve French (sfrench@samba.org)
The author wishes to express his appreciation and thanks to:
@@ -12,7 +17,7 @@ side of the original CIFS Unix extensions and reviewing and implementing
portions of the newer CIFS POSIX extensions into the Samba 3 file server. Thank
Dave Boutcher of IBM Rochester (author of the OS/400 smb/cifs filesystem client)
for proving years ago that very good smb/cifs clients could be done on Unix-like
-operating systems. Volker Lendecke, Andrew Tridgell, Urban Widmark, John
+operating systems. Volker Lendecke, Andrew Tridgell, Urban Widmark, John
Newbigin and others for their work on the Linux smbfs module. Thanks to
the other members of the Storage Network Industry Association CIFS Technical
Workgroup for their work specifying this highly complex protocol and finally
@@ -20,33 +25,34 @@ thanks to the Samba team for their technical advice and encouragement.
Patch Contributors
------------------
-Zwane Mwaikambo
-Andi Kleen
-Amrut Joshi
-Shobhit Dayal
-Sergey Vlasov
-Richard Hughes
-Yury Umanets
-Mark Hamzy (for some of the early cifs IPv6 work)
-Domen Puncer
-Jesper Juhl (in particular for lots of whitespace/formatting cleanup)
-Vince Negri and Dave Stahl (for finding an important caching bug)
-Adrian Bunk (kcalloc cleanups)
-Miklos Szeredi
-Kazeon team for various fixes especially for 2.4 version.
-Asser Ferno (Change Notify support)
-Shaggy (Dave Kleikamp) for innumerable small fs suggestions and some good cleanup
-Gunter Kukkukk (testing and suggestions for support of old servers)
-Igor Mammedov (DFS support)
-Jeff Layton (many, many fixes, as well as great work on the cifs Kerberos code)
-Scott Lovenberg
-Pavel Shilovsky (for great work adding SMB2 support, and various SMB3 features)
-Aurelien Aptel (for DFS SMB3 work and some key bug fixes)
-Ronnie Sahlberg (for SMB3 xattr work, bug fixes, and lots of great work on compounding)
-Shirish Pargaonkar (for many ACL patches over the years)
-Sachin Prabhu (many bug fixes, including for reconnect, copy offload and security)
-Paulo Alcantara
-Long Li (some great work on RDMA, SMB Direct)
+
+- Zwane Mwaikambo
+- Andi Kleen
+- Amrut Joshi
+- Shobhit Dayal
+- Sergey Vlasov
+- Richard Hughes
+- Yury Umanets
+- Mark Hamzy (for some of the early cifs IPv6 work)
+- Domen Puncer
+- Jesper Juhl (in particular for lots of whitespace/formatting cleanup)
+- Vince Negri and Dave Stahl (for finding an important caching bug)
+- Adrian Bunk (kcalloc cleanups)
+- Miklos Szeredi
+- Kazeon team for various fixes especially for 2.4 version.
+- Asser Ferno (Change Notify support)
+- Shaggy (Dave Kleikamp) for innumerable small fs suggestions and some good cleanup
+- Gunter Kukkukk (testing and suggestions for support of old servers)
+- Igor Mammedov (DFS support)
+- Jeff Layton (many, many fixes, as well as great work on the cifs Kerberos code)
+- Scott Lovenberg
+- Pavel Shilovsky (for great work adding SMB2 support, and various SMB3 features)
+- Aurelien Aptel (for DFS SMB3 work and some key bug fixes)
+- Ronnie Sahlberg (for SMB3 xattr work, bug fixes, and lots of great work on compounding)
+- Shirish Pargaonkar (for many ACL patches over the years)
+- Sachin Prabhu (many bug fixes, including for reconnect, copy offload and security)
+- Paulo Alcantara
+- Long Li (some great work on RDMA, SMB Direct)
Test case and Bug Report contributors
diff --git a/Documentation/filesystems/cifs/CHANGES b/Documentation/admin-guide/cifs/changes.rst
similarity index 91%
rename from Documentation/filesystems/cifs/CHANGES
rename to Documentation/admin-guide/cifs/changes.rst
index 1df7f4910eb2..71f2ecb62299 100644
--- a/Documentation/filesystems/cifs/CHANGES
+++ b/Documentation/admin-guide/cifs/changes.rst
@@ -1,3 +1,7 @@
+=======
+Changes
+=======
+
See https://wiki.samba.org/index.php/LinuxCIFSKernel for summary
information (that may be easier to read than parsing the output of
"git log fs/cifs") about fixes/improvements to CIFS/SMB2/SMB3 support (changes
diff --git a/Documentation/admin-guide/cifs/index.rst b/Documentation/admin-guide/cifs/index.rst
new file mode 100644
index 000000000000..fad5268635f5
--- /dev/null
+++ b/Documentation/admin-guide/cifs/index.rst
@@ -0,0 +1,21 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+====
+CIFS
+====
+
+.. toctree::
+ :maxdepth: 2
+
+ introduction
+ usage
+ todo
+ changes
+ authors
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/filesystems/cifs/cifs.txt b/Documentation/admin-guide/cifs/introduction.rst
similarity index 98%
rename from Documentation/filesystems/cifs/cifs.txt
rename to Documentation/admin-guide/cifs/introduction.rst
index 1be3d21c286e..0b98f672d36f 100644
--- a/Documentation/filesystems/cifs/cifs.txt
+++ b/Documentation/admin-guide/cifs/introduction.rst
@@ -1,3 +1,7 @@
+============
+Introduction
+============
+
This is the client VFS module for the SMB3 NAS protocol as well
as for older dialects such as the Common Internet File System (CIFS)
protocol which was the successor to the Server Message Block
@@ -33,7 +37,9 @@
tools (including smbinfo and setcifsacl) that can be obtained from
https://git.samba.org/?p=cifs-utils.git
+
or
+
git://git.samba.org/cifs-utils.git
mount.cifs should be installed in the directory with the other mount helpers.
@@ -41,5 +47,7 @@
For more information on the module see the project wiki page at
https://wiki.samba.org/index.php/LinuxCIFS
+
and
+
https://wiki.samba.org/index.php/LinuxCIFS_utils
diff --git a/Documentation/filesystems/cifs/TODO b/Documentation/admin-guide/cifs/todo.rst
similarity index 58%
rename from Documentation/filesystems/cifs/TODO
rename to Documentation/admin-guide/cifs/todo.rst
index 9267f3fb131f..95f18e8c9b8a 100644
--- a/Documentation/filesystems/cifs/TODO
+++ b/Documentation/admin-guide/cifs/todo.rst
@@ -1,3 +1,7 @@
+====
+TODO
+====
+
Version 2.14 December 21, 2018
A Partial List of Missing Features
@@ -8,6 +12,7 @@ for visible, important contributions to this module. Here
is a partial list of the known problems and missing features:
a) SMB3 (and SMB3.1.1) missing optional features:
+
- multichannel (started), integration with RDMA
- directory leases (improved metadata caching), started (root dir only)
- T10 copy offload ie "ODX" (copy chunk, and "Duplicate Extents" ioctl
@@ -16,45 +21,46 @@ a) SMB3 (and SMB3.1.1) missing optional features:
b) improved sparse file support
c) Directory entry caching relies on a 1 second timer, rather than
-using Directory Leases, currently only the root file handle is cached longer
+ using Directory Leases, currently only the root file handle is cached longer
d) quota support (needs minor kernel change since quota calls
-to make it to network filesystems or deviceless filesystems)
+ to make it to network filesystems or deviceless filesystems)
e) Additional use cases where we use "compoounding" (e.g. open/query/close
-and open/setinfo/close) to reduce the number of roundtrips, and also
-open to reduce redundant opens (using deferred close and reference counts more).
+ and open/setinfo/close) to reduce the number of roundtrips, and also
+ open to reduce redundant opens (using deferred close and reference counts
+ more).
f) Finish inotify support so kde and gnome file list windows
-will autorefresh (partially complete by Asser). Needs minor kernel
-vfs change to support removing D_NOTIFY on a file.
+ will autorefresh (partially complete by Asser). Needs minor kernel
+ vfs change to support removing D_NOTIFY on a file.
g) Add GUI tool to configure /proc/fs/cifs settings and for display of
-the CIFS statistics (started)
+ the CIFS statistics (started)
h) implement support for security and trusted categories of xattrs
-(requires minor protocol extension) to enable better support for SELINUX
+ (requires minor protocol extension) to enable better support for SELINUX
i) Add support for tree connect contexts (see MS-SMB2) a new SMB3.1.1 protocol
feature (may be especially useful for virtualization).
j) Create UID mapping facility so server UIDs can be mapped on a per
-mount or a per server basis to client UIDs or nobody if no mapping
-exists. Also better integration with winbind for resolving SID owners
+ mount or a per server basis to client UIDs or nobody if no mapping
+ exists. Also better integration with winbind for resolving SID owners
k) Add tools to take advantage of more smb3 specific ioctls and features
-(passthrough ioctl/fsctl for sending various SMB3 fsctls to the server
-is in progress, and a passthrough query_info call is already implemented
-in cifs.ko to allow smb3 info levels queries to be sent from userspace)
+ (passthrough ioctl/fsctl for sending various SMB3 fsctls to the server
+ is in progress, and a passthrough query_info call is already implemented
+ in cifs.ko to allow smb3 info levels queries to be sent from userspace)
l) encrypted file support
m) improved stats gathering tools (perhaps integration with nfsometer?)
-to extend and make easier to use what is currently in /proc/fs/cifs/Stats
+ to extend and make easier to use what is currently in /proc/fs/cifs/Stats
-n) allow setting more NTFS/SMB3 file attributes remotely (currently limited to compressed
-file attribute via chflags) and improve user space tools for managing and
-viewing them.
+n) allow setting more NTFS/SMB3 file attributes remotely (currently limited to
+ compressed file attribute via chflags) and improve user space tools for
+ managing and viewing them.
o) mount helper GUI (to simplify the various configuration options on mount)
@@ -65,55 +71,56 @@ p) Add support for witness protocol (perhaps ioctl to cifs.ko from user space
different servers, and the server we are connected to has gone down.
q) Allow mount.cifs to be more verbose in reporting errors with dialect
-or unsupported feature errors.
+ or unsupported feature errors.
r) updating cifs documentation, and user guide.
s) Addressing bugs found by running a broader set of xfstests in standard
-file system xfstest suite.
+ file system xfstest suite.
t) split cifs and smb3 support into separate modules so legacy (and less
-secure) CIFS dialect can be disabled in environments that don't need it
-and simplify the code.
+ secure) CIFS dialect can be disabled in environments that don't need it
+ and simplify the code.
v) POSIX Extensions for SMB3.1.1 (started, create and mkdir support added
-so far).
+ so far).
w) Add support for additional strong encryption types, and additional spnego
-authentication mechanisms (see MS-SMB2)
+ authentication mechanisms (see MS-SMB2)
+
+Known Bugs
+==========
-KNOWN BUGS
-====================================
See http://bugzilla.samba.org - search on product "CifsVFS" for
current bug list. Also check http://bugzilla.kernel.org (Product = File System, Component = CIFS)
1) existing symbolic links (Windows reparse points) are recognized but
-can not be created remotely. They are implemented for Samba and those that
-support the CIFS Unix extensions, although earlier versions of Samba
-overly restrict the pathnames.
+ can not be created remotely. They are implemented for Samba and those that
+ support the CIFS Unix extensions, although earlier versions of Samba
+ overly restrict the pathnames.
2) follow_link and readdir code does not follow dfs junctions
-but recognizes them
+ but recognizes them
Misc testing to do
==================
1) check out max path names and max path name components against various server
-types. Try nested symlinks (8 deep). Return max path name in stat -f information
+ types. Try nested symlinks (8 deep). Return max path name in stat -f information
2) Improve xfstest's cifs/smb3 enablement and adapt xfstests where needed to test
-cifs/smb3 better
+ cifs/smb3 better
-3) Additional performance testing and optimization using iozone and similar -
-there are some easy changes that can be done to parallelize sequential writes,
-and when signing is disabled to request larger read sizes (larger than
-negotiated size) and send larger write sizes to modern servers.
+3) Additional performance testing and optimization using iozone and similar -
+ there are some easy changes that can be done to parallelize sequential writes,
+ and when signing is disabled to request larger read sizes (larger than
+ negotiated size) and send larger write sizes to modern servers.
4) More exhaustively test against less common servers
5) Continue to extend the smb3 "buildbot" which does automated xfstesting
-against Windows, Samba and Azure currently - to add additional tests and
-to allow the buildbot to execute the tests faster. The URL for the
-buildbot is: http://smb3-test-rhel-75.southcentralus.cloudapp.azure.com
+ against Windows, Samba and Azure currently - to add additional tests and
+ to allow the buildbot to execute the tests faster. The URL for the
+ buildbot is: http://smb3-test-rhel-75.southcentralus.cloudapp.azure.com
6) Address various coverity warnings (most are not bugs per-se, but
-the more warnings are addressed, the easier it is to spot real
-problems that static analyzers will point out in the future).
+ the more warnings are addressed, the easier it is to spot real
+ problems that static analyzers will point out in the future).
diff --git a/Documentation/filesystems/cifs/README b/Documentation/admin-guide/cifs/usage.rst
similarity index 72%
rename from Documentation/filesystems/cifs/README
rename to Documentation/admin-guide/cifs/usage.rst
index 4a804619cff2..d3fb67b8a976 100644
--- a/Documentation/filesystems/cifs/README
+++ b/Documentation/admin-guide/cifs/usage.rst
@@ -1,53 +1,61 @@
+=====
+Usage
+=====
+
This module supports the SMB3 family of advanced network protocols (as well
as older dialects, originally called "CIFS" or SMB1).
The CIFS VFS module for Linux supports many advanced network filesystem
features such as hierarchical DFS like namespace, hardlinks, locking and more.
-It was designed to comply with the SNIA CIFS Technical Reference (which
-supersedes the 1992 X/Open SMB Standard) as well as to perform best practice
-practical interoperability with Windows 2000, Windows XP, Samba and equivalent
+It was designed to comply with the SNIA CIFS Technical Reference (which
+supersedes the 1992 X/Open SMB Standard) as well as to perform best practice
+practical interoperability with Windows 2000, Windows XP, Samba and equivalent
servers. This code was developed in participation with the Protocol Freedom
Information Foundation. CIFS and now SMB3 has now become a defacto
standard for interoperating between Macs and Windows and major NAS appliances.
Please see
- MS-SMB2 (for detailed SMB2/SMB3/SMB3.1.1 protocol specification)
- http://protocolfreedom.org/ and
- http://samba.org/samba/PFIF/
+MS-SMB2 (for detailed SMB2/SMB3/SMB3.1.1 protocol specification)
+http://protocolfreedom.org/ and
+http://samba.org/samba/PFIF/
for more details.
For questions or bug reports please contact:
+
smfrench@gmail.com
See the project page at: https://wiki.samba.org/index.php/LinuxCIFS_utils
-Build instructions:
+Build instructions
==================
+
For Linux:
+
1) Download the kernel (e.g. from http://www.kernel.org)
-and change directory into the top of the kernel directory tree
-(e.g. /usr/src/linux-2.5.73)
+ and change directory into the top of the kernel directory tree
+ (e.g. /usr/src/linux-2.5.73)
2) make menuconfig (or make xconfig)
3) select cifs from within the network filesystem choices
4) save and exit
5) make
-Installation instructions:
+Installation instructions
=========================
+
If you have built the CIFS vfs as module (successfully) simply
-type "make modules_install" (or if you prefer, manually copy the file to
+type ``make modules_install`` (or if you prefer, manually copy the file to
the modules directory e.g. /lib/modules/2.4.10-4GB/kernel/fs/cifs/cifs.ko).
If you have built the CIFS vfs into the kernel itself, follow the instructions
for your distribution on how to install a new kernel (usually you
-would simply type "make install").
+would simply type ``make install``).
If you do not have the utility mount.cifs (in the Samba 4.x source tree and on
the CIFS VFS web site) copy it to the same directory in which mount helpers
reside (usually /sbin). Although the helper software is not
-required, mount.cifs is recommended. Most distros include a "cifs-utils"
+required, mount.cifs is recommended. Most distros include a ``cifs-utils``
package that includes this utility so it is recommended to install this.
Note that running the Winbind pam/nss module (logon service) on all of your
@@ -57,13 +65,16 @@ found at cifs-utils.git on git.samba.org
If cifs is built as a module, then the size and number of network buffers
and maximum number of simultaneous requests to one server can be configured.
-Changing these from their defaults is not recommended. By executing modinfo
+Changing these from their defaults is not recommended. By executing modinfo::
+
modinfo kernel/fs/cifs/cifs.ko
+
on kernel/fs/cifs/cifs.ko the list of configuration changes that can be made
at module initialization time (by running insmod cifs.ko) can be seen.
Recommendations
===============
+
To improve security the SMB2.1 dialect or later (usually will get SMB3) is now
the new default. To use old dialects (e.g. to mount Windows XP) use "vers=1.0"
on mount (or vers=2.0 for Windows Vista). Note that the CIFS (vers=1.0) is
@@ -72,156 +83,168 @@ many advanced security features such as downgrade attack detection
and encrypted shares and stronger signing and authentication algorithms.
There are additional mount options that may be helpful for SMB3 to get
improved POSIX behavior (NB: can use vers=3.0 to force only SMB3, never 2.1):
- "mfsymlinks" and "cifsacl" and "idsfromsid"
+
+ ``mfsymlinks`` and ``cifsacl`` and ``idsfromsid``
Allowing User Mounts
====================
+
To permit users to mount and unmount over directories they own is possible
with the cifs vfs. A way to enable such mounting is to mark the mount.cifs
-utility as suid (e.g. "chmod +s /sbin/mount.cifs). To enable users to
+utility as suid (e.g. ``chmod +s /sbin/mount.cifs``). To enable users to
umount shares they mount requires
+
1) mount.cifs version 1.4 or later
2) an entry for the share in /etc/fstab indicating that a user may
-unmount it e.g.
-//server/usersharename /mnt/username cifs user 0 0
+ unmount it e.g.::
-Note that when the mount.cifs utility is run suid (allowing user mounts),
-in order to reduce risks, the "nosuid" mount flag is passed in on mount to
+ //server/usersharename /mnt/username cifs user 0 0
+
+Note that when the mount.cifs utility is run suid (allowing user mounts),
+in order to reduce risks, the ``nosuid`` mount flag is passed in on mount to
disallow execution of an suid program mounted on the remote target.
When mount is executed as root, nosuid is not passed in by default,
and execution of suid programs on the remote target would be enabled
-by default. This can be changed, as with nfs and other filesystems,
-by simply specifying "nosuid" among the mount options. For user mounts
-though to be able to pass the suid flag to mount requires rebuilding
+by default. This can be changed, as with nfs and other filesystems,
+by simply specifying ``nosuid`` among the mount options. For user mounts
+though to be able to pass the suid flag to mount requires rebuilding
mount.cifs with the following flag: CIFS_ALLOW_USR_SUID
There is a corresponding manual page for cifs mounting in the Samba 3.0 and
-later source tree in docs/manpages/mount.cifs.8
+later source tree in docs/manpages/mount.cifs.8
Allowing User Unmounts
======================
+
To permit users to ummount directories that they have user mounted (see above),
-the utility umount.cifs may be used. It may be invoked directly, or if
+the utility umount.cifs may be used. It may be invoked directly, or if
umount.cifs is placed in /sbin, umount can invoke the cifs umount helper
(at least for most versions of the umount utility) for umount of cifs
mounts, unless umount is invoked with -i (which will avoid invoking a umount
helper). As with mount.cifs, to enable user unmounts umount.cifs must be marked
-as suid (e.g. "chmod +s /sbin/umount.cifs") or equivalent (some distributions
+as suid (e.g. ``chmod +s /sbin/umount.cifs``) or equivalent (some distributions
allow adding entries to a file to the /etc/permissions file to achieve the
equivalent suid effect). For this utility to succeed the target path
must be a cifs mount, and the uid of the current user must match the uid
of the user who mounted the resource.
-Also note that the customary way of allowing user mounts and unmounts is
+Also note that the customary way of allowing user mounts and unmounts is
(instead of using mount.cifs and unmount.cifs as suid) to add a line
to the file /etc/fstab for each //server/share you wish to mount, but
this can become unwieldy when potential mount targets include many
or unpredictable UNC names.
-Samba Considerations
+Samba Considerations
====================
+
Most current servers support SMB2.1 and SMB3 which are more secure,
but there are useful protocol extensions for the older less secure CIFS
dialect, so to get the maximum benefit if mounting using the older dialect
(CIFS/SMB1), we recommend using a server that supports the SNIA CIFS
Unix Extensions standard (e.g. almost any version of Samba ie version
2.2.5 or later) but the CIFS vfs works fine with a wide variety of CIFS servers.
-Note that uid, gid and file permissions will display default values if you do
-not have a server that supports the Unix extensions for CIFS (such as Samba
-2.2.5 or later). To enable the Unix CIFS Extensions in the Samba server, add
-the line:
+Note that uid, gid and file permissions will display default values if you do
+not have a server that supports the Unix extensions for CIFS (such as Samba
+2.2.5 or later). To enable the Unix CIFS Extensions in the Samba server, add
+the line::
unix extensions = yes
-
-to your smb.conf file on the server. Note that the following smb.conf settings
-are also useful (on the Samba server) when the majority of clients are Unix or
-Linux:
+
+to your smb.conf file on the server. Note that the following smb.conf settings
+are also useful (on the Samba server) when the majority of clients are Unix or
+Linux::
case sensitive = yes
- delete readonly = yes
+ delete readonly = yes
ea support = yes
Note that server ea support is required for supporting xattrs from the Linux
-cifs client, and that EA support is present in later versions of Samba (e.g.
+cifs client, and that EA support is present in later versions of Samba (e.g.
3.0.6 and later (also EA support works in all versions of Windows, at least to
shares on NTFS filesystems). Extended Attribute (xattr) support is an optional
feature of most Linux filesystems which may require enabling via
make menuconfig. Client support for extended attributes (user xattr) can be
-disabled on a per-mount basis by specifying "nouser_xattr" on mount.
+disabled on a per-mount basis by specifying ``nouser_xattr`` on mount.
The CIFS client can get and set POSIX ACLs (getfacl, setfacl) to Samba servers
-version 3.10 and later. Setting POSIX ACLs requires enabling both XATTR and
+version 3.10 and later. Setting POSIX ACLs requires enabling both XATTR and
then POSIX support in the CIFS configuration options when building the cifs
module. POSIX ACL support can be disabled on a per mount basic by specifying
-"noacl" on mount.
-
-Some administrators may want to change Samba's smb.conf "map archive" and
-"create mask" parameters from the default. Unless the create mask is changed
+``noacl`` on mount.
+
+Some administrators may want to change Samba's smb.conf ``map archive`` and
+``create mask`` parameters from the default. Unless the create mask is changed
newly created files can end up with an unnecessarily restrictive default mode,
which may not be what you want, although if the CIFS Unix extensions are
enabled on the server and client, subsequent setattr calls (e.g. chmod) can
-fix the mode. Note that creating special devices (mknod) remotely
-may require specifying a mkdev function to Samba if you are not using
+fix the mode. Note that creating special devices (mknod) remotely
+may require specifying a mkdev function to Samba if you are not using
Samba 3.0.6 or later. For more information on these see the manual pages
-("man smb.conf") on the Samba server system. Note that the cifs vfs,
-unlike the smbfs vfs, does not read the smb.conf on the client system
-(the few optional settings are passed in on mount via -o parameters instead).
+(``man smb.conf``) on the Samba server system. Note that the cifs vfs,
+unlike the smbfs vfs, does not read the smb.conf on the client system
+(the few optional settings are passed in on mount via -o parameters instead).
Note that Samba 2.2.7 or later includes a fix that allows the CIFS VFS to delete
-open files (required for strict POSIX compliance). Windows Servers already
+open files (required for strict POSIX compliance). Windows Servers already
supported this feature. Samba server does not allow symlinks that refer to files
outside of the share, so in Samba versions prior to 3.0.6, most symlinks to
-files with absolute paths (ie beginning with slash) such as:
+files with absolute paths (ie beginning with slash) such as::
+
ln -s /mnt/foo bar
-would be forbidden. Samba 3.0.6 server or later includes the ability to create
-such symlinks safely by converting unsafe symlinks (ie symlinks to server
+
+would be forbidden. Samba 3.0.6 server or later includes the ability to create
+such symlinks safely by converting unsafe symlinks (ie symlinks to server
files that are outside of the share) to a samba specific format on the server
that is ignored by local server applications and non-cifs clients and that will
not be traversed by the Samba server). This is opaque to the Linux client
application using the cifs vfs. Absolute symlinks will work to Samba 3.0.5 or
later, but only for remote clients using the CIFS Unix extensions, and will
be invisbile to Windows clients and typically will not affect local
-applications running on the same server as Samba.
+applications running on the same server as Samba.
-Use instructions:
+Use instructions
================
-Once the CIFS VFS support is built into the kernel or installed as a module
+
+Once the CIFS VFS support is built into the kernel or installed as a module
(cifs.ko), you can use mount syntax like the following to access Samba or
-Mac or Windows servers:
+Mac or Windows servers::
mount -t cifs //9.53.216.11/e$ /mnt -o username=myname,password=mypassword
Before -o the option -v may be specified to make the mount.cifs
-mount helper display the mount steps more verbosely.
+mount helper display the mount steps more verbosely.
After -o the following commonly used cifs vfs specific options
-are supported:
+are supported::
username=<username>
password=<password>
domain=<domain name>
-
+
Other cifs mount options are described below. Use of TCP names (in addition to
ip addresses) is available if the mount helper (mount.cifs) is installed. If
you do not trust the server to which are mounted, or if you do not have
cifs signing enabled (and the physical network is insecure), consider use
-of the standard mount options "noexec" and "nosuid" to reduce the risk of
+of the standard mount options ``noexec`` and ``nosuid`` to reduce the risk of
running an altered binary on your local system (downloaded from a hostile server
or altered by a hostile router).
Although mounting using format corresponding to the CIFS URL specification is
not possible in mount.cifs yet, it is possible to use an alternate format
for the server and sharename (which is somewhat similar to NFS style mount
-syntax) instead of the more widely used UNC format (i.e. \\server\share):
+syntax) instead of the more widely used UNC format (i.e. \\server\share)::
+
mount -t cifs tcp_name_of_server:share_name /mnt -o user=myname,pass=mypasswd
When using the mount helper mount.cifs, passwords may be specified via alternate
-mechanisms, instead of specifying it after -o using the normal "pass=" syntax
+mechanisms, instead of specifying it after -o using the normal ``pass=`` syntax
on the command line:
1) By including it in a credential file. Specify credentials=filename as one
-of the mount options. Credential files contain two lines
- username=someuser
- password=your_password
+of the mount options. Credential files contain two lines::
+
+ username=someuser
+ password=your_password
+
2) By specifying the password in the PASSWD environment variable (similarly
-the user name can be taken from the USER environment variable).
+ the user name can be taken from the USER environment variable).
3) By specifying the password in a file by name via PASSWD_FILE
4) By specifying the password in a file by file descriptor via PASSWD_FD
@@ -229,39 +252,47 @@ If no password is provided, mount.cifs will prompt for password entry
Restrictions
============
-Servers must support either "pure-TCP" (port 445 TCP/IP CIFS connections) or RFC
-1001/1002 support for "Netbios-Over-TCP/IP." This is not likely to be a
+
+Servers must support either "pure-TCP" (port 445 TCP/IP CIFS connections) or RFC
+1001/1002 support for "Netbios-Over-TCP/IP." This is not likely to be a
problem as most servers support this.
Valid filenames differ between Windows and Linux. Windows typically restricts
-filenames which contain certain reserved characters (e.g.the character :
+filenames which contain certain reserved characters (e.g.the character :
which is used to delimit the beginning of a stream name by Windows), while
Linux allows a slightly wider set of valid characters in filenames. Windows
servers can remap such characters when an explicit mapping is specified in
-the Server's registry. Samba starting with version 3.10 will allow such
+the Server's registry. Samba starting with version 3.10 will allow such
filenames (ie those which contain valid Linux characters, which normally
would be forbidden for Windows/CIFS semantics) as long as the server is
configured for Unix Extensions (and the client has not disabled
/proc/fs/cifs/LinuxExtensionsEnabled). In addition the mount option
-"mapposix" can be used on CIFS (vers=1.0) to force the mapping of
+``mapposix`` can be used on CIFS (vers=1.0) to force the mapping of
illegal Windows/NTFS/SMB characters to a remap range (this mount parm
-is the default for SMB3). This remap ("mapposix") range is also
+is the default for SMB3). This remap (``mapposix``) range is also
compatible with Mac (and "Services for Mac" on some older Windows).
CIFS VFS Mount Options
======================
A partial list of the supported mount options follows:
- username The user name to use when trying to establish
+
+ username
+ The user name to use when trying to establish
the CIFS session.
- password The user password. If the mount helper is
+ password
+ The user password. If the mount helper is
installed, the user will be prompted for password
if not supplied.
- ip The ip address of the target server
- unc The target server Universal Network Name (export) to
- mount.
- domain Set the SMB/CIFS workgroup name prepended to the
+ ip
+ The ip address of the target server
+ unc
+ The target server Universal Network Name (export) to
+ mount.
+ domain
+ Set the SMB/CIFS workgroup name prepended to the
username during CIFS session establishment
- forceuid Set the default uid for inodes to the uid
+ forceuid
+ Set the default uid for inodes to the uid
passed in on mount. For mounts to servers
which do support the CIFS Unix extensions, such as a
properly configured Samba server, the server provides
@@ -276,32 +307,39 @@ A partial list of the supported mount options follows:
extensions, the default uid (and gid) returned on lookup
of existing files will be the uid (gid) of the person
who executed the mount (root, except when mount.cifs
- is configured setuid for user mounts) unless the "uid="
+ is configured setuid for user mounts) unless the ``uid=``
(gid) mount option is specified. Also note that permission
checks (authorization checks) on accesses to a file occur
at the server, but there are cases in which an administrator
may want to restrict at the client as well. For those
servers which do not report a uid/gid owner
(such as Windows), permissions can also be checked at the
- client, and a crude form of client side permission checking
- can be enabled by specifying file_mode and dir_mode on
+ client, and a crude form of client side permission checking
+ can be enabled by specifying file_mode and dir_mode on
the client. (default)
- forcegid (similar to above but for the groupid instead of uid) (default)
- noforceuid Fill in file owner information (uid) by requesting it from
+ forcegid
+ (similar to above but for the groupid instead of uid) (default)
+ noforceuid
+ Fill in file owner information (uid) by requesting it from
the server if possible. With this option, the value given in
the uid= option (on mount) will only be used if the server
can not support returning uids on inodes.
- noforcegid (similar to above but for the group owner, gid, instead of uid)
- uid Set the default uid for inodes, and indicate to the
+ noforcegid
+ (similar to above but for the group owner, gid, instead of uid)
+ uid
+ Set the default uid for inodes, and indicate to the
cifs kernel driver which local user mounted. If the server
supports the unix extensions the default uid is
not used to fill in the owner fields of inodes (files)
- unless the "forceuid" parameter is specified.
- gid Set the default gid for inodes (similar to above).
- file_mode If CIFS Unix extensions are not supported by the server
+ unless the ``forceuid`` parameter is specified.
+ gid
+ Set the default gid for inodes (similar to above).
+ file_mode
+ If CIFS Unix extensions are not supported by the server
this overrides the default mode for file inodes.
- fsc Enable local disk caching using FS-Cache (off by default). This
- option could be useful to improve performance on a slow link,
+ fsc
+ Enable local disk caching using FS-Cache (off by default). This
+ option could be useful to improve performance on a slow link,
heavily loaded server and/or network where reading from the
disk is faster than reading from the server (over the network).
This could also impact scalability positively as the
@@ -310,18 +348,22 @@ A partial list of the supported mount options follows:
type workloads. So, you need to consider carefully your
workload/scenario before using this option. Currently, local
disk caching is functional for CIFS files opened as read-only.
- dir_mode If CIFS Unix extensions are not supported by the server
+ dir_mode
+ If CIFS Unix extensions are not supported by the server
this overrides the default mode for directory inodes.
- port attempt to contact the server on this tcp port, before
+ port
+ attempt to contact the server on this tcp port, before
trying the usual ports (port 445, then 139).
- iocharset Codepage used to convert local path names to and from
+ iocharset
+ Codepage used to convert local path names to and from
Unicode. Unicode is used by default for network path
names if the server supports it. If iocharset is
not specified then the nls_default specified
during the local client kernel build will be used.
If server does not support Unicode, this parameter is
unused.
- rsize default read size (usually 16K). The client currently
+ rsize
+ default read size (usually 16K). The client currently
can not use rsize larger than CIFSMaxBufSize. CIFSMaxBufSize
defaults to 16K and may be changed (from 8K to the maximum
kmalloc size allowed by your kernel) at module install time
@@ -333,10 +375,12 @@ A partial list of the supported mount options follows:
newer servers (e.g. Samba 3.0.26 or later) do. rsize can be
set from a minimum of 2048 to a maximum of 130048 (127K or
CIFSMaxBufSize, whichever is smaller)
- wsize default write size (default 57344)
+ wsize
+ default write size (default 57344)
maximum wsize currently allowed by CIFS is 57344 (fourteen
4096 byte pages)
- actimeo=n attribute cache timeout in seconds (default 1 second).
+ actimeo=n
+ attribute cache timeout in seconds (default 1 second).
After this timeout, the cifs client requests fresh attribute
information from the server. This option allows to tune the
attribute cache timeout to suit the workload needs. Shorter
@@ -345,49 +389,67 @@ A partial list of the supported mount options follows:
of calls to the server at the expense of less stricter cache
coherency checks (i.e. incorrect attribute cache for a short
period of time).
- rw mount the network share read-write (note that the
+ rw
+ mount the network share read-write (note that the
server may still consider the share read-only)
- ro mount network share read-only
- version used to distinguish different versions of the
+ ro
+ mount network share read-only
+ version
+ used to distinguish different versions of the
mount helper utility (not typically needed)
- sep if first mount option (after the -o), overrides
+ sep
+ if first mount option (after the -o), overrides
the comma as the separator between the mount
- parms. e.g.
+ parms. e.g.::
+
-o user=myname,password=mypassword,domain=mydom
- could be passed instead with period as the separator by
+
+ could be passed instead with period as the separator by::
+
-o sep=.user=myname.password=mypassword.domain=mydom
+
this might be useful when comma is contained within username
or password or domain. This option is less important
when the cifs mount helper cifs.mount (version 1.1 or later)
is used.
- nosuid Do not allow remote executables with the suid bit
+ nosuid
+ Do not allow remote executables with the suid bit
program to be executed. This is only meaningful for mounts
to servers such as Samba which support the CIFS Unix Extensions.
If you do not trust the servers in your network (your mount
targets) it is recommended that you specify this option for
greater security.
- exec Permit execution of binaries on the mount.
- noexec Do not permit execution of binaries on the mount.
- dev Recognize block devices on the remote mount.
- nodev Do not recognize devices on the remote mount.
- suid Allow remote files on this mountpoint with suid enabled to
+ exec
+ Permit execution of binaries on the mount.
+ noexec
+ Do not permit execution of binaries on the mount.
+ dev
+ Recognize block devices on the remote mount.
+ nodev
+ Do not recognize devices on the remote mount.
+ suid
+ Allow remote files on this mountpoint with suid enabled to
be executed (default for mounts when executed as root,
nosuid is default for user mounts).
- credentials Although ignored by the cifs kernel component, it is used by
+ credentials
+ Although ignored by the cifs kernel component, it is used by
the mount helper, mount.cifs. When mount.cifs is installed it
- opens and reads the credential file specified in order
+ opens and reads the credential file specified in order
to obtain the userid and password arguments which are passed to
the cifs vfs.
- guest Although ignored by the kernel component, the mount.cifs
+ guest
+ Although ignored by the kernel component, the mount.cifs
mount helper will not prompt the user for a password
if guest is specified on the mount options. If no
password is specified a null password will be used.
- perm Client does permission checks (vfs_permission check of uid
+ perm
+ Client does permission checks (vfs_permission check of uid
and gid of the file against the mode and desired operation),
Note that this is in addition to the normal ACL check on the
- target machine done by the server software.
+ target machine done by the server software.
Client permission checking is enabled by default.
- noperm Client does not do permission checks. This can expose
+ noperm
+ Client does not do permission checks. This can expose
files on this mount to access by other users on the local
client system. It is typically only needed when the server
supports the CIFS Unix Extensions but the UIDs/GIDs on the
@@ -399,7 +461,8 @@ A partial list of the supported mount options follows:
Note that this does not affect the normal ACL check on the
target machine done by the server software (of the server
ACL against the user name provided at mount time).
- serverino Use server's inode numbers instead of generating automatically
+ serverino
+ Use server's inode numbers instead of generating automatically
incrementing inode numbers on the client. Although this will
make it easier to spot hardlinked files (as they will have
the same inode numbers) and inode numbers may be persistent,
@@ -412,14 +475,16 @@ A partial list of the supported mount options follows:
or the CIFS Unix Extensions equivalent and for those
this mount option will have no effect. Exporting cifs mounts
under nfsd requires this mount option on the cifs mount.
- This is now the default if server supports the
+ This is now the default if server supports the
required network operation.
- noserverino Client generates inode numbers (rather than using the actual one
+ noserverino
+ Client generates inode numbers (rather than using the actual one
from the server). These inode numbers will vary after
unmount or reboot which can confuse some applications,
but not all server filesystems support unique inode
numbers.
- setuids If the CIFS Unix extensions are negotiated with the server
+ setuids
+ If the CIFS Unix extensions are negotiated with the server
the client will attempt to set the effective uid and gid of
the local process on newly created files, directories, and
devices (create, mkdir, mknod). If the CIFS Unix Extensions
@@ -427,9 +492,10 @@ A partial list of the supported mount options follows:
instead of using the default uid and gid specified on
the mount, cache the new file's uid and gid locally which means
that the uid for the file can change when the inode is
- reloaded (or the user remounts the share).
- nosetuids The client will not attempt to set the uid and gid on
- on newly created files, directories, and devices (create,
+ reloaded (or the user remounts the share).
+ nosetuids
+ The client will not attempt to set the uid and gid on
+ on newly created files, directories, and devices (create,
mkdir, mknod) which will result in the server setting the
uid and gid to the default (usually the server uid of the
user who mounted the share). Letting the server (rather than
@@ -437,38 +503,49 @@ A partial list of the supported mount options follows:
Unix Extensions are not negotiated then the uid and gid for
new files will appear to be the uid (gid) of the mounter or the
uid (gid) parameter specified on the mount.
- netbiosname When mounting to servers via port 139, specifies the RFC1001
- source name to use to represent the client netbios machine
+ netbiosname
+ When mounting to servers via port 139, specifies the RFC1001
+ source name to use to represent the client netbios machine
name when doing the RFC1001 netbios session initialize.
- direct Do not do inode data caching on files opened on this mount.
+ direct
+ Do not do inode data caching on files opened on this mount.
This precludes mmapping files on this mount. In some cases
with fast networks and little or no caching benefits on the
client (e.g. when the application is doing large sequential
- reads bigger than page size without rereading the same data)
+ reads bigger than page size without rereading the same data)
this can provide better performance than the default
- behavior which caches reads (readahead) and writes
- (writebehind) through the local Linux client pagecache
+ behavior which caches reads (readahead) and writes
+ (writebehind) through the local Linux client pagecache
if oplock (caching token) is granted and held. Note that
direct allows write operations larger than page size
to be sent to the server.
- strictcache Use for switching on strict cache mode. In this mode the
+ strictcache
+ Use for switching on strict cache mode. In this mode the
client read from the cache all the time it has Oplock Level II,
otherwise - read from the server. All written data are stored
in the cache, but if the client doesn't have Exclusive Oplock,
it writes the data to the server.
- rwpidforward Forward pid of a process who opened a file to any read or write
+ rwpidforward
+ Forward pid of a process who opened a file to any read or write
operation on that file. This prevent applications like WINE
from failing on read and write if we use mandatory brlock style.
- acl Allow setfacl and getfacl to manage posix ACLs if server
+ acl
+ Allow setfacl and getfacl to manage posix ACLs if server
supports them. (default)
- noacl Do not allow setfacl and getfacl calls on this mount
- user_xattr Allow getting and setting user xattrs (those attributes whose
- name begins with "user." or "os2.") as OS/2 EAs (extended
+ noacl
+ Do not allow setfacl and getfacl calls on this mount
+ user_xattr
+ Allow getting and setting user xattrs (those attributes whose
+ name begins with ``user.`` or ``os2.``) as OS/2 EAs (extended
attributes) to the server. This allows support of the
setfattr and getfattr utilities. (default)
- nouser_xattr Do not allow getfattr/setfattr to get/set/list xattrs
- mapchars Translate six of the seven reserved characters (not backslash)
+ nouser_xattr
+ Do not allow getfattr/setfattr to get/set/list xattrs
+ mapchars
+ Translate six of the seven reserved characters (not backslash)::
+
*?<>|:
+
to the remap range (above 0xF000), which also
allows the CIFS client to recognize files created with
such characters by Windows's POSIX emulation. This can
@@ -477,39 +554,47 @@ A partial list of the supported mount options follows:
whose names contain any of these seven characters).
This has no effect if the server does not support
Unicode on the wire.
- nomapchars Do not translate any of these seven characters (default).
- nocase Request case insensitive path name matching (case
+ nomapchars
+ Do not translate any of these seven characters (default).
+ nocase
+ Request case insensitive path name matching (case
sensitive is the default if the server supports it).
- (mount option "ignorecase" is identical to "nocase")
- posixpaths If CIFS Unix extensions are supported, attempt to
+ (mount option ``ignorecase`` is identical to ``nocase``)
+ posixpaths
+ If CIFS Unix extensions are supported, attempt to
negotiate posix path name support which allows certain
characters forbidden in typical CIFS filenames, without
requiring remapping. (default)
- noposixpaths If CIFS Unix extensions are supported, do not request
+ noposixpaths
+ If CIFS Unix extensions are supported, do not request
posix path name support (this may cause servers to
reject creatingfile with certain reserved characters).
- nounix Disable the CIFS Unix Extensions for this mount (tree
+ nounix
+ Disable the CIFS Unix Extensions for this mount (tree
connection). This is rarely needed, but it may be useful
in order to turn off multiple settings all at once (ie
posix acls, posix locks, posix paths, symlink support
and retrieving uids/gids/mode from the server) or to
work around a bug in server which implement the Unix
Extensions.
- nobrl Do not send byte range lock requests to the server.
+ nobrl
+ Do not send byte range lock requests to the server.
This is necessary for certain applications that break
with cifs style mandatory byte range locks (and most
cifs servers do not yet support requesting advisory
byte range locks).
- forcemandatorylock Even if the server supports posix (advisory) byte range
+ forcemandatorylock
+ Even if the server supports posix (advisory) byte range
locking, send only mandatory lock requests. For some
(presumably rare) applications, originally coded for
DOS/Windows, which require Windows style mandatory byte range
locking, they may be able to take advantage of this option,
forcing the cifs client to only send mandatory locks
even if the cifs server would support posix advisory locks.
- "forcemand" is accepted as a shorter form of this mount
+ ``forcemand`` is accepted as a shorter form of this mount
option.
- nostrictsync If this mount option is set, when an application does an
+ nostrictsync
+ If this mount option is set, when an application does an
fsync call then the cifs client does not send an SMB Flush
to the server (to force the server to write all dirty data
for this file immediately to disk), although cifs still sends
@@ -522,41 +607,50 @@ A partial list of the supported mount options follows:
crash. If this mount option is not set, by default cifs will
send an SMB flush request (and wait for a response) on every
fsync call.
- nodfs Disable DFS (global name space support) even if the
+ nodfs
+ Disable DFS (global name space support) even if the
server claims to support it. This can help work around
a problem with parsing of DFS paths with Samba server
versions 3.0.24 and 3.0.25.
- remount remount the share (often used to change from ro to rw mounts
- or vice versa)
- cifsacl Report mode bits (e.g. on stat) based on the Windows ACL for
- the file. (EXPERIMENTAL)
- servern Specify the server 's netbios name (RFC1001 name) to use
- when attempting to setup a session to the server.
+ remount
+ remount the share (often used to change from ro to rw mounts
+ or vice versa)
+ cifsacl
+ Report mode bits (e.g. on stat) based on the Windows ACL for
+ the file. (EXPERIMENTAL)
+ servern
+ Specify the server 's netbios name (RFC1001 name) to use
+ when attempting to setup a session to the server.
This is needed for mounting to some older servers (such
as OS/2 or Windows 98 and Windows ME) since they do not
support a default server name. A server name can be up
to 15 characters long and is usually uppercased.
- sfu When the CIFS Unix Extensions are not negotiated, attempt to
+ sfu
+ When the CIFS Unix Extensions are not negotiated, attempt to
create device files and fifos in a format compatible with
Services for Unix (SFU). In addition retrieve bits 10-12
of the mode via the SETFILEBITS extended attribute (as
SFU does). In the future the bottom 9 bits of the
mode also will be emulated using queries of the security
descriptor (ACL).
- mfsymlinks Enable support for Minshall+French symlinks
+ mfsymlinks
+ Enable support for Minshall+French symlinks
(see http://wiki.samba.org/index.php/UNIX_Extensions#Minshall.2BFrench_symlinks)
This option is ignored when specified together with the
'sfu' option. Minshall+French symlinks are used even if
the server supports the CIFS Unix Extensions.
- sign Must use packet signing (helps avoid unwanted data modification
+ sign
+ Must use packet signing (helps avoid unwanted data modification
by intermediate systems in the route). Note that signing
does not work with lanman or plaintext authentication.
- seal Must seal (encrypt) all data on this mounted share before
+ seal
+ Must seal (encrypt) all data on this mounted share before
sending on the network. Requires support for Unix Extensions.
Note that this differs from the sign mount option in that it
causes encryption of data sent over this mounted share but other
shares mounted to the same server are unaffected.
- locallease This option is rarely needed. Fcntl F_SETLEASE is
+ locallease
+ This option is rarely needed. Fcntl F_SETLEASE is
used by some applications such as Samba and NFSv4 server to
check to see whether a file is cacheable. CIFS has no way
to explicitly request a lease, but can check whether a file
@@ -569,51 +663,73 @@ A partial list of the supported mount options follows:
will allow the cifs client to check for leases (only) locally
for files which are not oplocked instead of denying leases
in that case. (EXPERIMENTAL)
- sec Security mode. Allowed values are:
- none attempt to connection as a null user (no name)
- krb5 Use Kerberos version 5 authentication
- krb5i Use Kerberos authentication and packet signing
- ntlm Use NTLM password hashing (default)
- ntlmi Use NTLM password hashing with signing (if
+ sec
+ Security mode. Allowed values are:
+
+ none
+ attempt to connection as a null user (no name)
+ krb5
+ Use Kerberos version 5 authentication
+ krb5i
+ Use Kerberos authentication and packet signing
+ ntlm
+ Use NTLM password hashing (default)
+ ntlmi
+ Use NTLM password hashing with signing (if
/proc/fs/cifs/PacketSigningEnabled on or if
- server requires signing also can be the default)
- ntlmv2 Use NTLMv2 password hashing
- ntlmv2i Use NTLMv2 password hashing with packet signing
- lanman (if configured in kernel config) use older
+ server requires signing also can be the default)
+ ntlmv2
+ Use NTLMv2 password hashing
+ ntlmv2i
+ Use NTLMv2 password hashing with packet signing
+ lanman
+ (if configured in kernel config) use older
lanman hash
-hard Retry file operations if server is not responding
-soft Limit retries to unresponsive servers (usually only
+ hard
+ Retry file operations if server is not responding
+ soft
+ Limit retries to unresponsive servers (usually only
one retry) before returning an error. (default)
The mount.cifs mount helper also accepts a few mount options before -o
including:
+=============== ===============================================================
-S take password from stdin (equivalent to setting the environment
- variable "PASSWD_FD=0"
+ variable ``PASSWD_FD=0``
-V print mount.cifs version
-? display simple usage information
+=============== ===============================================================
With most 2.6 kernel versions of modutils, the version of the cifs kernel
module can be displayed via modinfo.
Misc /proc/fs/cifs Flags and Debug Info
=======================================
+
Informational pseudo-files:
+
+======================= =======================================================
DebugData Displays information about active CIFS sessions and
shares, features enabled as well as the cifs.ko
version.
Stats Lists summary resource usage information as well as per
share statistics.
+======================= =======================================================
Configuration pseudo-files:
+
+======================= =======================================================
SecurityFlags Flags which control security negotiation and
also packet signing. Authentication (may/must)
flags (e.g. for NTLM and/or NTLMv2) may be combined with
the signing flags. Specifying two different password
- hashing mechanisms (as "must use") on the other hand
- does not make much sense. Default flags are
- 0x07007
- (NTLM, NTLMv2 and packet signing allowed). The maximum
+ hashing mechanisms (as "must use") on the other hand
+ does not make much sense. Default flags are::
+
+ 0x07007
+
+ (NTLM, NTLMv2 and packet signing allowed). The maximum
allowable flags if you want to allow mounts to servers
using weaker password hashes is 0x37037 (lanman,
plaintext, ntlm, ntlmv2, signing allowed). Some
@@ -626,21 +742,21 @@ SecurityFlags Flags which control security negotiation and
laintext passwords using the older lanman dialect
form of the session setup SMB. (e.g. for authentication
using plain text passwords, set the SecurityFlags
- to 0x30030):
-
- may use packet signing 0x00001
- must use packet signing 0x01001
- may use NTLM (most common password hash) 0x00002
- must use NTLM 0x02002
- may use NTLMv2 0x00004
- must use NTLMv2 0x04004
- may use Kerberos security 0x00008
- must use Kerberos 0x08008
- may use lanman (weak) password hash 0x00010
- must use lanman password hash 0x10010
- may use plaintext passwords 0x00020
- must use plaintext passwords 0x20020
- (reserved for future packet encryption) 0x00040
+ to 0x30030)::
+
+ may use packet signing 0x00001
+ must use packet signing 0x01001
+ may use NTLM (most common password hash) 0x00002
+ must use NTLM 0x02002
+ may use NTLMv2 0x00004
+ must use NTLMv2 0x04004
+ may use Kerberos security 0x00008
+ must use Kerberos 0x08008
+ may use lanman (weak) password hash 0x00010
+ must use lanman password hash 0x10010
+ may use plaintext passwords 0x00020
+ must use plaintext passwords 0x20020
+ (reserved for future packet encryption) 0x00040
cifsFYI If set to non-zero value, additional debug information
will be logged to the system error log. This field
@@ -650,14 +766,19 @@ cifsFYI If set to non-zero value, additional debug information
Some debugging statements are not compiled into the
cifs kernel unless CONFIG_CIFS_DEBUG2 is enabled in the
kernel configuration. cifsFYI may be set to one or
- nore of the following flags (7 sets them all):
+ nore of the following flags (7 sets them all)::
+
+ +-----------------------------------------------+------+
+ | log cifs informational messages | 0x01 |
+ +-----------------------------------------------+------+
+ | log return codes from cifs entry points | 0x02 |
+ +-----------------------------------------------+------+
+ | log slow responses | 0x04 |
+ | (ie which take longer than 1 second) | |
+ | | |
+ | CONFIG_CIFS_STATS2 must be enabled in .config | |
+ +-----------------------------------------------+------+
- log cifs informational messages 0x01
- log return codes from cifs entry points 0x02
- log slow responses (ie which take longer than 1 second)
- CONFIG_CIFS_STATS2 must be enabled in .config 0x04
-
-
traceSMB If set to one, debug information is logged to the
system error log with the start of smb requests
and responses (default 0)
@@ -671,24 +792,25 @@ LinuxExtensionsEnabled If set to one then the client will attempt to
as support symbolic links. If you use servers
such as Samba that support the CIFS Unix
extensions but do not want to use symbolic link
- support and want to map the uid and gid fields
- to values supplied at mount (rather than the
+ support and want to map the uid and gid fields
+ to values supplied at mount (rather than the
actual values, then set this to zero. (default 1)
+======================= =======================================================
-These experimental features and tracing can be enabled by changing flags in
-/proc/fs/cifs (after the cifs module has been installed or built into the
-kernel, e.g. insmod cifs). To enable a feature set it to 1 e.g. to enable
-tracing to the kernel message log type:
+These experimental features and tracing can be enabled by changing flags in
+/proc/fs/cifs (after the cifs module has been installed or built into the
+kernel, e.g. insmod cifs). To enable a feature set it to 1 e.g. to enable
+tracing to the kernel message log type::
echo 7 > /proc/fs/cifs/cifsFYI
-
+
cifsFYI functions as a bit mask. Setting it to 1 enables additional kernel
logging of various informational messages. 2 enables logging of non-zero
SMB return codes while 4 enables logging of requests that take longer
-than one second to complete (except for byte range lock requests).
+than one second to complete (except for byte range lock requests).
Setting it to 4 requires CONFIG_CIFS_STATS2 to be set in kernel configuration
(.config). Setting it to seven enables all three. Finally, tracing
-the start of smb requests and responses can be enabled via:
+the start of smb requests and responses can be enabled via::
echo 1 > /proc/fs/cifs/traceSMB
@@ -700,10 +822,10 @@ server) SMB3 (or cifs) requests grouped by request type (read, write, close etc.
Also recorded is the total bytes read and bytes written to the server for
that share. Note that due to client caching effects this can be less than the
number of bytes read and written by the application running on the client.
-Statistics can be reset to zero by "echo 0 > /proc/fs/cifs/Stats" which may be
+Statistics can be reset to zero by ``echo 0 > /proc/fs/cifs/Stats`` which may be
useful if comparing performance of two different scenarios.
-
-Also note that "cat /proc/fs/cifs/DebugData" will display information about
+
+Also note that ``cat /proc/fs/cifs/DebugData`` will display information about
the active sessions and the shares that are mounted.
Enabling Kerberos (extended security) works but requires version 1.2 or later
@@ -725,19 +847,23 @@ space to ease network configuration and improve reliability.
To use cifs Kerberos and DFS support, the Linux keyutils package should be
installed and something like the following lines should be added to the
-/etc/request-key.conf file:
+/etc/request-key.conf file::
-create cifs.spnego * * /usr/local/sbin/cifs.upcall %k
-create dns_resolver * * /usr/local/sbin/cifs.upcall %k
+ create cifs.spnego * * /usr/local/sbin/cifs.upcall %k
+ create dns_resolver * * /usr/local/sbin/cifs.upcall %k
CIFS kernel module parameters
=============================
These module parameters can be specified or modified either during the time of
-module loading or during the runtime by using the interface
+module loading or during the runtime by using the interface::
+
/proc/module/cifs/parameters/<param>
-i.e. echo "value" > /sys/module/cifs/parameters/<param>
+i.e.::
-1. enable_oplocks - Enable or disable oplocks. Oplocks are enabled by default.
- [Y/y/1]. To disable use any of [N/n/0].
+ echo "value" > /sys/module/cifs/parameters/<param>
+================= ==========================================================
+1. enable_oplocks Enable or disable oplocks. Oplocks are enabled by default.
+ [Y/y/1]. To disable use any of [N/n/0].
+================= ==========================================================
diff --git a/Documentation/filesystems/cifs/winucase_convert.pl b/Documentation/admin-guide/cifs/winucase_convert.pl
similarity index 100%
rename from Documentation/filesystems/cifs/winucase_convert.pl
rename to Documentation/admin-guide/cifs/winucase_convert.pl
diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
index 3f8f7d564552..4a9de9806eaf 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -80,6 +80,7 @@ configure specific aspects of kernel behavior to your liking.
blockdev/index
ext4
binderfs
+ cifs/index
xfs
pm/index
thunderbolt
diff --git a/MAINTAINERS b/MAINTAINERS
index 4cd39259fcdc..c8c09d4062a1 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -4099,7 +4099,7 @@ L: samba-technical@lists.samba.org (moderated for non-subscribers)
W: http://linux-cifs.samba.org/
T: git git://git.samba.org/sfrench/cifs-2.6.git
S: Supported
-F: Documentation/filesystems/cifs/
+F: Documentation/admin-guide/cifs/
F: fs/cifs/
COMPACTPCI HOTPLUG CORE
--
2.21.0
^ permalink raw reply related
* [PATCH 14/22] docs: fs: convert porting to ReST
From: Mauro Carvalho Chehab @ 2019-07-22 11:07 UTC (permalink / raw)
Cc: Mauro Carvalho Chehab, Jonathan Corbet, Mike Marshall,
Martin Brandenburg, linux-doc, devel
In-Reply-To: <cover.1563792333.git.mchehab+samsung@kernel.org>
This file has its own proper style, except that, after a while,
the coding style gets violated and whitespaces are placed on
different ways.
As Sphinx and ReST are very sentitive to whitespace differences,
I had to opt if each entry after required/mandatory/... fields
should start with zero spaces or with a tab. I opted to start them
all from the zero position, in order to avoid needing to break lines
with more than 80 columns, with would make harder for review.
Most of the other changes at porting.rst were made to use an unified
notation with works nice as a text file while also produce a good html
output after being parsed.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/filesystems/index.rst | 2 +
Documentation/filesystems/porting | 686 ---------------------
Documentation/filesystems/porting.rst | 852 ++++++++++++++++++++++++++
fs/orangefs/orangefs-kernel.h | 2 +-
4 files changed, 855 insertions(+), 687 deletions(-)
delete mode 100644 Documentation/filesystems/porting
create mode 100644 Documentation/filesystems/porting.rst
diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst
index 08320c35d03b..96653ebefd7e 100644
--- a/Documentation/filesystems/index.rst
+++ b/Documentation/filesystems/index.rst
@@ -23,6 +23,8 @@ algorithms work.
locking
directory-locking
+ porting
+
Filesystem support layers
=========================
diff --git a/Documentation/filesystems/porting b/Documentation/filesystems/porting
deleted file mode 100644
index 6b7a41cfcaed..000000000000
--- a/Documentation/filesystems/porting
+++ /dev/null
@@ -1,686 +0,0 @@
-Changes since 2.5.0:
-
----
-[recommended]
-
-New helpers: sb_bread(), sb_getblk(), sb_find_get_block(), set_bh(),
- sb_set_blocksize() and sb_min_blocksize().
-
-Use them.
-
-(sb_find_get_block() replaces 2.4's get_hash_table())
-
----
-[recommended]
-
-New methods: ->alloc_inode() and ->destroy_inode().
-
-Remove inode->u.foo_inode_i
-Declare
- struct foo_inode_info {
- /* fs-private stuff */
- struct inode vfs_inode;
- };
- static inline struct foo_inode_info *FOO_I(struct inode *inode)
- {
- return list_entry(inode, struct foo_inode_info, vfs_inode);
- }
-
-Use FOO_I(inode) instead of &inode->u.foo_inode_i;
-
-Add foo_alloc_inode() and foo_destroy_inode() - the former should allocate
-foo_inode_info and return the address of ->vfs_inode, the latter should free
-FOO_I(inode) (see in-tree filesystems for examples).
-
-Make them ->alloc_inode and ->destroy_inode in your super_operations.
-
-Keep in mind that now you need explicit initialization of private data
-typically between calling iget_locked() and unlocking the inode.
-
-At some point that will become mandatory.
-
----
-[mandatory]
-
-Change of file_system_type method (->read_super to ->get_sb)
-
-->read_super() is no more. Ditto for DECLARE_FSTYPE and DECLARE_FSTYPE_DEV.
-
-Turn your foo_read_super() into a function that would return 0 in case of
-success and negative number in case of error (-EINVAL unless you have more
-informative error value to report). Call it foo_fill_super(). Now declare
-
-int foo_get_sb(struct file_system_type *fs_type,
- int flags, const char *dev_name, void *data, struct vfsmount *mnt)
-{
- return get_sb_bdev(fs_type, flags, dev_name, data, foo_fill_super,
- mnt);
-}
-
-(or similar with s/bdev/nodev/ or s/bdev/single/, depending on the kind of
-filesystem).
-
-Replace DECLARE_FSTYPE... with explicit initializer and have ->get_sb set as
-foo_get_sb.
-
----
-[mandatory]
-
-Locking change: ->s_vfs_rename_sem is taken only by cross-directory renames.
-Most likely there is no need to change anything, but if you relied on
-global exclusion between renames for some internal purpose - you need to
-change your internal locking. Otherwise exclusion warranties remain the
-same (i.e. parents and victim are locked, etc.).
-
----
-[informational]
-
-Now we have the exclusion between ->lookup() and directory removal (by
-->rmdir() and ->rename()). If you used to need that exclusion and do
-it by internal locking (most of filesystems couldn't care less) - you
-can relax your locking.
-
----
-[mandatory]
-
-->lookup(), ->truncate(), ->create(), ->unlink(), ->mknod(), ->mkdir(),
-->rmdir(), ->link(), ->lseek(), ->symlink(), ->rename()
-and ->readdir() are called without BKL now. Grab it on entry, drop upon return
-- that will guarantee the same locking you used to have. If your method or its
-parts do not need BKL - better yet, now you can shift lock_kernel() and
-unlock_kernel() so that they would protect exactly what needs to be
-protected.
-
----
-[mandatory]
-
-BKL is also moved from around sb operations. BKL should have been shifted into
-individual fs sb_op functions. If you don't need it, remove it.
-
----
-[informational]
-
-check for ->link() target not being a directory is done by callers. Feel
-free to drop it...
-
----
-[informational]
-
-->link() callers hold ->i_mutex on the object we are linking to. Some of your
-problems might be over...
-
----
-[mandatory]
-
-new file_system_type method - kill_sb(superblock). If you are converting
-an existing filesystem, set it according to ->fs_flags:
- FS_REQUIRES_DEV - kill_block_super
- FS_LITTER - kill_litter_super
- neither - kill_anon_super
-FS_LITTER is gone - just remove it from fs_flags.
-
----
-[mandatory]
-
- FS_SINGLE is gone (actually, that had happened back when ->get_sb()
-went in - and hadn't been documented ;-/). Just remove it from fs_flags
-(and see ->get_sb() entry for other actions).
-
----
-[mandatory]
-
-->setattr() is called without BKL now. Caller _always_ holds ->i_mutex, so
-watch for ->i_mutex-grabbing code that might be used by your ->setattr().
-Callers of notify_change() need ->i_mutex now.
-
----
-[recommended]
-
-New super_block field "struct export_operations *s_export_op" for
-explicit support for exporting, e.g. via NFS. The structure is fully
-documented at its declaration in include/linux/fs.h, and in
-Documentation/filesystems/nfs/Exporting.
-
-Briefly it allows for the definition of decode_fh and encode_fh operations
-to encode and decode filehandles, and allows the filesystem to use
-a standard helper function for decode_fh, and provide file-system specific
-support for this helper, particularly get_parent.
-
-It is planned that this will be required for exporting once the code
-settles down a bit.
-
-[mandatory]
-
-s_export_op is now required for exporting a filesystem.
-isofs, ext2, ext3, resierfs, fat
-can be used as examples of very different filesystems.
-
----
-[mandatory]
-
-iget4() and the read_inode2 callback have been superseded by iget5_locked()
-which has the following prototype,
-
- struct inode *iget5_locked(struct super_block *sb, unsigned long ino,
- int (*test)(struct inode *, void *),
- int (*set)(struct inode *, void *),
- void *data);
-
-'test' is an additional function that can be used when the inode
-number is not sufficient to identify the actual file object. 'set'
-should be a non-blocking function that initializes those parts of a
-newly created inode to allow the test function to succeed. 'data' is
-passed as an opaque value to both test and set functions.
-
-When the inode has been created by iget5_locked(), it will be returned with the
-I_NEW flag set and will still be locked. The filesystem then needs to finalize
-the initialization. Once the inode is initialized it must be unlocked by
-calling unlock_new_inode().
-
-The filesystem is responsible for setting (and possibly testing) i_ino
-when appropriate. There is also a simpler iget_locked function that
-just takes the superblock and inode number as arguments and does the
-test and set for you.
-
-e.g.
- inode = iget_locked(sb, ino);
- if (inode->i_state & I_NEW) {
- err = read_inode_from_disk(inode);
- if (err < 0) {
- iget_failed(inode);
- return err;
- }
- unlock_new_inode(inode);
- }
-
-Note that if the process of setting up a new inode fails, then iget_failed()
-should be called on the inode to render it dead, and an appropriate error
-should be passed back to the caller.
-
----
-[recommended]
-
-->getattr() finally getting used. See instances in nfs, minix, etc.
-
----
-[mandatory]
-
-->revalidate() is gone. If your filesystem had it - provide ->getattr()
-and let it call whatever you had as ->revlidate() + (for symlinks that
-had ->revalidate()) add calls in ->follow_link()/->readlink().
-
----
-[mandatory]
-
-->d_parent changes are not protected by BKL anymore. Read access is safe
-if at least one of the following is true:
- * filesystem has no cross-directory rename()
- * we know that parent had been locked (e.g. we are looking at
-->d_parent of ->lookup() argument).
- * we are called from ->rename().
- * the child's ->d_lock is held
-Audit your code and add locking if needed. Notice that any place that is
-not protected by the conditions above is risky even in the old tree - you
-had been relying on BKL and that's prone to screwups. Old tree had quite
-a few holes of that kind - unprotected access to ->d_parent leading to
-anything from oops to silent memory corruption.
-
----
-[mandatory]
-
- FS_NOMOUNT is gone. If you use it - just set SB_NOUSER in flags
-(see rootfs for one kind of solution and bdev/socket/pipe for another).
-
----
-[recommended]
-
- Use bdev_read_only(bdev) instead of is_read_only(kdev). The latter
-is still alive, but only because of the mess in drivers/s390/block/dasd.c.
-As soon as it gets fixed is_read_only() will die.
-
----
-[mandatory]
-
-->permission() is called without BKL now. Grab it on entry, drop upon
-return - that will guarantee the same locking you used to have. If
-your method or its parts do not need BKL - better yet, now you can
-shift lock_kernel() and unlock_kernel() so that they would protect
-exactly what needs to be protected.
-
----
-[mandatory]
-
-->statfs() is now called without BKL held. BKL should have been
-shifted into individual fs sb_op functions where it's not clear that
-it's safe to remove it. If you don't need it, remove it.
-
----
-[mandatory]
-
- is_read_only() is gone; use bdev_read_only() instead.
-
----
-[mandatory]
-
- destroy_buffers() is gone; use invalidate_bdev().
-
----
-[mandatory]
-
- fsync_dev() is gone; use fsync_bdev(). NOTE: lvm breakage is
-deliberate; as soon as struct block_device * is propagated in a reasonable
-way by that code fixing will become trivial; until then nothing can be
-done.
-
-[mandatory]
-
- block truncatation on error exit from ->write_begin, and ->direct_IO
-moved from generic methods (block_write_begin, cont_write_begin,
-nobh_write_begin, blockdev_direct_IO*) to callers. Take a look at
-ext2_write_failed and callers for an example.
-
-[mandatory]
-
- ->truncate is gone. The whole truncate sequence needs to be
-implemented in ->setattr, which is now mandatory for filesystems
-implementing on-disk size changes. Start with a copy of the old inode_setattr
-and vmtruncate, and the reorder the vmtruncate + foofs_vmtruncate sequence to
-be in order of zeroing blocks using block_truncate_page or similar helpers,
-size update and on finally on-disk truncation which should not fail.
-setattr_prepare (which used to be inode_change_ok) now includes the size checks
-for ATTR_SIZE and must be called in the beginning of ->setattr unconditionally.
-
-[mandatory]
-
- ->clear_inode() and ->delete_inode() are gone; ->evict_inode() should
-be used instead. It gets called whenever the inode is evicted, whether it has
-remaining links or not. Caller does *not* evict the pagecache or inode-associated
-metadata buffers; the method has to use truncate_inode_pages_final() to get rid
-of those. Caller makes sure async writeback cannot be running for the inode while
-(or after) ->evict_inode() is called.
-
- ->drop_inode() returns int now; it's called on final iput() with
-inode->i_lock held and it returns true if filesystems wants the inode to be
-dropped. As before, generic_drop_inode() is still the default and it's been
-updated appropriately. generic_delete_inode() is also alive and it consists
-simply of return 1. Note that all actual eviction work is done by caller after
-->drop_inode() returns.
-
- As before, clear_inode() must be called exactly once on each call of
-->evict_inode() (as it used to be for each call of ->delete_inode()). Unlike
-before, if you are using inode-associated metadata buffers (i.e.
-mark_buffer_dirty_inode()), it's your responsibility to call
-invalidate_inode_buffers() before clear_inode().
-
- NOTE: checking i_nlink in the beginning of ->write_inode() and bailing out
-if it's zero is not *and* *never* *had* *been* enough. Final unlink() and iput()
-may happen while the inode is in the middle of ->write_inode(); e.g. if you blindly
-free the on-disk inode, you may end up doing that while ->write_inode() is writing
-to it.
-
----
-[mandatory]
-
- .d_delete() now only advises the dcache as to whether or not to cache
-unreferenced dentries, and is now only called when the dentry refcount goes to
-0. Even on 0 refcount transition, it must be able to tolerate being called 0,
-1, or more times (eg. constant, idempotent).
-
----
-[mandatory]
-
- .d_compare() calling convention and locking rules are significantly
-changed. Read updated documentation in Documentation/filesystems/vfs.rst (and
-look at examples of other filesystems) for guidance.
-
----
-[mandatory]
-
- .d_hash() calling convention and locking rules are significantly
-changed. Read updated documentation in Documentation/filesystems/vfs.rst (and
-look at examples of other filesystems) for guidance.
-
----
-[mandatory]
- dcache_lock is gone, replaced by fine grained locks. See fs/dcache.c
-for details of what locks to replace dcache_lock with in order to protect
-particular things. Most of the time, a filesystem only needs ->d_lock, which
-protects *all* the dcache state of a given dentry.
-
---
-[mandatory]
-
- Filesystems must RCU-free their inodes, if they can have been accessed
-via rcu-walk path walk (basically, if the file can have had a path name in the
-vfs namespace).
-
- Even though i_dentry and i_rcu share storage in a union, we will
-initialize the former in inode_init_always(), so just leave it alone in
-the callback. It used to be necessary to clean it there, but not anymore
-(starting at 3.2).
-
---
-[recommended]
- vfs now tries to do path walking in "rcu-walk mode", which avoids
-atomic operations and scalability hazards on dentries and inodes (see
-Documentation/filesystems/path-lookup.txt). d_hash and d_compare changes
-(above) are examples of the changes required to support this. For more complex
-filesystem callbacks, the vfs drops out of rcu-walk mode before the fs call, so
-no changes are required to the filesystem. However, this is costly and loses
-the benefits of rcu-walk mode. We will begin to add filesystem callbacks that
-are rcu-walk aware, shown below. Filesystems should take advantage of this
-where possible.
-
---
-[mandatory]
- d_revalidate is a callback that is made on every path element (if
-the filesystem provides it), which requires dropping out of rcu-walk mode. This
-may now be called in rcu-walk mode (nd->flags & LOOKUP_RCU). -ECHILD should be
-returned if the filesystem cannot handle rcu-walk. See
-Documentation/filesystems/vfs.rst for more details.
-
- permission is an inode permission check that is called on many or all
-directory inodes on the way down a path walk (to check for exec permission). It
-must now be rcu-walk aware (mask & MAY_NOT_BLOCK). See
-Documentation/filesystems/vfs.rst for more details.
-
---
-[mandatory]
- In ->fallocate() you must check the mode option passed in. If your
-filesystem does not support hole punching (deallocating space in the middle of a
-file) you must return -EOPNOTSUPP if FALLOC_FL_PUNCH_HOLE is set in mode.
-Currently you can only have FALLOC_FL_PUNCH_HOLE with FALLOC_FL_KEEP_SIZE set,
-so the i_size should not change when hole punching, even when puching the end of
-a file off.
-
---
-[mandatory]
- ->get_sb() is gone. Switch to use of ->mount(). Typically it's just
-a matter of switching from calling get_sb_... to mount_... and changing the
-function type. If you were doing it manually, just switch from setting ->mnt_root
-to some pointer to returning that pointer. On errors return ERR_PTR(...).
-
---
-[mandatory]
- ->permission() and generic_permission()have lost flags
-argument; instead of passing IPERM_FLAG_RCU we add MAY_NOT_BLOCK into mask.
- generic_permission() has also lost the check_acl argument; ACL checking
-has been taken to VFS and filesystems need to provide a non-NULL ->i_op->get_acl
-to read an ACL from disk.
-
---
-[mandatory]
- If you implement your own ->llseek() you must handle SEEK_HOLE and
-SEEK_DATA. You can hanle this by returning -EINVAL, but it would be nicer to
-support it in some way. The generic handler assumes that the entire file is
-data and there is a virtual hole at the end of the file. So if the provided
-offset is less than i_size and SEEK_DATA is specified, return the same offset.
-If the above is true for the offset and you are given SEEK_HOLE, return the end
-of the file. If the offset is i_size or greater return -ENXIO in either case.
-
-[mandatory]
- If you have your own ->fsync() you must make sure to call
-filemap_write_and_wait_range() so that all dirty pages are synced out properly.
-You must also keep in mind that ->fsync() is not called with i_mutex held
-anymore, so if you require i_mutex locking you must make sure to take it and
-release it yourself.
-
---
-[mandatory]
- d_alloc_root() is gone, along with a lot of bugs caused by code
-misusing it. Replacement: d_make_root(inode). On success d_make_root(inode)
-allocates and returns a new dentry instantiated with the passed in inode.
-On failure NULL is returned and the passed in inode is dropped so the reference
-to inode is consumed in all cases and failure handling need not do any cleanup
-for the inode. If d_make_root(inode) is passed a NULL inode it returns NULL
-and also requires no further error handling. Typical usage is:
-
- inode = foofs_new_inode(....);
- s->s_root = d_make_root(inode);
- if (!s->s_root)
- /* Nothing needed for the inode cleanup */
- return -ENOMEM;
- ...
-
---
-[mandatory]
- The witch is dead! Well, 2/3 of it, anyway. ->d_revalidate() and
-->lookup() do *not* take struct nameidata anymore; just the flags.
---
-[mandatory]
- ->create() doesn't take struct nameidata *; unlike the previous
-two, it gets "is it an O_EXCL or equivalent?" boolean argument. Note that
-local filesystems can ignore tha argument - they are guaranteed that the
-object doesn't exist. It's remote/distributed ones that might care...
---
-[mandatory]
- FS_REVAL_DOT is gone; if you used to have it, add ->d_weak_revalidate()
-in your dentry operations instead.
---
-[mandatory]
- vfs_readdir() is gone; switch to iterate_dir() instead
---
-[mandatory]
- ->readdir() is gone now; switch to ->iterate()
-[mandatory]
- vfs_follow_link has been removed. Filesystems must use nd_set_link
- from ->follow_link for normal symlinks, or nd_jump_link for magic
- /proc/<pid> style links.
---
-[mandatory]
- iget5_locked()/ilookup5()/ilookup5_nowait() test() callback used to be
- called with both ->i_lock and inode_hash_lock held; the former is *not*
- taken anymore, so verify that your callbacks do not rely on it (none
- of the in-tree instances did). inode_hash_lock is still held,
- of course, so they are still serialized wrt removal from inode hash,
- as well as wrt set() callback of iget5_locked().
---
-[mandatory]
- d_materialise_unique() is gone; d_splice_alias() does everything you
- need now. Remember that they have opposite orders of arguments ;-/
---
-[mandatory]
- f_dentry is gone; use f_path.dentry, or, better yet, see if you can avoid
- it entirely.
---
-[mandatory]
- never call ->read() and ->write() directly; use __vfs_{read,write} or
- wrappers; instead of checking for ->write or ->read being NULL, look for
- FMODE_CAN_{WRITE,READ} in file->f_mode.
---
-[mandatory]
- do _not_ use new_sync_{read,write} for ->read/->write; leave it NULL
- instead.
---
-[mandatory]
- ->aio_read/->aio_write are gone. Use ->read_iter/->write_iter.
----
-[recommended]
- for embedded ("fast") symlinks just set inode->i_link to wherever the
- symlink body is and use simple_follow_link() as ->follow_link().
---
-[mandatory]
- calling conventions for ->follow_link() have changed. Instead of returning
- cookie and using nd_set_link() to store the body to traverse, we return
- the body to traverse and store the cookie using explicit void ** argument.
- nameidata isn't passed at all - nd_jump_link() doesn't need it and
- nd_[gs]et_link() is gone.
---
-[mandatory]
- calling conventions for ->put_link() have changed. It gets inode instead of
- dentry, it does not get nameidata at all and it gets called only when cookie
- is non-NULL. Note that link body isn't available anymore, so if you need it,
- store it as cookie.
---
-[mandatory]
- any symlink that might use page_follow_link_light/page_put_link() must
- have inode_nohighmem(inode) called before anything might start playing with
- its pagecache. No highmem pages should end up in the pagecache of such
- symlinks. That includes any preseeding that might be done during symlink
- creation. __page_symlink() will honour the mapping gfp flags, so once
- you've done inode_nohighmem() it's safe to use, but if you allocate and
- insert the page manually, make sure to use the right gfp flags.
---
-[mandatory]
- ->follow_link() is replaced with ->get_link(); same API, except that
- * ->get_link() gets inode as a separate argument
- * ->get_link() may be called in RCU mode - in that case NULL
- dentry is passed
---
-[mandatory]
- ->get_link() gets struct delayed_call *done now, and should do
- set_delayed_call() where it used to set *cookie.
- ->put_link() is gone - just give the destructor to set_delayed_call()
- in ->get_link().
---
-[mandatory]
- ->getxattr() and xattr_handler.get() get dentry and inode passed separately.
- dentry might be yet to be attached to inode, so do _not_ use its ->d_inode
- in the instances. Rationale: !@#!@# security_d_instantiate() needs to be
- called before we attach dentry to inode.
---
-[mandatory]
- symlinks are no longer the only inodes that do *not* have i_bdev/i_cdev/
- i_pipe/i_link union zeroed out at inode eviction. As the result, you can't
- assume that non-NULL value in ->i_nlink at ->destroy_inode() implies that
- it's a symlink. Checking ->i_mode is really needed now. In-tree we had
- to fix shmem_destroy_callback() that used to take that kind of shortcut;
- watch out, since that shortcut is no longer valid.
---
-[mandatory]
- ->i_mutex is replaced with ->i_rwsem now. inode_lock() et.al. work as
- they used to - they just take it exclusive. However, ->lookup() may be
- called with parent locked shared. Its instances must not
- * use d_instantiate) and d_rehash() separately - use d_add() or
- d_splice_alias() instead.
- * use d_rehash() alone - call d_add(new_dentry, NULL) instead.
- * in the unlikely case when (read-only) access to filesystem
- data structures needs exclusion for some reason, arrange it
- yourself. None of the in-tree filesystems needed that.
- * rely on ->d_parent and ->d_name not changing after dentry has
- been fed to d_add() or d_splice_alias(). Again, none of the
- in-tree instances relied upon that.
- We are guaranteed that lookups of the same name in the same directory
- will not happen in parallel ("same" in the sense of your ->d_compare()).
- Lookups on different names in the same directory can and do happen in
- parallel now.
---
-[recommended]
- ->iterate_shared() is added; it's a parallel variant of ->iterate().
- Exclusion on struct file level is still provided (as well as that
- between it and lseek on the same struct file), but if your directory
- has been opened several times, you can get these called in parallel.
- Exclusion between that method and all directory-modifying ones is
- still provided, of course.
-
- Often enough ->iterate() can serve as ->iterate_shared() without any
- changes - it is a read-only operation, after all. If you have any
- per-inode or per-dentry in-core data structures modified by ->iterate(),
- you might need something to serialize the access to them. If you
- do dcache pre-seeding, you'll need to switch to d_alloc_parallel() for
- that; look for in-tree examples.
-
- Old method is only used if the new one is absent; eventually it will
- be removed. Switch while you still can; the old one won't stay.
---
-[mandatory]
- ->atomic_open() calls without O_CREAT may happen in parallel.
---
-[mandatory]
- ->setxattr() and xattr_handler.set() get dentry and inode passed separately.
- dentry might be yet to be attached to inode, so do _not_ use its ->d_inode
- in the instances. Rationale: !@#!@# security_d_instantiate() needs to be
- called before we attach dentry to inode and !@#!@##!@$!$#!@#$!@$!@$ smack
- ->d_instantiate() uses not just ->getxattr() but ->setxattr() as well.
---
-[mandatory]
- ->d_compare() doesn't get parent as a separate argument anymore. If you
- used it for finding the struct super_block involved, dentry->d_sb will
- work just as well; if it's something more complicated, use dentry->d_parent.
- Just be careful not to assume that fetching it more than once will yield
- the same value - in RCU mode it could change under you.
---
-[mandatory]
- ->rename() has an added flags argument. Any flags not handled by the
- filesystem should result in EINVAL being returned.
---
-[recommended]
- ->readlink is optional for symlinks. Don't set, unless filesystem needs
- to fake something for readlink(2).
---
-[mandatory]
- ->getattr() is now passed a struct path rather than a vfsmount and
- dentry separately, and it now has request_mask and query_flags arguments
- to specify the fields and sync type requested by statx. Filesystems not
- supporting any statx-specific features may ignore the new arguments.
---
-[mandatory]
- ->atomic_open() calling conventions have changed. Gone is int *opened,
- along with FILE_OPENED/FILE_CREATED. In place of those we have
- FMODE_OPENED/FMODE_CREATED, set in file->f_mode. Additionally, return
- value for 'called finish_no_open(), open it yourself' case has become
- 0, not 1. Since finish_no_open() itself is returning 0 now, that part
- does not need any changes in ->atomic_open() instances.
---
-[mandatory]
- alloc_file() has become static now; two wrappers are to be used instead.
- alloc_file_pseudo(inode, vfsmount, name, flags, ops) is for the cases
- when dentry needs to be created; that's the majority of old alloc_file()
- users. Calling conventions: on success a reference to new struct file
- is returned and callers reference to inode is subsumed by that. On
- failure, ERR_PTR() is returned and no caller's references are affected,
- so the caller needs to drop the inode reference it held.
- alloc_file_clone(file, flags, ops) does not affect any caller's references.
- On success you get a new struct file sharing the mount/dentry with the
- original, on failure - ERR_PTR().
---
-[mandatory]
- ->clone_file_range() and ->dedupe_file_range have been replaced with
- ->remap_file_range(). See Documentation/filesystems/vfs.rst for more
- information.
---
-[recommended]
- ->lookup() instances doing an equivalent of
- if (IS_ERR(inode))
- return ERR_CAST(inode);
- return d_splice_alias(inode, dentry);
- don't need to bother with the check - d_splice_alias() will do the
- right thing when given ERR_PTR(...) as inode. Moreover, passing NULL
- inode to d_splice_alias() will also do the right thing (equivalent of
- d_add(dentry, NULL); return NULL;), so that kind of special cases
- also doesn't need a separate treatment.
---
-[strongly recommended]
- take the RCU-delayed parts of ->destroy_inode() into a new method -
- ->free_inode(). If ->destroy_inode() becomes empty - all the better,
- just get rid of it. Synchronous work (e.g. the stuff that can't
- be done from an RCU callback, or any WARN_ON() where we want the
- stack trace) *might* be movable to ->evict_inode(); however,
- that goes only for the things that are not needed to balance something
- done by ->alloc_inode(). IOW, if it's cleaning up the stuff that
- might have accumulated over the life of in-core inode, ->evict_inode()
- might be a fit.
-
- Rules for inode destruction:
- * if ->destroy_inode() is non-NULL, it gets called
- * if ->free_inode() is non-NULL, it gets scheduled by call_rcu()
- * combination of NULL ->destroy_inode and NULL ->free_inode is
- treated as NULL/free_inode_nonrcu, to preserve the compatibility.
-
- Note that the callback (be it via ->free_inode() or explicit call_rcu()
- in ->destroy_inode()) is *NOT* ordered wrt superblock destruction;
- as the matter of fact, the superblock and all associated structures
- might be already gone. The filesystem driver is guaranteed to be still
- there, but that's it. Freeing memory in the callback is fine; doing
- more than that is possible, but requires a lot of care and is best
- avoided.
---
-[mandatory]
- DCACHE_RCUACCESS is gone; having an RCU delay on dentry freeing is the
- default. DCACHE_NORCU opts out, and only d_alloc_pseudo() has any
- business doing so.
---
-[mandatory]
- d_alloc_pseudo() is internal-only; uses outside of alloc_file_pseudo() are
- very suspect (and won't work in modules). Such uses are very likely to
- be misspelled d_alloc_anon().
diff --git a/Documentation/filesystems/porting.rst b/Documentation/filesystems/porting.rst
new file mode 100644
index 000000000000..66aa521e6376
--- /dev/null
+++ b/Documentation/filesystems/porting.rst
@@ -0,0 +1,852 @@
+====================
+Changes since 2.5.0:
+====================
+
+---
+
+**recommended**
+
+New helpers: sb_bread(), sb_getblk(), sb_find_get_block(), set_bh(),
+sb_set_blocksize() and sb_min_blocksize().
+
+Use them.
+
+(sb_find_get_block() replaces 2.4's get_hash_table())
+
+---
+
+**recommended**
+
+New methods: ->alloc_inode() and ->destroy_inode().
+
+Remove inode->u.foo_inode_i
+
+Declare::
+
+ struct foo_inode_info {
+ /* fs-private stuff */
+ struct inode vfs_inode;
+ };
+ static inline struct foo_inode_info *FOO_I(struct inode *inode)
+ {
+ return list_entry(inode, struct foo_inode_info, vfs_inode);
+ }
+
+Use FOO_I(inode) instead of &inode->u.foo_inode_i;
+
+Add foo_alloc_inode() and foo_destroy_inode() - the former should allocate
+foo_inode_info and return the address of ->vfs_inode, the latter should free
+FOO_I(inode) (see in-tree filesystems for examples).
+
+Make them ->alloc_inode and ->destroy_inode in your super_operations.
+
+Keep in mind that now you need explicit initialization of private data
+typically between calling iget_locked() and unlocking the inode.
+
+At some point that will become mandatory.
+
+---
+
+**mandatory**
+
+Change of file_system_type method (->read_super to ->get_sb)
+
+->read_super() is no more. Ditto for DECLARE_FSTYPE and DECLARE_FSTYPE_DEV.
+
+Turn your foo_read_super() into a function that would return 0 in case of
+success and negative number in case of error (-EINVAL unless you have more
+informative error value to report). Call it foo_fill_super(). Now declare::
+
+ int foo_get_sb(struct file_system_type *fs_type,
+ int flags, const char *dev_name, void *data, struct vfsmount *mnt)
+ {
+ return get_sb_bdev(fs_type, flags, dev_name, data, foo_fill_super,
+ mnt);
+ }
+
+(or similar with s/bdev/nodev/ or s/bdev/single/, depending on the kind of
+filesystem).
+
+Replace DECLARE_FSTYPE... with explicit initializer and have ->get_sb set as
+foo_get_sb.
+
+---
+
+**mandatory**
+
+Locking change: ->s_vfs_rename_sem is taken only by cross-directory renames.
+Most likely there is no need to change anything, but if you relied on
+global exclusion between renames for some internal purpose - you need to
+change your internal locking. Otherwise exclusion warranties remain the
+same (i.e. parents and victim are locked, etc.).
+
+---
+
+**informational**
+
+Now we have the exclusion between ->lookup() and directory removal (by
+->rmdir() and ->rename()). If you used to need that exclusion and do
+it by internal locking (most of filesystems couldn't care less) - you
+can relax your locking.
+
+---
+
+**mandatory**
+
+->lookup(), ->truncate(), ->create(), ->unlink(), ->mknod(), ->mkdir(),
+->rmdir(), ->link(), ->lseek(), ->symlink(), ->rename()
+and ->readdir() are called without BKL now. Grab it on entry, drop upon return
+- that will guarantee the same locking you used to have. If your method or its
+parts do not need BKL - better yet, now you can shift lock_kernel() and
+unlock_kernel() so that they would protect exactly what needs to be
+protected.
+
+---
+
+**mandatory**
+
+BKL is also moved from around sb operations. BKL should have been shifted into
+individual fs sb_op functions. If you don't need it, remove it.
+
+---
+
+**informational**
+
+check for ->link() target not being a directory is done by callers. Feel
+free to drop it...
+
+---
+
+**informational**
+
+->link() callers hold ->i_mutex on the object we are linking to. Some of your
+problems might be over...
+
+---
+
+**mandatory**
+
+new file_system_type method - kill_sb(superblock). If you are converting
+an existing filesystem, set it according to ->fs_flags::
+
+ FS_REQUIRES_DEV - kill_block_super
+ FS_LITTER - kill_litter_super
+ neither - kill_anon_super
+
+FS_LITTER is gone - just remove it from fs_flags.
+
+---
+
+**mandatory**
+
+FS_SINGLE is gone (actually, that had happened back when ->get_sb()
+went in - and hadn't been documented ;-/). Just remove it from fs_flags
+(and see ->get_sb() entry for other actions).
+
+---
+
+**mandatory**
+
+->setattr() is called without BKL now. Caller _always_ holds ->i_mutex, so
+watch for ->i_mutex-grabbing code that might be used by your ->setattr().
+Callers of notify_change() need ->i_mutex now.
+
+---
+
+**recommended**
+
+New super_block field ``struct export_operations *s_export_op`` for
+explicit support for exporting, e.g. via NFS. The structure is fully
+documented at its declaration in include/linux/fs.h, and in
+Documentation/filesystems/nfs/Exporting.
+
+Briefly it allows for the definition of decode_fh and encode_fh operations
+to encode and decode filehandles, and allows the filesystem to use
+a standard helper function for decode_fh, and provide file-system specific
+support for this helper, particularly get_parent.
+
+It is planned that this will be required for exporting once the code
+settles down a bit.
+
+**mandatory**
+
+s_export_op is now required for exporting a filesystem.
+isofs, ext2, ext3, resierfs, fat
+can be used as examples of very different filesystems.
+
+---
+
+**mandatory**
+
+iget4() and the read_inode2 callback have been superseded by iget5_locked()
+which has the following prototype::
+
+ struct inode *iget5_locked(struct super_block *sb, unsigned long ino,
+ int (*test)(struct inode *, void *),
+ int (*set)(struct inode *, void *),
+ void *data);
+
+'test' is an additional function that can be used when the inode
+number is not sufficient to identify the actual file object. 'set'
+should be a non-blocking function that initializes those parts of a
+newly created inode to allow the test function to succeed. 'data' is
+passed as an opaque value to both test and set functions.
+
+When the inode has been created by iget5_locked(), it will be returned with the
+I_NEW flag set and will still be locked. The filesystem then needs to finalize
+the initialization. Once the inode is initialized it must be unlocked by
+calling unlock_new_inode().
+
+The filesystem is responsible for setting (and possibly testing) i_ino
+when appropriate. There is also a simpler iget_locked function that
+just takes the superblock and inode number as arguments and does the
+test and set for you.
+
+e.g.::
+
+ inode = iget_locked(sb, ino);
+ if (inode->i_state & I_NEW) {
+ err = read_inode_from_disk(inode);
+ if (err < 0) {
+ iget_failed(inode);
+ return err;
+ }
+ unlock_new_inode(inode);
+ }
+
+Note that if the process of setting up a new inode fails, then iget_failed()
+should be called on the inode to render it dead, and an appropriate error
+should be passed back to the caller.
+
+---
+
+**recommended**
+
+->getattr() finally getting used. See instances in nfs, minix, etc.
+
+---
+
+**mandatory**
+
+->revalidate() is gone. If your filesystem had it - provide ->getattr()
+and let it call whatever you had as ->revlidate() + (for symlinks that
+had ->revalidate()) add calls in ->follow_link()/->readlink().
+
+---
+
+**mandatory**
+
+->d_parent changes are not protected by BKL anymore. Read access is safe
+if at least one of the following is true:
+
+ * filesystem has no cross-directory rename()
+ * we know that parent had been locked (e.g. we are looking at
+ ->d_parent of ->lookup() argument).
+ * we are called from ->rename().
+ * the child's ->d_lock is held
+
+Audit your code and add locking if needed. Notice that any place that is
+not protected by the conditions above is risky even in the old tree - you
+had been relying on BKL and that's prone to screwups. Old tree had quite
+a few holes of that kind - unprotected access to ->d_parent leading to
+anything from oops to silent memory corruption.
+
+---
+
+**mandatory**
+
+FS_NOMOUNT is gone. If you use it - just set SB_NOUSER in flags
+(see rootfs for one kind of solution and bdev/socket/pipe for another).
+
+---
+
+**recommended**
+
+Use bdev_read_only(bdev) instead of is_read_only(kdev). The latter
+is still alive, but only because of the mess in drivers/s390/block/dasd.c.
+As soon as it gets fixed is_read_only() will die.
+
+---
+
+**mandatory**
+
+->permission() is called without BKL now. Grab it on entry, drop upon
+return - that will guarantee the same locking you used to have. If
+your method or its parts do not need BKL - better yet, now you can
+shift lock_kernel() and unlock_kernel() so that they would protect
+exactly what needs to be protected.
+
+---
+
+**mandatory**
+
+->statfs() is now called without BKL held. BKL should have been
+shifted into individual fs sb_op functions where it's not clear that
+it's safe to remove it. If you don't need it, remove it.
+
+---
+
+**mandatory**
+
+is_read_only() is gone; use bdev_read_only() instead.
+
+---
+
+**mandatory**
+
+destroy_buffers() is gone; use invalidate_bdev().
+
+---
+
+**mandatory**
+
+fsync_dev() is gone; use fsync_bdev(). NOTE: lvm breakage is
+deliberate; as soon as struct block_device * is propagated in a reasonable
+way by that code fixing will become trivial; until then nothing can be
+done.
+
+**mandatory**
+
+block truncatation on error exit from ->write_begin, and ->direct_IO
+moved from generic methods (block_write_begin, cont_write_begin,
+nobh_write_begin, blockdev_direct_IO*) to callers. Take a look at
+ext2_write_failed and callers for an example.
+
+**mandatory**
+
+->truncate is gone. The whole truncate sequence needs to be
+implemented in ->setattr, which is now mandatory for filesystems
+implementing on-disk size changes. Start with a copy of the old inode_setattr
+and vmtruncate, and the reorder the vmtruncate + foofs_vmtruncate sequence to
+be in order of zeroing blocks using block_truncate_page or similar helpers,
+size update and on finally on-disk truncation which should not fail.
+setattr_prepare (which used to be inode_change_ok) now includes the size checks
+for ATTR_SIZE and must be called in the beginning of ->setattr unconditionally.
+
+**mandatory**
+
+->clear_inode() and ->delete_inode() are gone; ->evict_inode() should
+be used instead. It gets called whenever the inode is evicted, whether it has
+remaining links or not. Caller does *not* evict the pagecache or inode-associated
+metadata buffers; the method has to use truncate_inode_pages_final() to get rid
+of those. Caller makes sure async writeback cannot be running for the inode while
+(or after) ->evict_inode() is called.
+
+->drop_inode() returns int now; it's called on final iput() with
+inode->i_lock held and it returns true if filesystems wants the inode to be
+dropped. As before, generic_drop_inode() is still the default and it's been
+updated appropriately. generic_delete_inode() is also alive and it consists
+simply of return 1. Note that all actual eviction work is done by caller after
+->drop_inode() returns.
+
+As before, clear_inode() must be called exactly once on each call of
+->evict_inode() (as it used to be for each call of ->delete_inode()). Unlike
+before, if you are using inode-associated metadata buffers (i.e.
+mark_buffer_dirty_inode()), it's your responsibility to call
+invalidate_inode_buffers() before clear_inode().
+
+NOTE: checking i_nlink in the beginning of ->write_inode() and bailing out
+if it's zero is not *and* *never* *had* *been* enough. Final unlink() and iput()
+may happen while the inode is in the middle of ->write_inode(); e.g. if you blindly
+free the on-disk inode, you may end up doing that while ->write_inode() is writing
+to it.
+
+---
+
+**mandatory**
+
+.d_delete() now only advises the dcache as to whether or not to cache
+unreferenced dentries, and is now only called when the dentry refcount goes to
+0. Even on 0 refcount transition, it must be able to tolerate being called 0,
+1, or more times (eg. constant, idempotent).
+
+---
+
+**mandatory**
+
+.d_compare() calling convention and locking rules are significantly
+changed. Read updated documentation in Documentation/filesystems/vfs.rst (and
+look at examples of other filesystems) for guidance.
+
+---
+
+**mandatory**
+
+.d_hash() calling convention and locking rules are significantly
+changed. Read updated documentation in Documentation/filesystems/vfs.rst (and
+look at examples of other filesystems) for guidance.
+
+---
+
+**mandatory**
+
+dcache_lock is gone, replaced by fine grained locks. See fs/dcache.c
+for details of what locks to replace dcache_lock with in order to protect
+particular things. Most of the time, a filesystem only needs ->d_lock, which
+protects *all* the dcache state of a given dentry.
+
+---
+
+**mandatory**
+
+Filesystems must RCU-free their inodes, if they can have been accessed
+via rcu-walk path walk (basically, if the file can have had a path name in the
+vfs namespace).
+
+Even though i_dentry and i_rcu share storage in a union, we will
+initialize the former in inode_init_always(), so just leave it alone in
+the callback. It used to be necessary to clean it there, but not anymore
+(starting at 3.2).
+
+---
+
+**recommended**
+
+vfs now tries to do path walking in "rcu-walk mode", which avoids
+atomic operations and scalability hazards on dentries and inodes (see
+Documentation/filesystems/path-lookup.txt). d_hash and d_compare changes
+(above) are examples of the changes required to support this. For more complex
+filesystem callbacks, the vfs drops out of rcu-walk mode before the fs call, so
+no changes are required to the filesystem. However, this is costly and loses
+the benefits of rcu-walk mode. We will begin to add filesystem callbacks that
+are rcu-walk aware, shown below. Filesystems should take advantage of this
+where possible.
+
+---
+
+**mandatory**
+
+d_revalidate is a callback that is made on every path element (if
+the filesystem provides it), which requires dropping out of rcu-walk mode. This
+may now be called in rcu-walk mode (nd->flags & LOOKUP_RCU). -ECHILD should be
+returned if the filesystem cannot handle rcu-walk. See
+Documentation/filesystems/vfs.rst for more details.
+
+permission is an inode permission check that is called on many or all
+directory inodes on the way down a path walk (to check for exec permission). It
+must now be rcu-walk aware (mask & MAY_NOT_BLOCK). See
+Documentation/filesystems/vfs.rst for more details.
+
+---
+
+**mandatory**
+
+In ->fallocate() you must check the mode option passed in. If your
+filesystem does not support hole punching (deallocating space in the middle of a
+file) you must return -EOPNOTSUPP if FALLOC_FL_PUNCH_HOLE is set in mode.
+Currently you can only have FALLOC_FL_PUNCH_HOLE with FALLOC_FL_KEEP_SIZE set,
+so the i_size should not change when hole punching, even when puching the end of
+a file off.
+
+---
+
+**mandatory**
+
+->get_sb() is gone. Switch to use of ->mount(). Typically it's just
+a matter of switching from calling ``get_sb_``... to ``mount_``... and changing
+the function type. If you were doing it manually, just switch from setting
+->mnt_root to some pointer to returning that pointer. On errors return
+ERR_PTR(...).
+
+---
+
+**mandatory**
+
+->permission() and generic_permission()have lost flags
+argument; instead of passing IPERM_FLAG_RCU we add MAY_NOT_BLOCK into mask.
+
+generic_permission() has also lost the check_acl argument; ACL checking
+has been taken to VFS and filesystems need to provide a non-NULL ->i_op->get_acl
+to read an ACL from disk.
+
+---
+
+**mandatory**
+
+If you implement your own ->llseek() you must handle SEEK_HOLE and
+SEEK_DATA. You can hanle this by returning -EINVAL, but it would be nicer to
+support it in some way. The generic handler assumes that the entire file is
+data and there is a virtual hole at the end of the file. So if the provided
+offset is less than i_size and SEEK_DATA is specified, return the same offset.
+If the above is true for the offset and you are given SEEK_HOLE, return the end
+of the file. If the offset is i_size or greater return -ENXIO in either case.
+
+**mandatory**
+
+If you have your own ->fsync() you must make sure to call
+filemap_write_and_wait_range() so that all dirty pages are synced out properly.
+You must also keep in mind that ->fsync() is not called with i_mutex held
+anymore, so if you require i_mutex locking you must make sure to take it and
+release it yourself.
+
+---
+
+**mandatory**
+
+d_alloc_root() is gone, along with a lot of bugs caused by code
+misusing it. Replacement: d_make_root(inode). On success d_make_root(inode)
+allocates and returns a new dentry instantiated with the passed in inode.
+On failure NULL is returned and the passed in inode is dropped so the reference
+to inode is consumed in all cases and failure handling need not do any cleanup
+for the inode. If d_make_root(inode) is passed a NULL inode it returns NULL
+and also requires no further error handling. Typical usage is::
+
+ inode = foofs_new_inode(....);
+ s->s_root = d_make_root(inode);
+ if (!s->s_root)
+ /* Nothing needed for the inode cleanup */
+ return -ENOMEM;
+ ...
+
+---
+
+**mandatory**
+
+The witch is dead! Well, 2/3 of it, anyway. ->d_revalidate() and
+->lookup() do *not* take struct nameidata anymore; just the flags.
+
+---
+
+**mandatory**
+
+->create() doesn't take ``struct nameidata *``; unlike the previous
+two, it gets "is it an O_EXCL or equivalent?" boolean argument. Note that
+local filesystems can ignore tha argument - they are guaranteed that the
+object doesn't exist. It's remote/distributed ones that might care...
+
+---
+
+**mandatory**
+
+FS_REVAL_DOT is gone; if you used to have it, add ->d_weak_revalidate()
+in your dentry operations instead.
+
+---
+
+**mandatory**
+
+vfs_readdir() is gone; switch to iterate_dir() instead
+
+---
+
+**mandatory**
+
+->readdir() is gone now; switch to ->iterate()
+
+**mandatory**
+
+vfs_follow_link has been removed. Filesystems must use nd_set_link
+from ->follow_link for normal symlinks, or nd_jump_link for magic
+/proc/<pid> style links.
+
+---
+
+**mandatory**
+
+iget5_locked()/ilookup5()/ilookup5_nowait() test() callback used to be
+called with both ->i_lock and inode_hash_lock held; the former is *not*
+taken anymore, so verify that your callbacks do not rely on it (none
+of the in-tree instances did). inode_hash_lock is still held,
+of course, so they are still serialized wrt removal from inode hash,
+as well as wrt set() callback of iget5_locked().
+
+---
+
+**mandatory**
+
+d_materialise_unique() is gone; d_splice_alias() does everything you
+need now. Remember that they have opposite orders of arguments ;-/
+
+---
+
+**mandatory**
+
+f_dentry is gone; use f_path.dentry, or, better yet, see if you can avoid
+it entirely.
+
+---
+
+**mandatory**
+
+never call ->read() and ->write() directly; use __vfs_{read,write} or
+wrappers; instead of checking for ->write or ->read being NULL, look for
+FMODE_CAN_{WRITE,READ} in file->f_mode.
+
+---
+
+**mandatory**
+
+do _not_ use new_sync_{read,write} for ->read/->write; leave it NULL
+instead.
+
+---
+
+**mandatory**
+ ->aio_read/->aio_write are gone. Use ->read_iter/->write_iter.
+
+---
+
+**recommended**
+
+for embedded ("fast") symlinks just set inode->i_link to wherever the
+symlink body is and use simple_follow_link() as ->follow_link().
+
+---
+
+**mandatory**
+
+calling conventions for ->follow_link() have changed. Instead of returning
+cookie and using nd_set_link() to store the body to traverse, we return
+the body to traverse and store the cookie using explicit void ** argument.
+nameidata isn't passed at all - nd_jump_link() doesn't need it and
+nd_[gs]et_link() is gone.
+
+---
+
+**mandatory**
+
+calling conventions for ->put_link() have changed. It gets inode instead of
+dentry, it does not get nameidata at all and it gets called only when cookie
+is non-NULL. Note that link body isn't available anymore, so if you need it,
+store it as cookie.
+
+---
+
+**mandatory**
+
+any symlink that might use page_follow_link_light/page_put_link() must
+have inode_nohighmem(inode) called before anything might start playing with
+its pagecache. No highmem pages should end up in the pagecache of such
+symlinks. That includes any preseeding that might be done during symlink
+creation. __page_symlink() will honour the mapping gfp flags, so once
+you've done inode_nohighmem() it's safe to use, but if you allocate and
+insert the page manually, make sure to use the right gfp flags.
+
+---
+
+**mandatory**
+
+->follow_link() is replaced with ->get_link(); same API, except that
+
+ * ->get_link() gets inode as a separate argument
+ * ->get_link() may be called in RCU mode - in that case NULL
+ dentry is passed
+
+---
+
+**mandatory**
+
+->get_link() gets struct delayed_call ``*done`` now, and should do
+set_delayed_call() where it used to set ``*cookie``.
+
+->put_link() is gone - just give the destructor to set_delayed_call()
+in ->get_link().
+
+---
+
+**mandatory**
+
+->getxattr() and xattr_handler.get() get dentry and inode passed separately.
+dentry might be yet to be attached to inode, so do _not_ use its ->d_inode
+in the instances. Rationale: !@#!@# security_d_instantiate() needs to be
+called before we attach dentry to inode.
+
+---
+
+**mandatory**
+
+symlinks are no longer the only inodes that do *not* have i_bdev/i_cdev/
+i_pipe/i_link union zeroed out at inode eviction. As the result, you can't
+assume that non-NULL value in ->i_nlink at ->destroy_inode() implies that
+it's a symlink. Checking ->i_mode is really needed now. In-tree we had
+to fix shmem_destroy_callback() that used to take that kind of shortcut;
+watch out, since that shortcut is no longer valid.
+
+---
+
+**mandatory**
+
+->i_mutex is replaced with ->i_rwsem now. inode_lock() et.al. work as
+they used to - they just take it exclusive. However, ->lookup() may be
+called with parent locked shared. Its instances must not
+
+ * use d_instantiate) and d_rehash() separately - use d_add() or
+ d_splice_alias() instead.
+ * use d_rehash() alone - call d_add(new_dentry, NULL) instead.
+ * in the unlikely case when (read-only) access to filesystem
+ data structures needs exclusion for some reason, arrange it
+ yourself. None of the in-tree filesystems needed that.
+ * rely on ->d_parent and ->d_name not changing after dentry has
+ been fed to d_add() or d_splice_alias(). Again, none of the
+ in-tree instances relied upon that.
+
+We are guaranteed that lookups of the same name in the same directory
+will not happen in parallel ("same" in the sense of your ->d_compare()).
+Lookups on different names in the same directory can and do happen in
+parallel now.
+
+---
+
+**recommended**
+
+->iterate_shared() is added; it's a parallel variant of ->iterate().
+Exclusion on struct file level is still provided (as well as that
+between it and lseek on the same struct file), but if your directory
+has been opened several times, you can get these called in parallel.
+Exclusion between that method and all directory-modifying ones is
+still provided, of course.
+
+Often enough ->iterate() can serve as ->iterate_shared() without any
+changes - it is a read-only operation, after all. If you have any
+per-inode or per-dentry in-core data structures modified by ->iterate(),
+you might need something to serialize the access to them. If you
+do dcache pre-seeding, you'll need to switch to d_alloc_parallel() for
+that; look for in-tree examples.
+
+Old method is only used if the new one is absent; eventually it will
+be removed. Switch while you still can; the old one won't stay.
+
+---
+
+**mandatory**
+
+->atomic_open() calls without O_CREAT may happen in parallel.
+
+---
+
+**mandatory**
+
+->setxattr() and xattr_handler.set() get dentry and inode passed separately.
+dentry might be yet to be attached to inode, so do _not_ use its ->d_inode
+in the instances. Rationale: !@#!@# security_d_instantiate() needs to be
+called before we attach dentry to inode and !@#!@##!@$!$#!@#$!@$!@$ smack
+->d_instantiate() uses not just ->getxattr() but ->setxattr() as well.
+
+---
+
+**mandatory**
+
+->d_compare() doesn't get parent as a separate argument anymore. If you
+used it for finding the struct super_block involved, dentry->d_sb will
+work just as well; if it's something more complicated, use dentry->d_parent.
+Just be careful not to assume that fetching it more than once will yield
+the same value - in RCU mode it could change under you.
+
+---
+
+**mandatory**
+
+->rename() has an added flags argument. Any flags not handled by the
+filesystem should result in EINVAL being returned.
+
+---
+
+
+**recommended**
+
+->readlink is optional for symlinks. Don't set, unless filesystem needs
+to fake something for readlink(2).
+
+---
+
+**mandatory**
+
+->getattr() is now passed a struct path rather than a vfsmount and
+dentry separately, and it now has request_mask and query_flags arguments
+to specify the fields and sync type requested by statx. Filesystems not
+supporting any statx-specific features may ignore the new arguments.
+
+---
+
+**mandatory**
+
+->atomic_open() calling conventions have changed. Gone is ``int *opened``,
+along with FILE_OPENED/FILE_CREATED. In place of those we have
+FMODE_OPENED/FMODE_CREATED, set in file->f_mode. Additionally, return
+value for 'called finish_no_open(), open it yourself' case has become
+0, not 1. Since finish_no_open() itself is returning 0 now, that part
+does not need any changes in ->atomic_open() instances.
+
+---
+
+**mandatory**
+
+alloc_file() has become static now; two wrappers are to be used instead.
+alloc_file_pseudo(inode, vfsmount, name, flags, ops) is for the cases
+when dentry needs to be created; that's the majority of old alloc_file()
+users. Calling conventions: on success a reference to new struct file
+is returned and callers reference to inode is subsumed by that. On
+failure, ERR_PTR() is returned and no caller's references are affected,
+so the caller needs to drop the inode reference it held.
+alloc_file_clone(file, flags, ops) does not affect any caller's references.
+On success you get a new struct file sharing the mount/dentry with the
+original, on failure - ERR_PTR().
+
+---
+
+**mandatory**
+
+->clone_file_range() and ->dedupe_file_range have been replaced with
+->remap_file_range(). See Documentation/filesystems/vfs.rst for more
+information.
+
+---
+
+**recommended**
+
+->lookup() instances doing an equivalent of::
+
+ if (IS_ERR(inode))
+ return ERR_CAST(inode);
+ return d_splice_alias(inode, dentry);
+
+don't need to bother with the check - d_splice_alias() will do the
+right thing when given ERR_PTR(...) as inode. Moreover, passing NULL
+inode to d_splice_alias() will also do the right thing (equivalent of
+d_add(dentry, NULL); return NULL;), so that kind of special cases
+also doesn't need a separate treatment.
+
+---
+
+**strongly recommended**
+
+take the RCU-delayed parts of ->destroy_inode() into a new method -
+->free_inode(). If ->destroy_inode() becomes empty - all the better,
+just get rid of it. Synchronous work (e.g. the stuff that can't
+be done from an RCU callback, or any WARN_ON() where we want the
+stack trace) *might* be movable to ->evict_inode(); however,
+that goes only for the things that are not needed to balance something
+done by ->alloc_inode(). IOW, if it's cleaning up the stuff that
+might have accumulated over the life of in-core inode, ->evict_inode()
+might be a fit.
+
+Rules for inode destruction:
+
+ * if ->destroy_inode() is non-NULL, it gets called
+ * if ->free_inode() is non-NULL, it gets scheduled by call_rcu()
+ * combination of NULL ->destroy_inode and NULL ->free_inode is
+ treated as NULL/free_inode_nonrcu, to preserve the compatibility.
+
+Note that the callback (be it via ->free_inode() or explicit call_rcu()
+in ->destroy_inode()) is *NOT* ordered wrt superblock destruction;
+as the matter of fact, the superblock and all associated structures
+might be already gone. The filesystem driver is guaranteed to be still
+there, but that's it. Freeing memory in the callback is fine; doing
+more than that is possible, but requires a lot of care and is best
+avoided.
+
+---
+
+**mandatory**
+
+DCACHE_RCUACCESS is gone; having an RCU delay on dentry freeing is the
+default. DCACHE_NORCU opts out, and only d_alloc_pseudo() has any
+business doing so.
+
+---
+
+**mandatory**
+
+d_alloc_pseudo() is internal-only; uses outside of alloc_file_pseudo() are
+very suspect (and won't work in modules). Such uses are very likely to
+be misspelled d_alloc_anon().
diff --git a/fs/orangefs/orangefs-kernel.h b/fs/orangefs/orangefs-kernel.h
index 572dd29fbd54..34a6c99fa29b 100644
--- a/fs/orangefs/orangefs-kernel.h
+++ b/fs/orangefs/orangefs-kernel.h
@@ -246,7 +246,7 @@ struct orangefs_read_options {
extern struct orangefs_stats orangefs_stats;
/*
- * NOTE: See Documentation/filesystems/porting for information
+ * NOTE: See Documentation/filesystems/porting.rst for information
* on implementing FOO_I and properly accessing fs private data
*/
static inline struct orangefs_inode_s *ORANGEFS_I(struct inode *inode)
--
2.21.0
^ permalink raw reply related
* [PATCH 06/22] docs: packing: move it to core-api book and adjust markups
From: Mauro Carvalho Chehab @ 2019-07-22 11:07 UTC (permalink / raw)
Cc: Mauro Carvalho Chehab, Jonathan Corbet, Vladimir Oltean,
linux-doc, netdev, Mike Rapoport
In-Reply-To: <cover.1563792333.git.mchehab+samsung@kernel.org>
The packing.txt file was misplaced, as docs should be part of
a documentation book, and not at the root dir.
So, move it to the core-api directory and add to its index.
Also, ensure that the file will be properly parsed and the bitmap
ascii artwork will use a monotonic font.
Fixes: 554aae35007e ("lib: Add support for generic packing operations")
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Reviewed-by: Vladimir Oltean <olteanv@gmail.com>
Tested-by: Vladimir Oltean <olteanv@gmail.com>
Reviewed-by: Mike Rapoport <rppt@linux.ibm.com>
---
Documentation/core-api/index.rst | 1 +
.../{packing.txt => core-api/packing.rst} | 81 +++++++++++--------
MAINTAINERS | 2 +-
3 files changed, 51 insertions(+), 33 deletions(-)
rename Documentation/{packing.txt => core-api/packing.rst} (61%)
diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
index da0ed972d224..dfd8fad1e1ec 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -25,6 +25,7 @@ Core utilities
librs
genalloc
errseq
+ packing
printk-formats
circular-buffers
generic-radix-tree
diff --git a/Documentation/packing.txt b/Documentation/core-api/packing.rst
similarity index 61%
rename from Documentation/packing.txt
rename to Documentation/core-api/packing.rst
index f830c98645f1..d8c341fe383e 100644
--- a/Documentation/packing.txt
+++ b/Documentation/core-api/packing.rst
@@ -30,6 +30,7 @@ The solution
------------
This API deals with 2 basic operations:
+
- Packing a CPU-usable number into a memory buffer (with hardware
constraints/quirks)
- Unpacking a memory buffer (which has hardware constraints/quirks)
@@ -49,10 +50,12 @@ What the examples show is where the logical bytes and bits sit.
1. Normally (no quirks), we would do it like this:
-63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32
-7 6 5 4
-31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
-3 2 1 0
+::
+
+ 63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32
+ 7 6 5 4
+ 31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
+ 3 2 1 0
That is, the MSByte (7) of the CPU-usable u64 sits at memory offset 0, and the
LSByte (0) of the u64 sits at memory offset 7.
@@ -63,10 +66,12 @@ comments as "logical" notation.
2. If QUIRK_MSB_ON_THE_RIGHT is set, we do it like this:
-56 57 58 59 60 61 62 63 48 49 50 51 52 53 54 55 40 41 42 43 44 45 46 47 32 33 34 35 36 37 38 39
-7 6 5 4
-24 25 26 27 28 29 30 31 16 17 18 19 20 21 22 23 8 9 10 11 12 13 14 15 0 1 2 3 4 5 6 7
-3 2 1 0
+::
+
+ 56 57 58 59 60 61 62 63 48 49 50 51 52 53 54 55 40 41 42 43 44 45 46 47 32 33 34 35 36 37 38 39
+ 7 6 5 4
+ 24 25 26 27 28 29 30 31 16 17 18 19 20 21 22 23 8 9 10 11 12 13 14 15 0 1 2 3 4 5 6 7
+ 3 2 1 0
That is, QUIRK_MSB_ON_THE_RIGHT does not affect byte positioning, but
inverts bit offsets inside a byte.
@@ -74,10 +79,12 @@ inverts bit offsets inside a byte.
3. If QUIRK_LITTLE_ENDIAN is set, we do it like this:
-39 38 37 36 35 34 33 32 47 46 45 44 43 42 41 40 55 54 53 52 51 50 49 48 63 62 61 60 59 58 57 56
-4 5 6 7
-7 6 5 4 3 2 1 0 15 14 13 12 11 10 9 8 23 22 21 20 19 18 17 16 31 30 29 28 27 26 25 24
-0 1 2 3
+::
+
+ 39 38 37 36 35 34 33 32 47 46 45 44 43 42 41 40 55 54 53 52 51 50 49 48 63 62 61 60 59 58 57 56
+ 4 5 6 7
+ 7 6 5 4 3 2 1 0 15 14 13 12 11 10 9 8 23 22 21 20 19 18 17 16 31 30 29 28 27 26 25 24
+ 0 1 2 3
Therefore, QUIRK_LITTLE_ENDIAN means that inside the memory region, every
byte from each 4-byte word is placed at its mirrored position compared to
@@ -86,18 +93,22 @@ the boundary of that word.
4. If QUIRK_MSB_ON_THE_RIGHT and QUIRK_LITTLE_ENDIAN are both set, we do it
like this:
-32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63
-4 5 6 7
-0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
-0 1 2 3
+::
+
+ 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63
+ 4 5 6 7
+ 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
+ 0 1 2 3
5. If just QUIRK_LSW32_IS_FIRST is set, we do it like this:
-31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
-3 2 1 0
-63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32
-7 6 5 4
+::
+
+ 31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
+ 3 2 1 0
+ 63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32
+ 7 6 5 4
In this case the 8 byte memory region is interpreted as follows: first
4 bytes correspond to the least significant 4-byte word, next 4 bytes to
@@ -107,28 +118,34 @@ the more significant 4-byte word.
6. If QUIRK_LSW32_IS_FIRST and QUIRK_MSB_ON_THE_RIGHT are set, we do it like
this:
-24 25 26 27 28 29 30 31 16 17 18 19 20 21 22 23 8 9 10 11 12 13 14 15 0 1 2 3 4 5 6 7
-3 2 1 0
-56 57 58 59 60 61 62 63 48 49 50 51 52 53 54 55 40 41 42 43 44 45 46 47 32 33 34 35 36 37 38 39
-7 6 5 4
+::
+
+ 24 25 26 27 28 29 30 31 16 17 18 19 20 21 22 23 8 9 10 11 12 13 14 15 0 1 2 3 4 5 6 7
+ 3 2 1 0
+ 56 57 58 59 60 61 62 63 48 49 50 51 52 53 54 55 40 41 42 43 44 45 46 47 32 33 34 35 36 37 38 39
+ 7 6 5 4
7. If QUIRK_LSW32_IS_FIRST and QUIRK_LITTLE_ENDIAN are set, it looks like
this:
-7 6 5 4 3 2 1 0 15 14 13 12 11 10 9 8 23 22 21 20 19 18 17 16 31 30 29 28 27 26 25 24
-0 1 2 3
-39 38 37 36 35 34 33 32 47 46 45 44 43 42 41 40 55 54 53 52 51 50 49 48 63 62 61 60 59 58 57 56
-4 5 6 7
+::
+
+ 7 6 5 4 3 2 1 0 15 14 13 12 11 10 9 8 23 22 21 20 19 18 17 16 31 30 29 28 27 26 25 24
+ 0 1 2 3
+ 39 38 37 36 35 34 33 32 47 46 45 44 43 42 41 40 55 54 53 52 51 50 49 48 63 62 61 60 59 58 57 56
+ 4 5 6 7
8. If QUIRK_LSW32_IS_FIRST, QUIRK_LITTLE_ENDIAN and QUIRK_MSB_ON_THE_RIGHT
are set, it looks like this:
-0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
-0 1 2 3
-32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63
-4 5 6 7
+::
+
+ 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
+ 0 1 2 3
+ 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63
+ 4 5 6 7
We always think of our offsets as if there were no quirk, and we translate
diff --git a/MAINTAINERS b/MAINTAINERS
index 2dce9f25474a..fd2af50e66b5 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -12089,7 +12089,7 @@ L: netdev@vger.kernel.org
S: Supported
F: lib/packing.c
F: include/linux/packing.h
-F: Documentation/packing.txt
+F: Documentation/core-api/packing.rst
PADATA PARALLEL EXECUTION MECHANISM
M: Steffen Klassert <steffen.klassert@secunet.com>
--
2.21.0
^ permalink raw reply related
* [PATCH 03/22] docs: w1: convert to ReST and add to the kAPI group of docs
From: Mauro Carvalho Chehab @ 2019-07-22 11:07 UTC (permalink / raw)
Cc: Mauro Carvalho Chehab, Jonathan Corbet, Evgeniy Polyakov,
linux-doc
In-Reply-To: <cover.1563792333.git.mchehab+samsung@kernel.org>
The 1wire documentation was written with w1 developers in
mind, so, it makes sense to add it together with the driver-api
set.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/ABI/stable/sysfs-bus-w1 | 2 +-
.../ABI/stable/sysfs-driver-w1_ds28e04 | 4 +-
.../ABI/stable/sysfs-driver-w1_ds28ea00 | 2 +-
Documentation/index.rst | 1 +
Documentation/w1/index.rst | 21 +++++
.../w1/masters/{ds2482 => ds2482.rst} | 16 +++-
.../w1/masters/{ds2490 => ds2490.rst} | 6 +-
Documentation/w1/masters/index.rst | 14 +++
Documentation/w1/masters/mxc-w1 | 12 ---
Documentation/w1/masters/mxc-w1.rst | 17 ++++
.../w1/masters/{omap-hdq => omap-hdq.rst} | 12 +--
.../w1/masters/{w1-gpio => w1-gpio.rst} | 21 +++--
Documentation/w1/slaves/index.rst | 16 ++++
.../w1/slaves/{w1_ds2406 => w1_ds2406.rst} | 4 +-
.../w1/slaves/{w1_ds2413 => w1_ds2413.rst} | 9 ++
Documentation/w1/slaves/w1_ds2423 | 47 ----------
Documentation/w1/slaves/w1_ds2423.rst | 54 +++++++++++
.../w1/slaves/{w1_ds2438 => w1_ds2438.rst} | 10 ++-
.../w1/slaves/{w1_ds28e04 => w1_ds28e04.rst} | 5 ++
.../w1/slaves/{w1_ds28e17 => w1_ds28e17.rst} | 16 ++--
.../w1/slaves/{w1_therm => w1_therm.rst} | 11 ++-
.../w1/{w1.generic => w1-generic.rst} | 88 ++++++++++--------
.../w1/{w1.netlink => w1-netlink.rst} | 89 +++++++++++--------
23 files changed, 308 insertions(+), 169 deletions(-)
create mode 100644 Documentation/w1/index.rst
rename Documentation/w1/masters/{ds2482 => ds2482.rst} (71%)
rename Documentation/w1/masters/{ds2490 => ds2490.rst} (98%)
create mode 100644 Documentation/w1/masters/index.rst
delete mode 100644 Documentation/w1/masters/mxc-w1
create mode 100644 Documentation/w1/masters/mxc-w1.rst
rename Documentation/w1/masters/{omap-hdq => omap-hdq.rst} (90%)
rename Documentation/w1/masters/{w1-gpio => w1-gpio.rst} (75%)
create mode 100644 Documentation/w1/slaves/index.rst
rename Documentation/w1/slaves/{w1_ds2406 => w1_ds2406.rst} (96%)
rename Documentation/w1/slaves/{w1_ds2413 => w1_ds2413.rst} (81%)
delete mode 100644 Documentation/w1/slaves/w1_ds2423
create mode 100644 Documentation/w1/slaves/w1_ds2423.rst
rename Documentation/w1/slaves/{w1_ds2438 => w1_ds2438.rst} (93%)
rename Documentation/w1/slaves/{w1_ds28e04 => w1_ds28e04.rst} (93%)
rename Documentation/w1/slaves/{w1_ds28e17 => w1_ds28e17.rst} (88%)
rename Documentation/w1/slaves/{w1_therm => w1_therm.rst} (95%)
rename Documentation/w1/{w1.generic => w1-generic.rst} (59%)
rename Documentation/w1/{w1.netlink => w1-netlink.rst} (77%)
diff --git a/Documentation/ABI/stable/sysfs-bus-w1 b/Documentation/ABI/stable/sysfs-bus-w1
index 140d85b4ae92..992dfb183ed0 100644
--- a/Documentation/ABI/stable/sysfs-bus-w1
+++ b/Documentation/ABI/stable/sysfs-bus-w1
@@ -6,6 +6,6 @@ Description: Bus scanning interval, microseconds component.
control systems are attached/generate presence for as short as
100 ms - hence the tens-to-hundreds milliseconds scan intervals
are required.
- see Documentation/w1/w1.generic for detailed information.
+ see Documentation/w1/w1-generic.rst for detailed information.
Users: any user space application which wants to know bus scanning
interval
diff --git a/Documentation/ABI/stable/sysfs-driver-w1_ds28e04 b/Documentation/ABI/stable/sysfs-driver-w1_ds28e04
index 26579ee868c9..3e1c1fa8d54d 100644
--- a/Documentation/ABI/stable/sysfs-driver-w1_ds28e04
+++ b/Documentation/ABI/stable/sysfs-driver-w1_ds28e04
@@ -2,7 +2,7 @@ What: /sys/bus/w1/devices/.../pio
Date: May 2012
Contact: Markus Franke <franm@hrz.tu-chemnitz.de>
Description: read/write the contents of the two PIO's of the DS28E04-100
- see Documentation/w1/slaves/w1_ds28e04 for detailed information
+ see Documentation/w1/slaves/w1_ds28e04.rst for detailed information
Users: any user space application which wants to communicate with DS28E04-100
@@ -11,5 +11,5 @@ What: /sys/bus/w1/devices/.../eeprom
Date: May 2012
Contact: Markus Franke <franm@hrz.tu-chemnitz.de>
Description: read/write the contents of the EEPROM memory of the DS28E04-100
- see Documentation/w1/slaves/w1_ds28e04 for detailed information
+ see Documentation/w1/slaves/w1_ds28e04.rst for detailed information
Users: any user space application which wants to communicate with DS28E04-100
diff --git a/Documentation/ABI/stable/sysfs-driver-w1_ds28ea00 b/Documentation/ABI/stable/sysfs-driver-w1_ds28ea00
index e928def14f28..534e63731a49 100644
--- a/Documentation/ABI/stable/sysfs-driver-w1_ds28ea00
+++ b/Documentation/ABI/stable/sysfs-driver-w1_ds28ea00
@@ -2,5 +2,5 @@ What: /sys/bus/w1/devices/.../w1_seq
Date: Apr 2015
Contact: Matt Campbell <mattrcampbell@gmail.com>
Description: Support for the DS28EA00 chain sequence function
- see Documentation/w1/slaves/w1_therm for detailed information
+ see Documentation/w1/slaves/w1_therm.rst for detailed information
Users: any user space application which wants to communicate with DS28EA00
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 9b45af84fd29..8730c7455265 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -115,6 +115,7 @@ needed).
power/index
target/index
timers/index
+ w1/index
watchdog/index
virtual/index
input/index
diff --git a/Documentation/w1/index.rst b/Documentation/w1/index.rst
new file mode 100644
index 000000000000..57cba81865e2
--- /dev/null
+++ b/Documentation/w1/index.rst
@@ -0,0 +1,21 @@
+. SPDX-License-Identifier: GPL-2.0
+
+================
+1-Wire Subsystem
+================
+
+.. toctree::
+ :maxdepth: 1
+
+
+ w1-generic.rst
+ w1-netlink.rst
+ masters/index
+ slaves/index
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/w1/masters/ds2482 b/Documentation/w1/masters/ds2482.rst
similarity index 71%
rename from Documentation/w1/masters/ds2482
rename to Documentation/w1/masters/ds2482.rst
index 56f8edace6ac..17ebe8f660cd 100644
--- a/Documentation/w1/masters/ds2482
+++ b/Documentation/w1/masters/ds2482.rst
@@ -1,13 +1,19 @@
+====================
Kernel driver ds2482
====================
Supported chips:
+
* Maxim DS2482-100, Maxim DS2482-800
+
Prefix: 'ds2482'
+
Addresses scanned: None
+
Datasheets:
- http://datasheets.maxim-ic.com/en/ds/DS2482-100.pdf
- http://datasheets.maxim-ic.com/en/ds/DS2482-800.pdf
+
+ - http://datasheets.maxim-ic.com/en/ds/DS2482-100.pdf
+ - http://datasheets.maxim-ic.com/en/ds/DS2482-800.pdf
Author: Ben Gardner <bgardner@wabtec.com>
@@ -23,9 +29,11 @@ General Remarks
---------------
Valid addresses are 0x18, 0x19, 0x1a, and 0x1b.
+
However, the device cannot be detected without writing to the i2c bus, so no
detection is done. You should instantiate the device explicitly.
-$ modprobe ds2482
-$ echo ds2482 0x18 > /sys/bus/i2c/devices/i2c-0/new_device
+::
+ $ modprobe ds2482
+ $ echo ds2482 0x18 > /sys/bus/i2c/devices/i2c-0/new_device
diff --git a/Documentation/w1/masters/ds2490 b/Documentation/w1/masters/ds2490.rst
similarity index 98%
rename from Documentation/w1/masters/ds2490
rename to Documentation/w1/masters/ds2490.rst
index 3e091151dd80..7e5b50f9c0f5 100644
--- a/Documentation/w1/masters/ds2490
+++ b/Documentation/w1/masters/ds2490.rst
@@ -1,7 +1,9 @@
+====================
Kernel driver ds2490
====================
Supported chips:
+
* Maxim DS2490 based
Author: Evgeniy Polyakov <johnpol@2ka.mipt.ru>
@@ -18,6 +20,7 @@ which has 0x81 family ID integrated chip and DS2490
low-level operational chip.
Notes and limitations.
+
- The weak pullup current is a minimum of 0.9mA and maximum of 6.0mA.
- The 5V strong pullup is supported with a minimum of 5.9mA and a
maximum of 30.4 mA. (From DS2490.pdf)
@@ -65,4 +68,5 @@ Notes and limitations.
reattaching would clear the problem. usbmon output in the guest and
host did not explain the problem. My guess is a bug in either qemu
or the host OS and more likely the host OS.
--- 03-06-2008 David Fries <David@Fries.net>
+
+03-06-2008 David Fries <David@Fries.net>
diff --git a/Documentation/w1/masters/index.rst b/Documentation/w1/masters/index.rst
new file mode 100644
index 000000000000..4442a98850ad
--- /dev/null
+++ b/Documentation/w1/masters/index.rst
@@ -0,0 +1,14 @@
+. SPDX-License-Identifier: GPL-2.0
+
+=====================
+1-wire Master Drivers
+=====================
+
+.. toctree::
+ :maxdepth: 1
+
+ ds2482
+ ds2490
+ mxc-w1
+ omap-hdq
+ w1-gpio
diff --git a/Documentation/w1/masters/mxc-w1 b/Documentation/w1/masters/mxc-w1
deleted file mode 100644
index 38be1ad65532..000000000000
--- a/Documentation/w1/masters/mxc-w1
+++ /dev/null
@@ -1,12 +0,0 @@
-Kernel driver mxc_w1
-====================
-
-Supported chips:
- * Freescale MX27, MX31 and probably other i.MX SoCs
- Datasheets:
- http://www.freescale.com/files/32bit/doc/data_sheet/MCIMX31.pdf?fpsp=1
- http://cache.freescale.com/files/dsp/doc/archive/MCIMX27.pdf?fsrch=1&WT_TYPE=
- Data%20Sheets&WT_VENDOR=FREESCALE&WT_FILE_FORMAT=pdf&WT_ASSET=Documentation
-
-Author: Originally based on Freescale code, prepared for mainline by
- Sascha Hauer <s.hauer@pengutronix.de>
diff --git a/Documentation/w1/masters/mxc-w1.rst b/Documentation/w1/masters/mxc-w1.rst
new file mode 100644
index 000000000000..334f9893103f
--- /dev/null
+++ b/Documentation/w1/masters/mxc-w1.rst
@@ -0,0 +1,17 @@
+====================
+Kernel driver mxc_w1
+====================
+
+Supported chips:
+
+ * Freescale MX27, MX31 and probably other i.MX SoCs
+
+ Datasheets:
+
+ - http://www.freescale.com/files/32bit/doc/data_sheet/MCIMX31.pdf?fpsp=1
+ - http://cache.freescale.com/files/dsp/doc/archive/MCIMX27.pdf?fsrch=1&WT_TYPE=Data%20Sheets&WT_VENDOR=FREESCALE&WT_FILE_FORMAT=pdf&WT_ASSET=Documentation
+
+Author:
+
+ Originally based on Freescale code, prepared for mainline by
+ Sascha Hauer <s.hauer@pengutronix.de>
diff --git a/Documentation/w1/masters/omap-hdq b/Documentation/w1/masters/omap-hdq.rst
similarity index 90%
rename from Documentation/w1/masters/omap-hdq
rename to Documentation/w1/masters/omap-hdq.rst
index 234522709a5f..345298a59e50 100644
--- a/Documentation/w1/masters/omap-hdq
+++ b/Documentation/w1/masters/omap-hdq.rst
@@ -1,9 +1,10 @@
-Kernel driver for omap HDQ/1-wire module.
+========================================
+Kernel driver for omap HDQ/1-wire module
========================================
Supported chips:
================
- HDQ/1-wire controller on the TI OMAP 2430/3430 platforms.
+HDQ/1-wire controller on the TI OMAP 2430/3430 platforms.
A useful link about HDQ basics:
===============================
@@ -40,9 +41,10 @@ driver(drivers/w1/slaves/w1_bq27000.c) sets the ID to 1.
Please note to load both the modules with a different ID if required, but note
that the ID used should be same for both master and slave driver loading.
-e.g:
-insmod omap_hdq.ko W1_ID=2
-inamod w1_bq27000.ko F_ID=2
+e.g::
+
+ insmod omap_hdq.ko W1_ID=2
+ inamod w1_bq27000.ko F_ID=2
The driver also supports 1-wire mode. In this mode, there is no need to
pass slave ID as parameter. The driver will auto-detect slaves connected
diff --git a/Documentation/w1/masters/w1-gpio b/Documentation/w1/masters/w1-gpio.rst
similarity index 75%
rename from Documentation/w1/masters/w1-gpio
rename to Documentation/w1/masters/w1-gpio.rst
index 623961d9e83f..18fdb7366372 100644
--- a/Documentation/w1/masters/w1-gpio
+++ b/Documentation/w1/masters/w1-gpio.rst
@@ -1,3 +1,4 @@
+=====================
Kernel driver w1-gpio
=====================
@@ -16,28 +17,30 @@ Documentation/devicetree/bindings/w1/w1-gpio.txt
Example (mach-at91)
-------------------
-#include <linux/gpio/machine.h>
-#include <linux/w1-gpio.h>
+::
-static struct gpiod_lookup_table foo_w1_gpiod_table = {
+ #include <linux/gpio/machine.h>
+ #include <linux/w1-gpio.h>
+
+ static struct gpiod_lookup_table foo_w1_gpiod_table = {
.dev_id = "w1-gpio",
.table = {
GPIO_LOOKUP_IDX("at91-gpio", AT91_PIN_PB20, NULL, 0,
GPIO_ACTIVE_HIGH|GPIO_OPEN_DRAIN),
},
-};
+ };
-static struct w1_gpio_platform_data foo_w1_gpio_pdata = {
+ static struct w1_gpio_platform_data foo_w1_gpio_pdata = {
.ext_pullup_enable_pin = -EINVAL,
-};
+ };
-static struct platform_device foo_w1_device = {
+ static struct platform_device foo_w1_device = {
.name = "w1-gpio",
.id = -1,
.dev.platform_data = &foo_w1_gpio_pdata,
-};
+ };
-...
+ ...
at91_set_GPIO_periph(foo_w1_gpio_pdata.pin, 1);
at91_set_multi_drive(foo_w1_gpio_pdata.pin, 1);
gpiod_add_lookup_table(&foo_w1_gpiod_table);
diff --git a/Documentation/w1/slaves/index.rst b/Documentation/w1/slaves/index.rst
new file mode 100644
index 000000000000..d0697b202f09
--- /dev/null
+++ b/Documentation/w1/slaves/index.rst
@@ -0,0 +1,16 @@
+. SPDX-License-Identifier: GPL-2.0
+
+====================
+1-wire Slave Drivers
+====================
+
+.. toctree::
+ :maxdepth: 1
+
+ w1_ds2406
+ w1_ds2413
+ w1_ds2423
+ w1_ds2438
+ w1_ds28e04
+ w1_ds28e17
+ w1_therm
diff --git a/Documentation/w1/slaves/w1_ds2406 b/Documentation/w1/slaves/w1_ds2406.rst
similarity index 96%
rename from Documentation/w1/slaves/w1_ds2406
rename to Documentation/w1/slaves/w1_ds2406.rst
index 8137fe6f6c3d..d3e68266084f 100644
--- a/Documentation/w1/slaves/w1_ds2406
+++ b/Documentation/w1/slaves/w1_ds2406.rst
@@ -1,7 +1,9 @@
+=======================
w1_ds2406 kernel driver
=======================
Supported chips:
+
* Maxim DS2406 (and other family 0x12) addressable switches
Author: Scott Alfter <scott@alfter.us>
@@ -9,7 +11,7 @@ Author: Scott Alfter <scott@alfter.us>
Description
-----------
-The w1_ds2406 driver allows connected devices to be switched on and off.
+The w1_ds2406 driver allows connected devices to be switched on and off.
These chips also provide 128 bytes of OTP EPROM, but reading/writing it is
not supported. In TSOC-6 form, the DS2406 provides two switch outputs and
can be provided with power on a dedicated input. In TO-92 form, it provides
diff --git a/Documentation/w1/slaves/w1_ds2413 b/Documentation/w1/slaves/w1_ds2413.rst
similarity index 81%
rename from Documentation/w1/slaves/w1_ds2413
rename to Documentation/w1/slaves/w1_ds2413.rst
index 936263a8ccb4..c15bb5b919b7 100644
--- a/Documentation/w1/slaves/w1_ds2413
+++ b/Documentation/w1/slaves/w1_ds2413.rst
@@ -1,11 +1,16 @@
+=======================
Kernel driver w1_ds2413
=======================
Supported chips:
+
* Maxim DS2413 1-Wire Dual Channel Addressable Switch
supported family codes:
+
+ ================ ====
W1_FAMILY_DS2413 0x3A
+ ================ ====
Author: Mariusz Bialonczyk <manio@skyboo.net>
@@ -20,11 +25,13 @@ Reading state
The "state" file provides one-byte value which is in the same format as for
the chip PIO_ACCESS_READ command (refer the datasheet for details):
+======== =============================================================
Bit 0: PIOA Pin State
Bit 1: PIOA Output Latch State
Bit 2: PIOB Pin State
Bit 3: PIOB Output Latch State
Bit 4-7: Complement of Bit 3 to Bit 0 (verified by the kernel module)
+======== =============================================================
This file is readonly.
@@ -34,9 +41,11 @@ You can set the PIO pins using the "output" file.
It is writable, you can write one-byte value to this sysfs file.
Similarly the byte format is the same as for the PIO_ACCESS_WRITE command:
+======== ======================================
Bit 0: PIOA
Bit 1: PIOB
Bit 2-7: No matter (driver will set it to "1"s)
+======== ======================================
The chip has some kind of basic protection against transmission errors.
diff --git a/Documentation/w1/slaves/w1_ds2423 b/Documentation/w1/slaves/w1_ds2423
deleted file mode 100644
index 3f98b505a0ee..000000000000
--- a/Documentation/w1/slaves/w1_ds2423
+++ /dev/null
@@ -1,47 +0,0 @@
-Kernel driver w1_ds2423
-=======================
-
-Supported chips:
- * Maxim DS2423 based counter devices.
-
-supported family codes:
- W1_THERM_DS2423 0x1D
-
-Author: Mika Laitio <lamikr@pilppa.org>
-
-Description
------------
-
-Support is provided through the sysfs w1_slave file. Each opening and
-read sequence of w1_slave file initiates the read of counters and ram
-available in DS2423 pages 12 - 15.
-
-Result of each page is provided as an ASCII output where each counter
-value and associated ram buffer is outpputed to own line.
-
-Each lines will contain the values of 42 bytes read from the counter and
-memory page along the crc=YES or NO for indicating whether the read operation
-was successful and CRC matched.
-If the operation was successful, there is also in the end of each line
-a counter value expressed as an integer after c=
-
-Meaning of 42 bytes represented is following:
- - 1 byte from ram page
- - 4 bytes for the counter value
- - 4 zero bytes
- - 2 bytes for crc16 which was calculated from the data read since the previous crc bytes
- - 31 remaining bytes from the ram page
- - crc=YES/NO indicating whether read was ok and crc matched
- - c=<int> current counter value
-
-example from the successful read:
-00 02 00 00 00 00 00 00 00 6d 38 00 ff ff 00 00 fe ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2
-00 02 00 00 00 00 00 00 00 e0 1f 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2
-00 29 c6 5d 18 00 00 00 00 04 37 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=408798761
-00 05 00 00 00 00 00 00 00 8d 39 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff crc=YES c=5
-
-example from the read with crc errors:
-00 02 00 00 00 00 00 00 00 6d 38 00 ff ff 00 00 fe ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2
-00 02 00 00 22 00 00 00 00 e0 1f 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=NO
-00 e1 61 5d 19 00 00 00 00 df 0b 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=NO
-00 05 00 00 20 00 00 00 00 8d 39 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff crc=NO
diff --git a/Documentation/w1/slaves/w1_ds2423.rst b/Documentation/w1/slaves/w1_ds2423.rst
new file mode 100644
index 000000000000..755d659ad997
--- /dev/null
+++ b/Documentation/w1/slaves/w1_ds2423.rst
@@ -0,0 +1,54 @@
+Kernel driver w1_ds2423
+=======================
+
+Supported chips:
+
+ * Maxim DS2423 based counter devices.
+
+supported family codes:
+
+ =============== ====
+ W1_THERM_DS2423 0x1D
+ =============== ====
+
+Author: Mika Laitio <lamikr@pilppa.org>
+
+Description
+-----------
+
+Support is provided through the sysfs w1_slave file. Each opening and
+read sequence of w1_slave file initiates the read of counters and ram
+available in DS2423 pages 12 - 15.
+
+Result of each page is provided as an ASCII output where each counter
+value and associated ram buffer is outpputed to own line.
+
+Each lines will contain the values of 42 bytes read from the counter and
+memory page along the crc=YES or NO for indicating whether the read operation
+was successful and CRC matched.
+If the operation was successful, there is also in the end of each line
+a counter value expressed as an integer after c=
+
+Meaning of 42 bytes represented is following:
+
+ - 1 byte from ram page
+ - 4 bytes for the counter value
+ - 4 zero bytes
+ - 2 bytes for crc16 which was calculated from the data read since the previous crc bytes
+ - 31 remaining bytes from the ram page
+ - crc=YES/NO indicating whether read was ok and crc matched
+ - c=<int> current counter value
+
+example from the successful read::
+
+ 00 02 00 00 00 00 00 00 00 6d 38 00 ff ff 00 00 fe ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2
+ 00 02 00 00 00 00 00 00 00 e0 1f 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2
+ 00 29 c6 5d 18 00 00 00 00 04 37 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=408798761
+ 00 05 00 00 00 00 00 00 00 8d 39 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff crc=YES c=5
+
+example from the read with crc errors::
+
+ 00 02 00 00 00 00 00 00 00 6d 38 00 ff ff 00 00 fe ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2
+ 00 02 00 00 22 00 00 00 00 e0 1f 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=NO
+ 00 e1 61 5d 19 00 00 00 00 df 0b 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=NO
+ 00 05 00 00 20 00 00 00 00 8d 39 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff crc=NO
diff --git a/Documentation/w1/slaves/w1_ds2438 b/Documentation/w1/slaves/w1_ds2438.rst
similarity index 93%
rename from Documentation/w1/slaves/w1_ds2438
rename to Documentation/w1/slaves/w1_ds2438.rst
index e64f65a09387..a29309a3f8e5 100644
--- a/Documentation/w1/slaves/w1_ds2438
+++ b/Documentation/w1/slaves/w1_ds2438.rst
@@ -2,10 +2,13 @@ Kernel driver w1_ds2438
=======================
Supported chips:
+
* Maxim DS2438 Smart Battery Monitor
supported family codes:
+ ================ ====
W1_FAMILY_DS2438 0x26
+ ================ ====
Author: Mariusz Bialonczyk <manio@skyboo.net>
@@ -56,8 +59,11 @@ Opening and reading this file initiates the CONVERT_V (voltage conversion)
command of the chip.
Depending on a sysfs filename a different input for the A/D will be selected:
-vad: general purpose A/D input (VAD)
-vdd: battery input (VDD)
+
+vad:
+ general purpose A/D input (VAD)
+vdd:
+ battery input (VDD)
After the voltage conversion the value is returned as decimal ASCII.
Note: To get a volts the value has to be divided by 100.
diff --git a/Documentation/w1/slaves/w1_ds28e04 b/Documentation/w1/slaves/w1_ds28e04.rst
similarity index 93%
rename from Documentation/w1/slaves/w1_ds28e04
rename to Documentation/w1/slaves/w1_ds28e04.rst
index 7819b65cfa48..b12b118890d3 100644
--- a/Documentation/w1/slaves/w1_ds28e04
+++ b/Documentation/w1/slaves/w1_ds28e04.rst
@@ -1,11 +1,16 @@
+========================
Kernel driver w1_ds28e04
========================
Supported chips:
+
* Maxim DS28E04-100 4096-Bit Addressable 1-Wire EEPROM with PIO
supported family codes:
+
+ ================= ====
W1_FAMILY_DS28E04 0x1C
+ ================= ====
Author: Markus Franke, <franke.m@sebakmt.com> <franm@hrz.tu-chemnitz.de>
diff --git a/Documentation/w1/slaves/w1_ds28e17 b/Documentation/w1/slaves/w1_ds28e17.rst
similarity index 88%
rename from Documentation/w1/slaves/w1_ds28e17
rename to Documentation/w1/slaves/w1_ds28e17.rst
index 7fcfad5b4a37..e2d9f96d8f2c 100644
--- a/Documentation/w1/slaves/w1_ds28e17
+++ b/Documentation/w1/slaves/w1_ds28e17.rst
@@ -1,11 +1,16 @@
+========================
Kernel driver w1_ds28e17
========================
Supported chips:
+
* Maxim DS28E17 1-Wire-to-I2C Master Bridge
supported family codes:
+
+ ================= ====
W1_FAMILY_DS28E17 0x19
+ ================= ====
Author: Jan Kandziora <jjj@gmx.de>
@@ -20,11 +25,11 @@ a DS28E17 can be accessed by the kernel or userspace tools as if they were
connected to a "native" I2C bus master.
-An udev rule like the following
--------------------------------------------------------------------------------
-SUBSYSTEM=="i2c-dev", KERNEL=="i2c-[0-9]*", ATTRS{name}=="w1-19-*", \
- SYMLINK+="i2c-$attr{name}"
--------------------------------------------------------------------------------
+An udev rule like the following::
+
+ SUBSYSTEM=="i2c-dev", KERNEL=="i2c-[0-9]*", ATTRS{name}=="w1-19-*", \
+ SYMLINK+="i2c-$attr{name}"
+
may be used to create stable /dev/i2c- entries based on the unique id of the
DS28E17 chip.
@@ -65,4 +70,3 @@ structure is created.
See https://github.com/ianka/w1_ds28e17 for even more information.
-
diff --git a/Documentation/w1/slaves/w1_therm b/Documentation/w1/slaves/w1_therm.rst
similarity index 95%
rename from Documentation/w1/slaves/w1_therm
rename to Documentation/w1/slaves/w1_therm.rst
index d1f93af36f38..90531c340a07 100644
--- a/Documentation/w1/slaves/w1_therm
+++ b/Documentation/w1/slaves/w1_therm.rst
@@ -1,7 +1,9 @@
+======================
Kernel driver w1_therm
-====================
+======================
Supported chips:
+
* Maxim ds18*20 based temperature sensors.
* Maxim ds1825 based temperature sensors.
@@ -13,12 +15,16 @@ Description
w1_therm provides basic temperature conversion for ds18*20 devices, and the
ds28ea00 device.
-supported family codes:
+
+Supported family codes:
+
+==================== ====
W1_THERM_DS18S20 0x10
W1_THERM_DS1822 0x22
W1_THERM_DS18B20 0x28
W1_THERM_DS1825 0x3B
W1_THERM_DS28EA00 0x42
+==================== ====
Support is provided through the sysfs w1_slave file. Each open and
read sequence will initiate a temperature conversion then provide two
@@ -51,6 +57,7 @@ If so, it will activate the master's strong pullup.
In case the detection of parasite devices using this command fails
(seems to be the case with some DS18S20) the strong pullup can
be force-enabled.
+
If the strong pullup is enabled, the master's strong pullup will be
driven when the conversion is taking place, provided the master driver
does support the strong pullup (or it falls back to a pullup
diff --git a/Documentation/w1/w1.generic b/Documentation/w1/w1-generic.rst
similarity index 59%
rename from Documentation/w1/w1.generic
rename to Documentation/w1/w1-generic.rst
index c51b1ab012d0..da4e8b4e9b01 100644
--- a/Documentation/w1/w1.generic
+++ b/Documentation/w1/w1-generic.rst
@@ -1,5 +1,7 @@
-The 1-wire (w1) subsystem
-------------------------------------------------------------------
+=========================================
+Introduction to the 1-wire (w1) subsystem
+=========================================
+
The 1-wire bus is a simple master-slave bus that communicates via a single
signal wire (plus ground, so two wires).
@@ -12,14 +14,16 @@ communication with slaves.
All w1 slave devices must be connected to a w1 bus master device.
Example w1 master devices:
- DS9490 usb device
- W1-over-GPIO
- DS2482 (i2c to w1 bridge)
- Emulated devices, such as a RS232 converter, parallel port adapter, etc
+
+ - DS9490 usb device
+ - W1-over-GPIO
+ - DS2482 (i2c to w1 bridge)
+ - Emulated devices, such as a RS232 converter, parallel port adapter, etc
What does the w1 subsystem do?
-------------------------------------------------------------------
+------------------------------
+
When a w1 master driver registers with the w1 subsystem, the following occurs:
- sysfs entries for that w1 master are created
@@ -43,24 +47,28 @@ be read, since no device was selected.
W1 device families
-------------------------------------------------------------------
+------------------
+
Slave devices are handled by a driver written for a family of w1 devices.
A family driver populates a struct w1_family_ops (see w1_family.h) and
registers with the w1 subsystem.
Current family drivers:
-w1_therm - (ds18?20 thermal sensor family driver)
+
+w1_therm
+ - (ds18?20 thermal sensor family driver)
provides temperature reading function which is bound to ->rbin() method
of the above w1_family_ops structure.
-w1_smem - driver for simple 64bit memory cell provides ID reading method.
+w1_smem
+ - driver for simple 64bit memory cell provides ID reading method.
You can call above methods by reading appropriate sysfs files.
What does a w1 master driver need to implement?
-------------------------------------------------------------------
+-----------------------------------------------
The driver for w1 bus master must provide at minimum two functions.
@@ -75,25 +83,26 @@ See struct w1_bus_master definition in w1.h for details.
w1 master sysfs interface
-------------------------------------------------------------------
-<xx-xxxxxxxxxxxx> - A directory for a found device. The format is family-serial
-bus - (standard) symlink to the w1 bus
-driver - (standard) symlink to the w1 driver
-w1_master_add - (rw) manually register a slave device
-w1_master_attempts - (ro) the number of times a search was attempted
-w1_master_max_slave_count
- - (rw) maximum number of slaves to search for at a time
-w1_master_name - (ro) the name of the device (w1_bus_masterX)
-w1_master_pullup - (rw) 5V strong pullup 0 enabled, 1 disabled
-w1_master_remove - (rw) manually remove a slave device
-w1_master_search - (rw) the number of searches left to do,
- -1=continual (default)
-w1_master_slave_count
- - (ro) the number of slaves found
-w1_master_slaves - (ro) the names of the slaves, one per line
-w1_master_timeout - (ro) the delay in seconds between searches
-w1_master_timeout_us
- - (ro) the delay in microseconds beetwen searches
+-------------------------
+
+========================= =====================================================
+<xx-xxxxxxxxxxxx> A directory for a found device. The format is
+ family-serial
+bus (standard) symlink to the w1 bus
+driver (standard) symlink to the w1 driver
+w1_master_add (rw) manually register a slave device
+w1_master_attempts (ro) the number of times a search was attempted
+w1_master_max_slave_count (rw) maximum number of slaves to search for at a time
+w1_master_name (ro) the name of the device (w1_bus_masterX)
+w1_master_pullup (rw) 5V strong pullup 0 enabled, 1 disabled
+w1_master_remove (rw) manually remove a slave device
+w1_master_search (rw) the number of searches left to do,
+ -1=continual (default)
+w1_master_slave_count (ro) the number of slaves found
+w1_master_slaves (ro) the names of the slaves, one per line
+w1_master_timeout (ro) the delay in seconds between searches
+w1_master_timeout_us (ro) the delay in microseconds beetwen searches
+========================= =====================================================
If you have a w1 bus that never changes (you don't add or remove devices),
you can set the module parameter search_count to a small positive number
@@ -111,11 +120,14 @@ decrements w1_master_search by 1 (down to 0) and increments
w1_master_attempts by 1.
w1 slave sysfs interface
-------------------------------------------------------------------
-bus - (standard) symlink to the w1 bus
-driver - (standard) symlink to the w1 driver
-name - the device name, usually the same as the directory name
-w1_slave - (optional) a binary file whose meaning depends on the
- family driver
-rw - (optional) created for slave devices which do not have
- appropriate family driver. Allows to read/write binary data.
+------------------------
+
+=================== ============================================================
+bus (standard) symlink to the w1 bus
+driver (standard) symlink to the w1 driver
+name the device name, usually the same as the directory name
+w1_slave (optional) a binary file whose meaning depends on the
+ family driver
+rw (optional) created for slave devices which do not have
+ appropriate family driver. Allows to read/write binary data.
+=================== ============================================================
diff --git a/Documentation/w1/w1.netlink b/Documentation/w1/w1-netlink.rst
similarity index 77%
rename from Documentation/w1/w1.netlink
rename to Documentation/w1/w1-netlink.rst
index 94ad4c420828..aaa13243a5e4 100644
--- a/Documentation/w1/w1.netlink
+++ b/Documentation/w1/w1-netlink.rst
@@ -1,22 +1,26 @@
-Userspace communication protocol over connector [1].
+===============================================
+Userspace communication protocol over connector
+===============================================
-
-Message types.
+Message types
=============
There are three types of messages between w1 core and userspace:
+
1. Events. They are generated each time a new master or slave device
- is found either due to automatic or requested search.
+ is found either due to automatic or requested search.
2. Userspace commands.
3. Replies to userspace commands.
-Protocol.
+Protocol
========
-[struct cn_msg] - connector header.
+::
+
+ [struct cn_msg] - connector header.
Its length field is equal to size of the attached data
-[struct w1_netlink_msg] - w1 netlink header.
+ [struct w1_netlink_msg] - w1 netlink header.
__u8 type - message type.
W1_LIST_MASTERS
list current bus masters
@@ -40,7 +44,7 @@ Protocol.
} mst;
} id;
-[struct w1_netlink_cmd] - command for given master or slave device.
+ [struct w1_netlink_cmd] - command for given master or slave device.
__u8 cmd - command opcode.
W1_CMD_READ - read command
W1_CMD_WRITE - write command
@@ -71,18 +75,18 @@ when it is added to w1 core.
Currently replies to userspace commands are only generated for read
command request. One reply is generated exactly for one w1_netlink_cmd
read request. Replies are not combined when sent - i.e. typical reply
-messages looks like the following:
+messages looks like the following::
-[cn_msg][w1_netlink_msg][w1_netlink_cmd]
-cn_msg.len = sizeof(struct w1_netlink_msg) +
+ [cn_msg][w1_netlink_msg][w1_netlink_cmd]
+ cn_msg.len = sizeof(struct w1_netlink_msg) +
sizeof(struct w1_netlink_cmd) +
cmd->len;
-w1_netlink_msg.len = sizeof(struct w1_netlink_cmd) + cmd->len;
-w1_netlink_cmd.len = cmd->len;
+ w1_netlink_msg.len = sizeof(struct w1_netlink_cmd) + cmd->len;
+ w1_netlink_cmd.len = cmd->len;
Replies to W1_LIST_MASTERS should send a message back to the userspace
which will contain list of all registered master ids in the following
-format:
+format::
cn_msg (CN_W1_IDX.CN_W1_VAL as id, len is equal to sizeof(struct
w1_netlink_msg) plus number of masters multiplied by 4)
@@ -90,39 +94,47 @@ format:
number of masters multiplied by 4 (u32 size))
id0 ... idN
- Each message is at most 4k in size, so if number of master devices
- exceeds this, it will be split into several messages.
+Each message is at most 4k in size, so if number of master devices
+exceeds this, it will be split into several messages.
W1 search and alarm search commands.
-request:
-[cn_msg]
- [w1_netlink_msg type = W1_MASTER_CMD
- id is equal to the bus master id to use for searching]
- [w1_netlink_cmd cmd = W1_CMD_SEARCH or W1_CMD_ALARM_SEARCH]
-reply:
+request::
+
+ [cn_msg]
+ [w1_netlink_msg type = W1_MASTER_CMD
+ id is equal to the bus master id to use for searching]
+ [w1_netlink_cmd cmd = W1_CMD_SEARCH or W1_CMD_ALARM_SEARCH]
+
+reply::
+
[cn_msg, ack = 1 and increasing, 0 means the last message,
- seq is equal to the request seq]
+ seq is equal to the request seq]
[w1_netlink_msg type = W1_MASTER_CMD]
[w1_netlink_cmd cmd = W1_CMD_SEARCH or W1_CMD_ALARM_SEARCH
len is equal to number of IDs multiplied by 8]
[64bit-id0 ... 64bit-idN]
+
Length in each header corresponds to the size of the data behind it, so
w1_netlink_cmd->len = N * 8; where N is number of IDs in this message.
- Can be zero.
-w1_netlink_msg->len = sizeof(struct w1_netlink_cmd) + N * 8;
-cn_msg->len = sizeof(struct w1_netlink_msg) +
+Can be zero.
+
+::
+
+ w1_netlink_msg->len = sizeof(struct w1_netlink_cmd) + N * 8;
+ cn_msg->len = sizeof(struct w1_netlink_msg) +
sizeof(struct w1_netlink_cmd) +
N*8;
-W1 reset command.
-[cn_msg]
- [w1_netlink_msg type = W1_MASTER_CMD
- id is equal to the bus master id to use for searching]
- [w1_netlink_cmd cmd = W1_CMD_RESET]
+W1 reset command::
+ [cn_msg]
+ [w1_netlink_msg type = W1_MASTER_CMD
+ id is equal to the bus master id to use for searching]
+ [w1_netlink_cmd cmd = W1_CMD_RESET]
-Command status replies.
+
+Command status replies
======================
Each command (either root, master or slave with or without w1_netlink_cmd
@@ -150,7 +162,7 @@ All w1_netlink_cmd command structures are handled in every w1_netlink_msg,
even if there were errors, only length mismatch interrupts message processing.
-Operation steps in w1 core when new command is received.
+Operation steps in w1 core when new command is received
=======================================================
When new message (w1_netlink_msg) is received w1 core detects if it is
@@ -167,7 +179,7 @@ When all commands (w1_netlink_cmd) are processed master device is unlocked
and next w1_netlink_msg header processing started.
-Connector [1] specific documentation.
+Connector [1] specific documentation
====================================
Each connector message includes two u32 fields as "address".
@@ -180,10 +192,11 @@ Sequence number for reply is the same as was in request, and
acknowledge number is set to seq+1.
-Additional documantion, source code examples.
-============================================
+Additional documentation, source code examples
+==============================================
1. Documentation/driver-api/connector.rst
2. http://www.ioremap.net/archive/w1
-This archive includes userspace application w1d.c which uses
-read/write/search commands for all master/slave devices found on the bus.
+
+ This archive includes userspace application w1d.c which uses
+ read/write/search commands for all master/slave devices found on the bus.
--
2.21.0
^ permalink raw reply related
* [PATCH 17/22] docs: mips: add to the documentation body as ReST
From: Mauro Carvalho Chehab @ 2019-07-22 11:07 UTC (permalink / raw)
Cc: Mauro Carvalho Chehab, Jonathan Corbet, Ralf Baechle, Paul Burton,
James Hogan, linux-doc, linux-mips
In-Reply-To: <cover.1563792333.git.mchehab+samsung@kernel.org>
Manually convert the AU1xxx_IDE.README file to ReST and add
to a MIPS book as part of the main documentation body.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/index.rst | 1 +
.../{AU1xxx_IDE.README => au1xxx_ide.rst} | 89 +++++++++++--------
Documentation/mips/index.rst | 17 ++++
3 files changed, 70 insertions(+), 37 deletions(-)
rename Documentation/mips/{AU1xxx_IDE.README => au1xxx_ide.rst} (67%)
create mode 100644 Documentation/mips/index.rst
diff --git a/Documentation/index.rst b/Documentation/index.rst
index c0132ad9c4d9..09d24878ad14 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -150,6 +150,7 @@ implementation.
ia64/index
m68k/index
powerpc/index
+ mips/index
openrisc/index
parisc/index
riscv/index
diff --git a/Documentation/mips/AU1xxx_IDE.README b/Documentation/mips/au1xxx_ide.rst
similarity index 67%
rename from Documentation/mips/AU1xxx_IDE.README
rename to Documentation/mips/au1xxx_ide.rst
index ff675a1b1422..2f9c2cff6738 100644
--- a/Documentation/mips/AU1xxx_IDE.README
+++ b/Documentation/mips/au1xxx_ide.rst
@@ -1,7 +1,14 @@
-README for MIPS AU1XXX IDE driver - Released 2005-07-15
+.. include:: <isonum.txt>
+
+======================
+MIPS AU1XXX IDE driver
+======================
+
+Released 2005-07-15
+
+About
+=====
-ABOUT
------
This file describes the 'drivers/ide/au1xxx-ide.c', related files and the
services they provide.
@@ -10,17 +17,17 @@ the white or black list, go to the 'ADD NEW HARD DISC TO WHITE OR BLACK LIST'
section.
-LICENSE
--------
+License
+=======
-Copyright (c) 2003-2005 AMD, Personal Connectivity Solutions
+:Copyright: |copy| 2003-2005 AMD, Personal Connectivity Solutions
This program is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation; either version 2 of the License, or (at your option) any later
version.
-THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
+THIS SOFTWARE IS PROVIDED ``AS IS`` AND ANY EXPRESS OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR
BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
@@ -35,31 +42,35 @@ You should have received a copy of the GNU General Public License along with
this program; if not, write to the Free Software Foundation, Inc.,
675 Mass Ave, Cambridge, MA 02139, USA.
-Note: for more information, please refer "AMD Alchemy Au1200/Au1550 IDE
+Note:
+ for more information, please refer "AMD Alchemy Au1200/Au1550 IDE
Interface and Linux Device Driver" Application Note.
-FILES, CONFIGS AND COMPATIBILITY
---------------------------------
+Files, Configs and Compatibility
+================================
Two files are introduced:
a) 'arch/mips/include/asm/mach-au1x00/au1xxx_ide.h'
contains : struct _auide_hwif
- timing parameters for PIO mode 0/1/2/3/4
- timing parameters for MWDMA 0/1/2
+
+ - timing parameters for PIO mode 0/1/2/3/4
+ - timing parameters for MWDMA 0/1/2
b) 'drivers/ide/mips/au1xxx-ide.c'
contains the functionality of the AU1XXX IDE driver
Following extra configs variables are introduced:
- CONFIG_BLK_DEV_IDE_AU1XXX_PIO_DBDMA - enable the PIO+DBDMA mode
- CONFIG_BLK_DEV_IDE_AU1XXX_MDMA2_DBDMA - enable the MWDMA mode
+ CONFIG_BLK_DEV_IDE_AU1XXX_PIO_DBDMA
+ - enable the PIO+DBDMA mode
+ CONFIG_BLK_DEV_IDE_AU1XXX_MDMA2_DBDMA
+ - enable the MWDMA mode
-SUPPORTED IDE MODES
--------------------
+Supported IDE Modes
+===================
The AU1XXX IDE driver supported all PIO modes - PIO mode 0/1/2/3/4 - and all
MWDMA modes - MWDMA 0/1/2 -. There is no support for SWDMA and UDMA mode.
@@ -69,20 +80,21 @@ To change the PIO mode use the program hdparm with option -p, e.g.
-X, e.g. 'hdparm -X32 [device]' for MWDMA mode 0.
-PERFORMANCE CONFIGURATIONS
---------------------------
+Performance Configurations
+==========================
-If the used system doesn't need USB support enable the following kernel configs:
+If the used system doesn't need USB support enable the following kernel
+configs::
-CONFIG_IDE=y
-CONFIG_BLK_DEV_IDE=y
-CONFIG_IDE_GENERIC=y
-CONFIG_BLK_DEV_IDEPCI=y
-CONFIG_BLK_DEV_GENERIC=y
-CONFIG_BLK_DEV_IDEDMA_PCI=y
-CONFIG_BLK_DEV_IDE_AU1XXX=y
-CONFIG_BLK_DEV_IDE_AU1XXX_MDMA2_DBDMA=y
-CONFIG_BLK_DEV_IDEDMA=y
+ CONFIG_IDE=y
+ CONFIG_BLK_DEV_IDE=y
+ CONFIG_IDE_GENERIC=y
+ CONFIG_BLK_DEV_IDEPCI=y
+ CONFIG_BLK_DEV_GENERIC=y
+ CONFIG_BLK_DEV_IDEDMA_PCI=y
+ CONFIG_BLK_DEV_IDE_AU1XXX=y
+ CONFIG_BLK_DEV_IDE_AU1XXX_MDMA2_DBDMA=y
+ CONFIG_BLK_DEV_IDEDMA=y
Also define 'IDE_AU1XXX_BURSTMODE' in 'drivers/ide/mips/au1xxx-ide.c' to enable
the burst support on DBDMA controller.
@@ -90,20 +102,22 @@ the burst support on DBDMA controller.
If the used system need the USB support enable the following kernel configs for
high IDE to USB throughput.
-CONFIG_IDE_GENERIC=y
-CONFIG_BLK_DEV_IDEPCI=y
-CONFIG_BLK_DEV_GENERIC=y
-CONFIG_BLK_DEV_IDEDMA_PCI=y
-CONFIG_BLK_DEV_IDE_AU1XXX=y
-CONFIG_BLK_DEV_IDE_AU1XXX_MDMA2_DBDMA=y
-CONFIG_BLK_DEV_IDEDMA=y
+::
+
+ CONFIG_IDE_GENERIC=y
+ CONFIG_BLK_DEV_IDEPCI=y
+ CONFIG_BLK_DEV_GENERIC=y
+ CONFIG_BLK_DEV_IDEDMA_PCI=y
+ CONFIG_BLK_DEV_IDE_AU1XXX=y
+ CONFIG_BLK_DEV_IDE_AU1XXX_MDMA2_DBDMA=y
+ CONFIG_BLK_DEV_IDEDMA=y
Also undefine 'IDE_AU1XXX_BURSTMODE' in 'drivers/ide/mips/au1xxx-ide.c' to
disable the burst support on DBDMA controller.
-ACKNOWLEDGMENTS
----------------
+Acknowledgments
+===============
These drivers wouldn't have been done without the base of kernel 2.4.x AU1XXX
IDE driver from AMD.
@@ -112,4 +126,5 @@ Additional input also from:
Matthias Lenk <matthias.lenk@amd.com>
Happy hacking!
+
Enrico Walther <enrico.walther@amd.com>
diff --git a/Documentation/mips/index.rst b/Documentation/mips/index.rst
new file mode 100644
index 000000000000..fd9023c8a89f
--- /dev/null
+++ b/Documentation/mips/index.rst
@@ -0,0 +1,17 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=================
+MIPS architecture
+=================
+
+.. toctree::
+ :maxdepth: 2
+
+ au1xxx_ide
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
--
2.21.0
^ permalink raw reply related
* [PATCH 10/22] docs: openrisc: convert to ReST and add to documentation body
From: Mauro Carvalho Chehab @ 2019-07-22 11:07 UTC (permalink / raw)
Cc: Mauro Carvalho Chehab, Jonathan Corbet, Jonas Bonn,
Stefan Kristiansson, Stafford Horne, linux-doc, openrisc
In-Reply-To: <cover.1563792333.git.mchehab+samsung@kernel.org>
Manually convert the two openRisc documents to ReST, adding them
to the Linux documentation body.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/index.rst | 1 +
Documentation/openrisc/index.rst | 18 +++++++++++++
.../openrisc/{README => openrisc_port.rst} | 25 +++++++++++++------
Documentation/openrisc/{TODO => todo.rst} | 9 ++++---
4 files changed, 43 insertions(+), 10 deletions(-)
create mode 100644 Documentation/openrisc/index.rst
rename Documentation/openrisc/{README => openrisc_port.rst} (80%)
rename Documentation/openrisc/{TODO => todo.rst} (78%)
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 9bb08d272bd5..5583b2e64692 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -149,6 +149,7 @@ implementation.
ia64/index
m68k/index
powerpc/index
+ openrisc/index
parisc/index
riscv/index
s390/index
diff --git a/Documentation/openrisc/index.rst b/Documentation/openrisc/index.rst
new file mode 100644
index 000000000000..748b3eea1707
--- /dev/null
+++ b/Documentation/openrisc/index.rst
@@ -0,0 +1,18 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=====================
+OpenRISC Architecture
+=====================
+
+.. toctree::
+ :maxdepth: 2
+
+ openrisc_port
+ todo
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/openrisc/README b/Documentation/openrisc/openrisc_port.rst
similarity index 80%
rename from Documentation/openrisc/README
rename to Documentation/openrisc/openrisc_port.rst
index 777a893d533d..a18747a8d191 100644
--- a/Documentation/openrisc/README
+++ b/Documentation/openrisc/openrisc_port.rst
@@ -1,3 +1,4 @@
+==============
OpenRISC Linux
==============
@@ -6,8 +7,10 @@ target architecture, specifically, is the 32-bit OpenRISC 1000 family (or1k).
For information about OpenRISC processors and ongoing development:
+ ======= =============================
website http://openrisc.io
email openrisc@lists.librecores.org
+ ======= =============================
---------------------------------------------------------------------
@@ -24,13 +27,15 @@ Toolchain binaries can be obtained from openrisc.io or our github releases page.
Instructions for building the different toolchains can be found on openrisc.io
or Stafford's toolchain build and release scripts.
+ ========== =================================================
binaries https://github.com/openrisc/or1k-gcc/releases
toolchains https://openrisc.io/software
building https://github.com/stffrdhrn/or1k-toolchain-build
+ ========== =================================================
2) Building
-Build the Linux kernel as usual
+Build the Linux kernel as usual::
make ARCH=openrisc defconfig
make ARCH=openrisc
@@ -43,6 +48,8 @@ development board with the OpenRISC SoC. During the build FPGA RTL is code
downloaded from the FuseSoC IP cores repository and built using the FPGA vendor
tools. Binaries are loaded onto the board with openocd.
+::
+
git clone https://github.com/olofk/fusesoc
cd fusesoc
sudo pip install -e .
@@ -65,7 +72,9 @@ platform. Please follow the OpenRISC instructions on the QEMU website to get
Linux running on QEMU. You can build QEMU yourself, but your Linux distribution
likely provides binary packages to support OpenRISC.
+ ============= ======================================================
qemu openrisc https://wiki.qemu.org/Documentation/Platforms/OpenRISC
+ ============= ======================================================
---------------------------------------------------------------------
@@ -75,36 +84,38 @@ Terminology
In the code, the following particles are used on symbols to limit the scope
to more or less specific processor implementations:
+========= =======================================
openrisc: the OpenRISC class of processors
or1k: the OpenRISC 1000 family of processors
or1200: the OpenRISC 1200 processor
+========= =======================================
---------------------------------------------------------------------
History
========
-18. 11. 2003 Matjaz Breskvar (phoenix@bsemi.com)
+18-11-2003 Matjaz Breskvar (phoenix@bsemi.com)
initial port of linux to OpenRISC/or32 architecture.
all the core stuff is implemented and seams usable.
-08. 12. 2003 Matjaz Breskvar (phoenix@bsemi.com)
+08-12-2003 Matjaz Breskvar (phoenix@bsemi.com)
complete change of TLB miss handling.
rewrite of exceptions handling.
fully functional sash-3.6 in default initrd.
a much improved version with changes all around.
-10. 04. 2004 Matjaz Breskvar (phoenix@bsemi.com)
+10-04-2004 Matjaz Breskvar (phoenix@bsemi.com)
alot of bugfixes all over.
ethernet support, functional http and telnet servers.
running many standard linux apps.
-26. 06. 2004 Matjaz Breskvar (phoenix@bsemi.com)
+26-06-2004 Matjaz Breskvar (phoenix@bsemi.com)
port to 2.6.x
-30. 11. 2004 Matjaz Breskvar (phoenix@bsemi.com)
+30-11-2004 Matjaz Breskvar (phoenix@bsemi.com)
lots of bugfixes and enhancments.
added opencores framebuffer driver.
-09. 10. 2010 Jonas Bonn (jonas@southpole.se)
+09-10-2010 Jonas Bonn (jonas@southpole.se)
major rewrite to bring up to par with upstream Linux 2.6.36
diff --git a/Documentation/openrisc/TODO b/Documentation/openrisc/todo.rst
similarity index 78%
rename from Documentation/openrisc/TODO
rename to Documentation/openrisc/todo.rst
index c43d4e1d14eb..420b18b87eda 100644
--- a/Documentation/openrisc/TODO
+++ b/Documentation/openrisc/todo.rst
@@ -1,12 +1,15 @@
+====
+TODO
+====
+
The OpenRISC Linux port is fully functional and has been tracking upstream
since 2.6.35. There are, however, remaining items to be completed within
the coming months. Here's a list of known-to-be-less-than-stellar items
that are due for investigation shortly, i.e. our TODO list:
--- Implement the rest of the DMA API... dma_map_sg, etc.
+- Implement the rest of the DMA API... dma_map_sg, etc.
--- Finish the renaming cleanup... there are references to or32 in the code
+- Finish the renaming cleanup... there are references to or32 in the code
which was an older name for the architecture. The name we've settled on is
or1k and this change is slowly trickling through the stack. For the time
being, or32 is equivalent to or1k.
-
--
2.21.0
^ permalink raw reply related
* [PATCH 20/22] docs: net: convert two README files to ReST format
From: Mauro Carvalho Chehab @ 2019-07-22 11:07 UTC (permalink / raw)
Cc: Mauro Carvalho Chehab, David S. Miller, Jonathan Corbet,
Johannes Berg, netdev, linux-doc, linux-wireless
In-Reply-To: <cover.1563792333.git.mchehab+samsung@kernel.org>
There are two README files there with doesn't have a .txt
extension nor are at ReST format.
In order to help with the docs conversion to ReST, rename those
and manually convert them to ReST format.
As there are lot more to be done for networking to be part of
the documentation body, for now mark those two files with
:orphan:, in order to supress a build warning.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
.../networking/caif/{README => caif.rst} | 88 +++++++++++++------
.../{README => mac80211_hwsim.rst} | 28 ++++--
MAINTAINERS | 2 +-
3 files changed, 81 insertions(+), 37 deletions(-)
rename Documentation/networking/caif/{README => caif.rst} (70%)
rename Documentation/networking/mac80211_hwsim/{README => mac80211_hwsim.rst} (81%)
diff --git a/Documentation/networking/caif/README b/Documentation/networking/caif/caif.rst
similarity index 70%
rename from Documentation/networking/caif/README
rename to Documentation/networking/caif/caif.rst
index 757ccfaa1385..07afc8063d4d 100644
--- a/Documentation/networking/caif/README
+++ b/Documentation/networking/caif/caif.rst
@@ -1,18 +1,31 @@
-Copyright (C) ST-Ericsson AB 2010
-Author: Sjur Brendeland/ sjur.brandeland@stericsson.com
-License terms: GNU General Public License (GPL) version 2
----------------------------------------------------------
+:orphan:
-=== Start ===
-If you have compiled CAIF for modules do:
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: <isonum.txt>
-$modprobe crc_ccitt
-$modprobe caif
-$modprobe caif_socket
-$modprobe chnl_net
+================
+Using Linux CAIF
+================
-=== Preparing the setup with a STE modem ===
+
+:Copyright: |copy| ST-Ericsson AB 2010
+
+:Author: Sjur Brendeland/ sjur.brandeland@stericsson.com
+
+Start
+=====
+
+If you have compiled CAIF for modules do::
+
+ $modprobe crc_ccitt
+ $modprobe caif
+ $modprobe caif_socket
+ $modprobe chnl_net
+
+
+Preparing the setup with a STE modem
+====================================
If you are working on integration of CAIF you should make sure
that the kernel is built with module support.
@@ -32,24 +45,30 @@ module parameter "ser_use_stx".
Normally Frame Checksum is always used on UART, but this is also provided as a
module parameter "ser_use_fcs".
-$ modprobe caif_serial ser_ttyname=/dev/ttyS0 ser_use_stx=yes
-$ ifconfig caif_ttyS0 up
+::
-PLEASE NOTE: There is a limitation in Android shell.
+ $ modprobe caif_serial ser_ttyname=/dev/ttyS0 ser_use_stx=yes
+ $ ifconfig caif_ttyS0 up
+
+PLEASE NOTE:
+ There is a limitation in Android shell.
It only accepts one argument to insmod/modprobe!
-=== Trouble shooting ===
+Trouble shooting
+================
There are debugfs parameters provided for serial communication.
/sys/kernel/debug/caif_serial/<tty-name>/
* ser_state: Prints the bit-mask status where
+
- 0x02 means SENDING, this is a transient state.
- 0x10 means FLOW_OFF_SENT, i.e. the previous frame has not been sent
- and is blocking further send operation. Flow OFF has been propagated
- to all CAIF Channels using this TTY.
+ and is blocking further send operation. Flow OFF has been propagated
+ to all CAIF Channels using this TTY.
* tty_status: Prints the bit-mask tty status information
+
- 0x01 - tty->warned is on.
- 0x02 - tty->low_latency is on.
- 0x04 - tty->packed is on.
@@ -58,13 +77,17 @@ There are debugfs parameters provided for serial communication.
- 0x20 - tty->stopped is on.
* last_tx_msg: Binary blob Prints the last transmitted frame.
- This can be printed with
+
+ This can be printed with::
+
$od --format=x1 /sys/kernel/debug/caif_serial/<tty>/last_rx_msg.
- The first two tx messages sent look like this. Note: The initial
- byte 02 is start of frame extension (STX) used for re-syncing
- upon errors.
- - Enumeration:
+ The first two tx messages sent look like this. Note: The initial
+ byte 02 is start of frame extension (STX) used for re-syncing
+ upon errors.
+
+ - Enumeration::
+
0000000 02 05 00 00 03 01 d2 02
| | | | | |
STX(1) | | | |
@@ -73,7 +96,9 @@ There are debugfs parameters provided for serial communication.
Command:Enumeration(1)
Link-ID(1)
Checksum(2)
- - Channel Setup:
+
+ - Channel Setup::
+
0000000 02 07 00 00 00 21 a1 00 48 df
| | | | | | | |
STX(1) | | | | | |
@@ -86,13 +111,18 @@ There are debugfs parameters provided for serial communication.
Checksum(2)
* last_rx_msg: Prints the last transmitted frame.
- The RX messages for LinkSetup look almost identical but they have the
- bit 0x20 set in the command bit, and Channel Setup has added one byte
- before Checksum containing Channel ID.
- NOTE: Several CAIF Messages might be concatenated. The maximum debug
+
+ The RX messages for LinkSetup look almost identical but they have the
+ bit 0x20 set in the command bit, and Channel Setup has added one byte
+ before Checksum containing Channel ID.
+
+ NOTE:
+ Several CAIF Messages might be concatenated. The maximum debug
buffer size is 128 bytes.
-== Error Scenarios:
+Error Scenarios
+===============
+
- last_tx_msg contains channel setup message and last_rx_msg is empty ->
The host seems to be able to send over the UART, at least the CAIF ldisc get
notified that sending is completed.
@@ -103,7 +133,9 @@ There are debugfs parameters provided for serial communication.
- if /sys/kernel/debug/caif_serial/<tty>/tty_status is non-zero there
might be problems transmitting over UART.
+
E.g. host and modem wiring is not correct you will typically see
tty_status = 0x10 (hw_stopped) and ser_state = 0x10 (FLOW_OFF_SENT).
+
You will probably see the enumeration message in last_tx_message
and empty last_rx_message.
diff --git a/Documentation/networking/mac80211_hwsim/README b/Documentation/networking/mac80211_hwsim/mac80211_hwsim.rst
similarity index 81%
rename from Documentation/networking/mac80211_hwsim/README
rename to Documentation/networking/mac80211_hwsim/mac80211_hwsim.rst
index 3566a725d19c..d2266ce5534e 100644
--- a/Documentation/networking/mac80211_hwsim/README
+++ b/Documentation/networking/mac80211_hwsim/mac80211_hwsim.rst
@@ -1,5 +1,13 @@
+:orphan:
+
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: <isonum.txt>
+
+===================================================================
mac80211_hwsim - software simulator of 802.11 radio(s) for mac80211
-Copyright (c) 2008, Jouni Malinen <j@w1.fi>
+===================================================================
+
+:Copyright: |copy| 2008, Jouni Malinen <j@w1.fi>
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License version 2 as
@@ -7,6 +15,7 @@ published by the Free Software Foundation.
Introduction
+============
mac80211_hwsim is a Linux kernel module that can be used to simulate
arbitrary number of IEEE 802.11 radios for mac80211. It can be used to
@@ -43,6 +52,7 @@ regardless of channel.
Simple example
+==============
This example shows how to use mac80211_hwsim to simulate two radios:
one to act as an access point and the other as a station that
@@ -50,17 +60,19 @@ associates with the AP. hostapd and wpa_supplicant are used to take
care of WPA2-PSK authentication. In addition, hostapd is also
processing access point side of association.
+::
-# Build mac80211_hwsim as part of kernel configuration
-# Load the module
-modprobe mac80211_hwsim
+ # Build mac80211_hwsim as part of kernel configuration
-# Run hostapd (AP) for wlan0
-hostapd hostapd.conf
+ # Load the module
+ modprobe mac80211_hwsim
-# Run wpa_supplicant (station) for wlan1
-wpa_supplicant -Dnl80211 -iwlan1 -c wpa_supplicant.conf
+ # Run hostapd (AP) for wlan0
+ hostapd hostapd.conf
+
+ # Run wpa_supplicant (station) for wlan1
+ wpa_supplicant -Dnl80211 -iwlan1 -c wpa_supplicant.conf
More test cases are available in hostap.git:
diff --git a/MAINTAINERS b/MAINTAINERS
index 665c3c1e939b..634d229fbfff 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -9568,7 +9568,7 @@ F: Documentation/networking/mac80211-injection.txt
F: include/net/mac80211.h
F: net/mac80211/
F: drivers/net/wireless/mac80211_hwsim.[ch]
-F: Documentation/networking/mac80211_hwsim/README
+F: Documentation/networking/mac80211_hwsim/mac80211_hwsim.rst
MAILBOX API
M: Jassi Brar <jassisinghbrar@gmail.com>
--
2.21.0
^ permalink raw reply related
page: next (older) | prev (newer) | latest
- recent:[subjects (threaded)|topics (new)|topics (active)]
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox