* Re: [PATCH v5] Documentation/checkpatch: Prefer strscpy/strscpy_pad over strcpy/strlcpy/strncpy
From: Joe Perches @ 2019-07-22 17:40 UTC (permalink / raw)
To: Kees Cook, NitinGote; +Cc: corbet, akpm, apw, linux-doc, kernel-hardening
In-Reply-To: <201907221029.B0CBED4F@keescook>
On Mon, 2019-07-22 at 10:30 -0700, Kees Cook wrote:
> On Wed, Jul 17, 2019 at 10:00:05AM +0530, NitinGote wrote:
> > From: Nitin Gote <nitin.r.gote@intel.com>
> >
> > Added check in checkpatch.pl to
> > 1. Deprecate strcpy() in favor of strscpy().
> > 2. Deprecate strlcpy() in favor of strscpy().
> > 3. Deprecate strncpy() in favor of strscpy() or strscpy_pad().
> >
> > Updated strncpy() section in Documentation/process/deprecated.rst
> > to cover strscpy_pad() case.
> >
> > Signed-off-by: Nitin Gote <nitin.r.gote@intel.com>
>
> Reviewed-by: Kees Cook <keescook@chromium.org>
>
> Joe, does this address your checkpatch concerns?
Well, kinda.
strscpy_pad isn't used anywhere in the kernel.
And
+ "strncpy" => "strscpy, strscpy_pad or for non-NUL-terminated strings, strncpy() can still be used, but destinations should be marked with __nonstring",
is a bit verbose. This could be simply:
+ "strncpy" => "strscpy - for non-NUL-terminated uses, strncpy() dst should be __nonstring",
And I still prefer adding stracpy as it
reduces code verbosity and eliminates defects.
^ permalink raw reply
* Re: [RFC PATCH] string.h: Add stracpy/stracpy_pad (was: Re: [PATCH] checkpatch: Added warnings in favor of strscpy().)
From: Kees Cook @ 2019-07-22 17:33 UTC (permalink / raw)
To: Joe Perches
Cc: Nitin Gote, akpm, corbet, apw, linux-doc, linux-kernel,
kernel-hardening, Rasmus Villemoes
In-Reply-To: <d1524130f91d7cfd61bc736623409693d2895f57.camel@perches.com>
On Thu, Jul 04, 2019 at 05:15:57PM -0700, Joe Perches wrote:
> On Thu, 2019-07-04 at 13:46 -0700, Joe Perches wrote:
> > On Thu, 2019-07-04 at 11:24 +0530, Nitin Gote wrote:
> > > Added warnings in checkpatch.pl script to :
> > >
> > > 1. Deprecate strcpy() in favor of strscpy().
> > > 2. Deprecate strlcpy() in favor of strscpy().
> > > 3. Deprecate strncpy() in favor of strscpy() or strscpy_pad().
> > >
> > > Updated strncpy() section in Documentation/process/deprecated.rst
> > > to cover strscpy_pad() case.
>
> []
>
> I sent a patch series for some strscpy/strlcpy misuses.
>
> How about adding a macro helper to avoid the misuses like:
> ---
> include/linux/string.h | 16 ++++++++++++++++
> 1 file changed, 16 insertions(+)
>
> diff --git a/include/linux/string.h b/include/linux/string.h
> index 4deb11f7976b..ef01bd6f19df 100644
> --- a/include/linux/string.h
> +++ b/include/linux/string.h
> @@ -35,6 +35,22 @@ ssize_t strscpy(char *, const char *, size_t);
> /* Wraps calls to strscpy()/memset(), no arch specific code required */
> ssize_t strscpy_pad(char *dest, const char *src, size_t count);
>
> +#define stracpy(to, from) \
> +({ \
> + size_t size = ARRAY_SIZE(to); \
> + BUILD_BUG_ON(!__same_type(typeof(*to), char)); \
> + \
> + strscpy(to, from, size); \
> +})
> +
> +#define stracpy_pad(to, from) \
> +({ \
> + size_t size = ARRAY_SIZE(to); \
> + BUILD_BUG_ON(!__same_type(typeof(*to), char)); \
> + \
> + strscpy_pad(to, from, size); \
> +})
> +
> #ifndef __HAVE_ARCH_STRCAT
> extern char * strcat(char *, const char *);
> #endif
This seems like a reasonable addition, yes. I think Coccinelle might
actually be able to find all the existing strscpy(dst, src, sizeof(dst))
cases to jump-start this conversion.
Devil's advocate: this adds yet more string handling functions... will
this cause even more confusion?
--
Kees Cook
^ permalink raw reply
* Re: [PATCH v5] Documentation/checkpatch: Prefer strscpy/strscpy_pad over strcpy/strlcpy/strncpy
From: Kees Cook @ 2019-07-22 17:30 UTC (permalink / raw)
To: NitinGote; +Cc: joe, corbet, akpm, apw, linux-doc, kernel-hardening
In-Reply-To: <20190717043005.19627-1-nitin.r.gote@intel.com>
On Wed, Jul 17, 2019 at 10:00:05AM +0530, NitinGote wrote:
> From: Nitin Gote <nitin.r.gote@intel.com>
>
> Added check in checkpatch.pl to
> 1. Deprecate strcpy() in favor of strscpy().
> 2. Deprecate strlcpy() in favor of strscpy().
> 3. Deprecate strncpy() in favor of strscpy() or strscpy_pad().
>
> Updated strncpy() section in Documentation/process/deprecated.rst
> to cover strscpy_pad() case.
>
> Signed-off-by: Nitin Gote <nitin.r.gote@intel.com>
Reviewed-by: Kees Cook <keescook@chromium.org>
Joe, does this address your checkpatch concerns?
-Kees
> ---
> Documentation/process/deprecated.rst | 6 +++---
> scripts/checkpatch.pl | 24 ++++++++++++++++++++++++
> 2 files changed, 27 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/process/deprecated.rst b/Documentation/process/deprecated.rst
> index 49e0f64a3427..c348ef9d44f5 100644
> --- a/Documentation/process/deprecated.rst
> +++ b/Documentation/process/deprecated.rst
> @@ -93,9 +93,9 @@ will be NUL terminated. This can lead to various linear read overflows
> and other misbehavior due to the missing termination. It also NUL-pads the
> destination buffer if the source contents are shorter than the destination
> buffer size, which may be a needless performance penalty for callers using
> -only NUL-terminated strings. The safe replacement is :c:func:`strscpy`.
> -(Users of :c:func:`strscpy` still needing NUL-padding will need an
> -explicit :c:func:`memset` added.)
> +only NUL-terminated strings. In this case, the safe replacement is
> +strscpy(). If, however, the destination buffer still needs NUL-padding,
> +the safe replacement is strscpy_pad().
>
> If a caller is using non-NUL-terminated strings, :c:func:`strncpy()` can
> still be used, but destinations should be marked with the `__nonstring
> diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl
> index bb28b178d929..1bb12127115d 100755
> --- a/scripts/checkpatch.pl
> +++ b/scripts/checkpatch.pl
> @@ -605,6 +605,20 @@ foreach my $entry (keys %deprecated_apis) {
> }
> $deprecated_apis_search = "(?:${deprecated_apis_search})";
>
> +our %deprecated_string_apis = (
> + "strcpy" => "strscpy",
> + "strlcpy" => "strscpy",
> + "strncpy" => "strscpy, strscpy_pad or for non-NUL-terminated strings, strncpy() can still be used, but destinations should be marked with __nonstring",
> +);
> +
> +#Create a search pattern for all these strings apis to speed up a loop below
> +our $deprecated_string_apis_search = "";
> +foreach my $entry (keys %deprecated_string_apis) {
> + $deprecated_string_apis_search .= '|' if ($deprecated_string_apis_search ne "");
> + $deprecated_string_apis_search .= $entry;
> +}
> +$deprecated_string_apis_search = "(?:${deprecated_string_apis_search})";
> +
> our $mode_perms_world_writable = qr{
> S_IWUGO |
> S_IWOTH |
> @@ -6446,6 +6460,16 @@ sub process {
> "Deprecated use of '$deprecated_api', prefer '$new_api' instead\n" . $herecurr);
> }
>
> +# check for string deprecated apis
> + if ($line =~ /\b($deprecated_string_apis_search)\b\s*\(/) {
> + my $deprecated_string_api = $1;
> + my $new_api = $deprecated_string_apis{$deprecated_string_api};
> + my $msg_level = \&WARN;
> + $msg_level = \&CHK if ($file);
> + &{$msg_level}("DEPRECATED_API",
> + "Deprecated use of '$deprecated_string_api', prefer '$new_api' instead\n" . $herecurr);
> + }
> +
> # check for various structs that are normally const (ops, kgdb, device_tree)
> # and avoid what seem like struct definitions 'struct foo {'
> if ($line !~ /\bconst\b/ &&
> --
> 2.17.1
>
--
Kees Cook
^ permalink raw reply
* Re: [PATCH 04/22] docs: spi: convert to ReST and add it to the kABI bookset
From: Mauro Carvalho Chehab @ 2019-07-22 15:51 UTC (permalink / raw)
To: Mark Brown
Cc: Jonathan Corbet, Jonathan Cameron, Hartmut Knaack,
Lars-Peter Clausen, Peter Meerwald-Stadler, linux-doc, linux-spi,
linux-iio, Jonathan Cameron
In-Reply-To: <20190722152110.GE4756@sirena.org.uk>
Em Mon, 22 Jul 2019 16:21:10 +0100
Mark Brown <broonie@kernel.org> escreveu:
> On Mon, Jul 22, 2019 at 10:10:35AM -0300, Mauro Carvalho Chehab wrote:
> > Mark Brown <broonie@kernel.org> escreveu:
>
> > > On Mon, Jul 22, 2019 at 08:07:31AM -0300, Mauro Carvalho Chehab wrote:
> > > > While there's one file there with briefily describes the uAPI,
> > > > the documentation was written just like most subsystems: focused
> > > > on kernel developers. So, add it together with driver-api books.
>
> > > Please use subject lines matching the style for the subsystem. This
> > > makes it easier for people to identify relevant patches.
>
> > Sure. Do you prefer this prefixed by:
>
> > spi: docs:
>
> > Or with something else?
>
> Anything starting with spi:
Ok.
>
> > > > Documentation/spi/{spidev => spidev.rst} | 30 +++--
> > >
> > > This is clearly a userspace focused document rather than a kernel
> > > internal one.
> >
> > True. What I've been doing so far is, for all drivers that I'm converting
> > with carries more than one documentation type (kABI, uABI and/or
> > admin-guide) is to keep the directory as-is, adding them under
> > this section at Documentation/index.rst:
...
> > Btw, if you look at spidev file, it contains stuff for both
> > userspace-api:
> >
> > "SPI devices have a limited userspace API, supporting basic half-duplex
> > read() and write() access to SPI slave devices. Using ioctl() requests,"
>
> > And for admin-guide:
>
> > "For a SPI device with chipselect C on bus B, you should see:
> >
> > /dev/spidevB.C ... character special device, major number 153 with
> > a dynamically chosen minor device number. "
>
> I think that split is higly artificial...
>
> > So, if we're willing to move it, the best is to do on a separate patch
> > with would split its contents into two files: admin-guide/spi-devices.rst and
> > userspace-api/spi-api.rst.
>
> ...
>
> > Ideally, we should split what's there at media/uapi into admin-guide
> > and userspace-api, but this would mean *a lot* of efforts. Not sure
> > if it is worth the effort.
>
> Is the admin/API stuff even sensible for things that are more embedded
> or desktop focused?
Yes. Btw, the plan is to add everything under Documentation/ABI at the
admin guide (parsed via some scripts).
> It feels very arbatrary and unhelpful for things
> like spidev where theuser is going to be writing a program.
I tend to agree with you. Doing such split may actually make things
worse for app developers, without providing much benefit for sysadmins.
I sent today an e-mail to the KS discussion ML about that, as, IMHO,
this is something that we should discuss at the Documentation track
there.
While the idea of having users/sysadmin-faced stuff at admin-guide
seems to be nice, doing it for driver-specific stuff could be overkill,
and will mean a lot of extra work.
Thanks,
Mauro
^ permalink raw reply
* Re: [PATCH 04/22] docs: spi: convert to ReST and add it to the kABI bookset
From: Mark Brown @ 2019-07-22 15:21 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Jonathan Corbet, Jonathan Cameron, Hartmut Knaack,
Lars-Peter Clausen, Peter Meerwald-Stadler, linux-doc, linux-spi,
linux-iio, Jonathan Cameron
In-Reply-To: <20190722101035.4f61c1bf@coco.lan>
[-- Attachment #1: Type: text/plain, Size: 2640 bytes --]
On Mon, Jul 22, 2019 at 10:10:35AM -0300, Mauro Carvalho Chehab wrote:
> Mark Brown <broonie@kernel.org> escreveu:
> > On Mon, Jul 22, 2019 at 08:07:31AM -0300, Mauro Carvalho Chehab wrote:
> > > While there's one file there with briefily describes the uAPI,
> > > the documentation was written just like most subsystems: focused
> > > on kernel developers. So, add it together with driver-api books.
> > Please use subject lines matching the style for the subsystem. This
> > makes it easier for people to identify relevant patches.
> Sure. Do you prefer this prefixed by:
> spi: docs:
> Or with something else?
Anything starting with spi:
> > > Documentation/spi/{spidev => spidev.rst} | 30 +++--
> >
> > This is clearly a userspace focused document rather than a kernel
> > internal one.
>
> True. What I've been doing so far is, for all drivers that I'm converting
> with carries more than one documentation type (kABI, uABI and/or
> admin-guide) is to keep the directory as-is, adding them under
> this section at Documentation/index.rst:
>
> Kernel API documentation
> ------------------------
>
> That's the case of media, input, hwmon, and so many other subsystems.
> Yet, you're right: this implies that there will be some things
> to be done, as the long-term documentation should be like:
>
> Documentation/admin-guide/{media, input, hwmon, spi, ...}
> Documentation/userspace-api/{media, input, hwmon, spi, ...}
> Documentation/driver-api/{media, input, hwmon, spi, ...}
> Btw, if you look at spidev file, it contains stuff for both
> userspace-api:
>
> "SPI devices have a limited userspace API, supporting basic half-duplex
> read() and write() access to SPI slave devices. Using ioctl() requests,"
> And for admin-guide:
> "For a SPI device with chipselect C on bus B, you should see:
>
> /dev/spidevB.C ... character special device, major number 153 with
> a dynamically chosen minor device number. "
I think that split is higly artificial...
> So, if we're willing to move it, the best is to do on a separate patch
> with would split its contents into two files: admin-guide/spi-devices.rst and
> userspace-api/spi-api.rst.
...
> Ideally, we should split what's there at media/uapi into admin-guide
> and userspace-api, but this would mean *a lot* of efforts. Not sure
> if it is worth the effort.
Is the admin/API stuff even sensible for things that are more embedded
or desktop focused? It feels very arbatrary and unhelpful for things
like spidev where theuser is going to be writing a program.
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]
^ permalink raw reply
* Re: [PATCH 01/22] docs: convert markdown documents to ReST
From: Rob Herring @ 2019-07-22 15:11 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Mark Rutland, Jonathan Corbet, devicetree, Linux Doc Mailing List
In-Reply-To: <40b78fbbe64108601c274d28b7c515b3cd29d206.1563792334.git.mchehab+samsung@kernel.org>
On Mon, Jul 22, 2019 at 5:08 AM Mauro Carvalho Chehab
<mchehab+samsung@kernel.org> wrote:
>
> The documentation standard is ReST and not markdown.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> Acked-by: Rob Herring <robh@kernel.org>
> ---
> Documentation/devicetree/writing-schema.md | 130 ---------------
> Documentation/devicetree/writing-schema.rst | 153 ++++++++++++++++++
Thinking about this some more, can you split this to a separate patch
for me to apply. I may have some changes to this file this cycle.
> ...entication.md => ubifs-authentication.rst} | 70 +++++---
> 3 files changed, 197 insertions(+), 156 deletions(-)
> delete mode 100644 Documentation/devicetree/writing-schema.md
> create mode 100644 Documentation/devicetree/writing-schema.rst
> rename Documentation/filesystems/{ubifs-authentication.md => ubifs-authentication.rst} (95%)
^ permalink raw reply
* Re: [PATCH 04/22] docs: spi: convert to ReST and add it to the kABI bookset
From: Mauro Carvalho Chehab @ 2019-07-22 13:10 UTC (permalink / raw)
To: Mark Brown
Cc: Jonathan Corbet, Jonathan Cameron, Hartmut Knaack,
Lars-Peter Clausen, Peter Meerwald-Stadler, linux-doc, linux-spi,
linux-iio, Jonathan Cameron
In-Reply-To: <20190722121151.GC4756@sirena.org.uk>
Em Mon, 22 Jul 2019 13:11:51 +0100
Mark Brown <broonie@kernel.org> escreveu:
> On Mon, Jul 22, 2019 at 08:07:31AM -0300, Mauro Carvalho Chehab wrote:
> > While there's one file there with briefily describes the uAPI,
> > the documentation was written just like most subsystems: focused
> > on kernel developers. So, add it together with driver-api books.
>
> Please use subject lines matching the style for the subsystem. This
> makes it easier for people to identify relevant patches.
Sure. Do you prefer this prefixed by:
spi: docs:
Or with something else?
> > Documentation/spi/{spidev => spidev.rst} | 30 +++--
>
> This is clearly a userspace focused document rather than a kernel
> internal one.
True. What I've been doing so far is, for all drivers that I'm converting
with carries more than one documentation type (kABI, uABI and/or
admin-guide) is to keep the directory as-is, adding them under
this section at Documentation/index.rst:
Kernel API documentation
------------------------
That's the case of media, input, hwmon, and so many other subsystems.
Yet, you're right: this implies that there will be some things
to be done, as the long-term documentation should be like:
Documentation/admin-guide/{media, input, hwmon, spi, ...}
Documentation/userspace-api/{media, input, hwmon, spi, ...}
Documentation/driver-api/{media, input, hwmon, spi, ...}
Btw, if you look at spidev file, it contains stuff for both
userspace-api:
"SPI devices have a limited userspace API, supporting basic half-duplex
read() and write() access to SPI slave devices. Using ioctl() requests,"
And for admin-guide:
"For a SPI device with chipselect C on bus B, you should see:
/dev/spidevB.C ... character special device, major number 153 with
a dynamically chosen minor device number. "
So, if we're willing to move it, the best is to do on a separate patch
with would split its contents into two files: admin-guide/spi-devices.rst and
userspace-api/spi-api.rst.
-
There are a couple of reasons why I opted for this strategy:
1) There are *lots* of docs that contain all 3 types of information
on it on a single file.
2) On media, we use SPHINXDIRS to produce the media book from our
devel tree:
https://linuxtv.org/downloads/v4l-dvb-apis-new/index.html
When documents are built with either PDF SPHINXDIRS, each subdir
will be on a different book and all inter-book cross-references
will break.
For this to be fixed, we'll likely need to use something like
intersphinx extension, but this would probably require a
per-subsystem mapping (for example, saying that, for media, the
site used to resolve broken cross references is linuxtv.org).
Maintaining it can be painful.
3) So far, I was unable to split even the media docs! Shame on
me! The reason is that this is not an easy task.
One interesting example is at what we consider to be the media
uAPI book. It actually contains both sysadmin and uAPI documentation.
For example, at:
Documentation/media/uapi/v4l/open.rst
You'll see that, while most things there belong to the admin
guide (device node descriptions, multiple opens, etc), it
mentions the Kernel userspace API - open(), read(), close() syscalls.
Splitting this file on two separate books won't be that easy.
Ideally, we should split what's there at media/uapi into admin-guide
and userspace-api, but this would mean *a lot* of efforts. Not sure
if it is worth the effort.
Thanks,
Mauro
^ permalink raw reply
* Re: [PATCH] mm, slab: Extend slab/shrink to shrink all the memcg caches
From: peter enderborg @ 2019-07-22 12:46 UTC (permalink / raw)
To: Waiman Long, Christoph Lameter, Pekka Enberg, David Rientjes,
Joonsoo Kim, Andrew Morton, Alexander Viro, Jonathan Corbet,
Luis Chamberlain, Kees Cook, Johannes Weiner, Michal Hocko,
Vladimir Davydov
Cc: linux-mm, linux-doc, linux-fsdevel, cgroups, linux-kernel,
Roman Gushchin, Shakeel Butt, Andrea Arcangeli
In-Reply-To: <20190702183730.14461-1-longman@redhat.com>
On 7/2/19 8:37 PM, Waiman Long wrote:
> Currently, a value of '1" is written to /sys/kernel/slab/<slab>/shrink
> file to shrink the slab by flushing all the per-cpu slabs and free
> slabs in partial lists. This applies only to the root caches, though.
>
> Extends this capability by shrinking all the child memcg caches and
> the root cache when a value of '2' is written to the shrink sysfs file.
>
> On a 4-socket 112-core 224-thread x86-64 system after a parallel kernel
> build, the the amount of memory occupied by slabs before shrinking
> slabs were:
>
> # grep task_struct /proc/slabinfo
> task_struct 7114 7296 7744 4 8 : tunables 0 0
> 0 : slabdata 1824 1824 0
> # grep "^S[lRU]" /proc/meminfo
> Slab: 1310444 kB
> SReclaimable: 377604 kB
> SUnreclaim: 932840 kB
>
> After shrinking slabs:
>
> # grep "^S[lRU]" /proc/meminfo
> Slab: 695652 kB
> SReclaimable: 322796 kB
> SUnreclaim: 372856 kB
> # grep task_struct /proc/slabinfo
> task_struct 2262 2572 7744 4 8 : tunables 0 0
> 0 : slabdata 643 643 0
What is the time between this measurement points? Should not the shrinked memory show up as reclaimable?
> Signed-off-by: Waiman Long <longman@redhat.com>
> ---
> Documentation/ABI/testing/sysfs-kernel-slab | 10 +++--
> mm/slab.h | 1 +
> mm/slab_common.c | 43 +++++++++++++++++++++
> mm/slub.c | 2 +
> 4 files changed, 52 insertions(+), 4 deletions(-)
>
> diff --git a/Documentation/ABI/testing/sysfs-kernel-slab b/Documentation/ABI/testing/sysfs-kernel-slab
> index 29601d93a1c2..2a3d0fc4b4ac 100644
> --- a/Documentation/ABI/testing/sysfs-kernel-slab
> +++ b/Documentation/ABI/testing/sysfs-kernel-slab
> @@ -429,10 +429,12 @@ KernelVersion: 2.6.22
> Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
> Christoph Lameter <cl@linux-foundation.org>
> Description:
> - The shrink file is written when memory should be reclaimed from
> - a cache. Empty partial slabs are freed and the partial list is
> - sorted so the slabs with the fewest available objects are used
> - first.
> + A value of '1' is written to the shrink file when memory should
> + be reclaimed from a cache. Empty partial slabs are freed and
> + the partial list is sorted so the slabs with the fewest
> + available objects are used first. When a value of '2' is
> + written, all the corresponding child memory cgroup caches
> + should be shrunk as well. All other values are invalid.
>
> What: /sys/kernel/slab/cache/slab_size
> Date: May 2007
> diff --git a/mm/slab.h b/mm/slab.h
> index 3b22931bb557..a16b2c7ff4dd 100644
> --- a/mm/slab.h
> +++ b/mm/slab.h
> @@ -174,6 +174,7 @@ int __kmem_cache_shrink(struct kmem_cache *);
> void __kmemcg_cache_deactivate(struct kmem_cache *s);
> void __kmemcg_cache_deactivate_after_rcu(struct kmem_cache *s);
> void slab_kmem_cache_release(struct kmem_cache *);
> +int kmem_cache_shrink_all(struct kmem_cache *s);
>
> struct seq_file;
> struct file;
> diff --git a/mm/slab_common.c b/mm/slab_common.c
> index 464faaa9fd81..493697ba1da5 100644
> --- a/mm/slab_common.c
> +++ b/mm/slab_common.c
> @@ -981,6 +981,49 @@ int kmem_cache_shrink(struct kmem_cache *cachep)
> }
> EXPORT_SYMBOL(kmem_cache_shrink);
>
> +/**
> + * kmem_cache_shrink_all - shrink a cache and all its memcg children
> + * @s: The root cache to shrink.
> + *
> + * Return: 0 if successful, -EINVAL if not a root cache
> + */
> +int kmem_cache_shrink_all(struct kmem_cache *s)
> +{
> + struct kmem_cache *c;
> +
> + if (!IS_ENABLED(CONFIG_MEMCG_KMEM)) {
> + kmem_cache_shrink(s);
> + return 0;
> + }
> + if (!is_root_cache(s))
> + return -EINVAL;
> +
> + /*
> + * The caller should have a reference to the root cache and so
> + * we don't need to take the slab_mutex. We have to take the
> + * slab_mutex, however, to iterate the memcg caches.
> + */
> + get_online_cpus();
> + get_online_mems();
> + kasan_cache_shrink(s);
> + __kmem_cache_shrink(s);
> +
> + mutex_lock(&slab_mutex);
> + for_each_memcg_cache(c, s) {
> + /*
> + * Don't need to shrink deactivated memcg caches.
> + */
> + if (s->flags & SLAB_DEACTIVATED)
> + continue;
> + kasan_cache_shrink(c);
> + __kmem_cache_shrink(c);
> + }
> + mutex_unlock(&slab_mutex);
> + put_online_mems();
> + put_online_cpus();
> + return 0;
> +}
> +
> bool slab_is_available(void)
> {
> return slab_state >= UP;
> diff --git a/mm/slub.c b/mm/slub.c
> index a384228ff6d3..5d7b0004c51f 100644
> --- a/mm/slub.c
> +++ b/mm/slub.c
> @@ -5298,6 +5298,8 @@ static ssize_t shrink_store(struct kmem_cache *s,
> {
> if (buf[0] == '1')
> kmem_cache_shrink(s);
> + else if (buf[0] == '2')
> + kmem_cache_shrink_all(s);
> else
> return -EINVAL;
> return length;
^ permalink raw reply
* Re: [PATCH 04/22] docs: spi: convert to ReST and add it to the kABI bookset
From: Mark Brown @ 2019-07-22 12:11 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Jonathan Corbet, Jonathan Cameron, Hartmut Knaack,
Lars-Peter Clausen, Peter Meerwald-Stadler, linux-doc, linux-spi,
linux-iio, Jonathan Cameron
In-Reply-To: <be171b438013f8824425595e3d637f5e7d466249.1563792334.git.mchehab+samsung@kernel.org>
[-- Attachment #1: Type: text/plain, Size: 540 bytes --]
On Mon, Jul 22, 2019 at 08:07:31AM -0300, Mauro Carvalho Chehab wrote:
> While there's one file there with briefily describes the uAPI,
> the documentation was written just like most subsystems: focused
> on kernel developers. So, add it together with driver-api books.
Please use subject lines matching the style for the subsystem. This
makes it easier for people to identify relevant patches.
> Documentation/spi/{spidev => spidev.rst} | 30 +++--
This is clearly a userspace focused document rather than a kernel
internal one.
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]
^ permalink raw reply
* Re: [PATCH 03/14] docs: fix broken doc references due to renames
From: Wolfram Sang @ 2019-07-22 11:38 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Paul E. McKenney, Josh Triplett, Steven Rostedt,
Mathieu Desnoyers, Lai Jiangshan, Joel Fernandes, Jonathan Corbet,
Rob Herring, Mark Rutland, Peter Zijlstra, Ingo Molnar,
Will Deacon, Alan Stern, Andrea Parri, Boqun Feng,
Nicholas Piggin, David Howells, Jade Alglave, Luc Maranget,
Akira Yokosawa, Daniel Lustig, Jerry Hoemann, Wim Van Sebroeck,
Guenter Roeck, Maarten Lankhorst, Maxime Ripard, Sean Paul,
David Airlie, Daniel Vetter, Ajay Gupta, Don Brace,
James E.J. Bottomley, Martin K. Petersen, rcu, linux-doc,
devicetree, linux-arch, linux-watchdog, dri-devel, linux-i2c,
esc.storagedev, linux-scsi
In-Reply-To: <aa415583bf6b812b0249093a601aa31412f3a1cf.1563277838.git.mchehab+samsung@kernel.org>
[-- Attachment #1: Type: text/plain, Size: 326 bytes --]
On Tue, Jul 16, 2019 at 09:10:42AM -0300, Mauro Carvalho Chehab wrote:
> Some files got renamed but probably due to some merge conflicts,
> a few references still point to the old locations.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Wolfram Sang <wsa@the-dreams.de> # I2C part
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply
* [PATCH 15/22] docs: index.rst: don't use genindex for pdf output
From: Mauro Carvalho Chehab @ 2019-07-22 11:07 UTC (permalink / raw)
Cc: Mauro Carvalho Chehab, Jonathan Corbet, Vinod Koul, Sanyog Kale,
Pierre-Louis Bossart, David S. Miller, Jaroslav Kysela,
Takashi Iwai, linux-doc, dmaengine, alsa-devel, netdev
In-Reply-To: <cover.1563792333.git.mchehab+samsung@kernel.org>
The genindex logic is meant to be used only for html output, as
pdf build has its own way to generate indexes.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/core-api/index.rst | 2 +-
Documentation/driver-api/dmaengine/index.rst | 2 +-
Documentation/driver-api/soundwire/index.rst | 2 +-
Documentation/networking/device_drivers/index.rst | 2 +-
Documentation/networking/index.rst | 2 +-
Documentation/sound/index.rst | 2 +-
6 files changed, 6 insertions(+), 6 deletions(-)
diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
index dfd8fad1e1ec..fa16a0538dcb 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -49,7 +49,7 @@ Interfaces for kernel debugging
debug-objects
tracepoint
-.. only:: subproject
+.. only:: subproject and html
Indices
=======
diff --git a/Documentation/driver-api/dmaengine/index.rst b/Documentation/driver-api/dmaengine/index.rst
index 3026fa975937..b9df904d0a79 100644
--- a/Documentation/driver-api/dmaengine/index.rst
+++ b/Documentation/driver-api/dmaengine/index.rst
@@ -47,7 +47,7 @@ This book adds some notes about PXA DMA
pxa_dma
-.. only:: subproject
+.. only:: subproject and html
Indices
=======
diff --git a/Documentation/driver-api/soundwire/index.rst b/Documentation/driver-api/soundwire/index.rst
index 6db026028f27..234911a0db99 100644
--- a/Documentation/driver-api/soundwire/index.rst
+++ b/Documentation/driver-api/soundwire/index.rst
@@ -10,7 +10,7 @@ SoundWire Documentation
error_handling
locking
-.. only:: subproject
+.. only:: subproject and html
Indices
=======
diff --git a/Documentation/networking/device_drivers/index.rst b/Documentation/networking/device_drivers/index.rst
index 2b7fefe72351..f724b7c69b9e 100644
--- a/Documentation/networking/device_drivers/index.rst
+++ b/Documentation/networking/device_drivers/index.rst
@@ -24,7 +24,7 @@ Contents:
google/gve
mellanox/mlx5
-.. only:: subproject
+.. only:: subproject and html
Indices
=======
diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst
index a46fca264bee..6739066acadb 100644
--- a/Documentation/networking/index.rst
+++ b/Documentation/networking/index.rst
@@ -31,7 +31,7 @@ Contents:
tls
tls-offload
-.. only:: subproject
+.. only:: subproject and html
Indices
=======
diff --git a/Documentation/sound/index.rst b/Documentation/sound/index.rst
index 47b89f014e69..4d7d42acf6df 100644
--- a/Documentation/sound/index.rst
+++ b/Documentation/sound/index.rst
@@ -12,7 +12,7 @@ Linux Sound Subsystem Documentation
hd-audio/index
cards/index
-.. only:: subproject
+.. only:: subproject and html
Indices
=======
--
2.21.0
^ permalink raw reply related
* [PATCH 13/22] docs: fs: convert docs without extension to ReST
From: Mauro Carvalho Chehab @ 2019-07-22 11:07 UTC (permalink / raw)
Cc: Mauro Carvalho Chehab, Jonathan Corbet, Steve French,
Mike Marshall, Martin Brandenburg, linux-doc, linux-cifs,
samba-technical, devel
In-Reply-To: <cover.1563792333.git.mchehab+samsung@kernel.org>
There are 3 remaining files without an extension inside the fs docs
dir.
Manually convert them to ReST.
In the case of the nfs/exporting.rst file, as the nfs docs
aren't ported yet, I opted to convert and add a :orphan: there,
with should be removed when it gets added into a nfs-specific
part of the fs documentation.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
...irectory-locking => directory-locking.rst} | 40 ++-
Documentation/filesystems/index.rst | 2 +
.../filesystems/{Locking => locking.rst} | 257 ++++++++++++------
.../nfs/{Exporting => exporting.rst} | 31 ++-
Documentation/filesystems/vfs.rst | 2 +-
fs/cifs/export.c | 2 +-
fs/exportfs/expfs.c | 2 +-
fs/isofs/export.c | 2 +-
fs/orangefs/file.c | 2 +-
include/linux/dcache.h | 2 +-
include/linux/exportfs.h | 2 +-
11 files changed, 225 insertions(+), 119 deletions(-)
rename Documentation/filesystems/{directory-locking => directory-locking.rst} (86%)
rename Documentation/filesystems/{Locking => locking.rst} (79%)
rename Documentation/filesystems/nfs/{Exporting => exporting.rst} (91%)
diff --git a/Documentation/filesystems/directory-locking b/Documentation/filesystems/directory-locking.rst
similarity index 86%
rename from Documentation/filesystems/directory-locking
rename to Documentation/filesystems/directory-locking.rst
index 4e32cb961e5b..de12016ee419 100644
--- a/Documentation/filesystems/directory-locking
+++ b/Documentation/filesystems/directory-locking.rst
@@ -1,12 +1,17 @@
- Locking scheme used for directory operations is based on two
+=================
+Directory Locking
+=================
+
+
+Locking scheme used for directory operations is based on two
kinds of locks - per-inode (->i_rwsem) and per-filesystem
(->s_vfs_rename_mutex).
- When taking the i_rwsem on multiple non-directory objects, we
+When taking the i_rwsem on multiple non-directory objects, we
always acquire the locks in order by increasing address. We'll call
that "inode pointer" order in the following.
- For our purposes all operations fall in 5 classes:
+For our purposes all operations fall in 5 classes:
1) read access. Locking rules: caller locks directory we are accessing.
The lock is taken shared.
@@ -27,25 +32,29 @@ NB: we might get away with locking the the source (and target in exchange
case) shared.
5) link creation. Locking rules:
+
* lock parent
* check that source is not a directory
* lock source
* call the method.
+
All locks are exclusive.
6) cross-directory rename. The trickiest in the whole bunch. Locking
rules:
+
* lock the filesystem
* lock parents in "ancestors first" order.
* find source and target.
* if old parent is equal to or is a descendent of target
- fail with -ENOTEMPTY
+ fail with -ENOTEMPTY
* if new parent is equal to or is a descendent of source
- fail with -ELOOP
+ fail with -ELOOP
* If it's an exchange, lock both the source and the target.
* If the target exists, lock it. If the source is a non-directory,
lock it. If we need to lock both, do so in inode pointer order.
* call the method.
+
All ->i_rwsem are taken exclusive. Again, we might get away with locking
the the source (and target in exchange case) shared.
@@ -54,10 +63,11 @@ read, modified or removed by method will be locked by caller.
If no directory is its own ancestor, the scheme above is deadlock-free.
+
Proof:
First of all, at any moment we have a partial ordering of the
-objects - A < B iff A is an ancestor of B.
+ objects - A < B iff A is an ancestor of B.
That ordering can change. However, the following is true:
@@ -77,32 +87,32 @@ objects - A < B iff A is an ancestor of B.
non-directory object, except renames, which take locks on source and
target in inode pointer order in the case they are not directories.)
- Now consider the minimal deadlock. Each process is blocked on
+Now consider the minimal deadlock. Each process is blocked on
attempt to acquire some lock and already holds at least one lock. Let's
consider the set of contended locks. First of all, filesystem lock is
not contended, since any process blocked on it is not holding any locks.
Thus all processes are blocked on ->i_rwsem.
- By (3), any process holding a non-directory lock can only be
+By (3), any process holding a non-directory lock can only be
waiting on another non-directory lock with a larger address. Therefore
the process holding the "largest" such lock can always make progress, and
non-directory objects are not included in the set of contended locks.
- Thus link creation can't be a part of deadlock - it can't be
+Thus link creation can't be a part of deadlock - it can't be
blocked on source and it means that it doesn't hold any locks.
- Any contended object is either held by cross-directory rename or
+Any contended object is either held by cross-directory rename or
has a child that is also contended. Indeed, suppose that it is held by
operation other than cross-directory rename. Then the lock this operation
is blocked on belongs to child of that object due to (1).
- It means that one of the operations is cross-directory rename.
+It means that one of the operations is cross-directory rename.
Otherwise the set of contended objects would be infinite - each of them
would have a contended child and we had assumed that no object is its
own descendent. Moreover, there is exactly one cross-directory rename
(see above).
- Consider the object blocking the cross-directory rename. One
+Consider the object blocking the cross-directory rename. One
of its descendents is locked by cross-directory rename (otherwise we
would again have an infinite set of contended objects). But that
means that cross-directory rename is taking locks out of order. Due
@@ -112,7 +122,7 @@ try to acquire lock on descendent before the lock on ancestor.
Contradiction. I.e. deadlock is impossible. Q.E.D.
- These operations are guaranteed to avoid loop creation. Indeed,
+These operations are guaranteed to avoid loop creation. Indeed,
the only operation that could introduce loops is cross-directory rename.
Since the only new (parent, child) pair added by rename() is (new parent,
source), such loop would have to contain these objects and the rest of it
@@ -123,13 +133,13 @@ new parent had been equal to or a descendent of source since the moment when
we had acquired filesystem lock and rename() would fail with -ELOOP in that
case.
- While this locking scheme works for arbitrary DAGs, it relies on
+While this locking scheme works for arbitrary DAGs, it relies on
ability to check that directory is a descendent of another object. Current
implementation assumes that directory graph is a tree. This assumption is
also preserved by all operations (cross-directory rename on a tree that would
not introduce a cycle will leave it a tree and link() fails for directories).
- Notice that "directory" in the above == "anything that might have
+Notice that "directory" in the above == "anything that might have
children", so if we are going to introduce hybrid objects we will need
either to make sure that link(2) doesn't work for them or to make changes
in is_subdir() that would make it work even in presence of such beasts.
diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst
index 2de2fe2ab078..08320c35d03b 100644
--- a/Documentation/filesystems/index.rst
+++ b/Documentation/filesystems/index.rst
@@ -20,6 +20,8 @@ algorithms work.
path-lookup
api-summary
splice
+ locking
+ directory-locking
Filesystem support layers
=========================
diff --git a/Documentation/filesystems/Locking b/Documentation/filesystems/locking.rst
similarity index 79%
rename from Documentation/filesystems/Locking
rename to Documentation/filesystems/locking.rst
index 204dd3ea36bb..fc3a0704553c 100644
--- a/Documentation/filesystems/Locking
+++ b/Documentation/filesystems/locking.rst
@@ -1,14 +1,22 @@
- The text below describes the locking rules for VFS-related methods.
+=======
+Locking
+=======
+
+The text below describes the locking rules for VFS-related methods.
It is (believed to be) up-to-date. *Please*, if you change anything in
prototypes or locking protocols - update this file. And update the relevant
instances in the tree, don't leave that to maintainers of filesystems/devices/
etc. At the very least, put the list of dubious cases in the end of this file.
Don't turn it into log - maintainers of out-of-the-tree code are supposed to
be able to use diff(1).
- Thing currently missing here: socket operations. Alexey?
---------------------------- dentry_operations --------------------------
-prototypes:
+Thing currently missing here: socket operations. Alexey?
+
+dentry_operations
+=================
+
+prototypes::
+
int (*d_revalidate)(struct dentry *, unsigned int);
int (*d_weak_revalidate)(struct dentry *, unsigned int);
int (*d_hash)(const struct dentry *, struct qstr *);
@@ -24,23 +32,30 @@ prototypes:
struct dentry *(*d_real)(struct dentry *, const struct inode *);
locking rules:
- rename_lock ->d_lock may block rcu-walk
-d_revalidate: no no yes (ref-walk) maybe
-d_weak_revalidate:no no yes no
-d_hash no no no maybe
-d_compare: yes no no maybe
-d_delete: no yes no no
-d_init: no no yes no
-d_release: no no yes no
-d_prune: no yes no no
-d_iput: no no yes no
-d_dname: no no no no
-d_automount: no no yes no
-d_manage: no no yes (ref-walk) maybe
-d_real no no yes no
---------------------------- inode_operations ---------------------------
-prototypes:
+================== =========== ======== ============== ========
+ops rename_lock ->d_lock may block rcu-walk
+================== =========== ======== ============== ========
+d_revalidate: no no yes (ref-walk) maybe
+d_weak_revalidate: no no yes no
+d_hash no no no maybe
+d_compare: yes no no maybe
+d_delete: no yes no no
+d_init: no no yes no
+d_release: no no yes no
+d_prune: no yes no no
+d_iput: no no yes no
+d_dname: no no no no
+d_automount: no no yes no
+d_manage: no no yes (ref-walk) maybe
+d_real no no yes no
+================== =========== ======== ============== ========
+
+inode_operations
+================
+
+prototypes::
+
int (*create) (struct inode *,struct dentry *,umode_t, bool);
struct dentry * (*lookup) (struct inode *,struct dentry *, unsigned int);
int (*link) (struct dentry *,struct inode *,struct dentry *);
@@ -68,7 +83,10 @@ prototypes:
locking rules:
all may block
- i_rwsem(inode)
+
+============ =============================================
+ops i_rwsem(inode)
+============ =============================================
lookup: shared
create: exclusive
link: exclusive (both)
@@ -89,17 +107,21 @@ fiemap: no
update_time: no
atomic_open: exclusive
tmpfile: no
+============ =============================================
Additionally, ->rmdir(), ->unlink() and ->rename() have ->i_rwsem
exclusive on victim.
cross-directory ->rename() has (per-superblock) ->s_vfs_rename_sem.
-See Documentation/filesystems/directory-locking for more detailed discussion
+See Documentation/filesystems/directory-locking.rst for more detailed discussion
of the locking scheme for directory operations.
------------------------ xattr_handler operations -----------------------
-prototypes:
+xattr_handler operations
+========================
+
+prototypes::
+
bool (*list)(struct dentry *dentry);
int (*get)(const struct xattr_handler *handler, struct dentry *dentry,
struct inode *inode, const char *name, void *buffer,
@@ -110,13 +132,20 @@ prototypes:
locking rules:
all may block
- i_rwsem(inode)
+
+===== ==============
+ops i_rwsem(inode)
+===== ==============
list: no
get: no
set: exclusive
+===== ==============
+
+super_operations
+================
+
+prototypes::
---------------------------- super_operations ---------------------------
-prototypes:
struct inode *(*alloc_inode)(struct super_block *sb);
void (*free_inode)(struct inode *);
void (*destroy_inode)(struct inode *);
@@ -138,7 +167,10 @@ prototypes:
locking rules:
All may block [not true, see below]
- s_umount
+
+====================== ============ ========================
+ops s_umount note
+====================== ============ ========================
alloc_inode:
free_inode: called from RCU callback
destroy_inode:
@@ -157,6 +189,7 @@ show_options: no (namespace_sem)
quota_read: no (see below)
quota_write: no (see below)
bdev_try_to_free_page: no (see below)
+====================== ============ ========================
->statfs() has s_umount (shared) when called by ustat(2) (native or
compat), but that's an accident of bad API; s_umount is used to pin
@@ -164,31 +197,44 @@ the superblock down when we only have dev_t given us by userland to
identify the superblock. Everything else (statfs(), fstatfs(), etc.)
doesn't hold it when calling ->statfs() - superblock is pinned down
by resolving the pathname passed to syscall.
+
->quota_read() and ->quota_write() functions are both guaranteed to
be the only ones operating on the quota file by the quota code (via
dqio_sem) (unless an admin really wants to screw up something and
writes to quota files with quotas on). For other details about locking
see also dquot_operations section.
+
->bdev_try_to_free_page is called from the ->releasepage handler of
the block device inode. See there for more details.
---------------------------- file_system_type ---------------------------
-prototypes:
+file_system_type
+================
+
+prototypes::
+
struct dentry *(*mount) (struct file_system_type *, int,
const char *, void *);
void (*kill_sb) (struct super_block *);
+
locking rules:
- may block
+
+======= =========
+ops may block
+======= =========
mount yes
kill_sb yes
+======= =========
->mount() returns ERR_PTR or the root dentry; its superblock should be locked
on return.
+
->kill_sb() takes a write-locked superblock, does all shutdown work on it,
unlocks and drops the reference.
---------------------------- address_space_operations --------------------------
-prototypes:
+address_space_operations
+========================
+prototypes::
+
int (*writepage)(struct page *page, struct writeback_control *wbc);
int (*readpage)(struct file *, struct page *);
int (*writepages)(struct address_space *, struct writeback_control *);
@@ -218,14 +264,16 @@ prototypes:
locking rules:
All except set_page_dirty and freepage may block
- PageLocked(page) i_rwsem
+====================== ======================== =========
+ops PageLocked(page) i_rwsem
+====================== ======================== =========
writepage: yes, unlocks (see below)
readpage: yes, unlocks
writepages:
set_page_dirty no
readpages:
-write_begin: locks the page exclusive
-write_end: yes, unlocks exclusive
+write_begin: locks the page exclusive
+write_end: yes, unlocks exclusive
bmap:
invalidatepage: yes
releasepage: yes
@@ -239,17 +287,18 @@ is_partially_uptodate: yes
error_remove_page: yes
swap_activate: no
swap_deactivate: no
+====================== ======================== =========
- ->write_begin(), ->write_end() and ->readpage() may be called from
+->write_begin(), ->write_end() and ->readpage() may be called from
the request handler (/dev/loop).
- ->readpage() unlocks the page, either synchronously or via I/O
+->readpage() unlocks the page, either synchronously or via I/O
completion.
- ->readpages() populates the pagecache with the passed pages and starts
+->readpages() populates the pagecache with the passed pages and starts
I/O against them. They come unlocked upon I/O completion.
- ->writepage() is used for two purposes: for "memory cleansing" and for
+->writepage() is used for two purposes: for "memory cleansing" and for
"sync". These are quite different operations and the behaviour may differ
depending upon the mode.
@@ -297,70 +346,81 @@ will leave the page itself marked clean but it will be tagged as dirty in the
radix tree. This incoherency can lead to all sorts of hard-to-debug problems
in the filesystem like having dirty inodes at umount and losing written data.
- ->writepages() is used for periodic writeback and for syscall-initiated
+->writepages() is used for periodic writeback and for syscall-initiated
sync operations. The address_space should start I/O against at least
-*nr_to_write pages. *nr_to_write must be decremented for each page which is
-written. The address_space implementation may write more (or less) pages
-than *nr_to_write asks for, but it should try to be reasonably close. If
-nr_to_write is NULL, all dirty pages must be written.
+``*nr_to_write`` pages. ``*nr_to_write`` must be decremented for each page
+which is written. The address_space implementation may write more (or less)
+pages than ``*nr_to_write`` asks for, but it should try to be reasonably close.
+If nr_to_write is NULL, all dirty pages must be written.
writepages should _only_ write pages which are present on
mapping->io_pages.
- ->set_page_dirty() is called from various places in the kernel
+->set_page_dirty() is called from various places in the kernel
when the target page is marked as needing writeback. It may be called
under spinlock (it cannot block) and is sometimes called with the page
not locked.
- ->bmap() is currently used by legacy ioctl() (FIBMAP) provided by some
+->bmap() is currently used by legacy ioctl() (FIBMAP) provided by some
filesystems and by the swapper. The latter will eventually go away. Please,
keep it that way and don't breed new callers.
- ->invalidatepage() is called when the filesystem must attempt to drop
+->invalidatepage() is called when the filesystem must attempt to drop
some or all of the buffers from the page when it is being truncated. It
returns zero on success. If ->invalidatepage is zero, the kernel uses
block_invalidatepage() instead.
- ->releasepage() is called when the kernel is about to try to drop the
+->releasepage() is called when the kernel is about to try to drop the
buffers from the page in preparation for freeing it. It returns zero to
indicate that the buffers are (or may be) freeable. If ->releasepage is zero,
the kernel assumes that the fs has no private interest in the buffers.
- ->freepage() is called when the kernel is done dropping the page
+->freepage() is called when the kernel is done dropping the page
from the page cache.
- ->launder_page() may be called prior to releasing a page if
+->launder_page() may be called prior to releasing a page if
it is still found to be dirty. It returns zero if the page was successfully
cleaned, or an error value if not. Note that in order to prevent the page
getting mapped back in and redirtied, it needs to be kept locked
across the entire operation.
- ->swap_activate will be called with a non-zero argument on
+->swap_activate will be called with a non-zero argument on
files backing (non block device backed) swapfiles. A return value
of zero indicates success, in which case this file can be used for
backing swapspace. The swapspace operations will be proxied to the
address space operations.
- ->swap_deactivate() will be called in the sys_swapoff()
+->swap_deactivate() will be called in the sys_swapoff()
path after ->swap_activate() returned success.
------------------------ file_lock_operations ------------------------------
-prototypes:
+file_lock_operations
+====================
+
+prototypes::
+
void (*fl_copy_lock)(struct file_lock *, struct file_lock *);
void (*fl_release_private)(struct file_lock *);
locking rules:
- inode->i_lock may block
+
+=================== ============= =========
+ops inode->i_lock may block
+=================== ============= =========
fl_copy_lock: yes no
-fl_release_private: maybe maybe[1]
+fl_release_private: maybe maybe[1]_
+=================== ============= =========
-[1]: ->fl_release_private for flock or POSIX locks is currently allowed
-to block. Leases however can still be freed while the i_lock is held and
-so fl_release_private called on a lease should not block.
+.. [1]:
+ ->fl_release_private for flock or POSIX locks is currently allowed
+ to block. Leases however can still be freed while the i_lock is held and
+ so fl_release_private called on a lease should not block.
+
+lock_manager_operations
+=======================
+
+prototypes::
------------------------ lock_manager_operations ---------------------------
-prototypes:
void (*lm_notify)(struct file_lock *); /* unblock callback */
int (*lm_grant)(struct file_lock *, struct file_lock *, int);
void (*lm_break)(struct file_lock *); /* break_lease callback */
@@ -368,24 +428,33 @@ prototypes:
locking rules:
- inode->i_lock blocked_lock_lock may block
+========== ============= ================= =========
+ops inode->i_lock blocked_lock_lock may block
+========== ============= ================= =========
lm_notify: yes yes no
lm_grant: no no no
lm_break: yes no no
lm_change yes no no
+========== ============= ================= =========
+
+buffer_head
+===========
+
+prototypes::
---------------------------- buffer_head -----------------------------------
-prototypes:
void (*b_end_io)(struct buffer_head *bh, int uptodate);
locking rules:
- called from interrupts. In other words, extreme care is needed here.
+
+called from interrupts. In other words, extreme care is needed here.
bh is locked, but that's all warranties we have here. Currently only RAID1,
highmem, fs/buffer.c, and fs/ntfs/aops.c are providing these. Block devices
call this method upon the IO completion.
---------------------------- block_device_operations -----------------------
-prototypes:
+block_device_operations
+=======================
+prototypes::
+
int (*open) (struct block_device *, fmode_t);
int (*release) (struct gendisk *, fmode_t);
int (*ioctl) (struct block_device *, fmode_t, unsigned, unsigned long);
@@ -399,7 +468,10 @@ prototypes:
void (*swap_slot_free_notify) (struct block_device *, unsigned long);
locking rules:
- bd_mutex
+
+======================= ===================
+ops bd_mutex
+======================= ===================
open: yes
release: yes
ioctl: no
@@ -410,6 +482,7 @@ unlock_native_capacity: no
revalidate_disk: no
getgeo: no
swap_slot_free_notify: no (see below)
+======================= ===================
media_changed, unlock_native_capacity and revalidate_disk are called only from
check_disk_change().
@@ -418,8 +491,11 @@ swap_slot_free_notify is called with swap_lock and sometimes the page lock
held.
---------------------------- file_operations -------------------------------
-prototypes:
+file_operations
+===============
+
+prototypes::
+
loff_t (*llseek) (struct file *, loff_t, int);
ssize_t (*read) (struct file *, char __user *, size_t, loff_t *);
ssize_t (*write) (struct file *, const char __user *, size_t, loff_t *);
@@ -455,7 +531,6 @@ prototypes:
size_t, unsigned int);
int (*setlease)(struct file *, long, struct file_lock **, void **);
long (*fallocate)(struct file *, int, loff_t, loff_t);
-};
locking rules:
All may block.
@@ -490,8 +565,11 @@ in sys_read() and friends.
the lease within the individual filesystem to record the result of the
operation
---------------------------- dquot_operations -------------------------------
-prototypes:
+dquot_operations
+================
+
+prototypes::
+
int (*write_dquot) (struct dquot *);
int (*acquire_dquot) (struct dquot *);
int (*release_dquot) (struct dquot *);
@@ -503,20 +581,26 @@ a proper locking wrt the filesystem and call the generic quota operations.
What filesystem should expect from the generic quota functions:
- FS recursion Held locks when called
+============== ============ =========================
+ops FS recursion Held locks when called
+============== ============ =========================
write_dquot: yes dqonoff_sem or dqptr_sem
acquire_dquot: yes dqonoff_sem or dqptr_sem
release_dquot: yes dqonoff_sem or dqptr_sem
mark_dirty: no -
write_info: yes dqonoff_sem
+============== ============ =========================
FS recursion means calling ->quota_read() and ->quota_write() from superblock
operations.
More details about quota locking can be found in fs/dquot.c.
---------------------------- vm_operations_struct -----------------------------
-prototypes:
+vm_operations_struct
+====================
+
+prototypes::
+
void (*open)(struct vm_area_struct*);
void (*close)(struct vm_area_struct*);
vm_fault_t (*fault)(struct vm_area_struct*, struct vm_fault *);
@@ -525,7 +609,10 @@ prototypes:
int (*access)(struct vm_area_struct *, unsigned long, void*, int, int);
locking rules:
- mmap_sem PageLocked(page)
+
+============= ======== ===========================
+ops mmap_sem PageLocked(page)
+============= ======== ===========================
open: yes
close: yes
fault: yes can return with page locked
@@ -533,8 +620,9 @@ map_pages: yes
page_mkwrite: yes can return with page locked
pfn_mkwrite: yes
access: yes
+============= ======== ===========================
- ->fault() is called when a previously not present pte is about
+->fault() is called when a previously not present pte is about
to be faulted in. The filesystem must find and return the page associated
with the passed in "pgoff" in the vm_fault structure. If it is possible that
the page may be truncated and/or invalidated, then the filesystem must lock
@@ -542,7 +630,7 @@ the page, then ensure it is not already truncated (the page lock will block
subsequent truncate), and then return with VM_FAULT_LOCKED, and the page
locked. The VM will unlock the page.
- ->map_pages() is called when VM asks to map easy accessible pages.
+->map_pages() is called when VM asks to map easy accessible pages.
Filesystem should find and map pages associated with offsets from "start_pgoff"
till "end_pgoff". ->map_pages() is called with page table locked and must
not block. If it's not possible to reach a page without blocking,
@@ -551,25 +639,26 @@ page table entry. Pointer to entry associated with the page is passed in
"pte" field in vm_fault structure. Pointers to entries for other offsets
should be calculated relative to "pte".
- ->page_mkwrite() is called when a previously read-only pte is
+->page_mkwrite() is called when a previously read-only pte is
about to become writeable. The filesystem again must ensure that there are
no truncate/invalidate races, and then return with the page locked. If
the page has been truncated, the filesystem should not look up a new page
like the ->fault() handler, but simply return with VM_FAULT_NOPAGE, which
will cause the VM to retry the fault.
- ->pfn_mkwrite() is the same as page_mkwrite but when the pte is
+->pfn_mkwrite() is the same as page_mkwrite but when the pte is
VM_PFNMAP or VM_MIXEDMAP with a page-less entry. Expected return is
VM_FAULT_NOPAGE. Or one of the VM_FAULT_ERROR types. The default behavior
after this call is to make the pte read-write, unless pfn_mkwrite returns
an error.
- ->access() is called when get_user_pages() fails in
+->access() is called when get_user_pages() fails in
access_process_vm(), typically used to debug a process through
/proc/pid/mem or ptrace. This function is needed only for
VM_IO | VM_PFNMAP VMAs.
-================================================================================
+--------------------------------------------------------------------------------
+
Dubious stuff
(if you break something or notice that it is broken and do not fix it yourself
diff --git a/Documentation/filesystems/nfs/Exporting b/Documentation/filesystems/nfs/exporting.rst
similarity index 91%
rename from Documentation/filesystems/nfs/Exporting
rename to Documentation/filesystems/nfs/exporting.rst
index 63889149f532..33d588a01ace 100644
--- a/Documentation/filesystems/nfs/Exporting
+++ b/Documentation/filesystems/nfs/exporting.rst
@@ -1,3 +1,4 @@
+:orphan:
Making Filesystems Exportable
=============================
@@ -42,9 +43,9 @@ filehandle fragment, there is no automatic creation of a path prefix
for the object. This leads to two related but distinct features of
the dcache that are not needed for normal filesystem access.
-1/ The dcache must sometimes contain objects that are not part of the
+1. The dcache must sometimes contain objects that are not part of the
proper prefix. i.e that are not connected to the root.
-2/ The dcache must be prepared for a newly found (via ->lookup) directory
+2. The dcache must be prepared for a newly found (via ->lookup) directory
to already have a (non-connected) dentry, and must be able to move
that dentry into place (based on the parent and name in the
->lookup). This is particularly needed for directories as
@@ -52,7 +53,7 @@ the dcache that are not needed for normal filesystem access.
To implement these features, the dcache has:
-a/ A dentry flag DCACHE_DISCONNECTED which is set on
+a. A dentry flag DCACHE_DISCONNECTED which is set on
any dentry that might not be part of the proper prefix.
This is set when anonymous dentries are created, and cleared when a
dentry is noticed to be a child of a dentry which is in the proper
@@ -71,48 +72,52 @@ a/ A dentry flag DCACHE_DISCONNECTED which is set on
dentries. That guarantees that we won't need to hunt them down upon
umount.
-b/ A primitive for creation of secondary roots - d_obtain_root(inode).
+b. A primitive for creation of secondary roots - d_obtain_root(inode).
Those do _not_ bear DCACHE_DISCONNECTED. They are placed on the
per-superblock list (->s_roots), so they can be located at umount
time for eviction purposes.
-c/ Helper routines to allocate anonymous dentries, and to help attach
+c. Helper routines to allocate anonymous dentries, and to help attach
loose directory dentries at lookup time. They are:
+
d_obtain_alias(inode) will return a dentry for the given inode.
If the inode already has a dentry, one of those is returned.
+
If it doesn't, a new anonymous (IS_ROOT and
- DCACHE_DISCONNECTED) dentry is allocated and attached.
+ DCACHE_DISCONNECTED) dentry is allocated and attached.
+
In the case of a directory, care is taken that only one dentry
can ever be attached.
+
d_splice_alias(inode, dentry) will introduce a new dentry into the tree;
either the passed-in dentry or a preexisting alias for the given inode
(such as an anonymous one created by d_obtain_alias), if appropriate.
It returns NULL when the passed-in dentry is used, following the calling
convention of ->lookup.
-
+
Filesystem Issues
-----------------
For a filesystem to be exportable it must:
-
- 1/ provide the filehandle fragment routines described below.
- 2/ make sure that d_splice_alias is used rather than d_add
+
+ 1. provide the filehandle fragment routines described below.
+ 2. make sure that d_splice_alias is used rather than d_add
when ->lookup finds an inode for a given parent and name.
- If inode is NULL, d_splice_alias(inode, dentry) is equivalent to
+ If inode is NULL, d_splice_alias(inode, dentry) is equivalent to::
d_add(dentry, inode), NULL
Similarly, d_splice_alias(ERR_PTR(err), dentry) = ERR_PTR(err)
- Typically the ->lookup routine will simply end with a:
+ Typically the ->lookup routine will simply end with a::
return d_splice_alias(inode, dentry);
}
- A file system implementation declares that instances of the filesystem
+A file system implementation declares that instances of the filesystem
are exportable by setting the s_export_op field in the struct
super_block. This field must point to a "struct export_operations"
struct which has the following members:
diff --git a/Documentation/filesystems/vfs.rst b/Documentation/filesystems/vfs.rst
index 0f85ab21c2ca..7d4d09dd5e6d 100644
--- a/Documentation/filesystems/vfs.rst
+++ b/Documentation/filesystems/vfs.rst
@@ -20,7 +20,7 @@ kernel which allows different filesystem implementations to coexist.
VFS system calls open(2), stat(2), read(2), write(2), chmod(2) and so on
are called from a process context. Filesystem locking is described in
-the document Documentation/filesystems/Locking.
+the document Documentation/filesystems/locking.rst.
Directory Entry Cache (dcache)
diff --git a/fs/cifs/export.c b/fs/cifs/export.c
index ce8b7f677c58..eb0bb8ca8e63 100644
--- a/fs/cifs/export.c
+++ b/fs/cifs/export.c
@@ -24,7 +24,7 @@
*/
/*
- * See Documentation/filesystems/nfs/Exporting
+ * See Documentation/filesystems/nfs/exporting.rst
* and examples in fs/exportfs
*
* Since cifs is a network file system, an "fsid" must be included for
diff --git a/fs/exportfs/expfs.c b/fs/exportfs/expfs.c
index f0e549783caf..09bc68708d28 100644
--- a/fs/exportfs/expfs.c
+++ b/fs/exportfs/expfs.c
@@ -7,7 +7,7 @@
* and for mapping back from file handles to dentries.
*
* For details on why we do all the strange and hairy things in here
- * take a look at Documentation/filesystems/nfs/Exporting.
+ * take a look at Documentation/filesystems/nfs/exporting.rst.
*/
#include <linux/exportfs.h>
#include <linux/fs.h>
diff --git a/fs/isofs/export.c b/fs/isofs/export.c
index 85a9093769a9..35768a63fb1d 100644
--- a/fs/isofs/export.c
+++ b/fs/isofs/export.c
@@ -10,7 +10,7 @@
*
* The following files are helpful:
*
- * Documentation/filesystems/nfs/Exporting
+ * Documentation/filesystems/nfs/exporting.rst
* fs/exportfs/expfs.c.
*/
diff --git a/fs/orangefs/file.c b/fs/orangefs/file.c
index 960f9a3c012d..a5612abc0936 100644
--- a/fs/orangefs/file.c
+++ b/fs/orangefs/file.c
@@ -555,7 +555,7 @@ static int orangefs_fsync(struct file *file,
* Change the file pointer position for an instance of an open file.
*
* \note If .llseek is overriden, we must acquire lock as described in
- * Documentation/filesystems/Locking.
+ * Documentation/filesystems/locking.rst.
*
* Future upgrade could support SEEK_DATA and SEEK_HOLE but would
* require much changes to the FS
diff --git a/include/linux/dcache.h b/include/linux/dcache.h
index 9451011ac014..10090f11ab95 100644
--- a/include/linux/dcache.h
+++ b/include/linux/dcache.h
@@ -151,7 +151,7 @@ struct dentry_operations {
/*
* Locking rules for dentry_operations callbacks are to be found in
- * Documentation/filesystems/Locking. Keep it updated!
+ * Documentation/filesystems/locking.rst. Keep it updated!
*
* FUrther descriptions are found in Documentation/filesystems/vfs.rst.
* Keep it updated too!
diff --git a/include/linux/exportfs.h b/include/linux/exportfs.h
index 0d3037419bc7..cf6571fc9c01 100644
--- a/include/linux/exportfs.h
+++ b/include/linux/exportfs.h
@@ -139,7 +139,7 @@ struct fid {
* @get_parent: find the parent of a given directory
* @commit_metadata: commit metadata changes to stable storage
*
- * See Documentation/filesystems/nfs/Exporting for details on how to use
+ * See Documentation/filesystems/nfs/exporting.rst for details on how to use
* this interface correctly.
*
* encode_fh:
--
2.21.0
^ permalink raw reply related
* [PATCH 19/22] docs: nios2: add it to the main Documentation body
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>
Rename and add the nios2 documentation to the documentation
body.
The nios2 document is already on an ReST compatible format.
All it needs is that the title of the document to be promoted
one level.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/index.rst | 1 +
Documentation/nios2/{README => nios2.rst} | 1 +
2 files changed, 2 insertions(+)
rename Documentation/nios2/{README => nios2.rst} (96%)
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 09d24878ad14..0a564f3c336e 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -151,6 +151,7 @@ implementation.
m68k/index
powerpc/index
mips/index
+ nios2/nios2
openrisc/index
parisc/index
riscv/index
diff --git a/Documentation/nios2/README b/Documentation/nios2/nios2.rst
similarity index 96%
rename from Documentation/nios2/README
rename to Documentation/nios2/nios2.rst
index 054a67d55563..43da3f7cee76 100644
--- a/Documentation/nios2/README
+++ b/Documentation/nios2/nios2.rst
@@ -1,3 +1,4 @@
+=================================
Linux on the Nios II architecture
=================================
--
2.21.0
^ permalink raw reply related
* [PATCH 18/22] docs: hwmon: pxe1610: convert to ReST format and add to the index
From: Mauro Carvalho Chehab @ 2019-07-22 11:07 UTC (permalink / raw)
Cc: Mauro Carvalho Chehab, Jean Delvare, Guenter Roeck,
Jonathan Corbet, linux-hwmon, linux-doc
In-Reply-To: <cover.1563792333.git.mchehab+samsung@kernel.org>
This document was recently introduced. Convert it to ReST
just like the other hwmon documents, adding it to the hwmon index.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/hwmon/index.rst | 1 +
Documentation/hwmon/{pxe1610 => pxe1610.rst} | 33 +++++++++++++++-----
2 files changed, 26 insertions(+), 8 deletions(-)
rename Documentation/hwmon/{pxe1610 => pxe1610.rst} (82%)
diff --git a/Documentation/hwmon/index.rst b/Documentation/hwmon/index.rst
index ee090e51653a..4d5f5fec43a3 100644
--- a/Documentation/hwmon/index.rst
+++ b/Documentation/hwmon/index.rst
@@ -130,6 +130,7 @@ Hardware Monitoring Kernel Drivers
pcf8591
pmbus
powr1220
+ pxe1610
pwm-fan
raspberrypi-hwmon
sch5627
diff --git a/Documentation/hwmon/pxe1610 b/Documentation/hwmon/pxe1610.rst
similarity index 82%
rename from Documentation/hwmon/pxe1610
rename to Documentation/hwmon/pxe1610.rst
index 211cedeefb44..4f2388840d06 100644
--- a/Documentation/hwmon/pxe1610
+++ b/Documentation/hwmon/pxe1610.rst
@@ -2,19 +2,29 @@ Kernel driver pxe1610
=====================
Supported chips:
+
* Infineon PXE1610
+
Prefix: 'pxe1610'
+
Addresses scanned: -
+
Datasheet: Datasheet is not publicly available.
* Infineon PXE1110
+
Prefix: 'pxe1110'
+
Addresses scanned: -
+
Datasheet: Datasheet is not publicly available.
* Infineon PXM1310
+
Prefix: 'pxm1310'
+
Addresses scanned: -
+
Datasheet: Datasheet is not publicly available.
Author: Vijay Khemka <vijaykhemka@fb.com>
@@ -25,14 +35,19 @@ Description
PXE1610/PXE1110 are Multi-rail/Multiphase Digital Controllers
and compliant to
- -- Intel VR13 DC-DC converter specifications.
- -- Intel SVID protocol.
+
+ - Intel VR13 DC-DC converter specifications.
+ - Intel SVID protocol.
+
Used for Vcore power regulation for Intel VR13 based microprocessors
- -- Servers, Workstations, and High-end desktops
+
+ - Servers, Workstations, and High-end desktops
PXM1310 is a Multi-rail Controller and it is compliant to
- -- Intel VR13 DC-DC converter specifications.
- -- Intel SVID protocol.
+
+ - Intel VR13 DC-DC converter specifications.
+ - Intel SVID protocol.
+
Used for DDR3/DDR4 Memory power regulation for Intel VR13 and
IMVP8 based systems
@@ -44,10 +59,10 @@ This driver does not probe for PMBus devices. You will have
to instantiate devices explicitly.
Example: the following commands will load the driver for an PXE1610
-at address 0x70 on I2C bus #4:
+at address 0x70 on I2C bus #4::
-# modprobe pxe1610
-# echo pxe1610 0x70 > /sys/bus/i2c/devices/i2c-4/new_device
+ # modprobe pxe1610
+ # echo pxe1610 0x70 > /sys/bus/i2c/devices/i2c-4/new_device
It can also be instantiated by declaring in device tree
@@ -55,6 +70,7 @@ It can also be instantiated by declaring in device tree
Sysfs attributes
----------------
+====================== ====================================
curr1_label "iin"
curr1_input Measured input current
curr1_alarm Current high alarm
@@ -88,3 +104,4 @@ temp[1-3]_crit Critical high temperature
temp[1-3]_crit_alarm Chip temperature critical high alarm
temp[1-3]_max Maximum temperature
temp[1-3]_max_alarm Chip temperature high alarm
+====================== ====================================
--
2.21.0
^ permalink raw reply related
* [PATCH 16/22] docs: wimax: convert to ReST and add to admin-guide
From: Mauro Carvalho Chehab @ 2019-07-22 11:07 UTC (permalink / raw)
Cc: Mauro Carvalho Chehab, Jonathan Corbet, Inaky Perez-Gonzalez,
linux-wimax, linux-doc
In-Reply-To: <cover.1563792333.git.mchehab+samsung@kernel.org>
Manually convert wimax documentation to ReST and add theit
to the Kernel doc body, inside the admin-guide.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/admin-guide/index.rst | 1 +
.../wimax/i2400m.rst} | 145 ++++++++++--------
Documentation/admin-guide/wimax/index.rst | 19 +++
.../wimax/wimax.rst} | 36 +++--
MAINTAINERS | 4 +-
5 files changed, 128 insertions(+), 77 deletions(-)
rename Documentation/{wimax/README.i2400m => admin-guide/wimax/i2400m.rst} (69%)
create mode 100644 Documentation/admin-guide/wimax/index.rst
rename Documentation/{wimax/README.wimax => admin-guide/wimax/wimax.rst} (74%)
diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
index 4a9de9806eaf..6bd211832bd7 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -110,6 +110,7 @@ configure specific aspects of kernel behavior to your liking.
pnp
rtc
svga
+ wimax/index
video-output
.. only:: subproject and html
diff --git a/Documentation/wimax/README.i2400m b/Documentation/admin-guide/wimax/i2400m.rst
similarity index 69%
rename from Documentation/wimax/README.i2400m
rename to Documentation/admin-guide/wimax/i2400m.rst
index 7dffd8919cb0..194388c0c351 100644
--- a/Documentation/wimax/README.i2400m
+++ b/Documentation/admin-guide/wimax/i2400m.rst
@@ -1,18 +1,23 @@
+.. include:: <isonum.txt>
- Driver for the Intel Wireless Wimax Connection 2400m
+====================================================
+Driver for the Intel Wireless Wimax Connection 2400m
+====================================================
- (C) 2008 Intel Corporation < linux-wimax@intel.com >
+:Copyright: |copy| 2008 Intel Corporation < linux-wimax@intel.com >
This provides a driver for the Intel Wireless WiMAX Connection 2400m
and a basic Linux kernel WiMAX stack.
1. Requirements
+===============
* Linux installation with Linux kernel 2.6.22 or newer (if building
from a separate tree)
* Intel i2400m Echo Peak or Baxter Peak; this includes the Intel
Wireless WiMAX/WiFi Link 5x50 series.
* build tools:
+
+ Linux kernel development package for the target kernel; to
build against your currently running kernel, you need to have
the kernel development package corresponding to the running
@@ -22,8 +27,10 @@
+ GNU C Compiler, make
2. Compilation and installation
+===============================
2.1. Compilation of the drivers included in the kernel
+------------------------------------------------------
Configure the kernel; to enable the WiMAX drivers select Drivers >
Networking Drivers > WiMAX device support. Enable all of them as
@@ -36,37 +43,39 @@
Compile and install your kernel as usual.
2.2. Compilation of the drivers distributed as an standalone module
+-------------------------------------------------------------------
- To compile
+ To compile::
-$ cd source/directory
-$ make
+ $ cd source/directory
+ $ make
Once built you can load and unload using the provided load.sh script;
load.sh will load the modules, load.sh u will unload them.
To install in the default kernel directories (and enable auto loading
- when the device is plugged):
+ when the device is plugged)::
-$ make install
-$ depmod -a
+ $ make install
+ $ depmod -a
If your kernel development files are located in a non standard
directory or if you want to build for a kernel that is not the
- currently running one, set KDIR to the right location:
+ currently running one, set KDIR to the right location::
-$ make KDIR=/path/to/kernel/dev/tree
+ $ make KDIR=/path/to/kernel/dev/tree
For more information, please contact linux-wimax@intel.com.
3. Installing the firmware
+--------------------------
The firmware can be obtained from http://linuxwimax.org or might have
been supplied with your hardware.
- It has to be installed in the target system:
- *
-$ cp FIRMWAREFILE.sbcf /lib/firmware/i2400m-fw-BUSTYPE-1.3.sbcf
+ It has to be installed in the target system::
+
+ $ cp FIRMWAREFILE.sbcf /lib/firmware/i2400m-fw-BUSTYPE-1.3.sbcf
* NOTE: if your firmware came in an .rpm or .deb file, just install
it as normal, with the rpm (rpm -i FIRMWARE.rpm) or dpkg
@@ -76,6 +85,7 @@ $ cp FIRMWAREFILE.sbcf /lib/firmware/i2400m-fw-BUSTYPE-1.3.sbcf
with other types.
4. Design
+=========
This package contains two major parts: a WiMAX kernel stack and a
driver for the Intel i2400m.
@@ -102,16 +112,17 @@ $ cp FIRMWAREFILE.sbcf /lib/firmware/i2400m-fw-BUSTYPE-1.3.sbcf
API calls should be replaced with the target OS's.
5. Usage
+========
To load the driver, follow the instructions in the install section;
once the driver is loaded, plug in the device (unless it is permanently
plugged in). The driver will enumerate the device, upload the firmware
and output messages in the kernel log (dmesg, /var/log/messages or
- /var/log/kern.log) such as:
+ /var/log/kern.log) such as::
-...
-i2400m_usb 5-4:1.0: firmware interface version 8.0.0
-i2400m_usb 5-4:1.0: WiMAX interface wmx0 (00:1d:e1:01:94:2c) ready
+ ...
+ i2400m_usb 5-4:1.0: firmware interface version 8.0.0
+ i2400m_usb 5-4:1.0: WiMAX interface wmx0 (00:1d:e1:01:94:2c) ready
At this point the device is ready to work.
@@ -120,38 +131,42 @@ i2400m_usb 5-4:1.0: WiMAX interface wmx0 (00:1d:e1:01:94:2c) ready
on how to scan, connect and disconnect.
5.1. Module parameters
+----------------------
Module parameters can be set at kernel or module load time or by
- echoing values:
+ echoing values::
-$ echo VALUE > /sys/module/MODULENAME/parameters/PARAMETERNAME
+ $ echo VALUE > /sys/module/MODULENAME/parameters/PARAMETERNAME
To make changes permanent, for example, for the i2400m module, you can
- also create a file named /etc/modprobe.d/i2400m containing:
+ also create a file named /etc/modprobe.d/i2400m containing::
-options i2400m idle_mode_disabled=1
+ options i2400m idle_mode_disabled=1
- To find which parameters are supported by a module, run:
+ To find which parameters are supported by a module, run::
-$ modinfo path/to/module.ko
+ $ modinfo path/to/module.ko
During kernel bootup (if the driver is linked in the kernel), specify
- the following to the kernel command line:
+ the following to the kernel command line::
-i2400m.PARAMETER=VALUE
+ i2400m.PARAMETER=VALUE
5.1.1. i2400m: idle_mode_disabled
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The i2400m module supports a parameter to disable idle mode. This
parameter, once set, will take effect only when the device is
reinitialized by the driver (eg: following a reset or a reconnect).
5.2. Debug operations: debugfs entries
+--------------------------------------
The driver will register debugfs entries that allow the user to tweak
debug settings. There are three main container directories where
entries are placed, which correspond to the three blocks a i2400m WiMAX
driver has:
+
* /sys/kernel/debug/wimax:DEVNAME/ for the generic WiMAX stack
controls
* /sys/kernel/debug/wimax:DEVNAME/i2400m for the i2400m generic
@@ -163,52 +178,55 @@ i2400m.PARAMETER=VALUE
/sys/kernel/debug, those paths will change.
5.2.1. Increasing debug output
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The files named *dl_* indicate knobs for controlling the debug output
- of different submodules:
- *
-# find /sys/kernel/debug/wimax\:wmx0 -name \*dl_\*
-/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_tx
-/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_rx
-/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_notif
-/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_fw
-/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_usb
-/sys/kernel/debug/wimax:wmx0/i2400m/dl_tx
-/sys/kernel/debug/wimax:wmx0/i2400m/dl_rx
-/sys/kernel/debug/wimax:wmx0/i2400m/dl_rfkill
-/sys/kernel/debug/wimax:wmx0/i2400m/dl_netdev
-/sys/kernel/debug/wimax:wmx0/i2400m/dl_fw
-/sys/kernel/debug/wimax:wmx0/i2400m/dl_debugfs
-/sys/kernel/debug/wimax:wmx0/i2400m/dl_driver
-/sys/kernel/debug/wimax:wmx0/i2400m/dl_control
-/sys/kernel/debug/wimax:wmx0/wimax_dl_stack
-/sys/kernel/debug/wimax:wmx0/wimax_dl_op_rfkill
-/sys/kernel/debug/wimax:wmx0/wimax_dl_op_reset
-/sys/kernel/debug/wimax:wmx0/wimax_dl_op_msg
-/sys/kernel/debug/wimax:wmx0/wimax_dl_id_table
-/sys/kernel/debug/wimax:wmx0/wimax_dl_debugfs
+ of different submodules::
+
+ # find /sys/kernel/debug/wimax\:wmx0 -name \*dl_\*
+ /sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_tx
+ /sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_rx
+ /sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_notif
+ /sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_fw
+ /sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_usb
+ /sys/kernel/debug/wimax:wmx0/i2400m/dl_tx
+ /sys/kernel/debug/wimax:wmx0/i2400m/dl_rx
+ /sys/kernel/debug/wimax:wmx0/i2400m/dl_rfkill
+ /sys/kernel/debug/wimax:wmx0/i2400m/dl_netdev
+ /sys/kernel/debug/wimax:wmx0/i2400m/dl_fw
+ /sys/kernel/debug/wimax:wmx0/i2400m/dl_debugfs
+ /sys/kernel/debug/wimax:wmx0/i2400m/dl_driver
+ /sys/kernel/debug/wimax:wmx0/i2400m/dl_control
+ /sys/kernel/debug/wimax:wmx0/wimax_dl_stack
+ /sys/kernel/debug/wimax:wmx0/wimax_dl_op_rfkill
+ /sys/kernel/debug/wimax:wmx0/wimax_dl_op_reset
+ /sys/kernel/debug/wimax:wmx0/wimax_dl_op_msg
+ /sys/kernel/debug/wimax:wmx0/wimax_dl_id_table
+ /sys/kernel/debug/wimax:wmx0/wimax_dl_debugfs
By reading the file you can obtain the current value of said debug
level; by writing to it, you can set it.
To increase the debug level of, for example, the i2400m's generic TX
- engine, just write:
+ engine, just write::
-$ echo 3 > /sys/kernel/debug/wimax:wmx0/i2400m/dl_tx
+ $ echo 3 > /sys/kernel/debug/wimax:wmx0/i2400m/dl_tx
Increasing numbers yield increasing debug information; for details of
what is printed and the available levels, check the source. The code
uses 0 for disabled and increasing values until 8.
5.2.2. RX and TX statistics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
The i2400m/rx_stats and i2400m/tx_stats provide statistics about the
- data reception/delivery from the device:
+ data reception/delivery from the device::
-$ cat /sys/kernel/debug/wimax:wmx0/i2400m/rx_stats
-45 1 3 34 3104 48 480
+ $ cat /sys/kernel/debug/wimax:wmx0/i2400m/rx_stats
+ 45 1 3 34 3104 48 480
+
+ The numbers reported are:
- The numbers reported are
* packets/RX-buffer: total, min, max
* RX-buffers: total RX buffers received, accumulated RX buffer size
in bytes, min size received, max size received
@@ -216,9 +234,9 @@ $ cat /sys/kernel/debug/wimax:wmx0/i2400m/rx_stats
Thus, to find the average buffer size received, divide accumulated
RX-buffer / total RX-buffers.
- To clear the statistics back to 0, write anything to the rx_stats file:
+ To clear the statistics back to 0, write anything to the rx_stats file::
-$ echo 1 > /sys/kernel/debug/wimax:wmx0/i2400m_rx_stats
+ $ echo 1 > /sys/kernel/debug/wimax:wmx0/i2400m_rx_stats
Likewise for TX.
@@ -227,14 +245,16 @@ $ echo 1 > /sys/kernel/debug/wimax:wmx0/i2400m_rx_stats
to the host. See drivers/net/wimax/i2400m/tx.c.
5.2.3. Tracing messages received from user space
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
To echo messages received from user space into the trace pipe that the
i2400m driver creates, set the debug file i2400m/trace_msg_from_user to
- 1:
- *
-$ echo 1 > /sys/kernel/debug/wimax:wmx0/i2400m/trace_msg_from_user
+ 1::
+
+ $ echo 1 > /sys/kernel/debug/wimax:wmx0/i2400m/trace_msg_from_user
5.2.4. Performing a device reset
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
By writing a 0, a 1 or a 2 to the file
/sys/kernel/debug/wimax:wmx0/reset, the driver performs a warm (without
@@ -242,18 +262,21 @@ $ echo 1 > /sys/kernel/debug/wimax:wmx0/i2400m/trace_msg_from_user
(bus specific) reset on the device.
5.2.5. Asking the device to enter power saving mode
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
By writing any value to the /sys/kernel/debug/wimax:wmx0 file, the
device will attempt to enter power saving mode.
6. Troubleshooting
+==================
-6.1. Driver complains about 'i2400m-fw-usb-1.2.sbcf: request failed'
+6.1. Driver complains about ``i2400m-fw-usb-1.2.sbcf: request failed``
+----------------------------------------------------------------------
If upon connecting the device, the following is output in the kernel
- log:
+ log::
-i2400m_usb 5-4:1.0: fw i2400m-fw-usb-1.3.sbcf: request failed: -2
+ i2400m_usb 5-4:1.0: fw i2400m-fw-usb-1.3.sbcf: request failed: -2
This means that the driver cannot locate the firmware file named
/lib/firmware/i2400m-fw-usb-1.2.sbcf. Check that the file is present in
diff --git a/Documentation/admin-guide/wimax/index.rst b/Documentation/admin-guide/wimax/index.rst
new file mode 100644
index 000000000000..fdf7c1f99ff5
--- /dev/null
+++ b/Documentation/admin-guide/wimax/index.rst
@@ -0,0 +1,19 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===============
+WiMAX subsystem
+===============
+
+.. toctree::
+ :maxdepth: 2
+
+ wimax
+
+ i2400m
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/wimax/README.wimax b/Documentation/admin-guide/wimax/wimax.rst
similarity index 74%
rename from Documentation/wimax/README.wimax
rename to Documentation/admin-guide/wimax/wimax.rst
index b78c4378084e..817ee8ba2732 100644
--- a/Documentation/wimax/README.wimax
+++ b/Documentation/admin-guide/wimax/wimax.rst
@@ -1,12 +1,16 @@
+.. include:: <isonum.txt>
- Linux kernel WiMAX stack
+========================
+Linux kernel WiMAX stack
+========================
- (C) 2008 Intel Corporation < linux-wimax@intel.com >
+:Copyright: |copy| 2008 Intel Corporation < linux-wimax@intel.com >
This provides a basic Linux kernel WiMAX stack to provide a common
control API for WiMAX devices, usable from kernel and user space.
1. Design
+=========
The WiMAX stack is designed to provide for common WiMAX control
services to current and future WiMAX devices from any vendor.
@@ -31,6 +35,7 @@
include/linux/wimax.h.
2. Usage
+========
For usage in a driver (registration, API, etc) please refer to the
instructions in the header file include/linux/wimax.h.
@@ -40,6 +45,7 @@
control.
2.1. Obtaining debug information: debugfs entries
+-------------------------------------------------
The WiMAX stack is compiled, by default, with debug messages that can
be used to diagnose issues. By default, said messages are disabled.
@@ -52,20 +58,22 @@
create more subentries below it.
2.1.1. Increasing debug output
+------------------------------
The files named *dl_* indicate knobs for controlling the debug output
- of different submodules of the WiMAX stack:
- *
-# find /sys/kernel/debug/wimax\:wmx0 -name \*dl_\*
-/sys/kernel/debug/wimax:wmx0/wimax_dl_stack
-/sys/kernel/debug/wimax:wmx0/wimax_dl_op_rfkill
-/sys/kernel/debug/wimax:wmx0/wimax_dl_op_reset
-/sys/kernel/debug/wimax:wmx0/wimax_dl_op_msg
-/sys/kernel/debug/wimax:wmx0/wimax_dl_id_table
-/sys/kernel/debug/wimax:wmx0/wimax_dl_debugfs
-/sys/kernel/debug/wimax:wmx0/.... # other driver specific files
+ of different submodules of the WiMAX stack::
- NOTE: Of course, if debugfs is mounted in a directory other than
+ # find /sys/kernel/debug/wimax\:wmx0 -name \*dl_\*
+ /sys/kernel/debug/wimax:wmx0/wimax_dl_stack
+ /sys/kernel/debug/wimax:wmx0/wimax_dl_op_rfkill
+ /sys/kernel/debug/wimax:wmx0/wimax_dl_op_reset
+ /sys/kernel/debug/wimax:wmx0/wimax_dl_op_msg
+ /sys/kernel/debug/wimax:wmx0/wimax_dl_id_table
+ /sys/kernel/debug/wimax:wmx0/wimax_dl_debugfs
+ /sys/kernel/debug/wimax:wmx0/.... # other driver specific files
+
+ NOTE:
+ Of course, if debugfs is mounted in a directory other than
/sys/kernel/debug, those paths will change.
By reading the file you can obtain the current value of said debug
@@ -74,7 +82,7 @@
To increase the debug level of, for example, the id-table submodule,
just write:
-$ echo 3 > /sys/kernel/debug/wimax:wmx0/wimax_dl_id_table
+ $ echo 3 > /sys/kernel/debug/wimax:wmx0/wimax_dl_id_table
Increasing numbers yield increasing debug information; for details of
what is printed and the available levels, check the source. The code
diff --git a/MAINTAINERS b/MAINTAINERS
index c8c09d4062a1..665c3c1e939b 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -8346,7 +8346,7 @@ M: linux-wimax@intel.com
L: wimax@linuxwimax.org (subscribers-only)
S: Supported
W: http://linuxwimax.org
-F: Documentation/wimax/README.i2400m
+F: Documentation/admin-guide/wimax/i2400m.rst
F: drivers/net/wimax/i2400m/
F: include/uapi/linux/wimax/i2400m.h
@@ -17348,7 +17348,7 @@ M: linux-wimax@intel.com
L: wimax@linuxwimax.org (subscribers-only)
S: Supported
W: http://linuxwimax.org
-F: Documentation/wimax/README.wimax
+F: Documentation/admin-guide/wimax/wimax.rst
F: include/linux/wimax/debug.h
F: include/net/wimax.h
F: include/uapi/linux/wimax.h
--
2.21.0
^ permalink raw reply related
* [PATCH 07/22] docs: admin-guide: add auxdisplay files to it after conversion to ReST
From: Mauro Carvalho Chehab @ 2019-07-22 11:07 UTC (permalink / raw)
Cc: Mauro Carvalho Chehab, Jonathan Corbet, Miguel Ojeda Sandonis,
linux-doc
In-Reply-To: <cover.1563792333.git.mchehab+samsung@kernel.org>
Those two files describe userspace-faced information. While part of
it might fit on uAPI, it sounds to me that the admin guide is the
best place for them.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
.../admin-guide/auxdisplay/cfag12864b.rst | 98 ++++++++++++++++
.../admin-guide/auxdisplay/index.rst | 16 +++
.../admin-guide/auxdisplay/ks0108.rst | 50 +++++++++
Documentation/admin-guide/index.rst | 1 +
Documentation/auxdisplay/cfag12864b | 105 ------------------
Documentation/auxdisplay/ks0108 | 55 ---------
MAINTAINERS | 2 +-
drivers/auxdisplay/Kconfig | 2 +-
8 files changed, 167 insertions(+), 162 deletions(-)
create mode 100644 Documentation/admin-guide/auxdisplay/cfag12864b.rst
create mode 100644 Documentation/admin-guide/auxdisplay/index.rst
create mode 100644 Documentation/admin-guide/auxdisplay/ks0108.rst
delete mode 100644 Documentation/auxdisplay/cfag12864b
delete mode 100644 Documentation/auxdisplay/ks0108
diff --git a/Documentation/admin-guide/auxdisplay/cfag12864b.rst b/Documentation/admin-guide/auxdisplay/cfag12864b.rst
new file mode 100644
index 000000000000..18c2865bd322
--- /dev/null
+++ b/Documentation/admin-guide/auxdisplay/cfag12864b.rst
@@ -0,0 +1,98 @@
+===================================
+cfag12864b LCD Driver Documentation
+===================================
+
+:License: GPLv2
+:Author & Maintainer: Miguel Ojeda Sandonis
+:Date: 2006-10-27
+
+
+
+.. INDEX
+
+ 1. DRIVER INFORMATION
+ 2. DEVICE INFORMATION
+ 3. WIRING
+ 4. USERSPACE PROGRAMMING
+
+1. Driver Information
+---------------------
+
+This driver supports a cfag12864b LCD.
+
+
+2. Device Information
+---------------------
+
+:Manufacturer: Crystalfontz
+:Device Name: Crystalfontz 12864b LCD Series
+:Device Code: cfag12864b
+:Webpage: http://www.crystalfontz.com
+:Device Webpage: http://www.crystalfontz.com/products/12864b/
+:Type: LCD (Liquid Crystal Display)
+:Width: 128
+:Height: 64
+:Colors: 2 (B/N)
+:Controller: ks0108
+:Controllers: 2
+:Pages: 8 each controller
+:Addresses: 64 each page
+:Data size: 1 byte each address
+:Memory size: 2 * 8 * 64 * 1 = 1024 bytes = 1 Kbyte
+
+
+3. Wiring
+---------
+
+The cfag12864b LCD Series don't have official wiring.
+
+The common wiring is done to the parallel port as shown::
+
+ Parallel Port cfag12864b
+
+ Name Pin# Pin# Name
+
+ Strobe ( 1)------------------------------(17) Enable
+ Data 0 ( 2)------------------------------( 4) Data 0
+ Data 1 ( 3)------------------------------( 5) Data 1
+ Data 2 ( 4)------------------------------( 6) Data 2
+ Data 3 ( 5)------------------------------( 7) Data 3
+ Data 4 ( 6)------------------------------( 8) Data 4
+ Data 5 ( 7)------------------------------( 9) Data 5
+ Data 6 ( 8)------------------------------(10) Data 6
+ Data 7 ( 9)------------------------------(11) Data 7
+ (10) [+5v]---( 1) Vdd
+ (11) [GND]---( 2) Ground
+ (12) [+5v]---(14) Reset
+ (13) [GND]---(15) Read / Write
+ Line (14)------------------------------(13) Controller Select 1
+ (15)
+ Init (16)------------------------------(12) Controller Select 2
+ Select (17)------------------------------(16) Data / Instruction
+ Ground (18)---[GND] [+5v]---(19) LED +
+ Ground (19)---[GND]
+ Ground (20)---[GND] E A Values:
+ Ground (21)---[GND] [GND]---[P1]---(18) Vee - R = Resistor = 22 ohm
+ Ground (22)---[GND] | - P1 = Preset = 10 Kohm
+ Ground (23)---[GND] ---- S ------( 3) V0 - P2 = Preset = 1 Kohm
+ Ground (24)---[GND] | |
+ Ground (25)---[GND] [GND]---[P2]---[R]---(20) LED -
+
+
+4. Userspace Programming
+------------------------
+
+The cfag12864bfb describes a framebuffer device (/dev/fbX).
+
+It has a size of 1024 bytes = 1 Kbyte.
+Each bit represents one pixel. If the bit is high, the pixel will
+turn on. If the pixel is low, the pixel will turn off.
+
+You can use the framebuffer as a file: fopen, fwrite, fclose...
+Although the LCD won't get updated until the next refresh time arrives.
+
+Also, you can mmap the framebuffer: open & mmap, munmap & close...
+which is the best option for most uses.
+
+Check samples/auxdisplay/cfag12864b-example.c
+for a real working userspace complete program with usage examples.
diff --git a/Documentation/admin-guide/auxdisplay/index.rst b/Documentation/admin-guide/auxdisplay/index.rst
new file mode 100644
index 000000000000..e466f0595248
--- /dev/null
+++ b/Documentation/admin-guide/auxdisplay/index.rst
@@ -0,0 +1,16 @@
+=========================
+Auxiliary Display Support
+=========================
+
+.. toctree::
+ :maxdepth: 1
+
+ ks0108.rst
+ cfag12864b.rst
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/admin-guide/auxdisplay/ks0108.rst b/Documentation/admin-guide/auxdisplay/ks0108.rst
new file mode 100644
index 000000000000..c0b7faf73136
--- /dev/null
+++ b/Documentation/admin-guide/auxdisplay/ks0108.rst
@@ -0,0 +1,50 @@
+==========================================
+ks0108 LCD Controller Driver Documentation
+==========================================
+
+:License: GPLv2
+:Author & Maintainer: Miguel Ojeda Sandonis
+:Date: 2006-10-27
+
+
+
+.. INDEX
+
+ 1. DRIVER INFORMATION
+ 2. DEVICE INFORMATION
+ 3. WIRING
+
+
+1. Driver Information
+---------------------
+
+This driver supports the ks0108 LCD controller.
+
+
+2. Device Information
+---------------------
+
+:Manufacturer: Samsung
+:Device Name: KS0108 LCD Controller
+:Device Code: ks0108
+:Webpage: -
+:Device Webpage: -
+:Type: LCD Controller (Liquid Crystal Display Controller)
+:Width: 64
+:Height: 64
+:Colors: 2 (B/N)
+:Pages: 8
+:Addresses: 64 each page
+:Data size: 1 byte each address
+:Memory size: 8 * 64 * 1 = 512 bytes
+
+
+3. Wiring
+---------
+
+The driver supports data parallel port wiring.
+
+If you aren't building LCD related hardware, you should check
+your LCD specific wiring information in the same folder.
+
+For example, check Documentation/admin-guide/auxdisplay/cfag12864b.rst
diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
index 457fd1112b65..3f8f7d564552 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -101,6 +101,7 @@ configure specific aspects of kernel behavior to your liking.
iostats
kernel-per-CPU-kthreads
laptops/index
+ auxdisplay/index
lcd-panel-cgram
ldm
lockup-watchdogs
diff --git a/Documentation/auxdisplay/cfag12864b b/Documentation/auxdisplay/cfag12864b
deleted file mode 100644
index 12fd51b8de75..000000000000
--- a/Documentation/auxdisplay/cfag12864b
+++ /dev/null
@@ -1,105 +0,0 @@
- ===================================
- cfag12864b LCD Driver Documentation
- ===================================
-
-License: GPLv2
-Author & Maintainer: Miguel Ojeda Sandonis
-Date: 2006-10-27
-
-
-
---------
-0. INDEX
---------
-
- 1. DRIVER INFORMATION
- 2. DEVICE INFORMATION
- 3. WIRING
- 4. USERSPACE PROGRAMMING
-
-
----------------------
-1. DRIVER INFORMATION
----------------------
-
-This driver supports a cfag12864b LCD.
-
-
----------------------
-2. DEVICE INFORMATION
----------------------
-
-Manufacturer: Crystalfontz
-Device Name: Crystalfontz 12864b LCD Series
-Device Code: cfag12864b
-Webpage: http://www.crystalfontz.com
-Device Webpage: http://www.crystalfontz.com/products/12864b/
-Type: LCD (Liquid Crystal Display)
-Width: 128
-Height: 64
-Colors: 2 (B/N)
-Controller: ks0108
-Controllers: 2
-Pages: 8 each controller
-Addresses: 64 each page
-Data size: 1 byte each address
-Memory size: 2 * 8 * 64 * 1 = 1024 bytes = 1 Kbyte
-
-
----------
-3. WIRING
----------
-
-The cfag12864b LCD Series don't have official wiring.
-
-The common wiring is done to the parallel port as shown:
-
-Parallel Port cfag12864b
-
- Name Pin# Pin# Name
-
-Strobe ( 1)------------------------------(17) Enable
-Data 0 ( 2)------------------------------( 4) Data 0
-Data 1 ( 3)------------------------------( 5) Data 1
-Data 2 ( 4)------------------------------( 6) Data 2
-Data 3 ( 5)------------------------------( 7) Data 3
-Data 4 ( 6)------------------------------( 8) Data 4
-Data 5 ( 7)------------------------------( 9) Data 5
-Data 6 ( 8)------------------------------(10) Data 6
-Data 7 ( 9)------------------------------(11) Data 7
- (10) [+5v]---( 1) Vdd
- (11) [GND]---( 2) Ground
- (12) [+5v]---(14) Reset
- (13) [GND]---(15) Read / Write
- Line (14)------------------------------(13) Controller Select 1
- (15)
- Init (16)------------------------------(12) Controller Select 2
-Select (17)------------------------------(16) Data / Instruction
-Ground (18)---[GND] [+5v]---(19) LED +
-Ground (19)---[GND]
-Ground (20)---[GND] E A Values:
-Ground (21)---[GND] [GND]---[P1]---(18) Vee - R = Resistor = 22 ohm
-Ground (22)---[GND] | - P1 = Preset = 10 Kohm
-Ground (23)---[GND] ---- S ------( 3) V0 - P2 = Preset = 1 Kohm
-Ground (24)---[GND] | |
-Ground (25)---[GND] [GND]---[P2]---[R]---(20) LED -
-
-
-------------------------
-4. USERSPACE PROGRAMMING
-------------------------
-
-The cfag12864bfb describes a framebuffer device (/dev/fbX).
-
-It has a size of 1024 bytes = 1 Kbyte.
-Each bit represents one pixel. If the bit is high, the pixel will
-turn on. If the pixel is low, the pixel will turn off.
-
-You can use the framebuffer as a file: fopen, fwrite, fclose...
-Although the LCD won't get updated until the next refresh time arrives.
-
-Also, you can mmap the framebuffer: open & mmap, munmap & close...
-which is the best option for most uses.
-
-Check samples/auxdisplay/cfag12864b-example.c
-for a real working userspace complete program with usage examples.
diff --git a/Documentation/auxdisplay/ks0108 b/Documentation/auxdisplay/ks0108
deleted file mode 100644
index 8ddda0c8ceef..000000000000
--- a/Documentation/auxdisplay/ks0108
+++ /dev/null
@@ -1,55 +0,0 @@
- ==========================================
- ks0108 LCD Controller Driver Documentation
- ==========================================
-
-License: GPLv2
-Author & Maintainer: Miguel Ojeda Sandonis
-Date: 2006-10-27
-
-
-
---------
-0. INDEX
---------
-
- 1. DRIVER INFORMATION
- 2. DEVICE INFORMATION
- 3. WIRING
-
-
----------------------
-1. DRIVER INFORMATION
----------------------
-
-This driver supports the ks0108 LCD controller.
-
-
----------------------
-2. DEVICE INFORMATION
----------------------
-
-Manufacturer: Samsung
-Device Name: KS0108 LCD Controller
-Device Code: ks0108
-Webpage: -
-Device Webpage: -
-Type: LCD Controller (Liquid Crystal Display Controller)
-Width: 64
-Height: 64
-Colors: 2 (B/N)
-Pages: 8
-Addresses: 64 each page
-Data size: 1 byte each address
-Memory size: 8 * 64 * 1 = 512 bytes
-
-
----------
-3. WIRING
----------
-
-The driver supports data parallel port wiring.
-
-If you aren't building LCD related hardware, you should check
-your LCD specific wiring information in the same folder.
-
-For example, check Documentation/auxdisplay/cfag12864b.
diff --git a/MAINTAINERS b/MAINTAINERS
index fd2af50e66b5..4cd39259fcdc 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -8991,7 +8991,7 @@ F: kernel/kprobes.c
KS0108 LCD CONTROLLER DRIVER
M: Miguel Ojeda Sandonis <miguel.ojeda.sandonis@gmail.com>
S: Maintained
-F: Documentation/auxdisplay/ks0108
+F: Documentation/admin-guide/auxdisplay/ks0108.rst
F: drivers/auxdisplay/ks0108.c
F: include/linux/ks0108.h
diff --git a/drivers/auxdisplay/Kconfig b/drivers/auxdisplay/Kconfig
index dd61fdd400f0..6b476e663e80 100644
--- a/drivers/auxdisplay/Kconfig
+++ b/drivers/auxdisplay/Kconfig
@@ -97,7 +97,7 @@ config CFAG12864B
say Y. You also need the ks0108 LCD Controller driver.
For help about how to wire your LCD to the parallel port,
- check Documentation/auxdisplay/cfag12864b
+ check Documentation/admin-guide/auxdisplay/cfag12864b.rst
Depends on the x86 arch and the framebuffer support.
--
2.21.0
^ permalink raw reply related
* [PATCH 01/22] docs: convert markdown documents to ReST
From: Mauro Carvalho Chehab @ 2019-07-22 11:07 UTC (permalink / raw)
Cc: Mauro Carvalho Chehab, Rob Herring, Mark Rutland, Jonathan Corbet,
devicetree, linux-doc, Rob Herring
In-Reply-To: <cover.1563792333.git.mchehab+samsung@kernel.org>
The documentation standard is ReST and not markdown.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Rob Herring <robh@kernel.org>
---
Documentation/devicetree/writing-schema.md | 130 ---------------
Documentation/devicetree/writing-schema.rst | 153 ++++++++++++++++++
...entication.md => ubifs-authentication.rst} | 70 +++++---
3 files changed, 197 insertions(+), 156 deletions(-)
delete mode 100644 Documentation/devicetree/writing-schema.md
create mode 100644 Documentation/devicetree/writing-schema.rst
rename Documentation/filesystems/{ubifs-authentication.md => ubifs-authentication.rst} (95%)
diff --git a/Documentation/devicetree/writing-schema.md b/Documentation/devicetree/writing-schema.md
deleted file mode 100644
index dc032db36262..000000000000
--- a/Documentation/devicetree/writing-schema.md
+++ /dev/null
@@ -1,130 +0,0 @@
-# Writing DeviceTree Bindings in json-schema
-
-Devicetree bindings are written using json-schema vocabulary. Schema files are
-written in a JSON compatible subset of YAML. YAML is used instead of JSON as it
-considered more human readable and has some advantages such as allowing
-comments (Prefixed with '#').
-
-## Schema Contents
-
-Each schema doc is a structured json-schema which is defined by a set of
-top-level properties. Generally, there is one binding defined per file. The
-top-level json-schema properties used are:
-
-- __$id__ - A json-schema unique identifier string. The string must be a valid
-URI typically containing the binding's filename and path. For DT schema, it must
-begin with "http://devicetree.org/schemas/". The URL is used in constructing
-references to other files specified in schema "$ref" properties. A $ref values
-with a leading '/' will have the hostname prepended. A $ref value a relative
-path or filename only will be prepended with the hostname and path components
-of the current schema file's '$id' value. A URL is used even for local files,
-but there may not actually be files present at those locations.
-
-- __$schema__ - Indicates the meta-schema the schema file adheres to.
-
-- __title__ - A one line description on the contents of the binding schema.
-
-- __maintainers__ - A DT specific property. Contains a list of email address(es)
-for maintainers of this binding.
-
-- __description__ - Optional. A multi-line text block containing any detailed
-information about this binding. It should contain things such as what the block
-or device does, standards the device conforms to, and links to datasheets for
-more information.
-
-- __select__ - Optional. A json-schema used to match nodes for applying the
-schema. By default without 'select', nodes are matched against their possible
-compatible string values or node name. Most bindings should not need select.
-
-- __allOf__ - Optional. A list of other schemas to include. This is used to
-include other schemas the binding conforms to. This may be schemas for a
-particular class of devices such as I2C or SPI controllers.
-
-- __properties__ - A set of sub-schema defining all the DT properties for the
-binding. The exact schema syntax depends on whether properties are known,
-common properties (e.g. 'interrupts') or are binding/vendor specific properties.
-
- A property can also define a child DT node with child properties defined
-under it.
-
- For more details on properties sections, see 'Property Schema' section.
-
-- __patternProperties__ - Optional. Similar to 'properties', but names are regex.
-
-- __required__ - A list of DT properties from the 'properties' section that
-must always be present.
-
-- __examples__ - Optional. A list of one or more DTS hunks implementing the
-binding. Note: YAML doesn't allow leading tabs, so spaces must be used instead.
-
-Unless noted otherwise, all properties are required.
-
-## Property Schema
-
-The 'properties' section of the schema contains all the DT properties for a
-binding. Each property contains a set of constraints using json-schema
-vocabulary for that property. The properties schemas are what is used for
-validation of DT files.
-
-For common properties, only additional constraints not covered by the common
-binding schema need to be defined such as how many values are valid or what
-possible values are valid.
-
-Vendor specific properties will typically need more detailed schema. With the
-exception of boolean properties, they should have a reference to a type in
-schemas/types.yaml. A "description" property is always required.
-
-The Devicetree schemas don't exactly match the YAML encoded DT data produced by
-dtc. They are simplified to make them more compact and avoid a bunch of
-boilerplate. The tools process the schema files to produce the final schema for
-validation. There are currently 2 transformations the tools perform.
-
-The default for arrays in json-schema is they are variable sized and allow more
-entries than explicitly defined. This can be restricted by defining 'minItems',
-'maxItems', and 'additionalItems'. However, for DeviceTree Schemas, a fixed
-size is desired in most cases, so these properties are added based on the
-number of entries in an 'items' list.
-
-The YAML Devicetree format also makes all string values an array and scalar
-values a matrix (in order to define groupings) even when only a single value
-is present. Single entries in schemas are fixed up to match this encoding.
-
-## Testing
-
-### Dependencies
-
-The DT schema project must be installed in order to validate the DT schema
-binding documents and validate DTS files using the DT schema. The DT schema
-project can be installed with pip:
-
-`pip3 install git+https://github.com/devicetree-org/dt-schema.git@master`
-
-dtc must also be built with YAML output support enabled. This requires that
-libyaml and its headers be installed on the host system.
-
-### Running checks
-
-The DT schema binding documents must be validated using the meta-schema (the
-schema for the schema) to ensure they are both valid json-schema and valid
-binding schema. All of the DT binding documents can be validated using the
-`dt_binding_check` target:
-
-`make dt_binding_check`
-
-In order to perform validation of DT source files, use the `dtbs_check` target:
-
-`make dtbs_check`
-
-This will first run the `dt_binding_check` which generates the processed schema.
-
-It is also possible to run checks with a single schema file by setting the
-'DT_SCHEMA_FILES' variable to a specific schema file.
-
-`make dtbs_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/trivial-devices.yaml`
-
-
-## json-schema Resources
-
-[JSON-Schema Specifications](http://json-schema.org/)
-
-[Using JSON Schema Book](http://usingjsonschema.com/)
diff --git a/Documentation/devicetree/writing-schema.rst b/Documentation/devicetree/writing-schema.rst
new file mode 100644
index 000000000000..8f71d1e2ac52
--- /dev/null
+++ b/Documentation/devicetree/writing-schema.rst
@@ -0,0 +1,153 @@
+:orphan:
+
+Writing DeviceTree Bindings in json-schema
+==========================================
+
+Devicetree bindings are written using json-schema vocabulary. Schema files are
+written in a JSON compatible subset of YAML. YAML is used instead of JSON as it
+considered more human readable and has some advantages such as allowing
+comments (Prefixed with '#').
+
+Schema Contents
+---------------
+
+Each schema doc is a structured json-schema which is defined by a set of
+top-level properties. Generally, there is one binding defined per file. The
+top-level json-schema properties used are:
+
+$id
+ A json-schema unique identifier string. The string must be a valid
+ URI typically containing the binding's filename and path. For DT schema, it must
+ begin with "http://devicetree.org/schemas/". The URL is used in constructing
+ references to other files specified in schema "$ref" properties. A $ref values
+ with a leading '/' will have the hostname prepended. A $ref value a relative
+ path or filename only will be prepended with the hostname and path components
+ of the current schema file's '$id' value. A URL is used even for local files,
+ but there may not actually be files present at those locations.
+
+$schema
+ Indicates the meta-schema the schema file adheres to.
+
+title
+ A one line description on the contents of the binding schema.
+
+maintainers
+ A DT specific property. Contains a list of email address(es)
+ for maintainers of this binding.
+
+description
+ Optional. A multi-line text block containing any detailed
+ information about this binding. It should contain things such as what the block
+ or device does, standards the device conforms to, and links to datasheets for
+ more information.
+
+select
+ Optional. A json-schema used to match nodes for applying the
+ schema. By default without 'select', nodes are matched against their possible
+ compatible string values or node name. Most bindings should not need select.
+
+ allOf
+ Optional. A list of other schemas to include. This is used to
+ include other schemas the binding conforms to. This may be schemas for a
+ particular class of devices such as I2C or SPI controllers.
+
+ properties
+ A set of sub-schema defining all the DT properties for the
+ binding. The exact schema syntax depends on whether properties are known,
+ common properties (e.g. 'interrupts') or are binding/vendor specific properties.
+
+A property can also define a child DT node with child properties defined
+under it.
+
+For more details on properties sections, see 'Property Schema' section.
+
+patternProperties
+ Optional. Similar to 'properties', but names are regex.
+
+required
+ A list of DT properties from the 'properties' section that
+ must always be present.
+
+examples
+ Optional. A list of one or more DTS hunks implementing the
+ binding. Note: YAML doesn't allow leading tabs, so spaces must be used instead.
+
+Unless noted otherwise, all properties are required.
+
+Property Schema
+---------------
+
+The 'properties' section of the schema contains all the DT properties for a
+binding. Each property contains a set of constraints using json-schema
+vocabulary for that property. The properties schemas are what is used for
+validation of DT files.
+
+For common properties, only additional constraints not covered by the common
+binding schema need to be defined such as how many values are valid or what
+possible values are valid.
+
+Vendor specific properties will typically need more detailed schema. With the
+exception of boolean properties, they should have a reference to a type in
+schemas/types.yaml. A "description" property is always required.
+
+The Devicetree schemas don't exactly match the YAML encoded DT data produced by
+dtc. They are simplified to make them more compact and avoid a bunch of
+boilerplate. The tools process the schema files to produce the final schema for
+validation. There are currently 2 transformations the tools perform.
+
+The default for arrays in json-schema is they are variable sized and allow more
+entries than explicitly defined. This can be restricted by defining 'minItems',
+'maxItems', and 'additionalItems'. However, for DeviceTree Schemas, a fixed
+size is desired in most cases, so these properties are added based on the
+number of entries in an 'items' list.
+
+The YAML Devicetree format also makes all string values an array and scalar
+values a matrix (in order to define groupings) even when only a single value
+is present. Single entries in schemas are fixed up to match this encoding.
+
+Testing
+-------
+
+Dependencies
+~~~~~~~~~~~~
+
+The DT schema project must be installed in order to validate the DT schema
+binding documents and validate DTS files using the DT schema. The DT schema
+project can be installed with pip::
+
+ pip3 install git+https://github.com/devicetree-org/dt-schema.git@master
+
+dtc must also be built with YAML output support enabled. This requires that
+libyaml and its headers be installed on the host system.
+
+Running checks
+~~~~~~~~~~~~~~
+
+The DT schema binding documents must be validated using the meta-schema (the
+schema for the schema) to ensure they are both valid json-schema and valid
+binding schema. All of the DT binding documents can be validated using the
+``dt_binding_check`` target::
+
+ make dt_binding_check
+
+In order to perform validation of DT source files, use the `dtbs_check` target::
+
+ make dtbs_check
+
+This will first run the `dt_binding_check` which generates the processed schema.
+
+It is also possible to run checks with a single schema file by setting the
+``DT_SCHEMA_FILES`` variable to a specific schema file.
+
+::
+
+ make dtbs_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/trivial-devices.yaml
+
+
+json-schema Resources
+---------------------
+
+
+`JSON-Schema Specifications <http://json-schema.org/>`_
+
+`Using JSON Schema Book <http://usingjsonschema.com/>`_
diff --git a/Documentation/filesystems/ubifs-authentication.md b/Documentation/filesystems/ubifs-authentication.rst
similarity index 95%
rename from Documentation/filesystems/ubifs-authentication.md
rename to Documentation/filesystems/ubifs-authentication.rst
index 23e698167141..6a9584f6ff46 100644
--- a/Documentation/filesystems/ubifs-authentication.md
+++ b/Documentation/filesystems/ubifs-authentication.rst
@@ -1,8 +1,11 @@
-% UBIFS Authentication
-% sigma star gmbh
-% 2018
+:orphan:
-# Introduction
+.. UBIFS Authentication
+.. sigma star gmbh
+.. 2018
+
+Introduction
+============
UBIFS utilizes the fscrypt framework to provide confidentiality for file
contents and file names. This prevents attacks where an attacker is able to
@@ -33,7 +36,8 @@ existing features like key derivation can be utilized. It should however also
be possible to use UBIFS authentication without using encryption.
-## MTD, UBI & UBIFS
+MTD, UBI & UBIFS
+----------------
On Linux, the MTD (Memory Technology Devices) subsystem provides a uniform
interface to access raw flash devices. One of the more prominent subsystems that
@@ -47,7 +51,7 @@ UBIFS is a filesystem for raw flash which operates on top of UBI. Thus, wear
leveling and some flash specifics are left to UBI, while UBIFS focuses on
scalability, performance and recoverability.
-
+::
+------------+ +*******+ +-----------+ +-----+
| | * UBIFS * | UBI-BLOCK | | ... |
@@ -84,7 +88,8 @@ persisted onto the flash directly. More details on UBIFS can also be found in
[UBIFS-WP].
-### UBIFS Index & Tree Node Cache
+UBIFS Index & Tree Node Cache
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Basic on-flash UBIFS entities are called *nodes*. UBIFS knows different types
of nodes. Eg. data nodes (`struct ubifs_data_node`) which store chunks of file
@@ -118,17 +123,18 @@ on-flash filesystem structures like the index. On every commit, the TNC nodes
marked as dirty are written to the flash to update the persisted index.
-### Journal
+Journal
+~~~~~~~
To avoid wearing out the flash, the index is only persisted (*commited*) when
-certain conditions are met (eg. `fsync(2)`). The journal is used to record
+certain conditions are met (eg. ``fsync(2)``). The journal is used to record
any changes (in form of inode nodes, data nodes etc.) between commits
of the index. During mount, the journal is read from the flash and replayed
onto the TNC (which will be created on-demand from the on-flash index).
UBIFS reserves a bunch of LEBs just for the journal called *log area*. The
amount of log area LEBs is configured on filesystem creation (using
-`mkfs.ubifs`) and stored in the superblock node. The log area contains only
+``mkfs.ubifs``) and stored in the superblock node. The log area contains only
two types of nodes: *reference nodes* and *commit start nodes*. A commit start
node is written whenever an index commit is performed. Reference nodes are
written on every journal update. Each reference node points to the position of
@@ -152,6 +158,7 @@ done for the last referenced LEB of the journal. Only this can become corrupt
because of a power cut. If the recovery fails, UBIFS will not mount. An error
for every other LEB will directly cause UBIFS to fail the mount operation.
+::
| ---- LOG AREA ---- | ---------- MAIN AREA ------------ |
@@ -172,10 +179,11 @@ for every other LEB will directly cause UBIFS to fail the mount operation.
containing their buds
-### LEB Property Tree/Table
+LEB Property Tree/Table
+~~~~~~~~~~~~~~~~~~~~~~~
The LEB property tree is used to store per-LEB information. This includes the
-LEB type and amount of free and *dirty* (old, obsolete content) space [1] on
+LEB type and amount of free and *dirty* (old, obsolete content) space [1]_ on
the LEB. The type is important, because UBIFS never mixes index nodes with data
nodes on a single LEB and thus each LEB has a specific purpose. This again is
useful for free space calculations. See [UBIFS-WP] for more details.
@@ -185,19 +193,21 @@ index. Due to its smaller size it is always written as one chunk on every
commit. Thus, saving the LPT is an atomic operation.
-[1] Since LEBs can only be appended and never overwritten, there is a
-difference between free space ie. the remaining space left on the LEB to be
-written to without erasing it and previously written content that is obsolete
-but can't be overwritten without erasing the full LEB.
+.. [1] Since LEBs can only be appended and never overwritten, there is a
+ difference between free space ie. the remaining space left on the LEB to be
+ written to without erasing it and previously written content that is obsolete
+ but can't be overwritten without erasing the full LEB.
-# UBIFS Authentication
+UBIFS Authentication
+====================
This chapter introduces UBIFS authentication which enables UBIFS to verify
the authenticity and integrity of metadata and file contents stored on flash.
-## Threat Model
+Threat Model
+------------
UBIFS authentication enables detection of offline data modification. While it
does not prevent it, it enables (trusted) code to check the integrity and
@@ -224,7 +234,8 @@ Additional measures like secure boot and trusted boot have to be taken to
ensure that only trusted code is executed on a device.
-## Authentication
+Authentication
+--------------
To be able to fully trust data read from flash, all UBIFS data structures
stored on flash are authenticated. That is:
@@ -236,7 +247,8 @@ stored on flash are authenticated. That is:
- The LPT which stores UBI LEB metadata which UBIFS uses for free space accounting
-### Index Authentication
+Index Authentication
+~~~~~~~~~~~~~~~~~~~~
Through UBIFS' concept of a wandering tree, it already takes care of only
updating and persisting changed parts from leaf node up to the root node
@@ -260,6 +272,7 @@ include a hash. All other types of nodes will remain unchanged. This reduces
the storage overhead which is precious for users of UBIFS (ie. embedded
devices).
+::
+---------------+
| Master Node |
@@ -303,7 +316,8 @@ hashes to index nodes does not change this since each hash will be persisted
atomically together with its respective node.
-### Journal Authentication
+Journal Authentication
+~~~~~~~~~~~~~~~~~~~~~~
The journal is authenticated too. Since the journal is continuously written
it is necessary to also add authentication information frequently to the
@@ -316,7 +330,7 @@ of the hash chain. That way a journal can be authenticated up to the last
authentication node. The tail of the journal which may not have a authentication
node cannot be authenticated and is skipped during journal replay.
-We get this picture for journal authentication:
+We get this picture for journal authentication::
,,,,,,,,
,......,...........................................
@@ -352,7 +366,8 @@ the superblock struct. The superblock node is stored in LEB 0 and is only
modified on feature flag or similar changes, but never on file changes.
-### LPT Authentication
+LPT Authentication
+~~~~~~~~~~~~~~~~~~
The location of the LPT root node on the flash is stored in the UBIFS master
node. Since the LPT is written and read atomically on every commit, there is
@@ -363,7 +378,8 @@ be verified by verifying the authenticity of the master node and comparing the
LTP hash stored there with the hash computed from the read on-flash LPT.
-## Key Management
+Key Management
+--------------
For simplicity, UBIFS authentication uses a single key to compute the HMACs
of superblock, master, commit start and reference nodes. This key has to be
@@ -399,7 +415,8 @@ approach is similar to the approach proposed for fscrypt encryption policy v2
[FSCRYPT-POLICY2].
-# Future Extensions
+Future Extensions
+=================
In certain cases where a vendor wants to provide an authenticated filesystem
image to customers, it should be possible to do so without sharing the secret
@@ -411,7 +428,8 @@ to the way the IMA/EVM subsystem deals with such situations. The HMAC key
will then have to be provided beforehand in the normal way.
-# References
+References
+==========
[CRYPTSETUP2] http://www.saout.de/pipermail/dm-crypt/2017-November/005745.html
--
2.21.0
^ permalink raw reply related
* [PATCH 09/22] docs: parisc: 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, James E.J. Bottomley,
Helge Deller, linux-doc, linux-parisc
In-Reply-To: <cover.1563792333.git.mchehab+samsung@kernel.org>
Manually convert the two PA-RISC documents to ReST, adding them
to the Linux documentation body.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/index.rst | 1 +
.../parisc/{debugging => debugging.rst} | 7 +++
Documentation/parisc/index.rst | 18 ++++++
.../parisc/{registers => registers.rst} | 59 +++++++++++++------
4 files changed, 68 insertions(+), 17 deletions(-)
rename Documentation/parisc/{debugging => debugging.rst} (94%)
create mode 100644 Documentation/parisc/index.rst
rename Documentation/parisc/{registers => registers.rst} (70%)
diff --git a/Documentation/index.rst b/Documentation/index.rst
index ef9543c2516d..9bb08d272bd5 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -149,6 +149,7 @@ implementation.
ia64/index
m68k/index
powerpc/index
+ parisc/index
riscv/index
s390/index
sh/index
diff --git a/Documentation/parisc/debugging b/Documentation/parisc/debugging.rst
similarity index 94%
rename from Documentation/parisc/debugging
rename to Documentation/parisc/debugging.rst
index 7d75223fa18d..de1b60402c5b 100644
--- a/Documentation/parisc/debugging
+++ b/Documentation/parisc/debugging.rst
@@ -1,8 +1,13 @@
+=================
+PA-RISC Debugging
+=================
+
okay, here are some hints for debugging the lower-level parts of
linux/parisc.
1. Absolute addresses
+=====================
A lot of the assembly code currently runs in real mode, which means
absolute addresses are used instead of virtual addresses as in the
@@ -12,6 +17,7 @@ currently).
2. HPMCs
+========
When real-mode code tries to access non-existent memory, you'll get
an HPMC instead of a kernel oops. To debug an HPMC, try to find
@@ -27,6 +33,7 @@ access it.
3. Q bit fun
+============
Certain, very critical code has to clear the Q bit in the PSW. What
happens when the Q bit is cleared is the CPU does not update the
diff --git a/Documentation/parisc/index.rst b/Documentation/parisc/index.rst
new file mode 100644
index 000000000000..aa3ee0470425
--- /dev/null
+++ b/Documentation/parisc/index.rst
@@ -0,0 +1,18 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+====================
+PA-RISC Architecture
+====================
+
+.. toctree::
+ :maxdepth: 2
+
+ debugging
+ registers
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/parisc/registers b/Documentation/parisc/registers.rst
similarity index 70%
rename from Documentation/parisc/registers
rename to Documentation/parisc/registers.rst
index 10c7d1730f5d..59c8ecf3e856 100644
--- a/Documentation/parisc/registers
+++ b/Documentation/parisc/registers.rst
@@ -1,11 +1,16 @@
+================================
Register Usage for Linux/PA-RISC
+================================
[ an asterisk is used for planned usage which is currently unimplemented ]
- General Registers as specified by ABI
+General Registers as specified by ABI
+=====================================
- Control Registers
+Control Registers
+-----------------
+=============================== ===============================================
CR 0 (Recovery Counter) used for ptrace
CR 1-CR 7(undefined) unused
CR 8 (Protection ID) per-process value*
@@ -29,26 +34,35 @@ CR28 (TR 4) not used
CR29 (TR 5) not used
CR30 (TR 6) current / 0
CR31 (TR 7) Temporary register, used in various places
+=============================== ===============================================
- Space Registers (kernel mode)
+Space Registers (kernel mode)
+-----------------------------
+=============================== ===============================================
SR0 temporary space register
SR4-SR7 set to 0
SR1 temporary space register
SR2 kernel should not clobber this
SR3 used for userspace accesses (current process)
+=============================== ===============================================
- Space Registers (user mode)
+Space Registers (user mode)
+---------------------------
+=============================== ===============================================
SR0 temporary space register
SR1 temporary space register
SR2 holds space of linux gateway page
SR3 holds user address space value while in kernel
SR4-SR7 Defines short address space for user/kernel
+=============================== ===============================================
- Processor Status Word
+Processor Status Word
+---------------------
+=============================== ===============================================
W (64-bit addresses) 0
E (Little-endian) 0
S (Secure Interval Timer) 0
@@ -69,15 +83,19 @@ Q (collect interruption state) 1 (0 in code directly preceding an rfi)
P (Protection Identifiers) 1*
D (Data address translation) 1, 0 while executing real-mode code
I (external interrupt mask) used by cli()/sti() macros
+=============================== ===============================================
- "Invisible" Registers
+"Invisible" Registers
+---------------------
+=============================== ===============================================
PSW default W value 0
PSW default E value 0
Shadow Registers used by interruption handler code
TOC enable bit 1
+=============================== ===============================================
-=========================================================================
+-------------------------------------------------------------------------
The PA-RISC architecture defines 7 registers as "shadow registers".
Those are used in RETURN FROM INTERRUPTION AND RESTORE instruction to reduce
@@ -85,7 +103,8 @@ the state save and restore time by eliminating the need for general register
(GR) saves and restores in interruption handlers.
Shadow registers are the GRs 1, 8, 9, 16, 17, 24, and 25.
-=========================================================================
+-------------------------------------------------------------------------
+
Register usage notes, originally from John Marvin, with some additional
notes from Randolph Chung.
@@ -96,10 +115,12 @@ course, you need to save them if you care about them, before calling
another procedure. Some of the above registers do have special meanings
that you should be aware of:
- r1: The addil instruction is hardwired to place its result in r1,
+ r1:
+ The addil instruction is hardwired to place its result in r1,
so if you use that instruction be aware of that.
- r2: This is the return pointer. In general you don't want to
+ r2:
+ This is the return pointer. In general you don't want to
use this, since you need the pointer to get back to your
caller. However, it is grouped with this set of registers
since the caller can't rely on the value being the same
@@ -107,23 +128,27 @@ that you should be aware of:
and return through that register after trashing r2, and
that should not cause a problem for the calling routine.
- r19-r22: these are generally regarded as temporary registers.
+ r19-r22:
+ these are generally regarded as temporary registers.
Note that in 64 bit they are arg7-arg4.
- r23-r26: these are arg3-arg0, i.e. you can use them if you
+ r23-r26:
+ these are arg3-arg0, i.e. you can use them if you
don't care about the values that were passed in anymore.
- r28,r29: are ret0 and ret1. They are what you pass return values
+ r28,r29:
+ are ret0 and ret1. They are what you pass return values
in. r28 is the primary return. When returning small structures
r29 may also be used to pass data back to the caller.
- r30: stack pointer
+ r30:
+ stack pointer
- r31: the ble instruction puts the return pointer in here.
+ r31:
+ the ble instruction puts the return pointer in here.
-r3-r18,r27,r30 need to be saved and restored. r3-r18 are just
+ r3-r18,r27,r30 need to be saved and restored. r3-r18 are just
general purpose registers. r27 is the data pointer, and is
used to make references to global variables easier. r30 is
the stack pointer.
-
--
2.21.0
^ permalink raw reply related
* [PATCH 00/22] ReST conversion of text files without .txt extension
From: Mauro Carvalho Chehab @ 2019-07-22 11:07 UTC (permalink / raw)
Cc: Mauro Carvalho Chehab, linux-spi, dmaengine, netdev, linux-wimax,
devel, linux-i2c, linux-parisc, devel, linux-cifs, rcu, linux-iio,
openrisc, Greg Kroah-Hartman, Jonathan Corbet, linux-doc,
alsa-devel, linux-wireless, linux-rtc, linux-mips
This series converts the text files under Documentation with doesn't end
neither .txt or .rst and are not part of ABI or features[1].
This series is at:
https://git.linuxtv.org/mchehab/experimental.git/log/?h=rst_for_5_4_v2.1
And comes after the pending patches I had for v5.13 (some not applied
yet):
https://git.linuxtv.org/mchehab/experimental.git/log/?h=pending_docs_after_5.13-rc1
[1] I submitted already a series to handle ABI and features.
There are some files besides the ones there with, IMHO, it
doesn't make sense to convert.
So, I wrote a small ugly script to track the files waiting to be
converted:
#!/bin/bash
find Documentation/ -name '*.txt'|grep -vE '(features/|devicetree/|sphinx/|output/|dax-hv-api.txt|draft-ietf-cipso-ipsecurity-01.txt|translations)'
for i in $(find Documentation/ -type f|grep -v translations/|grep -v output/|grep -v devicetree|grep -v -E "\.(rst|txt|py|pyc|pl|dot|conf|svg|sh|awk|gif|S|inf|c|csv|css|vim|exceptions|modes)$"|grep -v ABI/ |grep -v Documentation/EDID/hex|grep -v dontdiff|grep -v Kconfig|grep -v Makefile|grep -v Module.symvers|grep -vE '\b(CodingStyle|SubmittingPatches|target-export-device|hotplug-script|wusb-cbaf)\b'|grep -v -E '(LICENSE|COPY|gitignore|Makefile|AUTHORS|TODO|CHANGES|CREDITS|ChangeLog)'|grep -v Documentation/virtual/kvm/devices/README); do echo $i; done
After this patch series, the script reports 358 files missing conversion, all ending with .txt.
From those, ~40 files are already at ReST format - the ones at Documentation/*.txt - except
for a couple of files there.
So, there's around 320 files left to be converted after this series,
with gives me hope that we may finally finish the conversion this
year. Let's see.
Mauro Carvalho Chehab (22):
docs: convert markdown documents to ReST
docs: i2c: convert to ReST and add to driver-api bookset
docs: w1: convert to ReST and add to the kAPI group of docs
docs: spi: convert to ReST and add it to the kABI bookset
docs: ipmb: place it at driver-api and convert to ReST
docs: packing: move it to core-api book and adjust markups
docs: admin-guide: add auxdisplay files to it after conversion to ReST
docs: README.buddha: convert to ReST and add to m68k book
docs: parisc: convert to ReST and add to documentation body
docs: openrisc: convert to ReST and add to documentation body
docs: isdn: convert to ReST and add to kAPI bookset
docs: fs: cifs: convert to ReST and add to admin-guide book
docs: fs: convert docs without extension to ReST
docs: fs: convert porting to ReST
docs: index.rst: don't use genindex for pdf output
docs: wimax: convert to ReST and add to admin-guide
docs: mips: add to the documentation body as ReST
docs: hwmon: pxe1610: convert to ReST format and add to the index
docs: nios2: add it to the main Documentation body
docs: net: convert two README files to ReST format
docs: rcu: convert some articles from html to ReST
docs: ABI: remove extension from sysfs-class-mic.txt
Documentation/ABI/stable/sysfs-bus-w1 | 2 +-
.../ABI/stable/sysfs-driver-w1_ds28e04 | 4 +-
.../ABI/stable/sysfs-driver-w1_ds28ea00 | 2 +-
.../{sysfs-class-mic.txt => sysfs-class-mic} | 0
.../Data-Structures/Data-Structures.html | 1391 -------
.../Data-Structures/Data-Structures.rst | 1163 ++++++
.../Expedited-Grace-Periods.html | 668 ----
.../Expedited-Grace-Periods.rst | 521 +++
.../Memory-Ordering/Tree-RCU-Diagram.html | 9 -
.../Tree-RCU-Memory-Ordering.html | 704 ----
.../Tree-RCU-Memory-Ordering.rst | 625 ++++
.../RCU/Design/Requirements/Requirements.html | 3330 -----------------
.../RCU/Design/Requirements/Requirements.rst | 2662 +++++++++++++
Documentation/RCU/index.rst | 5 +
Documentation/RCU/whatisRCU.txt | 4 +-
.../admin-guide/auxdisplay/cfag12864b.rst | 98 +
.../admin-guide/auxdisplay/index.rst | 16 +
.../admin-guide/auxdisplay/ks0108.rst | 50 +
.../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 | 3 +
.../wimax/i2400m.rst} | 145 +-
Documentation/admin-guide/wimax/index.rst | 19 +
.../wimax/wimax.rst} | 36 +-
Documentation/auxdisplay/cfag12864b | 105 -
Documentation/auxdisplay/ks0108 | 55 -
Documentation/core-api/index.rst | 3 +-
.../{packing.txt => core-api/packing.rst} | 81 +-
.../devicetree/bindings/i2c/i2c-mux-gpmux.txt | 2 +-
Documentation/devicetree/writing-schema.md | 130 -
Documentation/devicetree/writing-schema.rst | 153 +
Documentation/driver-api/dmaengine/index.rst | 2 +-
Documentation/driver-api/index.rst | 1 +
Documentation/driver-api/ipmb.rst | 2 +-
Documentation/driver-api/soundwire/index.rst | 2 +-
...irectory-locking => directory-locking.rst} | 40 +-
Documentation/filesystems/index.rst | 4 +
.../filesystems/{Locking => locking.rst} | 257 +-
.../nfs/{Exporting => exporting.rst} | 31 +-
Documentation/filesystems/porting | 686 ----
Documentation/filesystems/porting.rst | 852 +++++
...entication.md => ubifs-authentication.rst} | 70 +-
Documentation/filesystems/vfs.rst | 2 +-
Documentation/hwmon/adm1021.rst | 2 +-
Documentation/hwmon/adm1275.rst | 2 +-
Documentation/hwmon/hih6130.rst | 2 +-
Documentation/hwmon/ibm-cffps.rst | 2 +-
Documentation/hwmon/index.rst | 1 +
Documentation/hwmon/lm25066.rst | 2 +-
Documentation/hwmon/max16064.rst | 2 +-
Documentation/hwmon/max16065.rst | 2 +-
Documentation/hwmon/max20751.rst | 2 +-
Documentation/hwmon/max34440.rst | 2 +-
Documentation/hwmon/max6650.rst | 2 +-
Documentation/hwmon/max8688.rst | 2 +-
Documentation/hwmon/menf21bmc.rst | 2 +-
Documentation/hwmon/pcf8591.rst | 2 +-
Documentation/hwmon/{pxe1610 => pxe1610.rst} | 33 +-
Documentation/hwmon/sht3x.rst | 2 +-
Documentation/hwmon/shtc1.rst | 2 +-
Documentation/hwmon/tmp103.rst | 2 +-
Documentation/hwmon/tps40422.rst | 2 +-
Documentation/hwmon/ucd9000.rst | 2 +-
Documentation/hwmon/ucd9200.rst | 2 +-
Documentation/hwmon/via686a.rst | 2 +-
Documentation/hwmon/zl6100.rst | 2 +-
.../busses/{i2c-ali1535 => i2c-ali1535.rst} | 13 +-
.../busses/{i2c-ali1563 => i2c-ali1563.rst} | 3 +
.../busses/{i2c-ali15x3 => i2c-ali15x3.rst} | 64 +-
Documentation/i2c/busses/i2c-amd-mp2 | 23 -
Documentation/i2c/busses/i2c-amd-mp2.rst | 25 +
.../i2c/busses/{i2c-amd756 => i2c-amd756.rst} | 8 +-
.../busses/{i2c-amd8111 => i2c-amd8111.rst} | 14 +-
.../{i2c-diolan-u2c => i2c-diolan-u2c.rst} | 3 +
.../i2c/busses/{i2c-i801 => i2c-i801.rst} | 33 +-
.../i2c/busses/{i2c-ismt => i2c-ismt.rst} | 20 +-
.../busses/{i2c-mlxcpld => i2c-mlxcpld.rst} | 6 +
.../busses/{i2c-nforce2 => i2c-nforce2.rst} | 33 +-
.../{i2c-nvidia-gpu => i2c-nvidia-gpu.rst} | 6 +-
.../i2c/busses/{i2c-ocores => i2c-ocores.rst} | 22 +-
Documentation/i2c/busses/i2c-parport | 178 -
...2c-parport-light => i2c-parport-light.rst} | 8 +-
Documentation/i2c/busses/i2c-parport.rst | 190 +
.../busses/{i2c-pca-isa => i2c-pca-isa.rst} | 9 +-
.../i2c/busses/{i2c-piix4 => i2c-piix4.rst} | 18 +-
.../busses/{i2c-sis5595 => i2c-sis5595.rst} | 19 +-
Documentation/i2c/busses/i2c-sis630 | 58 -
Documentation/i2c/busses/i2c-sis630.rst | 63 +
.../i2c/busses/{i2c-sis96x => i2c-sis96x.rst} | 31 +-
.../busses/{i2c-taos-evm => i2c-taos-evm.rst} | 8 +-
.../i2c/busses/{i2c-via => i2c-via.rst} | 28 +-
.../i2c/busses/{i2c-viapro => i2c-viapro.rst} | 12 +-
Documentation/i2c/busses/index.rst | 33 +
.../i2c/busses/{scx200_acb => scx200_acb.rst} | 9 +-
.../i2c/{dev-interface => dev-interface.rst} | 94 +-
...-considerations => dma-considerations.rst} | 0
.../i2c/{fault-codes => fault-codes.rst} | 5 +-
.../i2c/{functionality => functionality.rst} | 22 +-
...ult-injection => gpio-fault-injection.rst} | 12 +-
.../i2c/{i2c-protocol => i2c-protocol.rst} | 28 +-
Documentation/i2c/{i2c-stub => i2c-stub.rst} | 20 +-
.../i2c/{i2c-topology => i2c-topology.rst} | 68 +-
Documentation/i2c/index.rst | 37 +
...ting-devices => instantiating-devices.rst} | 45 +-
.../muxes/{i2c-mux-gpio => i2c-mux-gpio.rst} | 26 +-
...e-parameters => old-module-parameters.rst} | 27 +-
...eprom-backend => slave-eeprom-backend.rst} | 4 +-
.../{slave-interface => slave-interface.rst} | 33 +-
.../{smbus-protocol => smbus-protocol.rst} | 86 +-
Documentation/i2c/{summary => summary.rst} | 6 +-
...en-bit-addresses => ten-bit-addresses.rst} | 5 +
...pgrading-clients => upgrading-clients.rst} | 204 +-
.../{writing-clients => writing-clients.rst} | 94 +-
Documentation/index.rst | 8 +
.../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 +-
.../m68k/{README.buddha => buddha-driver.rst} | 95 +-
Documentation/m68k/index.rst | 1 +
.../{AU1xxx_IDE.README => au1xxx_ide.rst} | 89 +-
Documentation/mips/index.rst | 17 +
.../networking/caif/{README => caif.rst} | 88 +-
.../networking/device_drivers/index.rst | 2 +-
Documentation/networking/index.rst | 2 +-
.../{README => mac80211_hwsim.rst} | 28 +-
Documentation/nios2/{README => nios2.rst} | 1 +
Documentation/openrisc/index.rst | 18 +
.../openrisc/{README => openrisc_port.rst} | 25 +-
Documentation/openrisc/{TODO => todo.rst} | 9 +-
.../parisc/{debugging => debugging.rst} | 7 +
Documentation/parisc/index.rst | 18 +
.../parisc/{registers => registers.rst} | 59 +-
Documentation/sound/index.rst | 2 +-
.../spi/{butterfly => butterfly.rst} | 44 +-
Documentation/spi/index.rst | 22 +
Documentation/spi/{pxa2xx => pxa2xx.rst} | 95 +-
.../spi/{spi-lm70llp => spi-lm70llp.rst} | 17 +-
.../spi/{spi-sc18is602 => spi-sc18is602.rst} | 5 +-
.../spi/{spi-summary => spi-summary.rst} | 105 +-
Documentation/spi/{spidev => spidev.rst} | 30 +-
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 +-
MAINTAINERS | 60 +-
drivers/auxdisplay/Kconfig | 2 +-
drivers/hwmon/atxp1.c | 2 +-
drivers/hwmon/smm665.c | 2 +-
drivers/i2c/Kconfig | 4 +-
drivers/i2c/busses/Kconfig | 2 +-
drivers/i2c/busses/i2c-i801.c | 2 +-
drivers/i2c/busses/i2c-taos-evm.c | 2 +-
drivers/i2c/i2c-core-base.c | 4 +-
drivers/iio/dummy/iio_simple_dummy.c | 4 +-
drivers/rtc/rtc-ds1374.c | 2 +-
drivers/spi/Kconfig | 2 +-
drivers/spi/spi-butterfly.c | 2 +-
drivers/spi/spi-lm70llp.c | 2 +-
drivers/staging/isdn/hysdn/Kconfig | 2 +-
fs/cifs/export.c | 2 +-
fs/exportfs/expfs.c | 2 +-
fs/isofs/export.c | 2 +-
fs/orangefs/file.c | 2 +-
fs/orangefs/orangefs-kernel.h | 2 +-
include/linux/dcache.h | 2 +-
include/linux/exportfs.h | 2 +-
include/linux/i2c.h | 2 +-
include/linux/platform_data/sc18is602.h | 2 +-
192 files changed, 9538 insertions(+), 9201 deletions(-)
rename Documentation/ABI/testing/{sysfs-class-mic.txt => sysfs-class-mic} (100%)
delete mode 100644 Documentation/RCU/Design/Data-Structures/Data-Structures.html
create mode 100644 Documentation/RCU/Design/Data-Structures/Data-Structures.rst
delete mode 100644 Documentation/RCU/Design/Expedited-Grace-Periods/Expedited-Grace-Periods.html
create mode 100644 Documentation/RCU/Design/Expedited-Grace-Periods/Expedited-Grace-Periods.rst
delete mode 100644 Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Diagram.html
delete mode 100644 Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Memory-Ordering.html
create mode 100644 Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Memory-Ordering.rst
delete mode 100644 Documentation/RCU/Design/Requirements/Requirements.html
create mode 100644 Documentation/RCU/Design/Requirements/Requirements.rst
create mode 100644 Documentation/admin-guide/auxdisplay/cfag12864b.rst
create mode 100644 Documentation/admin-guide/auxdisplay/index.rst
create mode 100644 Documentation/admin-guide/auxdisplay/ks0108.rst
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%)
rename Documentation/{wimax/README.i2400m => admin-guide/wimax/i2400m.rst} (69%)
create mode 100644 Documentation/admin-guide/wimax/index.rst
rename Documentation/{wimax/README.wimax => admin-guide/wimax/wimax.rst} (74%)
delete mode 100644 Documentation/auxdisplay/cfag12864b
delete mode 100644 Documentation/auxdisplay/ks0108
rename Documentation/{packing.txt => core-api/packing.rst} (61%)
delete mode 100644 Documentation/devicetree/writing-schema.md
create mode 100644 Documentation/devicetree/writing-schema.rst
rename Documentation/filesystems/{directory-locking => directory-locking.rst} (86%)
rename Documentation/filesystems/{Locking => locking.rst} (79%)
rename Documentation/filesystems/nfs/{Exporting => exporting.rst} (91%)
delete mode 100644 Documentation/filesystems/porting
create mode 100644 Documentation/filesystems/porting.rst
rename Documentation/filesystems/{ubifs-authentication.md => ubifs-authentication.rst} (95%)
rename Documentation/hwmon/{pxe1610 => pxe1610.rst} (82%)
rename Documentation/i2c/busses/{i2c-ali1535 => i2c-ali1535.rst} (82%)
rename Documentation/i2c/busses/{i2c-ali1563 => i2c-ali1563.rst} (93%)
rename Documentation/i2c/busses/{i2c-ali15x3 => i2c-ali15x3.rst} (72%)
delete mode 100644 Documentation/i2c/busses/i2c-amd-mp2
create mode 100644 Documentation/i2c/busses/i2c-amd-mp2.rst
rename Documentation/i2c/busses/{i2c-amd756 => i2c-amd756.rst} (79%)
rename Documentation/i2c/busses/{i2c-amd8111 => i2c-amd8111.rst} (66%)
rename Documentation/i2c/busses/{i2c-diolan-u2c => i2c-diolan-u2c.rst} (91%)
rename Documentation/i2c/busses/{i2c-i801 => i2c-i801.rst} (89%)
rename Documentation/i2c/busses/{i2c-ismt => i2c-ismt.rst} (81%)
rename Documentation/i2c/busses/{i2c-mlxcpld => i2c-mlxcpld.rst} (88%)
rename Documentation/i2c/busses/{i2c-nforce2 => i2c-nforce2.rst} (58%)
rename Documentation/i2c/busses/{i2c-nvidia-gpu => i2c-nvidia-gpu.rst} (63%)
rename Documentation/i2c/busses/{i2c-ocores => i2c-ocores.rst} (82%)
delete mode 100644 Documentation/i2c/busses/i2c-parport
rename Documentation/i2c/busses/{i2c-parport-light => i2c-parport-light.rst} (91%)
create mode 100644 Documentation/i2c/busses/i2c-parport.rst
rename Documentation/i2c/busses/{i2c-pca-isa => i2c-pca-isa.rst} (72%)
rename Documentation/i2c/busses/{i2c-piix4 => i2c-piix4.rst} (92%)
rename Documentation/i2c/busses/{i2c-sis5595 => i2c-sis5595.rst} (74%)
delete mode 100644 Documentation/i2c/busses/i2c-sis630
create mode 100644 Documentation/i2c/busses/i2c-sis630.rst
rename Documentation/i2c/busses/{i2c-sis96x => i2c-sis96x.rst} (74%)
rename Documentation/i2c/busses/{i2c-taos-evm => i2c-taos-evm.rst} (91%)
rename Documentation/i2c/busses/{i2c-via => i2c-via.rst} (54%)
rename Documentation/i2c/busses/{i2c-viapro => i2c-viapro.rst} (87%)
create mode 100644 Documentation/i2c/busses/index.rst
rename Documentation/i2c/busses/{scx200_acb => scx200_acb.rst} (86%)
rename Documentation/i2c/{dev-interface => dev-interface.rst} (71%)
rename Documentation/i2c/{DMA-considerations => dma-considerations.rst} (100%)
rename Documentation/i2c/{fault-codes => fault-codes.rst} (98%)
rename Documentation/i2c/{functionality => functionality.rst} (91%)
rename Documentation/i2c/{gpio-fault-injection => gpio-fault-injection.rst} (97%)
rename Documentation/i2c/{i2c-protocol => i2c-protocol.rst} (83%)
rename Documentation/i2c/{i2c-stub => i2c-stub.rst} (93%)
rename Documentation/i2c/{i2c-topology => i2c-topology.rst} (89%)
create mode 100644 Documentation/i2c/index.rst
rename Documentation/i2c/{instantiating-devices => instantiating-devices.rst} (93%)
rename Documentation/i2c/muxes/{i2c-mux-gpio => i2c-mux-gpio.rst} (85%)
rename Documentation/i2c/{old-module-parameters => old-module-parameters.rst} (75%)
rename Documentation/i2c/{slave-eeprom-backend => slave-eeprom-backend.rst} (90%)
rename Documentation/i2c/{slave-interface => slave-interface.rst} (94%)
rename Documentation/i2c/{smbus-protocol => smbus-protocol.rst} (82%)
rename Documentation/i2c/{summary => summary.rst} (96%)
rename Documentation/i2c/{ten-bit-addresses => ten-bit-addresses.rst} (95%)
rename Documentation/i2c/{upgrading-clients => upgrading-clients.rst} (54%)
rename Documentation/i2c/{writing-clients => writing-clients.rst} (91%)
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%)
rename Documentation/m68k/{README.buddha => buddha-driver.rst} (73%)
rename Documentation/mips/{AU1xxx_IDE.README => au1xxx_ide.rst} (67%)
create mode 100644 Documentation/mips/index.rst
rename Documentation/networking/caif/{README => caif.rst} (70%)
rename Documentation/networking/mac80211_hwsim/{README => mac80211_hwsim.rst} (81%)
rename Documentation/nios2/{README => nios2.rst} (96%)
create mode 100644 Documentation/openrisc/index.rst
rename Documentation/openrisc/{README => openrisc_port.rst} (80%)
rename Documentation/openrisc/{TODO => todo.rst} (78%)
rename Documentation/parisc/{debugging => debugging.rst} (94%)
create mode 100644 Documentation/parisc/index.rst
rename Documentation/parisc/{registers => registers.rst} (70%)
rename Documentation/spi/{butterfly => butterfly.rst} (71%)
create mode 100644 Documentation/spi/index.rst
rename Documentation/spi/{pxa2xx => pxa2xx.rst} (83%)
rename Documentation/spi/{spi-lm70llp => spi-lm70llp.rst} (88%)
rename Documentation/spi/{spi-sc18is602 => spi-sc18is602.rst} (92%)
rename Documentation/spi/{spi-summary => spi-summary.rst} (93%)
rename Documentation/spi/{spidev => spidev.rst} (90%)
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%)
--
2.21.0
^ permalink raw reply
* [PATCH 04/22] docs: spi: convert to ReST and add it to the kABI bookset
From: Mauro Carvalho Chehab @ 2019-07-22 11:07 UTC (permalink / raw)
Cc: Mauro Carvalho Chehab, Jonathan Corbet, Mark Brown,
Jonathan Cameron, Hartmut Knaack, Lars-Peter Clausen,
Peter Meerwald-Stadler, linux-doc, linux-spi, linux-iio,
Jonathan Cameron
In-Reply-To: <cover.1563792333.git.mchehab+samsung@kernel.org>
While there's one file there with briefily describes the uAPI,
the documentation was written just like most subsystems: focused
on kernel developers. So, add it together with driver-api books.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Jonathan Cameron <Jonathan.Cameron@huawei.com> # for iio
---
Documentation/index.rst | 1 +
.../spi/{butterfly => butterfly.rst} | 44 ++++----
Documentation/spi/index.rst | 22 ++++
Documentation/spi/{pxa2xx => pxa2xx.rst} | 95 ++++++++--------
.../spi/{spi-lm70llp => spi-lm70llp.rst} | 17 ++-
.../spi/{spi-sc18is602 => spi-sc18is602.rst} | 3 +
.../spi/{spi-summary => spi-summary.rst} | 105 ++++++++++--------
Documentation/spi/{spidev => spidev.rst} | 30 +++--
drivers/iio/dummy/iio_simple_dummy.c | 2 +-
drivers/spi/Kconfig | 2 +-
drivers/spi/spi-butterfly.c | 2 +-
drivers/spi/spi-lm70llp.c | 2 +-
include/linux/platform_data/sc18is602.h | 2 +-
13 files changed, 198 insertions(+), 129 deletions(-)
rename Documentation/spi/{butterfly => butterfly.rst} (71%)
create mode 100644 Documentation/spi/index.rst
rename Documentation/spi/{pxa2xx => pxa2xx.rst} (83%)
rename Documentation/spi/{spi-lm70llp => spi-lm70llp.rst} (88%)
rename Documentation/spi/{spi-sc18is602 => spi-sc18is602.rst} (97%)
rename Documentation/spi/{spi-summary => spi-summary.rst} (93%)
rename Documentation/spi/{spidev => spidev.rst} (90%)
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 8730c7455265..ef9543c2516d 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -115,6 +115,7 @@ needed).
power/index
target/index
timers/index
+ spi/index
w1/index
watchdog/index
virtual/index
diff --git a/Documentation/spi/butterfly b/Documentation/spi/butterfly.rst
similarity index 71%
rename from Documentation/spi/butterfly
rename to Documentation/spi/butterfly.rst
index 9927af7a629c..e614a589547c 100644
--- a/Documentation/spi/butterfly
+++ b/Documentation/spi/butterfly.rst
@@ -1,3 +1,4 @@
+===================================================
spi_butterfly - parport-to-butterfly adapter driver
===================================================
@@ -27,25 +28,29 @@ need to reflash the firmware, and the pins are the standard Atmel "ISP"
connector pins (used also on non-Butterfly AVR boards). On the parport
side this is like "sp12" programming cables.
+ ====== ============= ===================
Signal Butterfly Parport (DB-25)
- ------ --------- ---------------
- SCK = J403.PB1/SCK = pin 2/D0
- RESET = J403.nRST = pin 3/D1
- VCC = J403.VCC_EXT = pin 8/D6
- MOSI = J403.PB2/MOSI = pin 9/D7
- MISO = J403.PB3/MISO = pin 11/S7,nBUSY
- GND = J403.GND = pin 23/GND
+ ====== ============= ===================
+ SCK J403.PB1/SCK pin 2/D0
+ RESET J403.nRST pin 3/D1
+ VCC J403.VCC_EXT pin 8/D6
+ MOSI J403.PB2/MOSI pin 9/D7
+ MISO J403.PB3/MISO pin 11/S7,nBUSY
+ GND J403.GND pin 23/GND
+ ====== ============= ===================
Then to let Linux master that bus to talk to the DataFlash chip, you must
(a) flash new firmware that disables SPI (set PRR.2, and disable pullups
by clearing PORTB.[0-3]); (b) configure the mtd_dataflash driver; and
(c) cable in the chipselect.
+ ====== ============ ===================
Signal Butterfly Parport (DB-25)
- ------ --------- ---------------
- VCC = J400.VCC_EXT = pin 7/D5
- SELECT = J400.PB0/nSS = pin 17/C3,nSELECT
- GND = J400.GND = pin 24/GND
+ ====== ============ ===================
+ VCC J400.VCC_EXT pin 7/D5
+ SELECT J400.PB0/nSS pin 17/C3,nSELECT
+ GND J400.GND pin 24/GND
+ ====== ============ ===================
Or you could flash firmware making the AVR into an SPI slave (keeping the
DataFlash in reset) and tweak the spi_butterfly driver to make it bind to
@@ -56,13 +61,14 @@ That would let you talk to the AVR using custom SPI-with-USI firmware,
while letting either Linux or the AVR use the DataFlash. There are plenty
of spare parport pins to wire this one up, such as:
+ ====== ============= ===================
Signal Butterfly Parport (DB-25)
- ------ --------- ---------------
- SCK = J403.PE4/USCK = pin 5/D3
- MOSI = J403.PE5/DI = pin 6/D4
- MISO = J403.PE6/DO = pin 12/S5,nPAPEROUT
- GND = J403.GND = pin 22/GND
-
- IRQ = J402.PF4 = pin 10/S6,ACK
- GND = J402.GND(P2) = pin 25/GND
+ ====== ============= ===================
+ SCK J403.PE4/USCK pin 5/D3
+ MOSI J403.PE5/DI pin 6/D4
+ MISO J403.PE6/DO pin 12/S5,nPAPEROUT
+ GND J403.GND pin 22/GND
+ IRQ J402.PF4 pin 10/S6,ACK
+ GND J402.GND(P2) pin 25/GND
+ ====== ============= ===================
diff --git a/Documentation/spi/index.rst b/Documentation/spi/index.rst
new file mode 100644
index 000000000000..06c34ea11bcf
--- /dev/null
+++ b/Documentation/spi/index.rst
@@ -0,0 +1,22 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=================================
+Serial Peripheral Interface (SPI)
+=================================
+
+.. toctree::
+ :maxdepth: 1
+
+ spi-summary
+ spidev
+ butterfly
+ pxa2xx
+ spi-lm70llp
+ spi-sc18is602
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/spi/pxa2xx b/Documentation/spi/pxa2xx.rst
similarity index 83%
rename from Documentation/spi/pxa2xx
rename to Documentation/spi/pxa2xx.rst
index 551325b66b23..882d3cc72cc2 100644
--- a/Documentation/spi/pxa2xx
+++ b/Documentation/spi/pxa2xx.rst
@@ -1,8 +1,10 @@
+==============================
PXA2xx SPI on SSP driver HOWTO
-===================================================
+==============================
+
This a mini howto on the pxa2xx_spi driver. The driver turns a PXA2xx
synchronous serial port into a SPI master controller
-(see Documentation/spi/spi-summary). The driver has the following features
+(see Documentation/spi/spi-summary.rst). The driver has the following features
- Support for any PXA2xx SSP
- SSP PIO and SSP DMA data transfers.
@@ -19,12 +21,12 @@ Declaring PXA2xx Master Controllers
-----------------------------------
Typically a SPI master is defined in the arch/.../mach-*/board-*.c as a
"platform device". The master configuration is passed to the driver via a table
-found in include/linux/spi/pxa2xx_spi.h:
+found in include/linux/spi/pxa2xx_spi.h::
-struct pxa2xx_spi_controller {
+ struct pxa2xx_spi_controller {
u16 num_chipselect;
u8 enable_dma;
-};
+ };
The "pxa2xx_spi_controller.num_chipselect" field is used to determine the number of
slave device (chips) attached to this SPI master.
@@ -36,9 +38,9 @@ See the "PXA2xx Developer Manual" section "DMA Controller".
NSSP MASTER SAMPLE
------------------
-Below is a sample configuration using the PXA255 NSSP.
+Below is a sample configuration using the PXA255 NSSP::
-static struct resource pxa_spi_nssp_resources[] = {
+ static struct resource pxa_spi_nssp_resources[] = {
[0] = {
.start = __PREG(SSCR0_P(2)), /* Start address of NSSP */
.end = __PREG(SSCR0_P(2)) + 0x2c, /* Range of registers */
@@ -49,14 +51,14 @@ static struct resource pxa_spi_nssp_resources[] = {
.end = IRQ_NSSP,
.flags = IORESOURCE_IRQ,
},
-};
+ };
-static struct pxa2xx_spi_controller pxa_nssp_master_info = {
+ static struct pxa2xx_spi_controller pxa_nssp_master_info = {
.num_chipselect = 1, /* Matches the number of chips attached to NSSP */
.enable_dma = 1, /* Enables NSSP DMA */
-};
+ };
-static struct platform_device pxa_spi_nssp = {
+ static struct platform_device pxa_spi_nssp = {
.name = "pxa2xx-spi", /* MUST BE THIS VALUE, so device match driver */
.id = 2, /* Bus number, MUST MATCH SSP number 1..n */
.resource = pxa_spi_nssp_resources,
@@ -64,22 +66,22 @@ static struct platform_device pxa_spi_nssp = {
.dev = {
.platform_data = &pxa_nssp_master_info, /* Passed to driver */
},
-};
+ };
-static struct platform_device *devices[] __initdata = {
+ static struct platform_device *devices[] __initdata = {
&pxa_spi_nssp,
-};
+ };
-static void __init board_init(void)
-{
+ static void __init board_init(void)
+ {
(void)platform_add_device(devices, ARRAY_SIZE(devices));
-}
+ }
Declaring Slave Devices
-----------------------
Typically each SPI slave (chip) is defined in the arch/.../mach-*/board-*.c
using the "spi_board_info" structure found in "linux/spi/spi.h". See
-"Documentation/spi/spi-summary" for additional information.
+"Documentation/spi/spi-summary.rst" for additional information.
Each slave device attached to the PXA must provide slave specific configuration
information via the structure "pxa2xx_spi_chip" found in
@@ -87,19 +89,21 @@ information via the structure "pxa2xx_spi_chip" found in
will uses the configuration whenever the driver communicates with the slave
device. All fields are optional.
-struct pxa2xx_spi_chip {
+::
+
+ struct pxa2xx_spi_chip {
u8 tx_threshold;
u8 rx_threshold;
u8 dma_burst_size;
u32 timeout;
u8 enable_loopback;
void (*cs_control)(u32 command);
-};
+ };
The "pxa2xx_spi_chip.tx_threshold" and "pxa2xx_spi_chip.rx_threshold" fields are
used to configure the SSP hardware fifo. These fields are critical to the
performance of pxa2xx_spi driver and misconfiguration will result in rx
-fifo overruns (especially in PIO mode transfers). Good default values are
+fifo overruns (especially in PIO mode transfers). Good default values are::
.tx_threshold = 8,
.rx_threshold = 8,
@@ -141,41 +145,43 @@ The pxa2xx_spi_chip structure is passed to the pxa2xx_spi driver in the
"spi_board_info.controller_data" field. Below is a sample configuration using
the PXA255 NSSP.
-/* Chip Select control for the CS8415A SPI slave device */
-static void cs8415a_cs_control(u32 command)
-{
+::
+
+ /* Chip Select control for the CS8415A SPI slave device */
+ static void cs8415a_cs_control(u32 command)
+ {
if (command & PXA2XX_CS_ASSERT)
GPCR(2) = GPIO_bit(2);
else
GPSR(2) = GPIO_bit(2);
-}
+ }
-/* Chip Select control for the CS8405A SPI slave device */
-static void cs8405a_cs_control(u32 command)
-{
+ /* Chip Select control for the CS8405A SPI slave device */
+ static void cs8405a_cs_control(u32 command)
+ {
if (command & PXA2XX_CS_ASSERT)
GPCR(3) = GPIO_bit(3);
else
GPSR(3) = GPIO_bit(3);
-}
+ }
-static struct pxa2xx_spi_chip cs8415a_chip_info = {
+ static struct pxa2xx_spi_chip cs8415a_chip_info = {
.tx_threshold = 8, /* SSP hardward FIFO threshold */
.rx_threshold = 8, /* SSP hardward FIFO threshold */
.dma_burst_size = 8, /* Byte wide transfers used so 8 byte bursts */
.timeout = 235, /* See Intel documentation */
.cs_control = cs8415a_cs_control, /* Use external chip select */
-};
+ };
-static struct pxa2xx_spi_chip cs8405a_chip_info = {
+ static struct pxa2xx_spi_chip cs8405a_chip_info = {
.tx_threshold = 8, /* SSP hardward FIFO threshold */
.rx_threshold = 8, /* SSP hardward FIFO threshold */
.dma_burst_size = 8, /* Byte wide transfers used so 8 byte bursts */
.timeout = 235, /* See Intel documentation */
.cs_control = cs8405a_cs_control, /* Use external chip select */
-};
+ };
-static struct spi_board_info streetracer_spi_board_info[] __initdata = {
+ static struct spi_board_info streetracer_spi_board_info[] __initdata = {
{
.modalias = "cs8415a", /* Name of spi_driver for this device */
.max_speed_hz = 3686400, /* Run SSP as fast a possbile */
@@ -193,13 +199,13 @@ static struct spi_board_info streetracer_spi_board_info[] __initdata = {
.controller_data = &cs8405a_chip_info, /* Master chip config */
.irq = STREETRACER_APCI_IRQ, /* Slave device interrupt */
},
-};
+ };
-static void __init streetracer_init(void)
-{
+ static void __init streetracer_init(void)
+ {
spi_register_board_info(streetracer_spi_board_info,
ARRAY_SIZE(streetracer_spi_board_info));
-}
+ }
DMA and PIO I/O Support
@@ -210,26 +216,25 @@ by setting the "enable_dma" flag in the "pxa2xx_spi_controller" structure. The
mode supports both coherent and stream based DMA mappings.
The following logic is used to determine the type of I/O to be used on
-a per "spi_transfer" basis:
+a per "spi_transfer" basis::
-if !enable_dma then
+ if !enable_dma then
always use PIO transfers
-if spi_message.len > 8191 then
+ if spi_message.len > 8191 then
print "rate limited" warning
use PIO transfers
-if spi_message.is_dma_mapped and rx_dma_buf != 0 and tx_dma_buf != 0 then
+ if spi_message.is_dma_mapped and rx_dma_buf != 0 and tx_dma_buf != 0 then
use coherent DMA mode
-if rx_buf and tx_buf are aligned on 8 byte boundary then
+ if rx_buf and tx_buf are aligned on 8 byte boundary then
use streaming DMA mode
-otherwise
+ otherwise
use PIO transfer
THANKS TO
---------
David Brownell and others for mentoring the development of this driver.
-
diff --git a/Documentation/spi/spi-lm70llp b/Documentation/spi/spi-lm70llp.rst
similarity index 88%
rename from Documentation/spi/spi-lm70llp
rename to Documentation/spi/spi-lm70llp.rst
index 463f6d01fa15..07631aef4343 100644
--- a/Documentation/spi/spi-lm70llp
+++ b/Documentation/spi/spi-lm70llp.rst
@@ -1,8 +1,11 @@
+==============================================
spi_lm70llp : LM70-LLP parport-to-SPI adapter
==============================================
Supported board/chip:
+
* National Semiconductor LM70 LLP evaluation board
+
Datasheet: http://www.national.com/pf/LM/LM70.html
Author:
@@ -29,9 +32,10 @@ available (on page 4) here:
The hardware interfacing on the LM70 LLP eval board is as follows:
+ ======== == ========= ==========
Parallel LM70 LLP
- Port Direction JP2 Header
- ----------- --------- ----------------
+ Port . Direction JP2 Header
+ ======== == ========= ==========
D0 2 - -
D1 3 --> V+ 5
D2 4 --> V+ 5
@@ -42,7 +46,7 @@ The hardware interfacing on the LM70 LLP eval board is as follows:
D7 9 --> SI/O 5
GND 25 - GND 7
Select 13 <-- SI/O 1
- ----------- --------- ----------------
+ ======== == ========= ==========
Note that since the LM70 uses a "3-wire" variant of SPI, the SI/SO pin
is connected to both pin D7 (as Master Out) and Select (as Master In)
@@ -74,6 +78,7 @@ inverting the value read at pin 13.
Thanks to
---------
-o David Brownell for mentoring the SPI-side driver development.
-o Dr.Craig Hollabaugh for the (early) "manual" bitbanging driver version.
-o Nadir Billimoria for help interpreting the circuit schematic.
+
+- David Brownell for mentoring the SPI-side driver development.
+- Dr.Craig Hollabaugh for the (early) "manual" bitbanging driver version.
+- Nadir Billimoria for help interpreting the circuit schematic.
diff --git a/Documentation/spi/spi-sc18is602 b/Documentation/spi/spi-sc18is602.rst
similarity index 97%
rename from Documentation/spi/spi-sc18is602
rename to Documentation/spi/spi-sc18is602.rst
index 0feffd5af411..2a31dc722321 100644
--- a/Documentation/spi/spi-sc18is602
+++ b/Documentation/spi/spi-sc18is602.rst
@@ -1,8 +1,11 @@
+===========================
Kernel driver spi-sc18is602
===========================
Supported chips:
+
* NXP SI18IS602/602B/603
+
Datasheet: http://www.nxp.com/documents/data_sheet/SC18IS602_602B_603.pdf
Author:
diff --git a/Documentation/spi/spi-summary b/Documentation/spi/spi-summary.rst
similarity index 93%
rename from Documentation/spi/spi-summary
rename to Documentation/spi/spi-summary.rst
index 1a63194b74d7..f1daffe10d78 100644
--- a/Documentation/spi/spi-summary
+++ b/Documentation/spi/spi-summary.rst
@@ -1,3 +1,4 @@
+====================================
Overview of Linux kernel SPI support
====================================
@@ -139,12 +140,14 @@ a command and then reading its response.
There are two types of SPI driver, here called:
- Controller drivers ... controllers may be built into System-On-Chip
+ Controller drivers ...
+ controllers may be built into System-On-Chip
processors, and often support both Master and Slave roles.
These drivers touch hardware registers and may use DMA.
Or they can be PIO bitbangers, needing just GPIO pins.
- Protocol drivers ... these pass messages through the controller
+ Protocol drivers ...
+ these pass messages through the controller
driver to communicate with a Slave or Master device on the
other side of an SPI link.
@@ -160,7 +163,7 @@ those two types of drivers.
There is a minimal core of SPI programming interfaces, focussing on
using the driver model to connect controller and protocol drivers using
device tables provided by board specific initialization code. SPI
-shows up in sysfs in several locations:
+shows up in sysfs in several locations::
/sys/devices/.../CTLR ... physical node for a given SPI controller
@@ -168,7 +171,7 @@ shows up in sysfs in several locations:
chipselect C, accessed through CTLR.
/sys/bus/spi/devices/spiB.C ... symlink to that physical
- .../CTLR/spiB.C device
+ .../CTLR/spiB.C device
/sys/devices/.../CTLR/spiB.C/modalias ... identifies the driver
that should be used with this device (for hotplug/coldplug)
@@ -206,7 +209,8 @@ Linux needs several kinds of information to properly configure SPI devices.
That information is normally provided by board-specific code, even for
chips that do support some of automated discovery/enumeration.
-DECLARE CONTROLLERS
+Declare Controllers
+^^^^^^^^^^^^^^^^^^^
The first kind of information is a list of what SPI controllers exist.
For System-on-Chip (SOC) based boards, these will usually be platform
@@ -221,7 +225,7 @@ same basic controller setup code. This is because most SOCs have several
SPI-capable controllers, and only the ones actually usable on a given
board should normally be set up and registered.
-So for example arch/.../mach-*/board-*.c files might have code like:
+So for example arch/.../mach-*/board-*.c files might have code like::
#include <mach/spi.h> /* for mysoc_spi_data */
@@ -238,7 +242,7 @@ So for example arch/.../mach-*/board-*.c files might have code like:
...
}
-And SOC-specific utility code might look something like:
+And SOC-specific utility code might look something like::
#include <mach/spi.h>
@@ -269,8 +273,8 @@ same SOC controller is used. For example, on one board SPI might use
an external clock, where another derives the SPI clock from current
settings of some master clock.
-
-DECLARE SLAVE DEVICES
+Declare Slave Devices
+^^^^^^^^^^^^^^^^^^^^^
The second kind of information is a list of what SPI slave devices exist
on the target board, often with some board-specific data needed for the
@@ -278,7 +282,7 @@ driver to work correctly.
Normally your arch/.../mach-*/board-*.c files would provide a small table
listing the SPI devices on each board. (This would typically be only a
-small handful.) That might look like:
+small handful.) That might look like::
static struct ads7846_platform_data ads_info = {
.vref_delay_usecs = 100,
@@ -316,7 +320,7 @@ not possible until the infrastructure knows how to deselect it.
Then your board initialization code would register that table with the SPI
infrastructure, so that it's available later when the SPI master controller
-driver is registered:
+driver is registered::
spi_register_board_info(spi_board_info, ARRAY_SIZE(spi_board_info));
@@ -324,12 +328,13 @@ Like with other static board-specific setup, you won't unregister those.
The widely used "card" style computers bundle memory, cpu, and little else
onto a card that's maybe just thirty square centimeters. On such systems,
-your arch/.../mach-.../board-*.c file would primarily provide information
+your ``arch/.../mach-.../board-*.c`` file would primarily provide information
about the devices on the mainboard into which such a card is plugged. That
certainly includes SPI devices hooked up through the card connectors!
-NON-STATIC CONFIGURATIONS
+Non-static Configurations
+^^^^^^^^^^^^^^^^^^^^^^^^^
Developer boards often play by different rules than product boards, and one
example is the potential need to hotplug SPI devices and/or controllers.
@@ -349,7 +354,7 @@ How do I write an "SPI Protocol Driver"?
Most SPI drivers are currently kernel drivers, but there's also support
for userspace drivers. Here we talk only about kernel drivers.
-SPI protocol drivers somewhat resemble platform device drivers:
+SPI protocol drivers somewhat resemble platform device drivers::
static struct spi_driver CHIP_driver = {
.driver = {
@@ -367,6 +372,8 @@ device whose board_info gave a modalias of "CHIP". Your probe() code
might look like this unless you're creating a device which is managing
a bus (appearing under /sys/class/spi_master).
+::
+
static int CHIP_probe(struct spi_device *spi)
{
struct CHIP *chip;
@@ -479,6 +486,8 @@ The main task of this type of driver is to provide an "spi_master".
Use spi_alloc_master() to allocate the master, and spi_master_get_devdata()
to get the driver-private data allocated for that device.
+::
+
struct spi_master *master;
struct CONTROLLER *c;
@@ -503,7 +512,8 @@ If you need to remove your SPI controller driver, spi_unregister_master()
will reverse the effect of spi_register_master().
-BUS NUMBERING
+Bus Numbering
+^^^^^^^^^^^^^
Bus numbering is important, since that's how Linux identifies a given
SPI bus (shared SCK, MOSI, MISO). Valid bus numbers start at zero. On
@@ -517,9 +527,10 @@ then be replaced by a dynamically assigned number. You'd then need to treat
this as a non-static configuration (see above).
-SPI MASTER METHODS
+SPI Master Methods
+^^^^^^^^^^^^^^^^^^
- master->setup(struct spi_device *spi)
+``master->setup(struct spi_device *spi)``
This sets up the device clock rate, SPI mode, and word sizes.
Drivers may change the defaults provided by board_info, and then
call spi_setup(spi) to invoke this routine. It may sleep.
@@ -528,37 +539,37 @@ SPI MASTER METHODS
change them right away ... otherwise drivers could corrupt I/O
that's in progress for other SPI devices.
- ** BUG ALERT: for some reason the first version of
- ** many spi_master drivers seems to get this wrong.
- ** When you code setup(), ASSUME that the controller
- ** is actively processing transfers for another device.
+ .. note::
- master->cleanup(struct spi_device *spi)
+ BUG ALERT: for some reason the first version of
+ many spi_master drivers seems to get this wrong.
+ When you code setup(), ASSUME that the controller
+ is actively processing transfers for another device.
+
+``master->cleanup(struct spi_device *spi)``
Your controller driver may use spi_device.controller_state to hold
state it dynamically associates with that device. If you do that,
be sure to provide the cleanup() method to free that state.
- master->prepare_transfer_hardware(struct spi_master *master)
+``master->prepare_transfer_hardware(struct spi_master *master)``
This will be called by the queue mechanism to signal to the driver
that a message is coming in soon, so the subsystem requests the
driver to prepare the transfer hardware by issuing this call.
This may sleep.
- master->unprepare_transfer_hardware(struct spi_master *master)
+``master->unprepare_transfer_hardware(struct spi_master *master)``
This will be called by the queue mechanism to signal to the driver
that there are no more messages pending in the queue and it may
relax the hardware (e.g. by power management calls). This may sleep.
- master->transfer_one_message(struct spi_master *master,
- struct spi_message *mesg)
+``master->transfer_one_message(struct spi_master *master, struct spi_message *mesg)``
The subsystem calls the driver to transfer a single message while
queuing transfers that arrive in the meantime. When the driver is
finished with this message, it must call
spi_finalize_current_message() so the subsystem can issue the next
message. This may sleep.
- master->transfer_one(struct spi_master *master, struct spi_device *spi,
- struct spi_transfer *transfer)
+``master->transfer_one(struct spi_master *master, struct spi_device *spi, struct spi_transfer *transfer)``
The subsystem calls the driver to transfer a single transfer while
queuing transfers that arrive in the meantime. When the driver is
finished with this transfer, it must call
@@ -568,19 +579,20 @@ SPI MASTER METHODS
not call your transfer_one callback.
Return values:
- negative errno: error
- 0: transfer is finished
- 1: transfer is still in progress
- master->set_cs_timing(struct spi_device *spi, u8 setup_clk_cycles,
- u8 hold_clk_cycles, u8 inactive_clk_cycles)
+ * negative errno: error
+ * 0: transfer is finished
+ * 1: transfer is still in progress
+
+``master->set_cs_timing(struct spi_device *spi, u8 setup_clk_cycles, u8 hold_clk_cycles, u8 inactive_clk_cycles)``
This method allows SPI client drivers to request SPI master controller
for configuring device specific CS setup, hold and inactive timing
requirements.
- DEPRECATED METHODS
+Deprecated Methods
+^^^^^^^^^^^^^^^^^^
- master->transfer(struct spi_device *spi, struct spi_message *message)
+``master->transfer(struct spi_device *spi, struct spi_message *message)``
This must not sleep. Its responsibility is to arrange that the
transfer happens and its complete() callback is issued. The two
will normally happen later, after other transfers complete, and
@@ -590,7 +602,8 @@ SPI MASTER METHODS
implemented.
-SPI MESSAGE QUEUE
+SPI Message Queue
+^^^^^^^^^^^^^^^^^
If you are happy with the standard queueing mechanism provided by the
SPI subsystem, just implement the queued methods specified above. Using
@@ -619,13 +632,13 @@ THANKS TO
Contributors to Linux-SPI discussions include (in alphabetical order,
by last name):
-Mark Brown
-David Brownell
-Russell King
-Grant Likely
-Dmitry Pervushin
-Stephen Street
-Mark Underwood
-Andrew Victor
-Linus Walleij
-Vitaly Wool
+- Mark Brown
+- David Brownell
+- Russell King
+- Grant Likely
+- Dmitry Pervushin
+- Stephen Street
+- Mark Underwood
+- Andrew Victor
+- Linus Walleij
+- Vitaly Wool
diff --git a/Documentation/spi/spidev b/Documentation/spi/spidev.rst
similarity index 90%
rename from Documentation/spi/spidev
rename to Documentation/spi/spidev.rst
index 3d14035b1766..f05dbc5ccdbc 100644
--- a/Documentation/spi/spidev
+++ b/Documentation/spi/spidev.rst
@@ -1,7 +1,13 @@
+=================
+SPI userspace API
+=================
+
SPI devices have a limited userspace API, supporting basic half-duplex
read() and write() access to SPI slave devices. Using ioctl() requests,
full duplex transfers and device I/O configuration are also available.
+::
+
#include <fcntl.h>
#include <unistd.h>
#include <sys/ioctl.h>
@@ -39,14 +45,17 @@ device node with a "dev" attribute that will be understood by udev or mdev.
busybox; it's less featureful, but often enough.) For a SPI device with
chipselect C on bus B, you should see:
- /dev/spidevB.C ... character special device, major number 153 with
+ /dev/spidevB.C ...
+ character special device, major number 153 with
a dynamically chosen minor device number. This is the node
that userspace programs will open, created by "udev" or "mdev".
- /sys/devices/.../spiB.C ... as usual, the SPI device node will
+ /sys/devices/.../spiB.C ...
+ as usual, the SPI device node will
be a child of its SPI master controller.
- /sys/class/spidev/spidevB.C ... created when the "spidev" driver
+ /sys/class/spidev/spidevB.C ...
+ created when the "spidev" driver
binds to that device. (Directory or symlink, based on whether
or not you enabled the "deprecated sysfs files" Kconfig option.)
@@ -80,7 +89,8 @@ the SPI_IOC_MESSAGE(N) request.
Several ioctl() requests let your driver read or override the device's current
settings for data transfer parameters:
- SPI_IOC_RD_MODE, SPI_IOC_WR_MODE ... pass a pointer to a byte which will
+ SPI_IOC_RD_MODE, SPI_IOC_WR_MODE ...
+ pass a pointer to a byte which will
return (RD) or assign (WR) the SPI transfer mode. Use the constants
SPI_MODE_0..SPI_MODE_3; or if you prefer you can combine SPI_CPOL
(clock polarity, idle high iff this is set) or SPI_CPHA (clock phase,
@@ -88,22 +98,26 @@ settings for data transfer parameters:
Note that this request is limited to SPI mode flags that fit in a
single byte.
- SPI_IOC_RD_MODE32, SPI_IOC_WR_MODE32 ... pass a pointer to a uin32_t
+ SPI_IOC_RD_MODE32, SPI_IOC_WR_MODE32 ...
+ pass a pointer to a uin32_t
which will return (RD) or assign (WR) the full SPI transfer mode,
not limited to the bits that fit in one byte.
- SPI_IOC_RD_LSB_FIRST, SPI_IOC_WR_LSB_FIRST ... pass a pointer to a byte
+ SPI_IOC_RD_LSB_FIRST, SPI_IOC_WR_LSB_FIRST ...
+ pass a pointer to a byte
which will return (RD) or assign (WR) the bit justification used to
transfer SPI words. Zero indicates MSB-first; other values indicate
the less common LSB-first encoding. In both cases the specified value
is right-justified in each word, so that unused (TX) or undefined (RX)
bits are in the MSBs.
- SPI_IOC_RD_BITS_PER_WORD, SPI_IOC_WR_BITS_PER_WORD ... pass a pointer to
+ SPI_IOC_RD_BITS_PER_WORD, SPI_IOC_WR_BITS_PER_WORD ...
+ pass a pointer to
a byte which will return (RD) or assign (WR) the number of bits in
each SPI transfer word. The value zero signifies eight bits.
- SPI_IOC_RD_MAX_SPEED_HZ, SPI_IOC_WR_MAX_SPEED_HZ ... pass a pointer to a
+ SPI_IOC_RD_MAX_SPEED_HZ, SPI_IOC_WR_MAX_SPEED_HZ ...
+ pass a pointer to a
u32 which will return (RD) or assign (WR) the maximum SPI transfer
speed, in Hz. The controller can't necessarily assign that specific
clock speed.
diff --git a/drivers/iio/dummy/iio_simple_dummy.c b/drivers/iio/dummy/iio_simple_dummy.c
index d28974ad9e0e..6cb02299a215 100644
--- a/drivers/iio/dummy/iio_simple_dummy.c
+++ b/drivers/iio/dummy/iio_simple_dummy.c
@@ -695,7 +695,7 @@ static int iio_dummy_remove(struct iio_sw_device *swd)
* i2c:
* Documentation/i2c/writing-clients.rst
* spi:
- * Documentation/spi/spi-summary
+ * Documentation/spi/spi-summary.rst
*/
static const struct iio_sw_device_ops iio_dummy_device_ops = {
.probe = iio_dummy_probe,
diff --git a/drivers/spi/Kconfig b/drivers/spi/Kconfig
index 3a1d8f1170de..d5a24fe983e7 100644
--- a/drivers/spi/Kconfig
+++ b/drivers/spi/Kconfig
@@ -543,7 +543,7 @@ config SPI_PXA2XX
help
This enables using a PXA2xx or Sodaville SSP port as a SPI master
controller. The driver can be configured to use any SSP port and
- additional documentation can be found a Documentation/spi/pxa2xx.
+ additional documentation can be found a Documentation/spi/pxa2xx.rst.
config SPI_PXA2XX_PCI
def_tristate SPI_PXA2XX && PCI && COMMON_CLK
diff --git a/drivers/spi/spi-butterfly.c b/drivers/spi/spi-butterfly.c
index 8c77d1114ad3..7e71a351f3b7 100644
--- a/drivers/spi/spi-butterfly.c
+++ b/drivers/spi/spi-butterfly.c
@@ -23,7 +23,7 @@
* with a battery powered AVR microcontroller and lots of goodies. You
* can use GCC to develop firmware for this.
*
- * See Documentation/spi/butterfly for information about how to build
+ * See Documentation/spi/butterfly.rst for information about how to build
* and use this custom parallel port cable.
*/
diff --git a/drivers/spi/spi-lm70llp.c b/drivers/spi/spi-lm70llp.c
index f18f912c9dea..174dba29b1dd 100644
--- a/drivers/spi/spi-lm70llp.c
+++ b/drivers/spi/spi-lm70llp.c
@@ -34,7 +34,7 @@
* available (on page 4) here:
* http://www.national.com/appinfo/tempsensors/files/LM70LLPEVALmanual.pdf
*
- * Also see Documentation/spi/spi-lm70llp. The SPI<->parport code here is
+ * Also see Documentation/spi/spi-lm70llp.rst. The SPI<->parport code here is
* (heavily) based on spi-butterfly by David Brownell.
*
* The LM70 LLP connects to the PC parallel port in the following manner:
diff --git a/include/linux/platform_data/sc18is602.h b/include/linux/platform_data/sc18is602.h
index e066d3b0d6d8..0e91489edfe6 100644
--- a/include/linux/platform_data/sc18is602.h
+++ b/include/linux/platform_data/sc18is602.h
@@ -4,7 +4,7 @@
*
* Copyright (C) 2012 Guenter Roeck <linux@roeck-us.net>
*
- * For further information, see the Documentation/spi/spi-sc18is602 file.
+ * For further information, see the Documentation/spi/spi-sc18is602.rst file.
*/
/**
--
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
* [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 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 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 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
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