* Re: [RFC tip/locking/lockdep v6 01/20] lockdep/Documention: Recursive read lock detection reasoning
From: Randy Dunlap @ 2018-04-15 0:38 UTC (permalink / raw)
To: Boqun Feng, linux-kernel
Cc: Peter Zijlstra, Ingo Molnar, Andrea Parri, Paul E. McKenney,
Jonathan Corbet, open list:DOCUMENTATION
In-Reply-To: <20180411135110.9217-2-boqun.feng@gmail.com>
Hi,
Just a few typos etc. below...
On 04/11/2018 06:50 AM, Boqun Feng wrote:
> Signed-off-by: Boqun Feng <boqun.feng@gmail.com>
> ---
> Documentation/locking/lockdep-design.txt | 178 +++++++++++++++++++++++++++++++
> 1 file changed, 178 insertions(+)
>
> diff --git a/Documentation/locking/lockdep-design.txt b/Documentation/locking/lockdep-design.txt
> index 9de1c158d44c..6bb9e90e2c4f 100644
> --- a/Documentation/locking/lockdep-design.txt
> +++ b/Documentation/locking/lockdep-design.txt
> @@ -284,3 +284,181 @@ Run the command and save the output, then compare against the output from
> a later run of this command to identify the leakers. This same output
> can also help you find situations where runtime lock initialization has
> been omitted.
> +
> +Recursive read locks:
> +---------------------
> +
> +Lockdep now is equipped with deadlock detection for recursive read locks.
> +
> +Recursive read locks, as their name indicates, are the locks able to be
> +acquired recursively. Unlike non-recursive read locks, recursive read locks
> +only get blocked by current write lock *holders* other than write lock
> +*waiters*, for example:
> +
> + TASK A: TASK B:
> +
> + read_lock(X);
> +
> + write_lock(X);
> +
> + read_lock(X);
> +
> +is not a deadlock for recursive read locks, as while the task B is waiting for
> +the lock X, the second read_lock() doesn't need to wait because it's a recursive
> +read lock. However if the read_lock() is non-recursive read lock, then the above
> +case is a deadlock, because even if the write_lock() in TASK B can not get the
> +lock, but it can block the second read_lock() in TASK A.
> +
> +Note that a lock can be a write lock (exclusive lock), a non-recursive read
> +lock (non-recursive shared lock) or a recursive read lock (recursive shared
> +lock), depending on the lock operations used to acquire it (more specifically,
> +the value of the 'read' parameter for lock_acquire()). In other words, a single
> +lock instance has three types of acquisition depending on the acquisition
> +functions: exclusive, non-recursive read, and recursive read.
> +
> +To be concise, we call that write locks and non-recursive read locks as
> +"non-recursive" locks and recursive read locks as "recursive" locks.
> +
> +Recursive locks don't block each other, while non-recursive locks do (this is
> +even true for two non-recursive read locks). A non-recursive lock can block the
> +corresponding recursive lock, and vice versa.
> +
> +A deadlock case with recursive locks involved is as follow:
> +
> + TASK A: TASK B:
> +
> + read_lock(X);
> + read_lock(Y);
> + write_lock(Y);
> + write_lock(X);
> +
> +Task A is waiting for task B to read_unlock() Y and task B is waiting for task
> +A to read_unlock() X.
> +
> +Dependency types and strong dependency paths:
> +---------------------------------------------
> +In order to detect deadlocks as above, lockdep needs to track different dependencies.
> +There are 4 categories for dependency edges in the lockdep graph:
> +
> +1) -(NN)->: non-recursive to non-recursive dependency. "X -(NN)-> Y" means
> + X -> Y and both X and Y are non-recursive locks.
> +
> +2) -(RN)->: recursive to non-recursive dependency. "X -(RN)-> Y" means
> + X -> Y and X is recursive read lock and Y is non-recursive lock.
> +
> +3) -(NR)->: non-recursive to recursive dependency, "X -(NR)-> Y" means
> + X -> Y and X is non-recursive lock and Y is recursive lock.
> +
> +4) -(RR)->: recursive to recursive dependency, "X -(RR)-> Y" means
> + X -> Y and both X and Y are recursive locks.
> +
> +Note that given two locks, they may have multiple dependencies between them, for example:
> +
> + TASK A:
> +
> + read_lock(X);
> + write_lock(Y);
> + ...
> +
> + TASK B:
> +
> + write_lock(X);
> + write_lock(Y);
> +
> +, we have both X -(RN)-> Y and X -(NN)-> Y in the dependency graph.
> +
> +We use -(*N)-> for edges that is either -(RN)-> or -(NN)->, the similar for -(N*)->,
> +-(*R)-> and -(R*)->
> +
> +A "path" is a series of conjunct dependency edges in the graph. And we define a
> +"strong" path, which indicates the strong dependency throughout each dependency
> +in the path, as the path that doesn't have two conjunct edges (dependencies) as
> +-(*R)-> and -(R*)->. In other words, a "strong" path is a path from a lock
> +walking to another through the lock dependencies, and if X -> Y -> Z in the
> +path (where X, Y, Z are locks), if the walk from X to Y is through a -(NR)-> or
> +-(RR)-> dependency, the walk from Y to Z must not be through a -(RN)-> or
> +-(RR)-> dependency, otherwise it's not a strong path.
> +
> +We will see why the path is called "strong" in next section.
> +
> +Recursive Read Deadlock Detection:
> +----------------------------------
> +
> +We now prove two things:
> +
> +Lemma 1:
> +
> +If there is a closed strong path (i.e. a strong cirle), then there is a
?? circle
> +combination of locking sequences that causes deadlock. I.e. a strong circle is
> +sufficient for deadlock detection.
> +
> +Lemma 2:
> +
> +If there is no closed strong path (i.e. strong cirle), then there is no
?? circle
> +combination of locking sequences that could cause deadlock. I.e. strong
> +circles are necessary for deadlock detection.
> +
> +With these two Lemmas, we can easily say a closed strong path is both sufficient
> +and necessary for deadlocks, therefore a closed strong path is equivalent to
> +deadlock possibility. As a closed strong path stands for a dependency chain that
> +could cause deadlocks, so we call it "strong", considering there are dependency
> +circles that won't cause deadlocks.
> +
> +Proof for sufficiency (Lemma 1):
> +
> +Let's say we have a strong cirlce:
circle:
> +
> + L1 -> L2 ... -> Ln -> L1
> +
> +, which means we have dependencies:
> +
> + L1 -> L2
> + L2 -> L3
> + ...
> + Ln-1 -> Ln
> + Ln -> L1
> +
> +We now can construct a combination of locking sequences that cause deadlock:
> +
> +Firstly let's make one CPU/task get the L1 in L1 -> L2, and then another get
> +the L2 in L2 -> L3, and so on. After this, all of the Lx in Lx -> Lx+1 are
> +held by different CPU/tasks.
> +
> +And then because we have L1 -> L2, so the holder of L1 is going to acquire L2
> +in L1 -> L2, however since L2 is already held by another CPU/task, plus L1 ->
> +L2 and L2 -> L3 are not *R and R* (the definition of strong), therefore the
> +holder of L1 can not get L2, it has to wait L2's holder to release.
> +
> +Moreover, we can have a similar conclusion for L2's holder: it has to wait L3's
> +holder to release, and so on. We now can proof that Lx's holder has to wait for
prove
> +Lx+1's holder to release, and note that Ln+1 is L1, so we have a circular
> +waiting scenario and nobody can get progress, therefore a deadlock.
> +
> +Proof for necessary (Lemma 2):
> +
> +Lemma 2 is equivalent to: If there is a deadlock scenario, then there must be a
> +strong circle in the dependency graph.
> +
> +According to Wikipedia[1], if there is a deadlock, then there must be a circular
> +waiting scenario, means there are N CPU/tasks, where CPU/task P1 is waiting for
> +a lock held by P2, and P2 is waiting for a lock held by P3, ... and Pn is waiting
> +for a lock held by P1. Let's name the lock Px is waiting as Lx, so since P1 is waiting
> +for L1 and holding Ln, so we will have Ln -> L1 in the dependency graph. Similarly,
> +we have L1 -> L2, L2 -> L3, ..., Ln-1 -> Ln in the dependency graph, which means we
> +have a circle:
> +
> + Ln -> L1 -> L2 -> ... -> Ln
> +
> +, and now let's prove the circle is strong:
> +
> +For a lock Lx, Px contributes the dependency Lx-1 -> Lx and Px+1 contributes
> +the dependency Lx -> Lx+1, and since Px is waiting for Px+1 to release Lx,
> +so Lx can not be both recursive in Lx -> Lx+1 and Lx-1 -> Lx, because recursive
> +locks don't block each other, therefore Lx-1 -> Lx and Lx -> Lx+1 can not be a
> +-(*R)-> -(R*)-> pair, and this is true for any lock in the circle, therefore,
> +the circle is strong.
> +
> +References:
> +-----------
> +[1]: https://en.wikipedia.org/wiki/Deadlock
> +[2]: Shibu, K. (2009). Intro To Embedded Systems (1st ed.). Tata McGraw-Hill
>
I would also change all /can not/ to /cannot/...
--
~Randy
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply
* [PATCH v3 4/4] target: add driver-api document
From: Randy Dunlap @ 2018-04-14 17:51 UTC (permalink / raw)
To: Nicholas A. Bellinger
Cc: Randy Dunlap, linux-scsi, target-devel, linux-doc,
James E.J. Bottomley, Martin K. Petersen, Jonathan Corbet
In-Reply-To: <20180414175106.13760-1-rd.dunlab@gmail.com>
From: Randy Dunlap <rdunlap@infradead.org>
Add a driver-api document for target/iSCSI interfaces.
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
To: "Nicholas A. Bellinger" <nab@linux-iscsi.org>
Cc: linux-scsi@vger.kernel.org
Cc: target-devel@vger.kernel.org
Cc: linux-doc@vger.kernel.org
Cc: "James E.J. Bottomley" <jejb@linux.vnet.ibm.com>
Cc: "Martin K. Petersen" <martin.petersen@oracle.com>
Cc: Jonathan Corbet <corbet@lwn.net>
---
Documentation/driver-api/index.rst | 1
Documentation/driver-api/scsi.rst | 2
Documentation/driver-api/target.rst | 64 ++++++++++++++++++++++++++
3 files changed, 66 insertions(+), 1 deletion(-)
--- linux-next-20180413.orig/Documentation/driver-api/index.rst
+++ linux-next-20180413/Documentation/driver-api/index.rst
@@ -34,6 +34,7 @@ available subsections can be seen below.
edac
scsi
libata
+ target
mtdnand
miscellaneous
w1
--- linux-next-20180413.orig/Documentation/driver-api/scsi.rst
+++ linux-next-20180413/Documentation/driver-api/scsi.rst
@@ -334,5 +334,5 @@ todo
~~~~
Parallel (fast/wide/ultra) SCSI, USB, SATA, SAS, Fibre Channel,
-FireWire, ATAPI devices, Infiniband, I2O, iSCSI, Parallel ports,
+FireWire, ATAPI devices, Infiniband, I2O, Parallel ports,
netlink...
--- /dev/null
+++ linux-next-20180413/Documentation/driver-api/target.rst
@@ -0,0 +1,64 @@
+=================================
+target and iSCSI Interfaces Guide
+=================================
+
+Introduction and Overview
+=========================
+
+TBD
+
+Target core device interfaces
+=============================
+
+.. kernel-doc:: drivers/target/target_core_device.c
+ :export:
+
+Target core transport interfaces
+================================
+
+.. kernel-doc:: drivers/target/target_core_transport.c
+ :export:
+
+Target-supported userspace I/O
+==============================
+
+.. kernel-doc:: drivers/target/target_core_user.c
+ :doc: Userspace I/O
+
+.. kernel-doc:: include/uapi/linux/target_core_user.h
+ :doc: Ring Design
+
+iSCSI helper functions
+======================
+
+.. kernel-doc:: drivers/scsi/libiscsi.c
+ :export:
+
+
+iSCSI boot information
+======================
+
+.. kernel-doc:: drivers/scsi/iscsi_boot_sysfs.c
+ :export:
+
+
+iSCSI transport class
+=====================
+
+The file drivers/scsi/scsi_transport_iscsi.c defines transport
+attributes for the iSCSI class, which sends SCSI packets over TCP/IP
+connections.
+
+.. kernel-doc:: drivers/scsi/scsi_transport_iscsi.c
+ :export:
+
+
+iSCSI TCP interfaces
+====================
+
+.. kernel-doc:: drivers/scsi/iscsi_tcp.c
+ :internal:
+
+.. kernel-doc:: drivers/scsi/libiscsi_tcp.c
+ :export:
+
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply
* [PATCH v3 3/4] target: target_core_user.[ch]: convert comments into DOC:
From: Randy Dunlap @ 2018-04-14 17:51 UTC (permalink / raw)
To: Nicholas A. Bellinger
Cc: Randy Dunlap, linux-scsi, target-devel, linux-doc,
James E.J. Bottomley, Martin K. Petersen, Jonathan Corbet
In-Reply-To: <20180414175106.13760-1-rd.dunlab@gmail.com>
From: Randy Dunlap <rdunlap@infradead.org>
Make documentation on target-supported userspace-I/O design be
usable by kernel-doc by using "DOC:". This is used in the driver-api
Documentation chapter.
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
To: "Nicholas A. Bellinger" <nab@linux-iscsi.org>
Cc: linux-scsi@vger.kernel.org
Cc: target-devel@vger.kernel.org
Cc: linux-doc@vger.kernel.org
Cc: "James E.J. Bottomley" <jejb@linux.vnet.ibm.com>
Cc: "Martin K. Petersen" <martin.petersen@oracle.com>
Cc: Jonathan Corbet <corbet@lwn.net>
---
drivers/target/target_core_user.c | 8 ++++++--
include/uapi/linux/target_core_user.h | 11 ++++++-----
2 files changed, 12 insertions(+), 7 deletions(-)
--- linux-next-20180413.orig/drivers/target/target_core_user.c
+++ linux-next-20180413/drivers/target/target_core_user.c
@@ -42,7 +42,11 @@
#include <linux/target_core_user.h>
-/*
+/**
+ * DOC: Userspace I/O
+ * Userspace I/O
+ * -------------
+ *
* Define a shared-memory interface for LIO to pass SCSI commands and
* data to userspace for processing. This is to allow backends that
* are too complex for in-kernel support to be possible.
@@ -53,7 +57,7 @@
* See the .h file for how the ring is laid out. Note that while the
* command ring is defined, the particulars of the data area are
* not. Offset values in the command entry point to other locations
- * internal to the mmap()ed area. There is separate space outside the
+ * internal to the mmap-ed area. There is separate space outside the
* command ring for data buffers. This leaves maximum flexibility for
* moving buffer allocations, or even page flipping or other
* allocation techniques, without altering the command ring layout.
--- linux-next-20180413.orig/include/uapi/linux/target_core_user.h
+++ linux-next-20180413/include/uapi/linux/target_core_user.h
@@ -9,21 +9,22 @@
#define TCMU_VERSION "2.0"
-/*
+/**
+ * DOC: Ring Design
* Ring Design
* -----------
*
* The mmaped area is divided into three parts:
- * 1) The mailbox (struct tcmu_mailbox, below)
- * 2) The command ring
- * 3) Everything beyond the command ring (data)
+ * 1) The mailbox (struct tcmu_mailbox, below);
+ * 2) The command ring;
+ * 3) Everything beyond the command ring (data).
*
* The mailbox tells userspace the offset of the command ring from the
* start of the shared memory region, and how big the command ring is.
*
* The kernel passes SCSI commands to userspace by putting a struct
* tcmu_cmd_entry in the ring, updating mailbox->cmd_head, and poking
- * userspace via uio's interrupt mechanism.
+ * userspace via UIO's interrupt mechanism.
*
* tcmu_cmd_entry contains a header. If the header type is PAD,
* userspace should skip hdr->length bytes (mod cmdr_size) to find the
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply
* [PATCH v3 2/4] target: target_core_transport.c: enable+fix kernel-doc
From: Randy Dunlap @ 2018-04-14 17:51 UTC (permalink / raw)
To: Nicholas A. Bellinger
Cc: Randy Dunlap, linux-scsi, target-devel, linux-doc,
James E.J. Bottomley, Martin K. Petersen, Jonathan Corbet
In-Reply-To: <20180414175106.13760-1-rd.dunlab@gmail.com>
From: Randy Dunlap <rdunlap@infradead.org>
For exported functions that already have near-kernel-doc notation,
fix them to begin with "/**" and make a few corrections so that they
don't have any kernel-doc warnings.
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
To: "Nicholas A. Bellinger" <nab@linux-iscsi.org>
Cc: linux-scsi@vger.kernel.org
Cc: target-devel@vger.kernel.org
Cc: linux-doc@vger.kernel.org
Cc: "James E.J. Bottomley" <jejb@linux.vnet.ibm.com>
Cc: "Martin K. Petersen" <martin.petersen@oracle.com>
Cc: Jonathan Corbet <corbet@lwn.net>
---
drivers/target/target_core_transport.c | 17 ++++++++++-------
1 file changed, 10 insertions(+), 7 deletions(-)
--- linux-next-20180413.orig/drivers/target/target_core_transport.c
+++ linux-next-20180413/drivers/target/target_core_transport.c
@@ -1431,7 +1431,7 @@ transport_generic_map_mem_to_cmd(struct
return 0;
}
-/*
+/**
* target_submit_cmd_map_sgls - lookup unpacked lun and submit uninitialized
* se_cmd + use pre-allocated SGL memory.
*
@@ -1441,7 +1441,7 @@ transport_generic_map_mem_to_cmd(struct
* @sense: pointer to SCSI sense buffer
* @unpacked_lun: unpacked LUN to reference for struct se_lun
* @data_length: fabric expected data transfer length
- * @task_addr: SAM task attribute
+ * @task_attr: SAM task attribute
* @data_dir: DMA data direction
* @flags: flags for command submission from target_sc_flags_tables
* @sgl: struct scatterlist memory for unidirectional mapping
@@ -1578,7 +1578,7 @@ int target_submit_cmd_map_sgls(struct se
}
EXPORT_SYMBOL(target_submit_cmd_map_sgls);
-/*
+/**
* target_submit_cmd - lookup unpacked lun and submit uninitialized se_cmd
*
* @se_cmd: command descriptor to submit
@@ -1587,7 +1587,7 @@ EXPORT_SYMBOL(target_submit_cmd_map_sgls
* @sense: pointer to SCSI sense buffer
* @unpacked_lun: unpacked LUN to reference for struct se_lun
* @data_length: fabric expected data transfer length
- * @task_addr: SAM task attribute
+ * @task_attr: SAM task attribute
* @data_dir: DMA data direction
* @flags: flags for command submission from target_sc_flags_tables
*
@@ -2606,7 +2606,8 @@ int transport_generic_free_cmd(struct se
}
EXPORT_SYMBOL(transport_generic_free_cmd);
-/* target_get_sess_cmd - Add command to active ->sess_cmd_list
+/**
+ * target_get_sess_cmd - Add command to active ->sess_cmd_list
* @se_cmd: command descriptor to add
* @ack_kref: Signal that fabric will perform an ack target_put_sess_cmd()
*/
@@ -2800,7 +2801,8 @@ void target_show_cmd(const char *pfx, st
}
EXPORT_SYMBOL(target_show_cmd);
-/* target_sess_cmd_list_set_waiting - Flag all commands in
+/**
+ * target_sess_cmd_list_set_waiting - Flag all commands in
* sess_cmd_list to complete cmd_wait_comp. Set
* sess_tearing_down so no more commands are queued.
* @se_sess: session to flag
@@ -2835,7 +2837,8 @@ void target_sess_cmd_list_set_waiting(st
}
EXPORT_SYMBOL(target_sess_cmd_list_set_waiting);
-/* target_wait_for_sess_cmds - Wait for outstanding descriptors
+/**
+ * target_wait_for_sess_cmds - Wait for outstanding descriptors
* @se_sess: session to wait for active I/O
*/
void target_wait_for_sess_cmds(struct se_session *se_sess)
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply
* [PATCH v3 1/4] target: target_core_transport.c: fix kernel-doc warnings
From: Randy Dunlap @ 2018-04-14 17:51 UTC (permalink / raw)
To: Nicholas A. Bellinger
Cc: Randy Dunlap, linux-scsi, target-devel, linux-doc,
James E.J. Bottomley, Martin K. Petersen, Jonathan Corbet
In-Reply-To: <20180414175106.13760-1-rd.dunlab@gmail.com>
From: Randy Dunlap <rdunlap@infradead.org>
Correct a function parameter's name to eliminate kernel-doc warnings
in drivers/target/target_core_transport.c.
Fixes these kernel-doc warnings: (tested by adding these files to a new
target.rst documentation file)
../drivers/target/target_core_transport.c:1671: warning: No description found for parameter 'fabric_tmr_ptr'
../drivers/target/target_core_transport.c:1671: warning: Excess function parameter 'fabric_context' description in 'target_submit_tmr'
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
To: "Nicholas A. Bellinger" <nab@linux-iscsi.org>
Cc: linux-scsi@vger.kernel.org
Cc: target-devel@vger.kernel.org
Cc: linux-doc@vger.kernel.org
Cc: "James E.J. Bottomley" <jejb@linux.vnet.ibm.com>
Cc: "Martin K. Petersen" <martin.petersen@oracle.com>
Cc: Jonathan Corbet <corbet@lwn.net>
---
drivers/target/target_core_transport.c | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
--- linux-next-20180413.orig/drivers/target/target_core_transport.c
+++ linux-next-20180413/drivers/target/target_core_transport.c
@@ -1654,7 +1654,7 @@ static bool target_lookup_lun_from_tag(s
* @se_sess: associated se_sess for endpoint
* @sense: pointer to SCSI sense buffer
* @unpacked_lun: unpacked LUN to reference for struct se_lun
- * @fabric_context: fabric context for TMR req
+ * @fabric_tmr_ptr: fabric context for TMR req
* @tm_type: Type of TM request
* @gfp: gfp type for caller
* @tag: referenced task tag for TMR_ABORT_TASK
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply
* target: clean up kernel-doc and add driver-api document
From: Randy Dunlap @ 2018-04-14 17:51 UTC (permalink / raw)
To: Nicholas A. Bellinger
Cc: Randy Dunlap, linux-scsi, target-devel, linux-doc,
James E.J. Bottomley, Martin K. Petersen, Jonathan Corbet
From: Randy Dunlap <rdunlap@infradead.org>
This patch series fixes kernel-doc warnings in drivers/target/ and
its header files, then adds a Documentation driver-api chapter for
target driver interfaces.
[PATCH v3 1/4] target: target_core_transport.c: fix kernel-doc warnings
[PATCH v3 2/4] target: target_core_transport.c: enable+fix kernel-doc
[PATCH v3 3/4] target: target_core_user.[ch]: convert comments into DOC:
[PATCH v3 4/4] target: add driver-api document
Documentation/driver-api/index.rst | 1
Documentation/driver-api/scsi.rst | 2
Documentation/driver-api/target.rst | 64 +++++++++++++++++++++++
drivers/target/target_core_transport.c | 19 +++---
drivers/target/target_core_user.c | 8 ++
include/uapi/linux/target_core_user.h | 11 ++-
6 files changed, 89 insertions(+), 16 deletions(-)
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply
* Re: target documentation patches?
From: Randy Dunlap @ 2018-04-14 17:44 UTC (permalink / raw)
To: Nicholas A. Bellinger, target-devel; +Cc: linux-scsi, linux-doc@vger.kernel.org
In-Reply-To: <e2bc69ce-2270-7996-ca50-928fa3c71ffa@infradead.org>
On 02/22/2018 04:38 PM, Randy Dunlap wrote:
> Hi Nicholas,
>
> I posted several patches for target documentation cleanups and adding
> a chapter to the driver-api chapter back in December.
>
> Do I need to repost those? Do you want someone else to merge them, even
> though several of them are in drivers/target/ ?
[no response in 7 weeks]
[adding linux-doc list]
I have a new 4-patch series for target kernel-doc fixes and adding
Documentation/driver-api/target.rst. However, I am wondering who will
merge the series.
I'll post the series to target-devel, linux-scsi, and linux-doc.
Hopefully one of the maintainers there will apply them.
thanks,
--
~Randy
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply
* Re: [PATCH] Documentation/i2c: sync docs with current state of i2c-tools.
From: Wolfram Sang @ 2018-04-14 6:27 UTC (permalink / raw)
To: Sam Hansen
Cc: Jean Delvare, linux-i2c, Jonathan Corbet, linux-doc, linux-kernel
In-Reply-To: <CAP9bUy6Hf+cQzAAckou3QPTk0mJM4xJ4xq-hf+RwyVmD3Le+qg@mail.gmail.com>
[-- Attachment #1: Type: text/plain, Size: 200 bytes --]
> (also, did I send the v3 patch series threaded correctly?)
Yes, that worked. Thanks!
Things to improve there: I was both in To: and CC: field, so I got mails
twice. Jean was missing completely.
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply
* [PATCH v3 5/5] FireWire: add driver-api Introduction section
From: Randy Dunlap @ 2018-04-14 1:27 UTC (permalink / raw)
To: linux1394-devel; +Cc: Stefan Richter, Takashi Sakamoto, linux-doc, Randy Dunlap
In-Reply-To: <20180414012722.17420-1-rd.dunlab@gmail.com>
From: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Replace the Introduction section's TBD with some useful overview text.
Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
To: linux1394-devel@lists.sourceforge.net
Cc: Stefan Richter <stefanr@s5r6.in-berlin.de>
Cc: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Cc: linux-doc@vger.kernel.org
Cc: Randy Dunlap <rdunlap@infradead.org>
---
Documentation/driver-api/firewire.rst | 18 +++++++++++++++++-
1 file changed, 17 insertions(+), 1 deletion(-)
--- linux-next-20180413.orig/Documentation/driver-api/firewire.rst
+++ linux-next-20180413/Documentation/driver-api/firewire.rst
@@ -5,17 +5,33 @@ Firewire (IEEE 1394) driver Interface Gu
Introduction and Overview
=========================
-TBD
+The Linux FireWire subsystem adds some interfaces into the Linux system
+to use/maintain any resource on the IEEE 1394 bus.
+
+The main purpose of these interfaces is to access address space on each node
+on the IEEE 1394 bus by ISO/IEC 13213 (IEEE 1212) procedure, and to control
+isochronous resources on the bus by IEEE 1394 procedure.
+
+Two types of interfaces are added, according to consumers of the interface. A
+set of userspace interfaces is available via `firewire character devices`. A set
+of kernel interfaces is available via exported symbols in the `firewire-core`
+module.
Firewire char device data structures
====================================
+.. include:: /ABI/stable/firewire-cdev
+ :literal:
+
.. kernel-doc:: include/uapi/linux/firewire-cdev.h
:internal:
Firewire device probing and sysfs interfaces
============================================
+.. include:: /ABI/stable/sysfs-bus-firewire
+ :literal:
+
.. kernel-doc:: drivers/firewire/core-device.c
:export:
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply
* [PATCH v3 4/5] FireWire: add a Documentation driver-api chapter
From: Randy Dunlap @ 2018-04-14 1:27 UTC (permalink / raw)
To: linux1394-devel; +Cc: Stefan Richter, Takashi Sakamoto, linux-doc, Randy Dunlap
In-Reply-To: <20180414012722.17420-1-rd.dunlab@gmail.com>
From: Randy Dunlap <rdunlap@infradead.org>
Add a basic Firewire/IEEE 1394 driver API chapter to the Linux
kernel documentation.
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
To: linux1394-devel@lists.sourceforge.net
Cc: Stefan Richter <stefanr@s5r6.in-berlin.de>
Cc: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Cc: linux-doc@vger.kernel.org
Cc: Randy Dunlap <rdunlap@infradead.org>
---
v2: drop final blank line;
in Cc:, change tab to space;
Documentation/driver-api/firewire.rst | 32 ++++++++++++++++++++++++
Documentation/driver-api/index.rst | 1
2 files changed, 33 insertions(+)
--- /dev/null
+++ linux-next-20180413/Documentation/driver-api/firewire.rst
@@ -0,0 +1,32 @@
+===========================================
+Firewire (IEEE 1394) driver Interface Guide
+===========================================
+
+Introduction and Overview
+=========================
+
+TBD
+
+Firewire char device data structures
+====================================
+
+.. kernel-doc:: include/uapi/linux/firewire-cdev.h
+ :internal:
+
+Firewire device probing and sysfs interfaces
+============================================
+
+.. kernel-doc:: drivers/firewire/core-device.c
+ :export:
+
+Firewire core transaction interfaces
+====================================
+
+.. kernel-doc:: drivers/firewire/core-transaction.c
+ :export:
+
+Firewire Isochronous I/O interfaces
+===================================
+
+.. kernel-doc:: drivers/firewire/core-iso.c
+ :export:
--- linux-next-20180413.orig/Documentation/driver-api/index.rst
+++ linux-next-20180413/Documentation/driver-api/index.rst
@@ -27,6 +27,7 @@ available subsections can be seen below.
iio/index
input
usb/index
+ firewire
pci
spi
i2c
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply
* [PATCH v3 3/5] FireWire: clean up core-transaction.c kernel-doc
From: Randy Dunlap @ 2018-04-14 1:27 UTC (permalink / raw)
To: linux1394-devel; +Cc: Stefan Richter, Takashi Sakamoto, linux-doc, Randy Dunlap
In-Reply-To: <20180414012722.17420-1-rd.dunlab@gmail.com>
From: Randy Dunlap <rdunlap@infradead.org>
Clean up kernel-doc warnings in <drivers/firewire/core-transaction.c>
so that it can be added to a Firewire/IEEE 1394 driver-api chapter
without adding lots of noisy warnings to the documentation build.
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
To: linux1394-devel@lists.sourceforge.net
Cc: Stefan Richter <stefanr@s5r6.in-berlin.de>
Cc: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Cc: linux-doc@vger.kernel.org
Cc: Randy Dunlap <rdunlap@infradead.org>
---
drivers/firewire/core-transaction.c | 10 ++++++++++
1 file changed, 10 insertions(+)
--- linux-next-20180413.orig/drivers/firewire/core-transaction.c
+++ linux-next-20180413/drivers/firewire/core-transaction.c
@@ -410,6 +410,14 @@ static void transaction_callback(struct
/**
* fw_run_transaction() - send request and sleep until transaction is completed
+ * @card: card interface for this request
+ * @tcode: transaction code
+ * @destination_id: destination node ID, consisting of bus_ID and phy_ID
+ * @generation: bus generation in which request and response are valid
+ * @speed: transmission speed
+ * @offset: 48bit wide offset into destination's address space
+ * @payload: data payload for the request subaction
+ * @length: length of the payload, in bytes
*
* Returns the RCODE. See fw_send_request() for parameter documentation.
* Unlike fw_send_request(), @data points to the payload of the request or/and
@@ -604,6 +612,7 @@ EXPORT_SYMBOL(fw_core_add_address_handle
/**
* fw_core_remove_address_handler() - unregister an address handler
+ * @handler: callback
*
* To be called in process context.
*
@@ -828,6 +837,7 @@ EXPORT_SYMBOL(fw_send_response);
/**
* fw_get_request_speed() - returns speed at which the @request was received
+ * @request: firewire request data
*/
int fw_get_request_speed(struct fw_request *request)
{
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply
* [PATCH v3 2/5] FireWire: clean up core-iso.c kernel-doc
From: Randy Dunlap @ 2018-04-14 1:27 UTC (permalink / raw)
To: linux1394-devel; +Cc: Stefan Richter, Takashi Sakamoto, linux-doc, Randy Dunlap
In-Reply-To: <20180414012722.17420-1-rd.dunlab@gmail.com>
From: Randy Dunlap <rdunlap@infradead.org>
Clean up kernel-doc warnings in <drivers/firewire/core-iso.c> so that
it can be added to a Firewire/IEEE 1394 driver-api chapter
without adding lots of noisy warnings to the documentation build.
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
To: linux1394-devel@lists.sourceforge.net
Cc: Stefan Richter <stefanr@s5r6.in-berlin.de>
Cc: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Cc: linux-doc@vger.kernel.org
Cc: Randy Dunlap <rdunlap@infradead.org>
---
drivers/firewire/core-iso.c | 7 +++++++
1 file changed, 7 insertions(+)
--- linux-next-20180413.orig/drivers/firewire/core-iso.c
+++ linux-next-20180413/drivers/firewire/core-iso.c
@@ -337,9 +337,16 @@ static void deallocate_channel(struct fw
/**
* fw_iso_resource_manage() - Allocate or deallocate a channel and/or bandwidth
+ * @card: card interface for this action
+ * @generation: bus generation
+ * @channels_mask: bitmask for channel allocation
+ * @channel: pointer for returning channel allocation result
+ * @bandwidth: pointer for returning bandwidth allocation result
+ * @allocate: whether to allocate (true) or deallocate (false)
*
* In parameters: card, generation, channels_mask, bandwidth, allocate
* Out parameters: channel, bandwidth
+ *
* This function blocks (sleeps) during communication with the IRM.
*
* Allocates or deallocates at most one channel out of channels_mask.
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply
* [PATCH v3 1/5] FireWire: clean up firewire-cdev.h kernel-doc
From: Randy Dunlap @ 2018-04-14 1:27 UTC (permalink / raw)
To: linux1394-devel; +Cc: Stefan Richter, Takashi Sakamoto, linux-doc, Randy Dunlap
In-Reply-To: <20180414012722.17420-1-rd.dunlab@gmail.com>
From: Randy Dunlap <rdunlap@infradead.org>
Clean up kernel-doc warnings in <linux/firewire-cdev.h> so that
it can be added to a Firewire/IEEE 1394 driver-api chapter
without adding lots of noisy warnings to the documentation build.
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Stefan Richter <stefanr@s5r6.in-berlin.de>
Cc: linux1394-devel@lists.sourceforge.net
Cc: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Cc: linux-doc@vger.kernel.org
Cc: Randy Dunlap <rdunlap@infradead.org>
---
@linux-doc: The patch that adds Documentation/driver-api/firewire.rst
causes a warning in this header file, but I don't see where it is
coming from (this header file patch does not touch that area of the
file):
../include/uapi/linux/firewire-cdev.h:312: WARNING: Inline literal start-string without end-string.
include/uapi/linux/firewire-cdev.h | 22 ++++++++++++++--------
1 file changed, 14 insertions(+), 8 deletions(-)
--- linux-next-20180413.orig/include/uapi/linux/firewire-cdev.h
+++ linux-next-20180413/include/uapi/linux/firewire-cdev.h
@@ -47,11 +47,11 @@
#define FW_CDEV_EVENT_ISO_INTERRUPT_MULTICHANNEL 0x09
/**
- * struct fw_cdev_event_common - Common part of all fw_cdev_event_ types
+ * struct fw_cdev_event_common - Common part of all fw_cdev_event_* types
* @closure: For arbitrary use by userspace
- * @type: Discriminates the fw_cdev_event_ types
+ * @type: Discriminates the fw_cdev_event_* types
*
- * This struct may be used to access generic members of all fw_cdev_event_
+ * This struct may be used to access generic members of all fw_cdev_event_*
* types regardless of the specific type.
*
* Data passed in the @closure field for a request will be returned in the
@@ -123,7 +123,13 @@ struct fw_cdev_event_response {
/**
* struct fw_cdev_event_request - Old version of &fw_cdev_event_request2
+ * @closure: See &fw_cdev_event_common; set by %FW_CDEV_IOC_ALLOCATE ioctl
* @type: See &fw_cdev_event_common; always %FW_CDEV_EVENT_REQUEST
+ * @tcode: Transaction code of the incoming request
+ * @offset: The offset into the 48-bit per-node address space
+ * @handle: Reference to the kernel-side pending request
+ * @length: Data length, i.e. the request's payload size in bytes
+ * @data: Incoming data, if any
*
* This event is sent instead of &fw_cdev_event_request2 if the kernel or
* the client implements ABI version <= 3. &fw_cdev_event_request lacks
@@ -353,7 +359,7 @@ struct fw_cdev_event_phy_packet {
};
/**
- * union fw_cdev_event - Convenience union of fw_cdev_event_ types
+ * union fw_cdev_event - Convenience union of fw_cdev_event_* types
* @common: Valid for all types
* @bus_reset: Valid if @common.type == %FW_CDEV_EVENT_BUS_RESET
* @response: Valid if @common.type == %FW_CDEV_EVENT_RESPONSE
@@ -735,7 +741,7 @@ struct fw_cdev_set_iso_channels {
* @header: Header and payload in case of a transmit context.
*
* &struct fw_cdev_iso_packet is used to describe isochronous packet queues.
- * Use the FW_CDEV_ISO_ macros to fill in @control.
+ * Use the FW_CDEV_ISO_* macros to fill in @control.
* The @header array is empty in case of receive contexts.
*
* Context type %FW_CDEV_ISO_CONTEXT_TRANSMIT:
@@ -842,7 +848,7 @@ struct fw_cdev_queue_iso {
* the %FW_CDEV_ISO_SYNC bit set
* @tags: Tag filter bit mask. Only valid for isochronous reception.
* Determines the tag values for which packets will be accepted.
- * Use FW_CDEV_ISO_CONTEXT_MATCH_ macros to set @tags.
+ * Use FW_CDEV_ISO_CONTEXT_MATCH_* macros to set @tags.
* @handle: Isochronous context handle within which to transmit or receive
*/
struct fw_cdev_start_iso {
@@ -1009,8 +1015,8 @@ struct fw_cdev_send_stream_packet {
* on the same card as this device. After transmission, an
* %FW_CDEV_EVENT_PHY_PACKET_SENT event is generated.
*
- * The payload @data[] shall be specified in host byte order. Usually,
- * @data[1] needs to be the bitwise inverse of @data[0]. VersaPHY packets
+ * The payload @data\[\] shall be specified in host byte order. Usually,
+ * @data\[1\] needs to be the bitwise inverse of @data\[0\]. VersaPHY packets
* are an exception to this rule.
*
* The ioctl is only permitted on device files which represent a local node.
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply
* [PATCH v2 0/5] FireWire: clean up kernel-doc, add Documentation chapter
From: Randy Dunlap @ 2018-04-14 1:27 UTC (permalink / raw)
To: linux1394-devel; +Cc: Stefan Richter, Takashi Sakamoto, linux-doc, Randy Dunlap
This patch series cleans up kernel-doc warnings in several
FireWire source files and then adds a Documentation driver-api
chapter for FireWire.
[PATCH v3 1/5] FireWire: clean up firewire-cdev.h kernel-doc
[PATCH v3 2/5] FireWire: clean up core-iso.c kernel-doc
[PATCH v3 3/5] FireWire: clean up core-transaction.c kernel-doc
[PATCH v3 4/5] FireWire: add a Documentation driver-api chapter
[PATCH v3 5/5] FireWire: add driver-api Introduction section
Documentation/driver-api/firewire.rst | 50 +++++++++++++++++++++++-
Documentation/driver-api/index.rst | 1
drivers/firewire/core-iso.c | 7 +++
drivers/firewire/core-transaction.c | 10 ++++
include/uapi/linux/firewire-cdev.h | 22 ++++++----
5 files changed, 81 insertions(+), 9 deletions(-)
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply
* Re: [PATCH] Documentation/i2c: sync docs with current state of i2c-tools.
From: Sam Hansen @ 2018-04-13 23:32 UTC (permalink / raw)
To: Jean Delvare
Cc: Wolfram Sang, linux-i2c, Jonathan Corbet, linux-doc, linux-kernel
In-Reply-To: <20180413204937.440437e9@endymion>
On Fri, Apr 13, 2018 at 11:49 AM, Jean Delvare <jdelvare@suse.de> wrote:
> On Fri, 13 Apr 2018 09:02:03 -0700, Sam Hansen wrote:
>> On Fri, Apr 13, 2018 at 5:13 AM, Jean Delvare <jdelvare@suse.de> wrote:
>> > On Fri, 13 Apr 2018 00:24:57 +0200, Wolfram Sang wrote:
>> >> On Thu, Apr 12, 2018 at 02:33:42PM -0700, Sam Hansen wrote:
>> >> > - Not meant to be called directly; instead, use the access functions
>> >> > - below.
>> >> > + If possible, use the provided i2c_smbus_* methods described below in favor
>> >> > + of issuing direct ioctls.
>> >>
>> >> Why this change?
>> >
>> > I'm also not sure if "in favor of" is right. "instead of" would sound
>> > better to me, but I'm no native English speaker, I could be wrong.
>>
>> Sounds good, I'll adopt "instead of". Regarding Wolfram's earlier
>> comment, as an engineer, requiring an out-of-tree library to build
>> drivers felt a little off. I can revert this section if you want,
>> just let me know.
>
> The i2c dev interface, and the overlaying library, are used by
> user-space applications. This has nothing to do with "building
> drivers", and makes your "out-of-tree" objection irrelevant. I doubt
> libi2c is the only user-space library building on top of a kernel
> interface.
Ok, sounds good. I'll send a revised patch set reverting this block.
(also, did I send the v3 patch series threaded correctly?)
>
> --
> Jean Delvare
> SUSE L3 Support
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply
* Re: [PATCH 00/32] docs/vm: convert to ReST format
From: Matthew Wilcox @ 2018-04-13 20:21 UTC (permalink / raw)
To: Jonathan Corbet
Cc: Mike Rapoport, Andrew Morton, Andrey Ryabinin, Richard Henderson,
Ivan Kokshaysky, Matt Turner, Tony Luck, Fenghua Yu, Ralf Baechle,
James Hogan, Michael Ellerman, Alexander Viro, linux-kernel,
linux-doc, kasan-dev, linux-alpha, linux-ia64, linux-mips,
linuxppc-dev, linux-fsdevel, linux-mm
In-Reply-To: <20180413135551.0e6d1b12@lwn.net>
On Fri, Apr 13, 2018 at 01:55:51PM -0600, Jonathan Corbet wrote:
> > I believe that keeping the mm docs together will give better visibility of
> > what (little) mm documentation we have and will make the updates easier.
> > The documents that fit well into a certain topic could be linked there. For
> > instance:
>
> ...but this sounds like just the opposite...?
>
> I've had this conversation with folks in a number of subsystems.
> Everybody wants to keep their documentation together in one place - it's
> easier for the developers after all. But for the readers I think it's
> objectively worse. It perpetuates the mess that Documentation/ is, and
> forces readers to go digging through all kinds of inappropriate material
> in the hope of finding something that tells them what they need to know.
>
> So I would *really* like to split the documentation by audience, as has
> been done for a number of other kernel subsystems (and eventually all, I
> hope).
>
> I can go ahead and apply the RST conversion, that seems like a step in
> the right direction regardless. But I sure hope we don't really have to
> keep it as an unorganized jumble of stuff...
I've started on Documentation/core-api/memory.rst which covers just
memory allocation. So far it has the Overview and GFP flags sections
written and an outline for 'The slab allocator', 'The page allocator',
'The vmalloc allocator' and 'The page_frag allocator'. And typing this
up, I realise we need a 'The percpu allocator'. I'm thinking that this
is *not* the right document for the DMA memory allocators (although it
should link to that documentation).
I suspect the existing Documentation/vm/ should probably stay as an
unorganised jumble of stuff. Developers mostly talking to other MM
developers. Stuff that people outside the MM fraternity should know
about needs to be centrally documented. By all means convert it to
ReST ... I don't much care, and it may make it easier to steal bits
or link to it from the organised documentation.
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply
* Re: [PATCH 00/32] docs/vm: convert to ReST format
From: Jonathan Corbet @ 2018-04-13 19:55 UTC (permalink / raw)
To: Mike Rapoport
Cc: Andrew Morton, Andrey Ryabinin, Richard Henderson,
Ivan Kokshaysky, Matt Turner, Tony Luck, Fenghua Yu, Ralf Baechle,
James Hogan, Michael Ellerman, Alexander Viro, linux-kernel,
linux-doc, kasan-dev, linux-alpha, linux-ia64, linux-mips,
linuxppc-dev, linux-fsdevel, linux-mm
In-Reply-To: <20180401063857.GA3357@rapoport-lnx>
Sorry for the silence, I'm pedaling as fast as I can, honest...
On Sun, 1 Apr 2018 09:38:58 +0300
Mike Rapoport <rppt@linux.vnet.ibm.com> wrote:
> My thinking was to start with mechanical RST conversion and then to start
> working on the contents and ordering of the documentation. Some of the
> existing files, e.g. ksm.txt, can be moved as is into the appropriate
> places, others, like transhuge.txt should be at least split into admin/user
> and developer guides.
>
> Another problem with many of the existing mm docs is that they are rather
> developer notes and it wouldn't be really straight forward to assign them
> to a particular topic.
All this sounds good.
> I believe that keeping the mm docs together will give better visibility of
> what (little) mm documentation we have and will make the updates easier.
> The documents that fit well into a certain topic could be linked there. For
> instance:
...but this sounds like just the opposite...?
I've had this conversation with folks in a number of subsystems.
Everybody wants to keep their documentation together in one place - it's
easier for the developers after all. But for the readers I think it's
objectively worse. It perpetuates the mess that Documentation/ is, and
forces readers to go digging through all kinds of inappropriate material
in the hope of finding something that tells them what they need to know.
So I would *really* like to split the documentation by audience, as has
been done for a number of other kernel subsystems (and eventually all, I
hope).
I can go ahead and apply the RST conversion, that seems like a step in
the right direction regardless. But I sure hope we don't really have to
keep it as an unorganized jumble of stuff...
Thanks,
jon
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply
* Re: [PATCH v2] Documentation: ftrace: clarify filters with dynamic ftrace and graph
From: Jonathan Corbet @ 2018-04-13 19:48 UTC (permalink / raw)
To: Steven Rostedt; +Cc: Steffen Maier, linux-doc, Ingo Molnar
In-Reply-To: <20180413115403.757b8c27@gandalf.local.home>
On Fri, 13 Apr 2018 11:54:03 -0400
Steven Rostedt <rostedt@goodmis.org> wrote:
> Jon, you want to take it in your tree?
Sure, I'll grab it.
jon
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply
* Re: [PATCH] Documentation/i2c: sync docs with current state of i2c-tools.
From: Jean Delvare @ 2018-04-13 18:49 UTC (permalink / raw)
To: Sam Hansen; +Cc: Wolfram Sang, linux-i2c, corbet, linux-doc, linux-kernel
In-Reply-To: <CAP9bUy7rONNHYeRkYtaWHcfqoZcGKXJz-JocED26zBj9n+-ZbQ@mail.gmail.com>
On Fri, 13 Apr 2018 09:02:03 -0700, Sam Hansen wrote:
> On Fri, Apr 13, 2018 at 5:13 AM, Jean Delvare <jdelvare@suse.de> wrote:
> > On Fri, 13 Apr 2018 00:24:57 +0200, Wolfram Sang wrote:
> >> On Thu, Apr 12, 2018 at 02:33:42PM -0700, Sam Hansen wrote:
> >> > - Not meant to be called directly; instead, use the access functions
> >> > - below.
> >> > + If possible, use the provided i2c_smbus_* methods described below in favor
> >> > + of issuing direct ioctls.
> >>
> >> Why this change?
> >
> > I'm also not sure if "in favor of" is right. "instead of" would sound
> > better to me, but I'm no native English speaker, I could be wrong.
>
> Sounds good, I'll adopt "instead of". Regarding Wolfram's earlier
> comment, as an engineer, requiring an out-of-tree library to build
> drivers felt a little off. I can revert this section if you want,
> just let me know.
The i2c dev interface, and the overlaying library, are used by
user-space applications. This has nothing to do with "building
drivers", and makes your "out-of-tree" objection irrelevant. I doubt
libi2c is the only user-space library building on top of a kernel
interface.
--
Jean Delvare
SUSE L3 Support
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply
* Re: [RFC bpf-next v2 4/8] bpf: add documentation for eBPF helpers (23-32)
From: Quentin Monnet @ 2018-04-13 18:18 UTC (permalink / raw)
To: Alexei Starovoitov; +Cc: daniel, ast, netdev, oss-drivers, linux-doc, linux-man
In-Reply-To: <20180413002838.atu7shp5cuubx32p@ast-mbp.dhcp.thefacebook.com>
2018-04-12 17:28 UTC-0700 ~ Alexei Starovoitov
<alexei.starovoitov@gmail.com>
> On Tue, Apr 10, 2018 at 03:41:53PM +0100, Quentin Monnet wrote:
>> Add documentation for eBPF helper functions to bpf.h user header file.
>> This documentation can be parsed with the Python script provided in
>> another commit of the patch series, in order to provide a RST document
>> that can later be converted into a man page.
>>
>> The objective is to make the documentation easily understandable and
>> accessible to all eBPF developers, including beginners.
>>
>> This patch contains descriptions for the following helper functions, all
>> written by Daniel:
>>
>> - bpf_get_prandom_u32()
>> - bpf_get_smp_processor_id()
>> - bpf_get_cgroup_classid()
>> - bpf_get_route_realm()
>> - bpf_skb_load_bytes()
>> - bpf_csum_diff()
>> - bpf_skb_get_tunnel_opt()
>> - bpf_skb_set_tunnel_opt()
>> - bpf_skb_change_proto()
>> - bpf_skb_change_type()
>>
>> Cc: Daniel Borkmann <daniel@iogearbox.net>
>> Signed-off-by: Quentin Monnet <quentin.monnet@netronome.com>
>> ---
>> include/uapi/linux/bpf.h | 125 +++++++++++++++++++++++++++++++++++++++++++++++
>> 1 file changed, 125 insertions(+)
>>
>> diff --git a/include/uapi/linux/bpf.h b/include/uapi/linux/bpf.h
>> index f3ea8824efbc..d147d9dd6a83 100644
>> --- a/include/uapi/linux/bpf.h
>> +++ b/include/uapi/linux/bpf.h
[...]
>> @@ -604,6 +612,13 @@ union bpf_attr {
>> * Return
>> * 0 on success, or a negative error in case of failure.
>> *
>> + * u32 bpf_get_cgroup_classid(struct sk_buff *skb)
>> + * Description
>> + * Retrieve the classid for the current task, i.e. for the
>> + * net_cls (network classifier) cgroup to which *skb* belongs.
>
> please add that kernel should be configured with CONFIG_NET_CLS_CGROUP=y|m
> and mention Documentation/cgroup-v1/net_cls.txt
Ok.
> Otherwise 'network classifier' is way too generic.
I am not so familiar with cgroups. What would you suggest instead?
> I'd also mention that placing a task into net_cls controller
> disables all of cgroup-bpf.
Could you please explain a bit more? Placing a task into the controller
is using:
echo <task_pid> > /sys/fs/cgroup/<my_cgroup_name>/tasks
correct? Then if I do this, it disables all of cgroup-bpf. Does this
mean that I loose the possibility to use or add BPF programs to all
cgroup-related attach points for this cgroup? I think I missed something
here.
>> + * Return
>> + * The classid, or 0 for the default unconfigured classid.
>> + *
>> * int bpf_skb_vlan_push(struct sk_buff *skb, __be16 vlan_proto, u16 vlan_tci)
>> * Description
>> * Push a *vlan_tci* (VLAN tag control information) of protocol
I have no particular comments on the other items you reported on this
patch, I will fix them. Thanks!
Quentin
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply
* [PATCH v3 2/3] Documentation/i2c: sync docs with current state of i2c-tools
From: Sam Hansen @ 2018-04-13 17:42 UTC (permalink / raw)
To: linux-i2c, hansens, wsa, corbet, linux-doc, linux-kernel
Cc: Sam Hansen, wsa, corbet, linux-doc, linux-kernel
In-Reply-To: <20180413174257.139182-1-hansens@google.com>
Currently, Documentation/i2c/dev-interface describes the use of
i2c_smbus_* helper routines as static inlined functions provided by
linux/i2c-dev.h. Work has been done to refactor the linux/i2c-dev.h file
in the i2c-tools project out into its own library. As a result, these
docs have become stale.
This patch corrects the discrepancy and directs the reader to the
i2c-tools project for more information.
Signed-off-by: Sam Hansen <hansens@google.com>
---
No changes from v2.
Documentation/i2c/dev-interface | 16 +++++-----------
1 file changed, 5 insertions(+), 11 deletions(-)
diff --git a/Documentation/i2c/dev-interface b/Documentation/i2c/dev-interface
index c8737d502791..f92ee1f59914 100644
--- a/Documentation/i2c/dev-interface
+++ b/Documentation/i2c/dev-interface
@@ -23,11 +23,6 @@ First, you need to include these two headers:
#include <linux/i2c-dev.h>
#include <i2c/smbus.h>
-(Please note that there are two files named "i2c-dev.h" out there. One is
-distributed with the Linux kernel and the other one is included in the
-source tree of i2c-tools. They used to be different in content but since 2012
-they're identical. You should use "linux/i2c-dev.h").
-
Now, you have to decide which adapter you want to access. You should
inspect /sys/class/i2c-dev/ or run "i2cdetect -l" to decide this.
Adapter numbers are assigned somewhat dynamically, so you can not
@@ -140,8 +135,8 @@ ioctl(file, I2C_RDWR, struct i2c_rdwr_ioctl_data *msgset)
set in each message, overriding the values set with the above ioctl's.
ioctl(file, I2C_SMBUS, struct i2c_smbus_ioctl_data *args)
- Not meant to be called directly; instead, use the access functions
- below.
+ If possible, use the provided i2c_smbus_* methods described below instead
+ of issuing direct ioctls.
You can do plain i2c transactions by using read(2) and write(2) calls.
You do not need to pass the address byte; instead, set it through
@@ -166,10 +161,9 @@ what happened. The 'write' transactions return 0 on success; the
returns the number of values read. The block buffers need not be longer
than 32 bytes.
-The above functions are all inline functions, that resolve to calls to
-the i2c_smbus_access function, that on its turn calls a specific ioctl
-with the data in a specific format. Read the source code if you
-want to know what happens behind the screens.
+The above functions are made available by linking against the libi2c library,
+which is provided by the i2c-tools project. See:
+https://git.kernel.org/pub/scm/utils/i2c-tools/i2c-tools.git/.
Implementation details
--
2.17.0.484.g0c8726318c-goog
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply related
* [PATCH v3 3/3] Documentation/i2c: adopt kernel commenting style in examples
From: Sam Hansen @ 2018-04-13 17:42 UTC (permalink / raw)
To: linux-i2c, hansens, wsa, corbet, linux-doc, linux-kernel
Cc: Sam Hansen, wsa, corbet, linux-doc, linux-kernel
In-Reply-To: <20180413174257.139182-1-hansens@google.com>
The example I2C code is rewritten to adopt the preferred kernel block
commenting style.
Signed-off-by: Sam Hansen <hansens@google.com>
---
Changes from v2:
1. only the block comment is updated.
2. one-line comments are reverted to prior form.
Documentation/i2c/dev-interface | 6 ++++--
1 file changed, 4 insertions(+), 2 deletions(-)
diff --git a/Documentation/i2c/dev-interface b/Documentation/i2c/dev-interface
index f92ee1f59914..fbed645ccd75 100644
--- a/Documentation/i2c/dev-interface
+++ b/Documentation/i2c/dev-interface
@@ -67,8 +67,10 @@ the device supports them. Both are illustrated below.
/* res contains the read word */
}
- /* Using I2C Write, equivalent of
- i2c_smbus_write_word_data(file, reg, 0x6543) */
+ /*
+ * Using I2C Write, equivalent of
+ * i2c_smbus_write_word_data(file, reg, 0x6543)
+ */
buf[0] = reg;
buf[1] = 0x43;
buf[2] = 0x65;
--
2.17.0.484.g0c8726318c-goog
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply related
* [PATCH v3 1/3] Documentation/i2c: whitespace cleanup
From: Sam Hansen @ 2018-04-13 17:42 UTC (permalink / raw)
To: linux-i2c, hansens, wsa, corbet, linux-doc, linux-kernel
Cc: Sam Hansen, wsa, corbet, linux-doc, linux-kernel
This strips trailing whitespace in Documentation/i2c/dev-interface.
Signed-off-by: Sam Hansen <hansens@google.com>
---
No changes from v2.
Documentation/i2c/dev-interface | 12 ++++++------
1 file changed, 6 insertions(+), 6 deletions(-)
diff --git a/Documentation/i2c/dev-interface b/Documentation/i2c/dev-interface
index d04e6e4964ee..c8737d502791 100644
--- a/Documentation/i2c/dev-interface
+++ b/Documentation/i2c/dev-interface
@@ -9,8 +9,8 @@ i2c adapters present on your system at a given time. i2cdetect is part of
the i2c-tools package.
I2C device files are character device files with major device number 89
-and a minor device number corresponding to the number assigned as
-explained above. They should be called "i2c-%d" (i2c-0, i2c-1, ...,
+and a minor device number corresponding to the number assigned as
+explained above. They should be called "i2c-%d" (i2c-0, i2c-1, ...,
i2c-10, ...). All 256 minor device numbers are reserved for i2c.
@@ -38,7 +38,7 @@ Next thing, open the device file, as follows:
int file;
int adapter_nr = 2; /* probably dynamically determined */
char filename[20];
-
+
snprintf(filename, 19, "/dev/i2c-%d", adapter_nr);
file = open(filename, O_RDWR);
if (file < 0) {
@@ -72,7 +72,7 @@ the device supports them. Both are illustrated below.
/* res contains the read word */
}
- /* Using I2C Write, equivalent of
+ /* Using I2C Write, equivalent of
i2c_smbus_write_word_data(file, reg, 0x6543) */
buf[0] = reg;
buf[1] = 0x43;
@@ -147,7 +147,7 @@ You can do plain i2c transactions by using read(2) and write(2) calls.
You do not need to pass the address byte; instead, set it through
ioctl I2C_SLAVE before you try to access the device.
-You can do SMBus level transactions (see documentation file smbus-protocol
+You can do SMBus level transactions (see documentation file smbus-protocol
for details) through the following functions:
__s32 i2c_smbus_write_quick(int file, __u8 value);
__s32 i2c_smbus_read_byte(int file);
@@ -158,7 +158,7 @@ for details) through the following functions:
__s32 i2c_smbus_write_word_data(int file, __u8 command, __u16 value);
__s32 i2c_smbus_process_call(int file, __u8 command, __u16 value);
__s32 i2c_smbus_read_block_data(int file, __u8 command, __u8 *values);
- __s32 i2c_smbus_write_block_data(int file, __u8 command, __u8 length,
+ __s32 i2c_smbus_write_block_data(int file, __u8 command, __u8 length,
__u8 *values);
All these transactions return -1 on failure; you can read errno to see
what happened. The 'write' transactions return 0 on success; the
--
2.17.0.484.g0c8726318c-goog
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply related
* Re: [PATCH v2 3/3] Documentation/i2c: adopt kernel commenting style in examples
From: Sam Hansen @ 2018-04-13 17:39 UTC (permalink / raw)
To: Wolfram Sang; +Cc: linux-i2c, corbet, linux-doc, linux-kernel
In-Reply-To: <20180413165000.2svg2j5ozdd2egbd@ninjato>
On Fri, Apr 13, 2018 at 9:50 AM, Wolfram Sang <wsa@the-dreams.de> wrote:
>
>> - int adapter_nr = 2; /* probably dynamically determined */
>
> Such comments are actually OK.
Ah, gotcha. Thanks for the correction. Standby for revised patch set.
>
>> - /* ERROR HANDLING; you can check errno to see what went wrong */
>
> Such as well.
>
>> - /* Using I2C Write, equivalent of
>> - i2c_smbus_write_word_data(file, reg, 0x6543) */
>> + /*
>> + * Using I2C Write, equivalent of
>> + * i2c_smbus_write_word_data(file, reg, 0x6543).
>> + */
>
> This is the only broken one AFAICT.
>
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply
* Re: [PATCH v2 2/3] Documentation/i2c: sync docs with current state of i2c-tools
From: Wolfram Sang @ 2018-04-13 16:50 UTC (permalink / raw)
To: Sam Hansen; +Cc: linux-i2c, corbet, linux-doc, linux-kernel
In-Reply-To: <20180413164405.127522-2-hansens@google.com>
[-- Attachment #1: Type: text/plain, Size: 578 bytes --]
On Fri, Apr 13, 2018 at 09:44:04AM -0700, Sam Hansen wrote:
> Currently, Documentation/i2c/dev-interface describes the use of
> i2c_smbus_* helper routines as static inlined functions provided by
> linux/i2c-dev.h. Work has been done to refactor the linux/i2c-dev.h file
> in the i2c-tools project out into its own library. As a result, these
> docs have become stale.
>
> This patch corrects the discrepancy and directs the reader to the
> i2c-tools project for more information.
>
> Signed-off-by: Sam Hansen <hansens@google.com>
Looks good to me as well.
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply
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