* Re: [PATCH v2 2/2] tracing/kprobe: Add kprobe_event= boot parameter
From: Masami Hiramatsu @ 2019-06-03 12:41 UTC (permalink / raw)
To: Masami Hiramatsu
Cc: Anders Roxell, Steven Rostedt, Ingo Molnar, Naveen N . Rao,
Anil S Keshavamurthy, David S . Miller, Linux Kernel Mailing List,
linux-doc
In-Reply-To: <20190603205238.3cef1ef724bda35d11369ea7@kernel.org>
On Mon, 3 Jun 2019 20:52:38 +0900
Masami Hiramatsu <mhiramat@kernel.org> wrote:
> Hi Anders,
>
> Sorry for replying later.
>
> On Tue, 28 May 2019 15:39:15 +0200
> Anders Roxell <anders.roxell@linaro.org> wrote:
>
> > On Tue, 28 May 2019 at 14:36, Steven Rostedt <rostedt@goodmis.org> wrote:
> > >
> > > On Tue, 28 May 2019 14:23:43 +0200
> > > Anders Roxell <anders.roxell@linaro.org> wrote:
> > >
> > > > On Wed, 22 May 2019 at 10:32, Masami Hiramatsu <mhiramat@kernel.org> wrote:
> > > > >
> > > > > Add kprobe_event= boot parameter to define kprobe events
> > > > > at boot time.
> > > > > The definition syntax is similar to tracefs/kprobe_events
> > > > > interface, but use ',' and ';' instead of ' ' and '\n'
> > > > > respectively. e.g.
> > > > >
> > > > > kprobe_event=p,vfs_read,$arg1,$arg2
> > > > >
> > > > > This puts a probe on vfs_read with argument1 and 2, and
> > > > > enable the new event.
> > > > >
> > > > > Signed-off-by: Masami Hiramatsu <mhiramat@kernel.org>
> > > >
> > > > I built an arm64 kernel from todays linux-next tag next-20190528 and
> > > > ran in to this issue when I booted it up in qemu:
>
> Thank you for reporting!
>
>
> > [ 9.020354][ T1] Kprobe smoke test: started
> > [ 9.064132][ T1] Internal error: aarch64 BRK: f2000004 [#1] PREEMPT SMP
> > [ 9.067084][ T1] Modules linked in:
> > [ 9.068772][ T1] CPU: 0 PID: 1 Comm: swapper/0 Not tainted
> > 5.2.0-rc2-next-20190528-00019-g9a6008710716 #8
> > [ 9.072893][ T1] Hardware name: linux,dummy-virt (DT)
> > [ 9.075143][ T1] pstate: 80400005 (Nzcv daif +PAN -UAO)
> > [ 9.077528][ T1] pc : kprobe_target+0x0/0x30
> > [ 9.079479][ T1] lr : init_test_probes+0x134/0x540
> > [ 9.081611][ T1] sp : ffff80003f51fbe0
> > [ 9.083331][ T1] x29: ffff80003f51fbe0 x28: ffff200013c17820
> > [ 9.085906][ T1] x27: ffff200015d3ab40 x26: ffff2000122bb120
> > [ 9.088491][ T1] x25: 0000000000000000 x24: ffff200013c08ae0
> > [ 9.091068][ T1] x23: ffff200015d39000 x22: ffff200013a15ac8
> > [ 9.093667][ T1] x21: 1ffff00007ea3f86 x20: ffff200015d39420
> > [ 9.096214][ T1] x19: ffff2000122bad20 x18: 0000000000001400
> > [ 9.098831][ T1] x17: 0000000000000000 x16: ffff80003f510040
> > [ 9.101410][ T1] x15: 0000000000001480 x14: 1ffff00007ea3ea2
> > [ 9.103963][ T1] x13: 00000000f1f1f1f1 x12: ffff040002782e0d
> > [ 9.106549][ T1] x11: 1fffe40002782e0c x10: ffff040002782e0c
> > [ 9.109120][ T1] x9 : 1fffe40002782e0c x8 : dfff200000000000
> > [ 9.111676][ T1] x7 : ffff040002782e0d x6 : ffff200013c17067
> > [ 9.114234][ T1] x5 : ffff80003f510040 x4 : 0000000000000000
> > [ 9.116843][ T1] x3 : ffff200010427508 x2 : 0000000000000000
> > [ 9.119409][ T1] x1 : ffff200010426e10 x0 : 0000000000a6326b
> > [ 9.121980][ T1] Call trace:
> > [ 9.123380][ T1] kprobe_target+0x0/0x30
> > [ 9.125205][ T1] init_kprobes+0x2b8/0x300
> > [ 9.127074][ T1] do_one_initcall+0x4c0/0xa68
> > [ 9.129076][ T1] kernel_init_freeable+0x3c4/0x4e4
> > [ 9.131234][ T1] kernel_init+0x14/0x1fc
> > [ 9.133032][ T1] ret_from_fork+0x10/0x18
> > [ 9.134908][ T1] Code: a9446bf9 f9402bfb a8d87bfd d65f03c0 (d4200080)
> > [ 9.137845][ T1] ---[ end trace 49243ee03446b072 ]---
> > [ 9.140114][ T1] Kernel panic - not syncing: Fatal exception
> > [ 9.142684][ T1] ---[ end Kernel panic - not syncing: Fatal exception ]---
>
> Ah, I think you hit this in [1/2], not this change.
>
> I guess arm64's breakpoint handler is not initialized at postcore_initcall().
> I have to check the arch depend implementation on arm64.
Yes, for some reason, arm64 breakpoint handler vector is initalized in arch_initcall().
Let's move init_kprobes to subsys_initcall, which is called before fs_initcall.
Thank you,
--
Masami Hiramatsu <mhiramat@kernel.org>
^ permalink raw reply
* Re: [PATCH v2 2/2] tracing/kprobe: Add kprobe_event= boot parameter
From: Masami Hiramatsu @ 2019-06-03 11:52 UTC (permalink / raw)
To: Anders Roxell
Cc: Steven Rostedt, Masami Hiramatsu, Ingo Molnar, Naveen N . Rao,
Anil S Keshavamurthy, David S . Miller, Linux Kernel Mailing List,
linux-doc
In-Reply-To: <CADYN=9L2Lz9xgsP7jn3UNMOtAYtg6fAb1hbv=OJ_Xi4dA0Z5NQ@mail.gmail.com>
Hi Anders,
Sorry for replying later.
On Tue, 28 May 2019 15:39:15 +0200
Anders Roxell <anders.roxell@linaro.org> wrote:
> On Tue, 28 May 2019 at 14:36, Steven Rostedt <rostedt@goodmis.org> wrote:
> >
> > On Tue, 28 May 2019 14:23:43 +0200
> > Anders Roxell <anders.roxell@linaro.org> wrote:
> >
> > > On Wed, 22 May 2019 at 10:32, Masami Hiramatsu <mhiramat@kernel.org> wrote:
> > > >
> > > > Add kprobe_event= boot parameter to define kprobe events
> > > > at boot time.
> > > > The definition syntax is similar to tracefs/kprobe_events
> > > > interface, but use ',' and ';' instead of ' ' and '\n'
> > > > respectively. e.g.
> > > >
> > > > kprobe_event=p,vfs_read,$arg1,$arg2
> > > >
> > > > This puts a probe on vfs_read with argument1 and 2, and
> > > > enable the new event.
> > > >
> > > > Signed-off-by: Masami Hiramatsu <mhiramat@kernel.org>
> > >
> > > I built an arm64 kernel from todays linux-next tag next-20190528 and
> > > ran in to this issue when I booted it up in qemu:
Thank you for reporting!
> [ 9.020354][ T1] Kprobe smoke test: started
> [ 9.064132][ T1] Internal error: aarch64 BRK: f2000004 [#1] PREEMPT SMP
> [ 9.067084][ T1] Modules linked in:
> [ 9.068772][ T1] CPU: 0 PID: 1 Comm: swapper/0 Not tainted
> 5.2.0-rc2-next-20190528-00019-g9a6008710716 #8
> [ 9.072893][ T1] Hardware name: linux,dummy-virt (DT)
> [ 9.075143][ T1] pstate: 80400005 (Nzcv daif +PAN -UAO)
> [ 9.077528][ T1] pc : kprobe_target+0x0/0x30
> [ 9.079479][ T1] lr : init_test_probes+0x134/0x540
> [ 9.081611][ T1] sp : ffff80003f51fbe0
> [ 9.083331][ T1] x29: ffff80003f51fbe0 x28: ffff200013c17820
> [ 9.085906][ T1] x27: ffff200015d3ab40 x26: ffff2000122bb120
> [ 9.088491][ T1] x25: 0000000000000000 x24: ffff200013c08ae0
> [ 9.091068][ T1] x23: ffff200015d39000 x22: ffff200013a15ac8
> [ 9.093667][ T1] x21: 1ffff00007ea3f86 x20: ffff200015d39420
> [ 9.096214][ T1] x19: ffff2000122bad20 x18: 0000000000001400
> [ 9.098831][ T1] x17: 0000000000000000 x16: ffff80003f510040
> [ 9.101410][ T1] x15: 0000000000001480 x14: 1ffff00007ea3ea2
> [ 9.103963][ T1] x13: 00000000f1f1f1f1 x12: ffff040002782e0d
> [ 9.106549][ T1] x11: 1fffe40002782e0c x10: ffff040002782e0c
> [ 9.109120][ T1] x9 : 1fffe40002782e0c x8 : dfff200000000000
> [ 9.111676][ T1] x7 : ffff040002782e0d x6 : ffff200013c17067
> [ 9.114234][ T1] x5 : ffff80003f510040 x4 : 0000000000000000
> [ 9.116843][ T1] x3 : ffff200010427508 x2 : 0000000000000000
> [ 9.119409][ T1] x1 : ffff200010426e10 x0 : 0000000000a6326b
> [ 9.121980][ T1] Call trace:
> [ 9.123380][ T1] kprobe_target+0x0/0x30
> [ 9.125205][ T1] init_kprobes+0x2b8/0x300
> [ 9.127074][ T1] do_one_initcall+0x4c0/0xa68
> [ 9.129076][ T1] kernel_init_freeable+0x3c4/0x4e4
> [ 9.131234][ T1] kernel_init+0x14/0x1fc
> [ 9.133032][ T1] ret_from_fork+0x10/0x18
> [ 9.134908][ T1] Code: a9446bf9 f9402bfb a8d87bfd d65f03c0 (d4200080)
> [ 9.137845][ T1] ---[ end trace 49243ee03446b072 ]---
> [ 9.140114][ T1] Kernel panic - not syncing: Fatal exception
> [ 9.142684][ T1] ---[ end Kernel panic - not syncing: Fatal exception ]---
Ah, I think you hit this in [1/2], not this change.
I guess arm64's breakpoint handler is not initialized at postcore_initcall().
I have to check the arch depend implementation on arm64.
Thank you,
--
Masami Hiramatsu <mhiramat@kernel.org>
^ permalink raw reply
* Re: [PATCH v8 3/7] s390/pci: add support for IOMMU default DMA mode build options
From: Sebastian Ott @ 2019-06-03 11:51 UTC (permalink / raw)
To: Zhen Lei
Cc: Jean-Philippe Brucker, John Garry, Robin Murphy, Will Deacon,
Joerg Roedel, Jonathan Corbet, linux-doc, Gerald Schaefer,
Martin Schwidefsky, Heiko Carstens, Benjamin Herrenschmidt,
Paul Mackerras, Michael Ellerman, Tony Luck, Fenghua Yu,
Thomas Gleixner, Ingo Molnar, Borislav Petkov, H . Peter Anvin,
David Woodhouse, iommu, linux-kernel, linux-s390, linuxppc-dev,
x86, linux-ia64, Hanjun Guo
In-Reply-To: <20190530034831.4184-4-thunder.leizhen@huawei.com>
On Thu, 30 May 2019, Zhen Lei wrote:
> The default DMA mode is LAZY on s390, this patch make it can be set to
> STRICT at build time. It can be overridden by boot option.
>
> There is no functional change.
>
> Signed-off-by: Zhen Lei <thunder.leizhen@huawei.com>
Acked-by: Sebastian Ott <sebott@linux.ibm.com>
^ permalink raw reply
* Re: [PATCH v3 3/4] f2fs: Fix accounting for unusable blocks
From: Chao Yu @ 2019-06-03 10:39 UTC (permalink / raw)
To: Daniel Rosenberg, Jaegeuk Kim, Jonathan Corbet, linux-f2fs-devel
Cc: linux-kernel, linux-doc, linux-fsdevel, kernel-team
In-Reply-To: <20190530004906.261170-4-drosen@google.com>
On 2019/5/30 8:49, Daniel Rosenberg wrote:
> Fixes possible underflows when dealing with unusable blocks.
>
> Signed-off-by: Daniel Rosenberg <drosen@google.com>
> ---
> fs/f2fs/f2fs.h | 15 ++++++++++-----
> 1 file changed, 10 insertions(+), 5 deletions(-)
>
> diff --git a/fs/f2fs/f2fs.h b/fs/f2fs/f2fs.h
> index 9b3d9977cd1ef..a39cc4ffeb4b1 100644
> --- a/fs/f2fs/f2fs.h
> +++ b/fs/f2fs/f2fs.h
> @@ -1769,8 +1769,12 @@ static inline int inc_valid_block_count(struct f2fs_sb_info *sbi,
>
> if (!__allow_reserved_blocks(sbi, inode, true))
> avail_user_block_count -= F2FS_OPTION(sbi).root_reserved_blocks;
> - if (unlikely(is_sbi_flag_set(sbi, SBI_CP_DISABLED)))
> - avail_user_block_count -= sbi->unusable_block_count;
> + if (unlikely(is_sbi_flag_set(sbi, SBI_CP_DISABLED))) {
> + if (avail_user_block_count > sbi->unusable_block_count)
> + avail_user_block_count = 0;
avail_user_block_count -= sbi->unusable_block_count;
> + else
> + avail_user_block_count -= sbi->unusable_block_count;
avail_user_block_count = 0;
Thanks,
> + }
> if (unlikely(sbi->total_valid_block_count > avail_user_block_count)) {
> diff = sbi->total_valid_block_count - avail_user_block_count;
> if (diff > *count)
> @@ -1970,7 +1974,7 @@ static inline int inc_valid_node_count(struct f2fs_sb_info *sbi,
> struct inode *inode, bool is_inode)
> {
> block_t valid_block_count;
> - unsigned int valid_node_count;
> + unsigned int valid_node_count, user_block_count;
> int err;
>
> if (is_inode) {
> @@ -1997,10 +2001,11 @@ static inline int inc_valid_node_count(struct f2fs_sb_info *sbi,
>
> if (!__allow_reserved_blocks(sbi, inode, false))
> valid_block_count += F2FS_OPTION(sbi).root_reserved_blocks;
> + user_block_count = sbi->user_block_count;
> if (unlikely(is_sbi_flag_set(sbi, SBI_CP_DISABLED)))
> - valid_block_count += sbi->unusable_block_count;
> + user_block_count -= sbi->unusable_block_count;
>
> - if (unlikely(valid_block_count > sbi->user_block_count)) {
> + if (unlikely(valid_block_count > user_block_count)) {
> spin_unlock(&sbi->stat_lock);
> goto enospc;
> }
>
^ permalink raw reply
* Re: [PATCH v3 2/4] f2fs: Fix root reserved on remount
From: Chao Yu @ 2019-06-03 10:34 UTC (permalink / raw)
To: Daniel Rosenberg, Jaegeuk Kim, Jonathan Corbet, linux-f2fs-devel
Cc: linux-kernel, linux-doc, linux-fsdevel, kernel-team
In-Reply-To: <20190530004906.261170-3-drosen@google.com>
On 2019/5/30 8:49, Daniel Rosenberg wrote:
> On a remount, you can currently set root reserved if it was not
> previously set. This can cause an underflow if reserved has been set to
> a very high value, since then root reserved + current reserved could be
> greater than user_block_count. inc_valid_block_count later subtracts out
> these values from user_block_count, causing an underflow.
>
> Signed-off-by: Daniel Rosenberg <drosen@google.com>
Reviewed-by: Chao Yu <yuchao0@huawei.com>
Thanks,
^ permalink raw reply
* Re: [PATCH v3 1/4] f2fs: Lower threshold for disable_cp_again
From: Chao Yu @ 2019-06-03 10:33 UTC (permalink / raw)
To: Daniel Rosenberg, Jaegeuk Kim, Jonathan Corbet, linux-f2fs-devel
Cc: linux-kernel, linux-doc, linux-fsdevel, kernel-team
In-Reply-To: <20190530004906.261170-2-drosen@google.com>
On 2019/5/30 8:49, Daniel Rosenberg wrote:
> The existing threshold for allowable holes at checkpoint=disable time is
> too high. The OVP space contains reserved segments, which are always in
> the form of free segments. These must be subtracted from the OVP value.
>
> The current threshold is meant to be the maximum value of holes of a
> single type we can have and still guarantee that we can fill the disk
> without failing to find space for a block of a given type.
>
> If the disk is full, ignoring current reserved, which only helps us,
> the amount of unused blocks is equal to the OVP area. Of that, there
> are reserved segments, which must be free segments, and the rest of the
> ovp area, which can come from either free segments or holes. The maximum
> possible amount of holes is OVP-reserved.
>
> Now, consider the disk when mounting with checkpoint=disable.
> We must be able to fill all available free space with either data or
> node blocks. When we start with checkpoint=disable, holes are locked to
> their current type. Say we have H of one type of hole, and H+X of the
> other. We can fill H of that space with arbitrary typed blocks via SSR.
> For the remaining H+X blocks, we may not have any of a given block type
> left at all. For instance, if we were to fill the disk entirely with
> blocks of the type with fewer holes, the H+X blocks of the opposite type
> would not be used. If H+X > OVP-reserved, there would be more holes than
> could possibly exist, and we would have failed to find a suitable block
> earlier on, leading to a crash in update_sit_entry.
>
> If H+X <= OVP-reserved, then the holes end up effectively masked by the OVP
> region in this case.
>
> Signed-off-by: Daniel Rosenberg <drosen@google.com>
Reviewed-by: Chao Yu <yuchao0@huawei.com>
Thanks,
^ permalink raw reply
* Re: [PATCH v2 2/3] ima: don't ignore INTEGRITY_UNKNOWN EVM status
From: Roberto Sassu @ 2019-06-03 9:25 UTC (permalink / raw)
To: Mimi Zohar, dmitry.kasatkin, mjg59
Cc: linux-integrity, linux-security-module, linux-doc, linux-kernel,
silviu.vlasceanu, stable
In-Reply-To: <1559217621.4008.7.camel@linux.ibm.com>
On 5/30/2019 2:00 PM, Mimi Zohar wrote:
> On Wed, 2019-05-29 at 15:30 +0200, Roberto Sassu wrote:
>> Currently, ima_appraise_measurement() ignores the EVM status when
>> evm_verifyxattr() returns INTEGRITY_UNKNOWN. If a file has a valid
>> security.ima xattr with type IMA_XATTR_DIGEST or IMA_XATTR_DIGEST_NG,
>> ima_appraise_measurement() returns INTEGRITY_PASS regardless of the EVM
>> status. The problem is that the EVM status is overwritten with the
>>> appraisal statu
>
> Roberto, your framing of this problem is harsh and misleading. IMA
> and EVM are intentionally independent of each other and can be
> configured independently of each other. The intersection of the two
> is the call to evm_verifyxattr(). INTEGRITY_UNKNOWN is returned for a
> number of reasons - when EVM is not configured, the EVM hmac key has
> not yet been loaded, the protected security attribute is unknown, or
> the file is not in policy.
>
> This patch does not differentiate between any of the above cases,
> requiring mutable files to always be protected by EVM, when specified
> as an "ima_appraise=" option on the boot command line.
>
> IMA could be extended to require EVM on a per IMA policy rule basis.
> Instead of framing allowing IMA file hashes without EVM as a bug that
> has existed from the very beginning, now that IMA/EVM have matured and
> is being used, you could frame it as extending IMA or hardening.
I'm seeing it from the perspective of an administrator that manages an
already hardened system, and expects that the system only grants access
to files with a valid signature/HMAC. That system would not enforce this
behavior if EVM keys are removed and the digest in security.ima is set
to the actual file digest.
Framing it as a bug rather than an extension would in my opinion help to
convince people about the necessity to switch to the safe mode, if their
system is already hardened.
>> This patch mitigates the issue by selecting signature verification as the
>> only method allowed for appraisal when EVM is not initialized. Since the
>> new behavior might break user space, it must be turned on by adding the
>> '-evm' suffix to the value of the ima_appraise= kernel option.
>>
>> Fixes: 2fe5d6def1672 ("ima: integrity appraisal extension")
>> Signed-off-by: Roberto Sassu <roberto.sassu@huawei.com>
>> Cc: stable@vger.kernel.org
>> ---
>> Documentation/admin-guide/kernel-parameters.txt | 3 ++-
>> security/integrity/ima/ima_appraise.c | 8 ++++++++
>> 2 files changed, 10 insertions(+), 1 deletion(-)
>>
>> diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
>> index 138f6664b2e2..d84a2e612b93 100644
>> --- a/Documentation/admin-guide/kernel-parameters.txt
>> +++ b/Documentation/admin-guide/kernel-parameters.txt
>> @@ -1585,7 +1585,8 @@
>> Set number of hash buckets for inode cache.
>>
>> ima_appraise= [IMA] appraise integrity measurements
>> - Format: { "off" | "enforce" | "fix" | "log" }
>> + Format: { "off" | "enforce" | "fix" | "log" |
>> + "enforce-evm" | "log-evm" }
>
> Is it necessary to define both "enforce-evm" and "log-evm"? Perhaps
> defining "require-evm" is sufficient.
ima_appraise= accepts as values modes of operation. I consider the -evm
suffix as a modifier of already defined modes.
Roberto
--
HUAWEI TECHNOLOGIES Duesseldorf GmbH, HRB 56063
Managing Director: Bo PENG, Jian LI, Yanli SHI
^ permalink raw reply
* [char-misc-next 7/7] mei: docs: fix broken links in iamt documentation.
From: Tomas Winkler @ 2019-06-03 9:14 UTC (permalink / raw)
To: Greg Kroah-Hartman
Cc: Alexander Usyskin, linux-kernel, Tomas Winkler, Jonathan Corbet,
linux-doc
In-Reply-To: <20190603091406.28915-1-tomas.winkler@intel.com>
The iAMT documentation moved from http:// https://,
and LMS is moved to github.com
Signed-off-by: Tomas Winkler <tomas.winkler@intel.com>
---
Documentation/driver-api/mei/iamt.rst | 105 ++++++++++++--------------
1 file changed, 50 insertions(+), 55 deletions(-)
diff --git a/Documentation/driver-api/mei/iamt.rst b/Documentation/driver-api/mei/iamt.rst
index 6dcf5b16e958..6ef3e613684b 100644
--- a/Documentation/driver-api/mei/iamt.rst
+++ b/Documentation/driver-api/mei/iamt.rst
@@ -27,62 +27,57 @@ starting with Release 6.0) over HTTP/S or WS-Management protocol over
HTTP/S that are received from a remote management console application.
For more information about Intel AMT:
-http://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide
+https://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide/default.htm
Intel AMT Applications
-======================
-
- 1) Intel Local Management Service (Intel LMS)
-
- Applications running locally on the platform communicate with Intel AMT Release
- 2.0 and later releases in the same way that network applications do via SOAP
- over HTTP (deprecated starting with Release 6.0) or with WS-Management over
- SOAP over HTTP. This means that some Intel AMT features can be accessed from a
- local application using the same network interface as a remote application
- communicating with Intel AMT over the network.
-
- When a local application sends a message addressed to the local Intel AMT host
- name, the Intel LMS, which listens for traffic directed to the host name,
- intercepts the message and routes it to the Intel MEI.
- For more information:
- http://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide
- Under "About Intel AMT" => "Local Access"
-
- For downloading Intel LMS:
- http://software.intel.com/en-us/articles/download-the-latest-intel-amt-open-source-drivers/
-
- The Intel LMS opens a connection using the Intel MEI driver to the Intel LMS
- firmware feature using a defined UUID and then communicates with the feature
- using a protocol called Intel AMT Port Forwarding Protocol (Intel APF protocol).
- The protocol is used to maintain multiple sessions with Intel AMT from a
- single application.
-
- See the protocol specification in the Intel AMT Software Development Kit (SDK)
- http://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide
- Under "SDK Resources" => "Intel(R) vPro(TM) Gateway (MPS)"
- => "Information for Intel(R) vPro(TM) Gateway Developers"
- => "Description of the Intel AMT Port Forwarding (APF) Protocol"
-
- 2) Intel AMT Remote configuration using a Local Agent
-
- A Local Agent enables IT personnel to configure Intel AMT out-of-the-box
- without requiring installing additional data to enable setup. The remote
- configuration process may involve an ISV-developed remote configuration
- agent that runs on the host.
- For more information:
- http://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide
- Under "Setup and Configuration of Intel AMT" =>
- "SDK Tools Supporting Setup and Configuration" =>
- "Using the Local Agent Sample"
-
- An open source Intel AMT configuration utility, implementing a local agent
- that accesses the Intel MEI driver, can be found here:
- http://software.intel.com/en-us/articles/download-the-latest-intel-amt-open-source-drivers/
-
+----------------------
+
+ 1) Intel Local Management Service (Intel LMS)
+
+ Applications running locally on the platform communicate with Intel AMT Release
+ 2.0 and later releases in the same way that network applications do via SOAP
+ over HTTP (deprecated starting with Release 6.0) or with WS-Management over
+ SOAP over HTTP. This means that some Intel AMT features can be accessed from a
+ local application using the same network interface as a remote application
+ communicating with Intel AMT over the network.
+
+ When a local application sends a message addressed to the local Intel AMT host
+ name, the Intel LMS, which listens for traffic directed to the host name,
+ intercepts the message and routes it to the Intel MEI.
+ For more information:
+ https://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide/default.htm
+ Under "About Intel AMT" => "Local Access"
+
+ For downloading Intel LMS:
+ https://github.com/intel/lms
+
+ The Intel LMS opens a connection using the Intel MEI driver to the Intel LMS
+ firmware feature using a defined GUID and then communicates with the feature
+ using a protocol called Intel AMT Port Forwarding Protocol (Intel APF protocol).
+ The protocol is used to maintain multiple sessions with Intel AMT from a
+ single application.
+
+ See the protocol specification in the Intel AMT Software Development Kit (SDK)
+ https://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide/default.htm
+ Under "SDK Resources" => "Intel(R) vPro(TM) Gateway (MPS)"
+ => "Information for Intel(R) vPro(TM) Gateway Developers"
+ => "Description of the Intel AMT Port Forwarding (APF) Protocol"
+
+ 2) Intel AMT Remote configuration using a Local Agent
+
+ A Local Agent enables IT personnel to configure Intel AMT out-of-the-box
+ without requiring installing additional data to enable setup. The remote
+ configuration process may involve an ISV-developed remote configuration
+ agent that runs on the host.
+ For more information:
+ https://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide/default.htm
+ Under "Setup and Configuration of Intel AMT" =>
+ "SDK Tools Supporting Setup and Configuration" =>
+ "Using the Local Agent Sample"
Intel AMT OS Health Watchdog
-============================
+----------------------------
The Intel AMT Watchdog is an OS Health (Hang/Crash) watchdog.
Whenever the OS hangs or crashes, Intel AMT will send an event
@@ -90,10 +85,10 @@ to any subscriber to this event. This mechanism means that
IT knows when a platform crashes even when there is a hard failure on the host.
The Intel AMT Watchdog is composed of two parts:
- 1) Firmware feature - receives the heartbeats
- and sends an event when the heartbeats stop.
- 2) Intel MEI iAMT watchdog driver - connects to the watchdog feature,
- configures the watchdog and sends the heartbeats.
+ 1) Firmware feature - receives the heartbeats
+ and sends an event when the heartbeats stop.
+ 2) Intel MEI iAMT watchdog driver - connects to the watchdog feature,
+ configures the watchdog and sends the heartbeats.
The Intel iAMT watchdog MEI driver uses the kernel watchdog API to configure
the Intel AMT Watchdog and to send heartbeats to it. The default timeout of the
--
2.20.1
^ permalink raw reply related
* [char-misc-next 6/7] mei: docs: add hdcp documentation
From: Tomas Winkler @ 2019-06-03 9:14 UTC (permalink / raw)
To: Greg Kroah-Hartman
Cc: Alexander Usyskin, linux-kernel, Tomas Winkler, Jonathan Corbet,
linux-doc
In-Reply-To: <20190603091406.28915-1-tomas.winkler@intel.com>
1. Add a short ducumentation for MEI HDCP driver,
and fix DOC comments in drivers/misc/mei/hdcp/mei_hdcp.c
Signed-off-by: Tomas Winkler <tomas.winkler@intel.com>
---
Documentation/driver-api/mei/hdcp.rst | 32 +++++++++++++++++++
.../driver-api/mei/mei-client-bus.rst | 1 +
drivers/misc/mei/hdcp/mei_hdcp.c | 11 +++----
3 files changed, 37 insertions(+), 7 deletions(-)
create mode 100644 Documentation/driver-api/mei/hdcp.rst
diff --git a/Documentation/driver-api/mei/hdcp.rst b/Documentation/driver-api/mei/hdcp.rst
new file mode 100644
index 000000000000..e85a065b1cdc
--- /dev/null
+++ b/Documentation/driver-api/mei/hdcp.rst
@@ -0,0 +1,32 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+HDCP:
+=====
+
+ME FW as a security engine provides the capability for setting up
+HDCP2.2 protocol negotiation between the Intel graphics device and
+an HDC2.2 sink.
+
+ME FW prepares HDCP2.2 negotiation parameters, signs and encrypts them
+according the HDCP 2.2 spec. The Intel graphics sends the created blob
+to the HDCP2.2 sink.
+
+Similarly, the HDCP2.2 sink's response is transferred to ME FW
+for decryption and verification.
+
+Once all the steps of HDCP2.2 negotiation are completed,
+upon request ME FW will configure the port as authenticated and supply
+the HDCP encryption keys to Intel graphics hardware.
+
+
+mei_hdcp driver
+---------------
+.. kernel-doc:: drivers/misc/mei/hdcp/mei_hdcp.c
+ :doc: MEI_HDCP Client Driver
+
+mei_hdcp api
+------------
+
+.. kernel-doc:: drivers/misc/mei/hdcp/mei_hdcp.c
+ :functions:
+
diff --git a/Documentation/driver-api/mei/mei-client-bus.rst b/Documentation/driver-api/mei/mei-client-bus.rst
index bfe28ebc3ca8..f242b3f8d6aa 100644
--- a/Documentation/driver-api/mei/mei-client-bus.rst
+++ b/Documentation/driver-api/mei/mei-client-bus.rst
@@ -164,4 +164,5 @@ MEI Client Bus Drivers
.. toctree::
:maxdepth: 2
+ hdcp
nfc
diff --git a/drivers/misc/mei/hdcp/mei_hdcp.c b/drivers/misc/mei/hdcp/mei_hdcp.c
index b07000202d4a..ed816939fb32 100644
--- a/drivers/misc/mei/hdcp/mei_hdcp.c
+++ b/drivers/misc/mei/hdcp/mei_hdcp.c
@@ -2,7 +2,7 @@
/*
* Copyright © 2019 Intel Corporation
*
- * Mei_hdcp.c: HDCP client driver for mei bus
+ * mei_hdcp.c: HDCP client driver for mei bus
*
* Author:
* Ramalingam C <ramalingam.c@intel.com>
@@ -11,12 +11,9 @@
/**
* DOC: MEI_HDCP Client Driver
*
- * This is a client driver to the mei_bus to make the HDCP2.2 services of
- * ME FW available for the interested consumers like I915.
- *
- * This module will act as a translation layer between HDCP protocol
- * implementor(I915) and ME FW by translating HDCP2.2 authentication
- * messages to ME FW command payloads and vice versa.
+ * The mei_hdcp driver acts as a translation layer between HDCP 2.2
+ * protocol implementer (I915) and ME FW by translating HDCP2.2
+ * negotiation messages to ME FW command payloads and vice versa.
*/
#include <linux/module.h>
--
2.20.1
^ permalink raw reply related
* [char-misc-next 5/7] mei: docs: add a short description for nfc behind mei
From: Tomas Winkler @ 2019-06-03 9:14 UTC (permalink / raw)
To: Greg Kroah-Hartman
Cc: Alexander Usyskin, linux-kernel, Tomas Winkler, Jonathan Corbet,
linux-doc
In-Reply-To: <20190603091406.28915-1-tomas.winkler@intel.com>
Signed-off-by: Tomas Winkler <tomas.winkler@intel.com>
---
Documentation/driver-api/mei/index.rst | 2 +-
.../driver-api/mei/mei-client-bus.rst | 7 +++++
Documentation/driver-api/mei/nfc.rst | 28 +++++++++++++++++++
3 files changed, 36 insertions(+), 1 deletion(-)
create mode 100644 Documentation/driver-api/mei/nfc.rst
diff --git a/Documentation/driver-api/mei/index.rst b/Documentation/driver-api/mei/index.rst
index d261afac6852..3a22b522ee78 100644
--- a/Documentation/driver-api/mei/index.rst
+++ b/Documentation/driver-api/mei/index.rst
@@ -16,7 +16,7 @@ Intel(R) Management Engine Interface (Intel(R) MEI)
Table of Contents
.. toctree::
- :maxdepth: 2
+ :maxdepth: 3
mei
mei-client-bus
diff --git a/Documentation/driver-api/mei/mei-client-bus.rst b/Documentation/driver-api/mei/mei-client-bus.rst
index 7310dd45c484..bfe28ebc3ca8 100644
--- a/Documentation/driver-api/mei/mei-client-bus.rst
+++ b/Documentation/driver-api/mei/mei-client-bus.rst
@@ -158,3 +158,10 @@ process received data.
}
+MEI Client Bus Drivers
+======================
+
+.. toctree::
+ :maxdepth: 2
+
+ nfc
diff --git a/Documentation/driver-api/mei/nfc.rst b/Documentation/driver-api/mei/nfc.rst
new file mode 100644
index 000000000000..b5b6fc96f85e
--- /dev/null
+++ b/Documentation/driver-api/mei/nfc.rst
@@ -0,0 +1,28 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+MEI NFC
+-------
+
+Some Intel 8 and 9 Serieses chipsets supports NFC devices connected behind
+the Intel Management Engine controller.
+MEI client bus exposes the NFC chips as NFC phy devices and enables
+binding with Microread and NXP PN544 NFC device driver from the Linux NFC
+subsystem.
+
+.. kernel-render:: DOT
+ :alt: MEI NFC digraph
+ :caption: **MEI NFC** Stack
+
+ digraph NFC {
+ cl_nfc -> me_cl_nfc;
+ "drivers/nfc/mei_phy" -> cl_nfc [lhead=bus];
+ "drivers/nfc/microread/mei" -> cl_nfc;
+ "drivers/nfc/microread/mei" -> "drivers/nfc/mei_phy";
+ "drivers/nfc/pn544/mei" -> cl_nfc;
+ "drivers/nfc/pn544/mei" -> "drivers/nfc/mei_phy";
+ "net/nfc" -> "drivers/nfc/microread/mei";
+ "net/nfc" -> "drivers/nfc/pn544/mei";
+ "neard" -> "net/nfc";
+ cl_nfc [label="mei/bus(nfc)"];
+ me_cl_nfc [label="me fw (nfc)"];
+ }
--
2.20.1
^ permalink raw reply related
* [char-misc-next 4/7] mei: docs: update mei client bus documentation.
From: Tomas Winkler @ 2019-06-03 9:14 UTC (permalink / raw)
To: Greg Kroah-Hartman
Cc: Alexander Usyskin, linux-kernel, Tomas Winkler, Jonathan Corbet,
linux-doc
In-Reply-To: <20190603091406.28915-1-tomas.winkler@intel.com>
The mei client bus API has changed significantly from
time it was documented, and had required update.
Signed-off-by: Tomas Winkler <tomas.winkler@intel.com>
---
.../driver-api/mei/mei-client-bus.rst | 162 +++++++++---------
1 file changed, 85 insertions(+), 77 deletions(-)
diff --git a/Documentation/driver-api/mei/mei-client-bus.rst b/Documentation/driver-api/mei/mei-client-bus.rst
index a26a85453bdf..7310dd45c484 100644
--- a/Documentation/driver-api/mei/mei-client-bus.rst
+++ b/Documentation/driver-api/mei/mei-client-bus.rst
@@ -8,13 +8,13 @@ Intel(R) Management Engine (ME) Client bus API
Rationale
=========
-MEI misc character device is useful for dedicated applications to send and receive
+The MEI character device is useful for dedicated applications to send and receive
data to the many FW appliance found in Intel's ME from the user space.
-However for some of the ME functionalities it make sense to leverage existing software
+However, for some of the ME functionalities it makes sense to leverage existing software
stack and expose them through existing kernel subsystems.
In order to plug seamlessly into the kernel device driver model we add kernel virtual
-bus abstraction on top of the MEI driver. This allows implementing linux kernel drivers
+bus abstraction on top of the MEI driver. This allows implementing Linux kernel drivers
for the various MEI features as a stand alone entities found in their respective subsystem.
Existing device drivers can even potentially be re-used by adding an MEI CL bus layer to
the existing code.
@@ -23,9 +23,9 @@ the existing code.
MEI CL bus API
==============
-A driver implementation for an MEI Client is very similar to existing bus
+A driver implementation for an MEI Client is very similar to any other existing bus
based device drivers. The driver registers itself as an MEI CL bus driver through
-the ``struct mei_cl_driver`` structure:
+the ``struct mei_cl_driver`` structure defined in :file:`include/linux/mei_cl_bus.c`
.. code-block:: C
@@ -39,25 +39,38 @@ the ``struct mei_cl_driver`` structure:
int (*remove)(struct mei_cl_device *dev);
};
- struct mei_cl_id {
- char name[MEI_NAME_SIZE];
+
+
+The mei_cl_device_id structure defined in :file:`include/linux/mod_devicetable.h` allows a
+driver to bind itself against a device name.
+
+.. code-block:: C
+
+ struct mei_cl_device_id {
+ char name[MEI_CL_NAME_SIZE];
+ uuid_le uuid;
+ __u8 version;
kernel_ulong_t driver_info;
};
-The mei_cl_id structure allows the driver to bind itself against a device name.
+To actually register a driver on the ME Client bus one must call the :c:func:`mei_cl_add_driver`
+API. This is typically called at module initialization time.
+
+Once the driver is registered and bound to the device, a driver will typically
+try to do some I/O on this bus and this should be done through the :c:func:`mei_cl_send`
+and :c:func:`mei_cl_recv` functions. More detailed information is in :ref:`api` section.
+
+In order for a driver to be notified about pending traffic or event, the driver
+should register a callback via :c:func:`mei_cl_devev_register_rx_cb` and
+:c:func:`mei_cldev_register_notify_cb` function respectively.
-To actually register a driver on the ME Client bus one must call the mei_cl_add_driver()
-API. This is typically called at module init time.
+.. _api:
+
+API:
+----
+.. kernel-doc:: drivers/misc/mei/bus.c
+ :export: drivers/misc/mei/bus.c
-Once registered on the ME Client bus, a driver will typically try to do some I/O on
-this bus and this should be done through the mei_cl_send() and mei_cl_recv()
-routines. The latter is synchronous (blocks and sleeps until data shows up).
-In order for drivers to be notified of pending events waiting for them (e.g.
-an Rx event) they can register an event handler through the
-mei_cl_register_event_cb() routine. Currently only the MEI_EVENT_RX event
-will trigger an event handler call and the driver implementation is supposed
-to call mei_recv() from the event handler in order to fetch the pending
-received buffers.
Example
@@ -68,85 +81,80 @@ The driver init and exit routines for this device would look like:
.. code-block:: C
- #define CONTACT_DRIVER_NAME "contact"
+ #define CONTACT_DRIVER_NAME "contact"
- static struct mei_cl_device_id contact_mei_cl_tbl[] = {
- { CONTACT_DRIVER_NAME, },
+ static struct mei_cl_device_id contact_mei_cl_tbl[] = {
+ { CONTACT_DRIVER_NAME, },
- /* required last entry */
- { }
- };
- MODULE_DEVICE_TABLE(mei_cl, contact_mei_cl_tbl);
+ /* required last entry */
+ { }
+ };
+ MODULE_DEVICE_TABLE(mei_cl, contact_mei_cl_tbl);
- static struct mei_cl_driver contact_driver = {
- .id_table = contact_mei_tbl,
- .name = CONTACT_DRIVER_NAME,
+ static struct mei_cl_driver contact_driver = {
+ .id_table = contact_mei_tbl,
+ .name = CONTACT_DRIVER_NAME,
- .probe = contact_probe,
- .remove = contact_remove,
- };
+ .probe = contact_probe,
+ .remove = contact_remove,
+ };
- static int contact_init(void)
- {
- int r;
+ static int contact_init(void)
+ {
+ int r;
- r = mei_cl_driver_register(&contact_driver);
- if (r) {
- pr_err(CONTACT_DRIVER_NAME ": driver registration failed\n");
- return r;
- }
+ r = mei_cl_driver_register(&contact_driver);
+ if (r) {
+ pr_err(CONTACT_DRIVER_NAME ": driver registration failed\n");
+ return r;
+ }
- return 0;
- }
+ return 0;
+ }
- static void __exit contact_exit(void)
- {
- mei_cl_driver_unregister(&contact_driver);
- }
+ static void __exit contact_exit(void)
+ {
+ mei_cl_driver_unregister(&contact_driver);
+ }
- module_init(contact_init);
- module_exit(contact_exit);
+ module_init(contact_init);
+ module_exit(contact_exit);
And the driver's simplified probe routine would look like that:
.. code-block:: C
- int contact_probe(struct mei_cl_device *dev, struct mei_cl_device_id *id)
- {
- struct contact_driver *contact;
+ int contact_probe(struct mei_cl_device *dev, struct mei_cl_device_id *id)
+ {
+ [...]
+ mei_cldev_enable(dev);
- [...]
- mei_cl_enable_device(dev);
+ mei_cldev_register_rx_cb(dev, contact_rx_cb);
- mei_cl_register_event_cb(dev, contact_event_cb, contact);
-
- return 0;
- }
+ return 0;
+ }
In the probe routine the driver first enable the MEI device and then registers
-an ME bus event handler which is as close as it can get to registering a
-threaded IRQ handler.
-The handler implementation will typically call some I/O routine depending on
-the pending events:
-
-#define MAX_NFC_PAYLOAD 128
+an rx handler which is as close as it can get to registering a threaded IRQ handler.
+The handler implementation will typically call :c:func:`mei_cldev_recv` and then
+process received data.
.. code-block:: C
- static void contact_event_cb(struct mei_cl_device *dev, u32 events,
- void *context)
- {
- struct contact_driver *contact = context;
+ #define MAX_PAYLOAD 128
+ #define HDR_SIZE 4
+ static void conntact_rx_cb(struct mei_cl_device *cldev)
+ {
+ struct contact *c = mei_cldev_get_drvdata(cldev);
+ unsigned char payload[MAX_PAYLOAD];
+ ssize_t payload_sz;
+
+ payload_sz = mei_cldev_recv(cldev, payload, MAX_PAYLOAD)
+ if (reply_size < HDR_SIZE) {
+ return;
+ }
- if (events & BIT(MEI_EVENT_RX)) {
- u8 payload[MAX_NFC_PAYLOAD];
- int payload_size;
+ c->process_rx(payload);
- payload_size = mei_recv(dev, payload, MAX_NFC_PAYLOAD);
- if (payload_size <= 0)
- return;
+ }
- /* Hook to the NFC subsystem */
- nfc_hci_recv_frame(contact->hdev, payload, payload_size);
- }
- }
--
2.20.1
^ permalink raw reply related
* [char-misc-next 3/7] mei: docs: update mei documentation
From: Tomas Winkler @ 2019-06-03 9:14 UTC (permalink / raw)
To: Greg Kroah-Hartman
Cc: Alexander Usyskin, linux-kernel, Tomas Winkler, Jonathan Corbet,
linux-doc
In-Reply-To: <20190603091406.28915-1-tomas.winkler@intel.com>
The mei driver went via multiple changes, update
the documentation and fix formatting.
Signed-off-by: Tomas Winkler <tomas.winkler@intel.com>
---
Documentation/driver-api/mei/mei.rst | 96 ++++++++++++++++++----------
1 file changed, 61 insertions(+), 35 deletions(-)
diff --git a/Documentation/driver-api/mei/mei.rst b/Documentation/driver-api/mei/mei.rst
index c7f10a4b46ff..c800d8e5f422 100644
--- a/Documentation/driver-api/mei/mei.rst
+++ b/Documentation/driver-api/mei/mei.rst
@@ -5,34 +5,32 @@ Introduction
The Intel Management Engine (Intel ME) is an isolated and protected computing
resource (Co-processor) residing inside certain Intel chipsets. The Intel ME
-provides support for computer/IT management features. The feature set
-depends on the Intel chipset SKU.
+provides support for computer/IT management and security features.
+The actual feature set depends on the Intel chipset SKU.
The Intel Management Engine Interface (Intel MEI, previously known as HECI)
is the interface between the Host and Intel ME. This interface is exposed
-to the host as a PCI device. The Intel MEI Driver is in charge of the
-communication channel between a host application and the Intel ME feature.
+to the host as a PCI device, actually multiple PCI devices might be exposed.
+The Intel MEI Driver is in charge of the communication channel between
+a host application and the Intel ME features.
-Each Intel ME feature (Intel ME Client) is addressed by a GUID/UUID and
+Each Intel ME feature, or Intel ME Client is addressed by a unique GUID and
each client has its own protocol. The protocol is message-based with a
-header and payload up to 512 bytes.
+header and payload up to maximal number of bytes advertised by the client,
+upon connection.
Intel MEI Driver
================
-The driver exposes a misc device called /dev/mei.
+The driver exposes a character device with device nodes /dev/meiX.
An application maintains communication with an Intel ME feature while
-/dev/mei is open. The binding to a specific feature is performed by calling
-MEI_CONNECT_CLIENT_IOCTL, which passes the desired UUID.
+/dev/meiX is open. The binding to a specific feature is performed by calling
+:c:macro:`MEI_CONNECT_CLIENT_IOCTL`, which passes the desired GUID.
The number of instances of an Intel ME feature that can be opened
at the same time depends on the Intel ME feature, but most of the
features allow only a single instance.
-The Intel AMT Host Interface (Intel AMTHI) feature supports multiple
-simultaneous user connected applications. The Intel MEI driver
-handles this internally by maintaining request queues for the applications.
-
The driver is transparent to data that are passed between firmware feature
and host application.
@@ -40,6 +38,8 @@ Because some of the Intel ME features can change the system
configuration, the driver by default allows only a privileged
user to access it.
+The session is terminated calling :c:func:`close(int fd)`.
+
A code snippet for an application communicating with Intel AMTHI client:
.. code-block:: C
@@ -47,13 +47,13 @@ A code snippet for an application communicating with Intel AMTHI client:
struct mei_connect_client_data data;
fd = open(MEI_DEVICE);
- data.d.in_client_uuid = AMTHI_UUID;
+ data.d.in_client_uuid = AMTHI_GUID;
ioctl(fd, IOCTL_MEI_CONNECT_CLIENT, &data);
printf("Ver=%d, MaxLen=%ld\n",
- data.d.in_client_uuid.protocol_version,
- data.d.in_client_uuid.max_msg_length);
+ data.d.in_client_uuid.protocol_version,
+ data.d.in_client_uuid.max_msg_length);
[...]
@@ -67,60 +67,86 @@ A code snippet for an application communicating with Intel AMTHI client:
close(fd);
-IOCTLs
-======
+User space API
+
+IOCTLs:
+=======
The Intel MEI Driver supports the following IOCTL commands:
- IOCTL_MEI_CONNECT_CLIENT Connect to firmware Feature (client).
- usage:
- struct mei_connect_client_data clientData;
- ioctl(fd, IOCTL_MEI_CONNECT_CLIENT, &clientData);
+IOCTL_MEI_CONNECT_CLIENT
+-------------------------
+Connect to firmware Feature/Client.
+
+.. code-block:: none
+
+ Usage:
- inputs:
- mei_connect_client_data struct contain the following
- input field:
+ struct mei_connect_client_data client_data;
- in_client_uuid - UUID of the FW Feature that needs
+ ioctl(fd, IOCTL_MEI_CONNECT_CLIENT, &client_data);
+
+ Inputs:
+
+ struct mei_connect_client_data - contain the following
+ Input field:
+
+ in_client_uuid - GUID of the FW Feature that needs
to connect to.
- outputs:
+ Outputs:
out_client_properties - Client Properties: MTU and Protocol Version.
- error returns:
+ Error returns:
+
+ ENOTTY No such client (i.e. wrong GUID) or connection is not allowed.
EINVAL Wrong IOCTL Number
- ENODEV Device or Connection is not initialized or ready. (e.g. Wrong UUID)
+ ENODEV Device or Connection is not initialized or ready.
ENOMEM Unable to allocate memory to client internal data.
EFAULT Fatal Error (e.g. Unable to access user input data)
EBUSY Connection Already Open
+:Note:
max_msg_length (MTU) in client properties describes the maximum
data that can be sent or received. (e.g. if MTU=2K, can send
requests up to bytes 2k and received responses up to 2k bytes).
- IOCTL_MEI_NOTIFY_SET: enable or disable event notifications
+
+IOCTL_MEI_NOTIFY_SET
+---------------------
+Enable or disable event notifications.
+
+
+.. code-block:: none
Usage:
+
uint32_t enable;
+
ioctl(fd, IOCTL_MEI_NOTIFY_SET, &enable);
- Inputs:
+
uint32_t enable = 1;
or
uint32_t enable[disable] = 0;
Error returns:
+
+
EINVAL Wrong IOCTL Number
ENODEV Device is not initialized or the client not connected
ENOMEM Unable to allocate memory to client internal data.
EFAULT Fatal Error (e.g. Unable to access user input data)
EOPNOTSUPP if the device doesn't support the feature
+:Note:
The client must be connected in order to enable notification events
- IOCTL_MEI_NOTIFY_GET : retrieve event
+IOCTL_MEI_NOTIFY_GET
+--------------------
+Retrieve event
+
+.. code-block:: none
Usage:
uint32_t event;
@@ -137,7 +163,7 @@ The Intel MEI Driver supports the following IOCTL commands:
EFAULT Fatal Error (e.g. Unable to access user input data)
EOPNOTSUPP if the device doesn't support the feature
+:Note:
The client must be connected and event notification has to be enabled
in order to receive an event
--
2.20.1
^ permalink raw reply related
* [char-misc-next 2/7] mei: docs: move iamt docs to a iamt.rst file
From: Tomas Winkler @ 2019-06-03 9:14 UTC (permalink / raw)
To: Greg Kroah-Hartman
Cc: Alexander Usyskin, linux-kernel, Tomas Winkler, Jonathan Corbet,
linux-doc
In-Reply-To: <20190603091406.28915-1-tomas.winkler@intel.com>
Move intel amt documentation to a seprate file.
Signed-off-by: Tomas Winkler <tomas.winkler@intel.com>
---
Documentation/driver-api/mei/iamt.rst | 106 +++++++++++++++++++++++++
Documentation/driver-api/mei/index.rst | 1 +
Documentation/driver-api/mei/mei.rst | 100 -----------------------
3 files changed, 107 insertions(+), 100 deletions(-)
create mode 100644 Documentation/driver-api/mei/iamt.rst
diff --git a/Documentation/driver-api/mei/iamt.rst b/Documentation/driver-api/mei/iamt.rst
new file mode 100644
index 000000000000..6dcf5b16e958
--- /dev/null
+++ b/Documentation/driver-api/mei/iamt.rst
@@ -0,0 +1,106 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+Intel(R) Active Management Technology (Intel AMT)
+=================================================
+
+Prominent usage of the Intel ME Interface is to communicate with Intel(R)
+Active Management Technology (Intel AMT) implemented in firmware running on
+the Intel ME.
+
+Intel AMT provides the ability to manage a host remotely out-of-band (OOB)
+even when the operating system running on the host processor has crashed or
+is in a sleep state.
+
+Some examples of Intel AMT usage are:
+ - Monitoring hardware state and platform components
+ - Remote power off/on (useful for green computing or overnight IT
+ maintenance)
+ - OS updates
+ - Storage of useful platform information such as software assets
+ - Built-in hardware KVM
+ - Selective network isolation of Ethernet and IP protocol flows based
+ on policies set by a remote management console
+ - IDE device redirection from remote management console
+
+Intel AMT (OOB) communication is based on SOAP (deprecated
+starting with Release 6.0) over HTTP/S or WS-Management protocol over
+HTTP/S that are received from a remote management console application.
+
+For more information about Intel AMT:
+http://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide
+
+
+Intel AMT Applications
+======================
+
+ 1) Intel Local Management Service (Intel LMS)
+
+ Applications running locally on the platform communicate with Intel AMT Release
+ 2.0 and later releases in the same way that network applications do via SOAP
+ over HTTP (deprecated starting with Release 6.0) or with WS-Management over
+ SOAP over HTTP. This means that some Intel AMT features can be accessed from a
+ local application using the same network interface as a remote application
+ communicating with Intel AMT over the network.
+
+ When a local application sends a message addressed to the local Intel AMT host
+ name, the Intel LMS, which listens for traffic directed to the host name,
+ intercepts the message and routes it to the Intel MEI.
+ For more information:
+ http://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide
+ Under "About Intel AMT" => "Local Access"
+
+ For downloading Intel LMS:
+ http://software.intel.com/en-us/articles/download-the-latest-intel-amt-open-source-drivers/
+
+ The Intel LMS opens a connection using the Intel MEI driver to the Intel LMS
+ firmware feature using a defined UUID and then communicates with the feature
+ using a protocol called Intel AMT Port Forwarding Protocol (Intel APF protocol).
+ The protocol is used to maintain multiple sessions with Intel AMT from a
+ single application.
+
+ See the protocol specification in the Intel AMT Software Development Kit (SDK)
+ http://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide
+ Under "SDK Resources" => "Intel(R) vPro(TM) Gateway (MPS)"
+ => "Information for Intel(R) vPro(TM) Gateway Developers"
+ => "Description of the Intel AMT Port Forwarding (APF) Protocol"
+
+ 2) Intel AMT Remote configuration using a Local Agent
+
+ A Local Agent enables IT personnel to configure Intel AMT out-of-the-box
+ without requiring installing additional data to enable setup. The remote
+ configuration process may involve an ISV-developed remote configuration
+ agent that runs on the host.
+ For more information:
+ http://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide
+ Under "Setup and Configuration of Intel AMT" =>
+ "SDK Tools Supporting Setup and Configuration" =>
+ "Using the Local Agent Sample"
+
+ An open source Intel AMT configuration utility, implementing a local agent
+ that accesses the Intel MEI driver, can be found here:
+ http://software.intel.com/en-us/articles/download-the-latest-intel-amt-open-source-drivers/
+
+
+Intel AMT OS Health Watchdog
+============================
+
+The Intel AMT Watchdog is an OS Health (Hang/Crash) watchdog.
+Whenever the OS hangs or crashes, Intel AMT will send an event
+to any subscriber to this event. This mechanism means that
+IT knows when a platform crashes even when there is a hard failure on the host.
+
+The Intel AMT Watchdog is composed of two parts:
+ 1) Firmware feature - receives the heartbeats
+ and sends an event when the heartbeats stop.
+ 2) Intel MEI iAMT watchdog driver - connects to the watchdog feature,
+ configures the watchdog and sends the heartbeats.
+
+The Intel iAMT watchdog MEI driver uses the kernel watchdog API to configure
+the Intel AMT Watchdog and to send heartbeats to it. The default timeout of the
+watchdog is 120 seconds.
+
+If the Intel AMT is not enabled in the firmware then the watchdog client won't enumerate
+on the me client bus and watchdog devices won't be exposed.
+
+---
+linux-mei@linux.intel.com
diff --git a/Documentation/driver-api/mei/index.rst b/Documentation/driver-api/mei/index.rst
index 35c1117d8366..d261afac6852 100644
--- a/Documentation/driver-api/mei/index.rst
+++ b/Documentation/driver-api/mei/index.rst
@@ -20,3 +20,4 @@ Intel(R) Management Engine Interface (Intel(R) MEI)
mei
mei-client-bus
+ iamt
diff --git a/Documentation/driver-api/mei/mei.rst b/Documentation/driver-api/mei/mei.rst
index 5aa3a5e6496a..c7f10a4b46ff 100644
--- a/Documentation/driver-api/mei/mei.rst
+++ b/Documentation/driver-api/mei/mei.rst
@@ -17,33 +17,6 @@ Each Intel ME feature (Intel ME Client) is addressed by a GUID/UUID and
each client has its own protocol. The protocol is message-based with a
header and payload up to 512 bytes.
-Prominent usage of the Intel ME Interface is to communicate with Intel(R)
-Active Management Technology (Intel AMT) implemented in firmware running on
-the Intel ME.
-
-Intel AMT provides the ability to manage a host remotely out-of-band (OOB)
-even when the operating system running on the host processor has crashed or
-is in a sleep state.
-
-Some examples of Intel AMT usage are:
- - Monitoring hardware state and platform components
- - Remote power off/on (useful for green computing or overnight IT
- maintenance)
- - OS updates
- - Storage of useful platform information such as software assets
- - Built-in hardware KVM
- - Selective network isolation of Ethernet and IP protocol flows based
- on policies set by a remote management console
- - IDE device redirection from remote management console
-
-Intel AMT (OOB) communication is based on SOAP (deprecated
-starting with Release 6.0) over HTTP/S or WS-Management protocol over
-HTTP/S that are received from a remote management console application.
-
-For more information about Intel AMT:
-http://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide
-
-
Intel MEI Driver
================
@@ -169,82 +142,9 @@ The Intel MEI Driver supports the following IOCTL commands:
in order to receive an event
-Intel ME Applications
-=====================
-
- 1) Intel Local Management Service (Intel LMS)
-
- Applications running locally on the platform communicate with Intel AMT Release
- 2.0 and later releases in the same way that network applications do via SOAP
- over HTTP (deprecated starting with Release 6.0) or with WS-Management over
- SOAP over HTTP. This means that some Intel AMT features can be accessed from a
- local application using the same network interface as a remote application
- communicating with Intel AMT over the network.
-
- When a local application sends a message addressed to the local Intel AMT host
- name, the Intel LMS, which listens for traffic directed to the host name,
- intercepts the message and routes it to the Intel MEI.
- For more information:
- http://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide
- Under "About Intel AMT" => "Local Access"
-
- For downloading Intel LMS:
- http://software.intel.com/en-us/articles/download-the-latest-intel-amt-open-source-drivers/
-
- The Intel LMS opens a connection using the Intel MEI driver to the Intel LMS
- firmware feature using a defined UUID and then communicates with the feature
- using a protocol called Intel AMT Port Forwarding Protocol (Intel APF protocol).
- The protocol is used to maintain multiple sessions with Intel AMT from a
- single application.
-
- See the protocol specification in the Intel AMT Software Development Kit (SDK)
- http://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide
- Under "SDK Resources" => "Intel(R) vPro(TM) Gateway (MPS)"
- => "Information for Intel(R) vPro(TM) Gateway Developers"
- => "Description of the Intel AMT Port Forwarding (APF) Protocol"
-
- 2) Intel AMT Remote configuration using a Local Agent
-
- A Local Agent enables IT personnel to configure Intel AMT out-of-the-box
- without requiring installing additional data to enable setup. The remote
- configuration process may involve an ISV-developed remote configuration
- agent that runs on the host.
- For more information:
- http://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide
- Under "Setup and Configuration of Intel AMT" =>
- "SDK Tools Supporting Setup and Configuration" =>
- "Using the Local Agent Sample"
-
- An open source Intel AMT configuration utility, implementing a local agent
- that accesses the Intel MEI driver, can be found here:
- http://software.intel.com/en-us/articles/download-the-latest-intel-amt-open-source-drivers/
-
-
-Intel AMT OS Health Watchdog
-============================
-
-The Intel AMT Watchdog is an OS Health (Hang/Crash) watchdog.
-Whenever the OS hangs or crashes, Intel AMT will send an event
-to any subscriber to this event. This mechanism means that
-IT knows when a platform crashes even when there is a hard failure on the host.
-
-The Intel AMT Watchdog is composed of two parts:
- 1) Firmware feature - receives the heartbeats
- and sends an event when the heartbeats stop.
- 2) Intel MEI iAMT watchdog driver - connects to the watchdog feature,
- configures the watchdog and sends the heartbeats.
-
-The Intel iAMT watchdog MEI driver uses the kernel watchdog API to configure
-the Intel AMT Watchdog and to send heartbeats to it. The default timeout of the
-watchdog is 120 seconds.
-
-If the Intel AMT is not enabled in the firmware then the watchdog client won't enumerate
-on the me client bus and watchdog devices won't be exposed.
Supported Chipsets
==================
82X38/X48 Express and newer
-
----
linux-mei@linux.intel.com
--
2.20.1
^ permalink raw reply related
* [char-misc-next 1/7] mei: docs: move documentation under driver-api
From: Tomas Winkler @ 2019-06-03 9:14 UTC (permalink / raw)
To: Greg Kroah-Hartman
Cc: Alexander Usyskin, linux-kernel, Tomas Winkler, Jonathan Corbet,
linux-doc
In-Reply-To: <20190603091406.28915-1-tomas.winkler@intel.com>
Move mei driver documentation under Documentation/driver-api/
Perform some minimal formating changes to produce correct sphinx rendering
and add index.rst
Signed-off-by: Tomas Winkler <tomas.winkler@intel.com>
---
Documentation/driver-api/index.rst | 1 +
Documentation/driver-api/mei/index.rst | 22 +++
.../mei/mei-client-bus.rst} | 135 ++++++++++--------
.../mei/mei.txt => driver-api/mei/mei.rst} | 30 +---
MAINTAINERS | 2 +-
5 files changed, 104 insertions(+), 86 deletions(-)
create mode 100644 Documentation/driver-api/mei/index.rst
rename Documentation/{misc-devices/mei/mei-client-bus.txt => driver-api/mei/mei-client-bus.rst} (54%)
rename Documentation/{misc-devices/mei/mei.txt => driver-api/mei/mei.rst} (94%)
diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst
index d26308af6036..0dbaa987aa11 100644
--- a/Documentation/driver-api/index.rst
+++ b/Documentation/driver-api/index.rst
@@ -42,6 +42,7 @@ available subsections can be seen below.
target
mtdnand
miscellaneous
+ mei/index
w1
rapidio
s390-drivers
diff --git a/Documentation/driver-api/mei/index.rst b/Documentation/driver-api/mei/index.rst
new file mode 100644
index 000000000000..35c1117d8366
--- /dev/null
+++ b/Documentation/driver-api/mei/index.rst
@@ -0,0 +1,22 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. include:: <isonum.txt>
+
+===================================================
+Intel(R) Management Engine Interface (Intel(R) MEI)
+===================================================
+
+**Copyright** |copy| 2019 Intel Corporation
+
+
+.. only:: html
+
+ .. class:: toc-title
+
+ Table of Contents
+
+.. toctree::
+ :maxdepth: 2
+
+ mei
+ mei-client-bus
diff --git a/Documentation/misc-devices/mei/mei-client-bus.txt b/Documentation/driver-api/mei/mei-client-bus.rst
similarity index 54%
rename from Documentation/misc-devices/mei/mei-client-bus.txt
rename to Documentation/driver-api/mei/mei-client-bus.rst
index 743be4ec8989..a26a85453bdf 100644
--- a/Documentation/misc-devices/mei/mei-client-bus.txt
+++ b/Documentation/driver-api/mei/mei-client-bus.rst
@@ -1,3 +1,6 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+==============================================
Intel(R) Management Engine (ME) Client bus API
==============================================
@@ -22,22 +25,24 @@ MEI CL bus API
A driver implementation for an MEI Client is very similar to existing bus
based device drivers. The driver registers itself as an MEI CL bus driver through
-the mei_cl_driver structure:
+the ``struct mei_cl_driver`` structure:
+
+.. code-block:: C
-struct mei_cl_driver {
- struct device_driver driver;
- const char *name;
+ struct mei_cl_driver {
+ struct device_driver driver;
+ const char *name;
- const struct mei_cl_device_id *id_table;
+ const struct mei_cl_device_id *id_table;
- int (*probe)(struct mei_cl_device *dev, const struct mei_cl_id *id);
- int (*remove)(struct mei_cl_device *dev);
-};
+ int (*probe)(struct mei_cl_device *dev, const struct mei_cl_id *id);
+ int (*remove)(struct mei_cl_device *dev);
+ };
-struct mei_cl_id {
- char name[MEI_NAME_SIZE];
- kernel_ulong_t driver_info;
-};
+ struct mei_cl_id {
+ char name[MEI_NAME_SIZE];
+ kernel_ulong_t driver_info;
+ };
The mei_cl_id structure allows the driver to bind itself against a device name.
@@ -61,58 +66,62 @@ Example
As a theoretical example let's pretend the ME comes with a "contact" NFC IP.
The driver init and exit routines for this device would look like:
-#define CONTACT_DRIVER_NAME "contact"
+.. code-block:: C
-static struct mei_cl_device_id contact_mei_cl_tbl[] = {
- { CONTACT_DRIVER_NAME, },
+ #define CONTACT_DRIVER_NAME "contact"
- /* required last entry */
- { }
-};
-MODULE_DEVICE_TABLE(mei_cl, contact_mei_cl_tbl);
+ static struct mei_cl_device_id contact_mei_cl_tbl[] = {
+ { CONTACT_DRIVER_NAME, },
-static struct mei_cl_driver contact_driver = {
- .id_table = contact_mei_tbl,
- .name = CONTACT_DRIVER_NAME,
+ /* required last entry */
+ { }
+ };
+ MODULE_DEVICE_TABLE(mei_cl, contact_mei_cl_tbl);
- .probe = contact_probe,
- .remove = contact_remove,
-};
+ static struct mei_cl_driver contact_driver = {
+ .id_table = contact_mei_tbl,
+ .name = CONTACT_DRIVER_NAME,
-static int contact_init(void)
-{
- int r;
+ .probe = contact_probe,
+ .remove = contact_remove,
+ };
- r = mei_cl_driver_register(&contact_driver);
- if (r) {
- pr_err(CONTACT_DRIVER_NAME ": driver registration failed\n");
- return r;
- }
+ static int contact_init(void)
+ {
+ int r;
+
+ r = mei_cl_driver_register(&contact_driver);
+ if (r) {
+ pr_err(CONTACT_DRIVER_NAME ": driver registration failed\n");
+ return r;
+ }
- return 0;
-}
+ return 0;
+ }
-static void __exit contact_exit(void)
-{
- mei_cl_driver_unregister(&contact_driver);
-}
+ static void __exit contact_exit(void)
+ {
+ mei_cl_driver_unregister(&contact_driver);
+ }
-module_init(contact_init);
-module_exit(contact_exit);
+ module_init(contact_init);
+ module_exit(contact_exit);
And the driver's simplified probe routine would look like that:
-int contact_probe(struct mei_cl_device *dev, struct mei_cl_device_id *id)
-{
- struct contact_driver *contact;
+.. code-block:: C
- [...]
- mei_cl_enable_device(dev);
+ int contact_probe(struct mei_cl_device *dev, struct mei_cl_device_id *id)
+ {
+ struct contact_driver *contact;
- mei_cl_register_event_cb(dev, contact_event_cb, contact);
+ [...]
+ mei_cl_enable_device(dev);
- return 0;
-}
+ mei_cl_register_event_cb(dev, contact_event_cb, contact);
+
+ return 0;
+ }
In the probe routine the driver first enable the MEI device and then registers
an ME bus event handler which is as close as it can get to registering a
@@ -122,20 +131,22 @@ the pending events:
#define MAX_NFC_PAYLOAD 128
-static void contact_event_cb(struct mei_cl_device *dev, u32 events,
- void *context)
-{
- struct contact_driver *contact = context;
+.. code-block:: C
+
+ static void contact_event_cb(struct mei_cl_device *dev, u32 events,
+ void *context)
+ {
+ struct contact_driver *contact = context;
- if (events & BIT(MEI_EVENT_RX)) {
- u8 payload[MAX_NFC_PAYLOAD];
- int payload_size;
+ if (events & BIT(MEI_EVENT_RX)) {
+ u8 payload[MAX_NFC_PAYLOAD];
+ int payload_size;
- payload_size = mei_recv(dev, payload, MAX_NFC_PAYLOAD);
- if (payload_size <= 0)
- return;
+ payload_size = mei_recv(dev, payload, MAX_NFC_PAYLOAD);
+ if (payload_size <= 0)
+ return;
- /* Hook to the NFC subsystem */
- nfc_hci_recv_frame(contact->hdev, payload, payload_size);
+ /* Hook to the NFC subsystem */
+ nfc_hci_recv_frame(contact->hdev, payload, payload_size);
+ }
}
-}
diff --git a/Documentation/misc-devices/mei/mei.txt b/Documentation/driver-api/mei/mei.rst
similarity index 94%
rename from Documentation/misc-devices/mei/mei.txt
rename to Documentation/driver-api/mei/mei.rst
index 2b80a0cd621f..5aa3a5e6496a 100644
--- a/Documentation/misc-devices/mei/mei.txt
+++ b/Documentation/driver-api/mei/mei.rst
@@ -1,5 +1,4 @@
-Intel(R) Management Engine Interface (Intel(R) MEI)
-===================================================
+.. SPDX-License-Identifier: GPL-2.0
Introduction
============
@@ -70,6 +69,8 @@ user to access it.
A code snippet for an application communicating with Intel AMTHI client:
+.. code-block:: C
+
struct mei_connect_client_data data;
fd = open(MEI_DEVICE);
@@ -93,8 +94,8 @@ A code snippet for an application communicating with Intel AMTHI client:
close(fd);
-IOCTL
-=====
+IOCTLs
+======
The Intel MEI Driver supports the following IOCTL commands:
IOCTL_MEI_CONNECT_CLIENT Connect to firmware Feature (client).
@@ -114,8 +115,7 @@ The Intel MEI Driver supports the following IOCTL commands:
error returns:
EINVAL Wrong IOCTL Number
- ENODEV Device or Connection is not initialized or ready.
- (e.g. Wrong UUID)
+ ENODEV Device or Connection is not initialized or ready. (e.g. Wrong UUID)
ENOMEM Unable to allocate memory to client internal data.
EFAULT Fatal Error (e.g. Unable to access user input data)
EBUSY Connection Already Open
@@ -241,26 +241,10 @@ watchdog is 120 seconds.
If the Intel AMT is not enabled in the firmware then the watchdog client won't enumerate
on the me client bus and watchdog devices won't be exposed.
-
Supported Chipsets
==================
+82X38/X48 Express and newer
-7 Series Chipset Family
-6 Series Chipset Family
-5 Series Chipset Family
-4 Series Chipset Family
-Mobile 4 Series Chipset Family
-ICH9
-82946GZ/GL
-82G35 Express
-82Q963/Q965
-82P965/G965
-Mobile PM965/GM965
-Mobile GME965/GLE960
-82Q35 Express
-82G33/G31/P35/P31 Express
-82Q33 Express
-82X38/X48 Express
---
linux-mei@linux.intel.com
diff --git a/MAINTAINERS b/MAINTAINERS
index 5cfbea4ce575..bfe48cbea84c 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -8021,7 +8021,7 @@ F: include/uapi/linux/mei.h
F: include/linux/mei_cl_bus.h
F: drivers/misc/mei/*
F: drivers/watchdog/mei_wdt.c
-F: Documentation/misc-devices/mei/*
+F: Documentation/driver-api/mei/*
F: samples/mei/*
INTEL MENLOW THERMAL DRIVER
--
2.20.1
^ permalink raw reply related
* [char-misc-next 0/7] mei: docs: move documentation under driver-api
From: Tomas Winkler @ 2019-06-03 9:13 UTC (permalink / raw)
To: Greg Kroah-Hartman
Cc: Alexander Usyskin, linux-kernel, Tomas Winkler, Jonathan Corbet,
linux-doc
Move mei documentation under driver-api, convert the docs to rst,
fix the outdated information, update broken links, and add new docs.
Tomas Winkler (7):
mei: docs: move documentation under driver-api
mei: docs: move iamt docs to a iamt.rst file
mei: docs: update mei documentation
mei: docs: update mei client bus documentation.
mei: docs: add a short description for nfc behind mei
mei: docs: add hdcp documentation
mei: docs: fix broken links in iamt documentation.
Documentation/driver-api/index.rst | 1 +
Documentation/driver-api/mei/hdcp.rst | 32 +++
Documentation/driver-api/mei/iamt.rst | 101 +++++++
Documentation/driver-api/mei/index.rst | 23 ++
.../driver-api/mei/mei-client-bus.rst | 168 +++++++++++
Documentation/driver-api/mei/mei.rst | 176 ++++++++++++
Documentation/driver-api/mei/nfc.rst | 28 ++
.../misc-devices/mei/mei-client-bus.txt | 141 ----------
Documentation/misc-devices/mei/mei.txt | 266 ------------------
MAINTAINERS | 2 +-
drivers/misc/mei/hdcp/mei_hdcp.c | 11 +-
11 files changed, 534 insertions(+), 415 deletions(-)
create mode 100644 Documentation/driver-api/mei/hdcp.rst
create mode 100644 Documentation/driver-api/mei/iamt.rst
create mode 100644 Documentation/driver-api/mei/index.rst
create mode 100644 Documentation/driver-api/mei/mei-client-bus.rst
create mode 100644 Documentation/driver-api/mei/mei.rst
create mode 100644 Documentation/driver-api/mei/nfc.rst
delete mode 100644 Documentation/misc-devices/mei/mei-client-bus.txt
delete mode 100644 Documentation/misc-devices/mei/mei.txt
--
2.20.1
^ permalink raw reply
* Re: [PATCH 2/3] x86: Move CPU feature test out of uaccess region
From: Marco Elver @ 2019-06-03 9:03 UTC (permalink / raw)
To: H. Peter Anvin
Cc: Peter Zijlstra, Andrey Ryabinin, Dmitry Vyukov,
Alexander Potapenko, Andrey Konovalov, Mark Rutland,
Jonathan Corbet, Thomas Gleixner, Ingo Molnar, Borislav Petkov,
the arch/x86 maintainers, Arnd Bergmann, Josh Poimboeuf,
open list:DOCUMENTATION, LKML, linux-arch, kasan-dev
In-Reply-To: <3B49EF08-147F-451C-AA5B-FC4E1B8568EE@zytor.com>
Thanks for the clarification.
I found that static_cpu_has was replaced by static_cpu_has_safe:
https://lkml.org/lkml/2016/1/24/29 -- so is it fair to assume that
both are equally safe at this point?
I have sent a follow-up patch which uses static_cpu_has:
http://lkml.kernel.org/r/20190531150828.157832-3-elver@google.com
Many thanks!
-- Marco
On Sat, 1 Jun 2019 at 03:13, <hpa@zytor.com> wrote:
>
> On May 31, 2019 2:57:36 AM PDT, Marco Elver <elver@google.com> wrote:
> >On Wed, 29 May 2019 at 16:29, <hpa@zytor.com> wrote:
> >>
> >> On May 29, 2019 7:15:00 AM PDT, Marco Elver <elver@google.com> wrote:
> >> >This patch is a pre-requisite for enabling KASAN bitops
> >> >instrumentation:
> >> >moves boot_cpu_has feature test out of the uaccess region, as
> >> >boot_cpu_has uses test_bit. With instrumentation, the KASAN check
> >would
> >> >otherwise be flagged by objtool.
> >> >
> >> >This approach is preferred over adding the explicit kasan_check_*
> >> >functions to the uaccess whitelist of objtool, as the case here
> >appears
> >> >to be the only one.
> >> >
> >> >Signed-off-by: Marco Elver <elver@google.com>
> >> >---
> >> >v1:
> >> >* This patch replaces patch: 'tools/objtool: add kasan_check_* to
> >> > uaccess whitelist'
> >> >---
> >> > arch/x86/ia32/ia32_signal.c | 9 ++++++++-
> >> > 1 file changed, 8 insertions(+), 1 deletion(-)
> >> >
> >> >diff --git a/arch/x86/ia32/ia32_signal.c
> >b/arch/x86/ia32/ia32_signal.c
> >> >index 629d1ee05599..12264e3c9c43 100644
> >> >--- a/arch/x86/ia32/ia32_signal.c
> >> >+++ b/arch/x86/ia32/ia32_signal.c
> >> >@@ -333,6 +333,7 @@ int ia32_setup_rt_frame(int sig, struct ksignal
> >> >*ksig,
> >> > void __user *restorer;
> >> > int err = 0;
> >> > void __user *fpstate = NULL;
> >> >+ bool has_xsave;
> >> >
> >> > /* __copy_to_user optimizes that into a single 8 byte store
> >*/
> >> > static const struct {
> >> >@@ -352,13 +353,19 @@ int ia32_setup_rt_frame(int sig, struct
> >ksignal
> >> >*ksig,
> >> > if (!access_ok(frame, sizeof(*frame)))
> >> > return -EFAULT;
> >> >
> >> >+ /*
> >> >+ * Move non-uaccess accesses out of uaccess region if not
> >strictly
> >> >+ * required; this also helps avoid objtool flagging these
> >accesses
> >> >with
> >> >+ * instrumentation enabled.
> >> >+ */
> >> >+ has_xsave = boot_cpu_has(X86_FEATURE_XSAVE);
> >> > put_user_try {
> >> > put_user_ex(sig, &frame->sig);
> >> > put_user_ex(ptr_to_compat(&frame->info),
> >&frame->pinfo);
> >> > put_user_ex(ptr_to_compat(&frame->uc), &frame->puc);
> >> >
> >> > /* Create the ucontext. */
> >> >- if (boot_cpu_has(X86_FEATURE_XSAVE))
> >> >+ if (has_xsave)
> >> > put_user_ex(UC_FP_XSTATE,
> >&frame->uc.uc_flags);
> >> > else
> >> > put_user_ex(0, &frame->uc.uc_flags);
> >>
> >> This was meant to use static_cpu_has(). Why did that get dropped?
> >
> >I couldn't find any mailing list thread referring to why this doesn't
> >use static_cpu_has, do you have any background?
> >
> >static_cpu_has also solves the UACCESS warning.
> >
> >If you confirm it is safe to change to static_cpu_has(), I will change
> >this patch. Note that I should then also change
> >arch/x86/kernel/signal.c to mirror the change for 32bit (although
> >KASAN is not supported for 32bit x86).
> >
> >Thanks,
> >-- Marco
>
> I believe at some point the intent was that boot_cpu_has() was safer and could be used everywhere.
> --
> Sent from my Android device with K-9 Mail. Please excuse my brevity.
^ permalink raw reply
* Re: [PATCH 09/22] docs: mark orphan documents as such
From: Christophe Leroy @ 2019-06-03 7:32 UTC (permalink / raw)
To: Mauro Carvalho Chehab, Linux Doc Mailing List
Cc: kvm, Radim Krčmář, Maxime Ripard, dri-devel,
platform-driver-x86, Paul Mackerras, linux-stm32,
Alexandre Torgue, Jonathan Corbet, David Airlie, Andrew Donnellan,
linux-pm, Maarten Lankhorst, Matan Ziv-Av, Mauro Carvalho Chehab,
Daniel Vetter, Sean Paul, linux-arm-kernel, linux-kernel,
Maxime Coquelin, Frederic Barrat, Paolo Bonzini, linuxppc-dev,
Georgi Djakov
In-Reply-To: <e0bf4e767dd5de9189e5993fbec2f4b1bafd2064.1559171394.git.mchehab+samsung@kernel.org>
Le 30/05/2019 à 01:23, Mauro Carvalho Chehab a écrit :
> Sphinx doesn't like orphan documents:
>
> Documentation/accelerators/ocxl.rst: WARNING: document isn't included in any toctree
> Documentation/arm/stm32/overview.rst: WARNING: document isn't included in any toctree
> Documentation/arm/stm32/stm32f429-overview.rst: WARNING: document isn't included in any toctree
> Documentation/arm/stm32/stm32f746-overview.rst: WARNING: document isn't included in any toctree
> Documentation/arm/stm32/stm32f769-overview.rst: WARNING: document isn't included in any toctree
> Documentation/arm/stm32/stm32h743-overview.rst: WARNING: document isn't included in any toctree
> Documentation/arm/stm32/stm32mp157-overview.rst: WARNING: document isn't included in any toctree
> Documentation/gpu/msm-crash-dump.rst: WARNING: document isn't included in any toctree
> Documentation/interconnect/interconnect.rst: WARNING: document isn't included in any toctree
> Documentation/laptops/lg-laptop.rst: WARNING: document isn't included in any toctree
> Documentation/powerpc/isa-versions.rst: WARNING: document isn't included in any toctree
> Documentation/virtual/kvm/amd-memory-encryption.rst: WARNING: document isn't included in any toctree
> Documentation/virtual/kvm/vcpu-requests.rst: WARNING: document isn't included in any toctree
>
> So, while they aren't on any toctree, add :orphan: to them, in order
> to silent this warning.
Are those files really not meant to be included in a toctree ?
Shouldn't we include them in the relevant toctree instead of just
shutting up Sphinx warnings ?
Christophe
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> ---
> Documentation/accelerators/ocxl.rst | 2 ++
> Documentation/arm/stm32/overview.rst | 2 ++
> Documentation/arm/stm32/stm32f429-overview.rst | 2 ++
> Documentation/arm/stm32/stm32f746-overview.rst | 2 ++
> Documentation/arm/stm32/stm32f769-overview.rst | 2 ++
> Documentation/arm/stm32/stm32h743-overview.rst | 2 ++
> Documentation/arm/stm32/stm32mp157-overview.rst | 2 ++
> Documentation/gpu/msm-crash-dump.rst | 2 ++
> Documentation/interconnect/interconnect.rst | 2 ++
> Documentation/laptops/lg-laptop.rst | 2 ++
> Documentation/powerpc/isa-versions.rst | 2 ++
> Documentation/virtual/kvm/amd-memory-encryption.rst | 2 ++
> Documentation/virtual/kvm/vcpu-requests.rst | 2 ++
> 13 files changed, 26 insertions(+)
>
> diff --git a/Documentation/accelerators/ocxl.rst b/Documentation/accelerators/ocxl.rst
> index 14cefc020e2d..b1cea19a90f5 100644
> --- a/Documentation/accelerators/ocxl.rst
> +++ b/Documentation/accelerators/ocxl.rst
> @@ -1,3 +1,5 @@
> +:orphan:
> +
> ========================================================
> OpenCAPI (Open Coherent Accelerator Processor Interface)
> ========================================================
> diff --git a/Documentation/arm/stm32/overview.rst b/Documentation/arm/stm32/overview.rst
> index 85cfc8410798..f7e734153860 100644
> --- a/Documentation/arm/stm32/overview.rst
> +++ b/Documentation/arm/stm32/overview.rst
> @@ -1,3 +1,5 @@
> +:orphan:
> +
> ========================
> STM32 ARM Linux Overview
> ========================
> diff --git a/Documentation/arm/stm32/stm32f429-overview.rst b/Documentation/arm/stm32/stm32f429-overview.rst
> index 18feda97f483..65bbb1c3b423 100644
> --- a/Documentation/arm/stm32/stm32f429-overview.rst
> +++ b/Documentation/arm/stm32/stm32f429-overview.rst
> @@ -1,3 +1,5 @@
> +:orphan:
> +
> STM32F429 Overview
> ==================
>
> diff --git a/Documentation/arm/stm32/stm32f746-overview.rst b/Documentation/arm/stm32/stm32f746-overview.rst
> index b5f4b6ce7656..42d593085015 100644
> --- a/Documentation/arm/stm32/stm32f746-overview.rst
> +++ b/Documentation/arm/stm32/stm32f746-overview.rst
> @@ -1,3 +1,5 @@
> +:orphan:
> +
> STM32F746 Overview
> ==================
>
> diff --git a/Documentation/arm/stm32/stm32f769-overview.rst b/Documentation/arm/stm32/stm32f769-overview.rst
> index 228656ced2fe..f6adac862b17 100644
> --- a/Documentation/arm/stm32/stm32f769-overview.rst
> +++ b/Documentation/arm/stm32/stm32f769-overview.rst
> @@ -1,3 +1,5 @@
> +:orphan:
> +
> STM32F769 Overview
> ==================
>
> diff --git a/Documentation/arm/stm32/stm32h743-overview.rst b/Documentation/arm/stm32/stm32h743-overview.rst
> index 3458dc00095d..c525835e7473 100644
> --- a/Documentation/arm/stm32/stm32h743-overview.rst
> +++ b/Documentation/arm/stm32/stm32h743-overview.rst
> @@ -1,3 +1,5 @@
> +:orphan:
> +
> STM32H743 Overview
> ==================
>
> diff --git a/Documentation/arm/stm32/stm32mp157-overview.rst b/Documentation/arm/stm32/stm32mp157-overview.rst
> index 62e176d47ca7..2c52cd020601 100644
> --- a/Documentation/arm/stm32/stm32mp157-overview.rst
> +++ b/Documentation/arm/stm32/stm32mp157-overview.rst
> @@ -1,3 +1,5 @@
> +:orphan:
> +
> STM32MP157 Overview
> ===================
>
> diff --git a/Documentation/gpu/msm-crash-dump.rst b/Documentation/gpu/msm-crash-dump.rst
> index 757cd257e0d8..240ef200f76c 100644
> --- a/Documentation/gpu/msm-crash-dump.rst
> +++ b/Documentation/gpu/msm-crash-dump.rst
> @@ -1,3 +1,5 @@
> +:orphan:
> +
> =====================
> MSM Crash Dump Format
> =====================
> diff --git a/Documentation/interconnect/interconnect.rst b/Documentation/interconnect/interconnect.rst
> index c3e004893796..56e331dab70e 100644
> --- a/Documentation/interconnect/interconnect.rst
> +++ b/Documentation/interconnect/interconnect.rst
> @@ -1,5 +1,7 @@
> .. SPDX-License-Identifier: GPL-2.0
>
> +:orphan:
> +
> =====================================
> GENERIC SYSTEM INTERCONNECT SUBSYSTEM
> =====================================
> diff --git a/Documentation/laptops/lg-laptop.rst b/Documentation/laptops/lg-laptop.rst
> index aa503ee9b3bc..f2c2ffe31101 100644
> --- a/Documentation/laptops/lg-laptop.rst
> +++ b/Documentation/laptops/lg-laptop.rst
> @@ -1,5 +1,7 @@
> .. SPDX-License-Identifier: GPL-2.0+
>
> +:orphan:
> +
> LG Gram laptop extra features
> =============================
>
> diff --git a/Documentation/powerpc/isa-versions.rst b/Documentation/powerpc/isa-versions.rst
> index 812e20cc898c..66c24140ebf1 100644
> --- a/Documentation/powerpc/isa-versions.rst
> +++ b/Documentation/powerpc/isa-versions.rst
> @@ -1,3 +1,5 @@
> +:orphan:
> +
> CPU to ISA Version Mapping
> ==========================
>
> diff --git a/Documentation/virtual/kvm/amd-memory-encryption.rst b/Documentation/virtual/kvm/amd-memory-encryption.rst
> index 659bbc093b52..33d697ab8a58 100644
> --- a/Documentation/virtual/kvm/amd-memory-encryption.rst
> +++ b/Documentation/virtual/kvm/amd-memory-encryption.rst
> @@ -1,3 +1,5 @@
> +:orphan:
> +
> ======================================
> Secure Encrypted Virtualization (SEV)
> ======================================
> diff --git a/Documentation/virtual/kvm/vcpu-requests.rst b/Documentation/virtual/kvm/vcpu-requests.rst
> index 5feb3706a7ae..c1807a1b92e6 100644
> --- a/Documentation/virtual/kvm/vcpu-requests.rst
> +++ b/Documentation/virtual/kvm/vcpu-requests.rst
> @@ -1,3 +1,5 @@
> +:orphan:
> +
> =================
> KVM VCPU Requests
> =================
>
^ permalink raw reply
* Re: [PATCH] crypto: doc - improve the skcipher API example code
From: Ard Biesheuvel @ 2019-06-03 6:51 UTC (permalink / raw)
To: Eric Biggers
Cc: open list:HARDWARE RANDOM NUMBER GENERATOR CORE,
Linux Doc Mailing List
In-Reply-To: <20190603054408.5903-1-ebiggers@kernel.org>
On Mon, 3 Jun 2019 at 07:44, Eric Biggers <ebiggers@kernel.org> wrote:
>
> From: Eric Biggers <ebiggers@google.com>
>
> Rewrite the skcipher API example, changing it to encrypt a buffer with
> AES-256-XTS. This addresses various problems with the previous example:
>
> - It requests a specific driver "cbc-aes-aesni", which is unusual.
> Normally users ask for "cbc(aes)", not a specific driver.
>
> - It encrypts only a single AES block. For the reader, that doesn't
> clearly distinguish the "skcipher" API from the "cipher" API.
>
> - Showing how to encrypt something with bare CBC is arguably a poor
> choice of example, as it doesn't follow modern crypto trends. Now,
> usually authenticated encryption is recommended, in which case the
> user would use the AEAD API, not skcipher. Disk encryption is still a
> legitimate use for skcipher, but for that usually XTS is recommended.
>
> - Many other bugs and poor coding practices, such as not setting
> CRYPTO_TFM_REQ_MAY_SLEEP, unnecessarily allocating a heap buffer for
> the IV, unnecessary NULL checks, using a pointless wrapper struct, and
> forgetting to set an error code in one case.
>
> Signed-off-by: Eric Biggers <ebiggers@google.com>
Acked-by: Ard Biesheuvel <ard.biesheuvel@linaro.org>
> ---
> Documentation/crypto/api-samples.rst | 176 ++++++++++++---------------
> 1 file changed, 77 insertions(+), 99 deletions(-)
>
> diff --git a/Documentation/crypto/api-samples.rst b/Documentation/crypto/api-samples.rst
> index f14afaaf2f324..e923f17bc2bd5 100644
> --- a/Documentation/crypto/api-samples.rst
> +++ b/Documentation/crypto/api-samples.rst
> @@ -4,111 +4,89 @@ Code Examples
> Code Example For Symmetric Key Cipher Operation
> -----------------------------------------------
>
> -::
> -
> -
> - /* tie all data structures together */
> - struct skcipher_def {
> - struct scatterlist sg;
> - struct crypto_skcipher *tfm;
> - struct skcipher_request *req;
> - struct crypto_wait wait;
> - };
> -
> - /* Perform cipher operation */
> - static unsigned int test_skcipher_encdec(struct skcipher_def *sk,
> - int enc)
> - {
> - int rc;
> -
> - if (enc)
> - rc = crypto_wait_req(crypto_skcipher_encrypt(sk->req), &sk->wait);
> - else
> - rc = crypto_wait_req(crypto_skcipher_decrypt(sk->req), &sk->wait);
> -
> - if (rc)
> - pr_info("skcipher encrypt returned with result %d\n", rc);
> +This code encrypts some data with AES-256-XTS. For sake of example,
> +all inputs are random bytes, the encryption is done in-place, and it's
> +assumed the code is running in a context where it can sleep.
>
> - return rc;
> - }
> +::
>
> - /* Initialize and trigger cipher operation */
> static int test_skcipher(void)
> {
> - struct skcipher_def sk;
> - struct crypto_skcipher *skcipher = NULL;
> - struct skcipher_request *req = NULL;
> - char *scratchpad = NULL;
> - char *ivdata = NULL;
> - unsigned char key[32];
> - int ret = -EFAULT;
> -
> - skcipher = crypto_alloc_skcipher("cbc-aes-aesni", 0, 0);
> - if (IS_ERR(skcipher)) {
> - pr_info("could not allocate skcipher handle\n");
> - return PTR_ERR(skcipher);
> - }
> -
> - req = skcipher_request_alloc(skcipher, GFP_KERNEL);
> - if (!req) {
> - pr_info("could not allocate skcipher request\n");
> - ret = -ENOMEM;
> - goto out;
> - }
> -
> - skcipher_request_set_callback(req, CRYPTO_TFM_REQ_MAY_BACKLOG,
> - crypto_req_done,
> - &sk.wait);
> -
> - /* AES 256 with random key */
> - get_random_bytes(&key, 32);
> - if (crypto_skcipher_setkey(skcipher, key, 32)) {
> - pr_info("key could not be set\n");
> - ret = -EAGAIN;
> - goto out;
> - }
> -
> - /* IV will be random */
> - ivdata = kmalloc(16, GFP_KERNEL);
> - if (!ivdata) {
> - pr_info("could not allocate ivdata\n");
> - goto out;
> - }
> - get_random_bytes(ivdata, 16);
> -
> - /* Input data will be random */
> - scratchpad = kmalloc(16, GFP_KERNEL);
> - if (!scratchpad) {
> - pr_info("could not allocate scratchpad\n");
> - goto out;
> - }
> - get_random_bytes(scratchpad, 16);
> -
> - sk.tfm = skcipher;
> - sk.req = req;
> -
> - /* We encrypt one block */
> - sg_init_one(&sk.sg, scratchpad, 16);
> - skcipher_request_set_crypt(req, &sk.sg, &sk.sg, 16, ivdata);
> - crypto_init_wait(&sk.wait);
> -
> - /* encrypt data */
> - ret = test_skcipher_encdec(&sk, 1);
> - if (ret)
> - goto out;
> -
> - pr_info("Encryption triggered successfully\n");
> -
> + struct crypto_skcipher *tfm = NULL;
> + struct skcipher_request *req = NULL;
> + u8 *data = NULL;
> + const size_t datasize = 512; /* data size in bytes */
> + struct scatterlist sg;
> + DECLARE_CRYPTO_WAIT(wait);
> + u8 iv[16]; /* AES-256-XTS takes a 16-byte IV */
> + u8 key[64]; /* AES-256-XTS takes a 64-byte key */
> + int err;
> +
> + /*
> + * Allocate a tfm (a transformation object) and set the key.
> + *
> + * In real-world use, a tfm and key are typically used for many
> + * encryption/decryption operations. But in this example, we'll just do a
> + * single encryption operation with it (which is not very efficient).
> + */
> +
> + tfm = crypto_alloc_skcipher("xts(aes)", 0, 0);
> + if (IS_ERR(tfm)) {
> + pr_err("Error allocating xts(aes) handle: %ld\n", PTR_ERR(tfm));
> + return PTR_ERR(tfm);
> + }
> +
> + get_random_bytes(key, sizeof(key));
> + err = crypto_skcipher_setkey(tfm, key, sizeof(key));
> + if (err) {
> + pr_err("Error setting key: %d\n", err);
> + goto out;
> + }
> +
> + /* Allocate a request object */
> + req = skcipher_request_alloc(tfm, GFP_KERNEL);
> + if (!req) {
> + err = -ENOMEM;
> + goto out;
> + }
> +
> + /* Prepare the input data */
> + data = kmalloc(datasize, GFP_KERNEL);
> + if (!data) {
> + err = -ENOMEM;
> + goto out;
> + }
> + get_random_bytes(data, datasize);
> +
> + /* Initialize the IV */
> + get_random_bytes(iv, sizeof(iv));
> +
> + /*
> + * Encrypt the data in-place.
> + *
> + * For simplicity, in this example we wait for the request to complete
> + * before proceeding, even if the underlying implementation is asynchronous.
> + *
> + * To decrypt instead of encrypt, just change crypto_skcipher_encrypt() to
> + * crypto_skcipher_decrypt().
> + */
> + sg_init_one(&sg, data, datasize);
> + skcipher_request_set_callback(req, CRYPTO_TFM_REQ_MAY_BACKLOG |
> + CRYPTO_TFM_REQ_MAY_SLEEP,
> + crypto_req_done, &wait);
> + skcipher_request_set_crypt(req, &sg, &sg, datasize, iv);
> + err = crypto_wait_req(crypto_skcipher_encrypt(req), &wait);
> + if (err) {
> + pr_err("Error encrypting data: %d\n", err);
> + goto out;
> + }
> +
> + pr_debug("Encryption was successful\n");
> out:
> - if (skcipher)
> - crypto_free_skcipher(skcipher);
> - if (req)
> + crypto_free_skcipher(tfm);
> skcipher_request_free(req);
> - if (ivdata)
> - kfree(ivdata);
> - if (scratchpad)
> - kfree(scratchpad);
> - return ret;
> + kfree(data);
> + return err;
> }
>
>
> --
> 2.21.0
>
^ permalink raw reply
* [PATCH] crypto: doc - improve the skcipher API example code
From: Eric Biggers @ 2019-06-03 5:44 UTC (permalink / raw)
To: linux-crypto; +Cc: linux-doc
From: Eric Biggers <ebiggers@google.com>
Rewrite the skcipher API example, changing it to encrypt a buffer with
AES-256-XTS. This addresses various problems with the previous example:
- It requests a specific driver "cbc-aes-aesni", which is unusual.
Normally users ask for "cbc(aes)", not a specific driver.
- It encrypts only a single AES block. For the reader, that doesn't
clearly distinguish the "skcipher" API from the "cipher" API.
- Showing how to encrypt something with bare CBC is arguably a poor
choice of example, as it doesn't follow modern crypto trends. Now,
usually authenticated encryption is recommended, in which case the
user would use the AEAD API, not skcipher. Disk encryption is still a
legitimate use for skcipher, but for that usually XTS is recommended.
- Many other bugs and poor coding practices, such as not setting
CRYPTO_TFM_REQ_MAY_SLEEP, unnecessarily allocating a heap buffer for
the IV, unnecessary NULL checks, using a pointless wrapper struct, and
forgetting to set an error code in one case.
Signed-off-by: Eric Biggers <ebiggers@google.com>
---
Documentation/crypto/api-samples.rst | 176 ++++++++++++---------------
1 file changed, 77 insertions(+), 99 deletions(-)
diff --git a/Documentation/crypto/api-samples.rst b/Documentation/crypto/api-samples.rst
index f14afaaf2f324..e923f17bc2bd5 100644
--- a/Documentation/crypto/api-samples.rst
+++ b/Documentation/crypto/api-samples.rst
@@ -4,111 +4,89 @@ Code Examples
Code Example For Symmetric Key Cipher Operation
-----------------------------------------------
-::
-
-
- /* tie all data structures together */
- struct skcipher_def {
- struct scatterlist sg;
- struct crypto_skcipher *tfm;
- struct skcipher_request *req;
- struct crypto_wait wait;
- };
-
- /* Perform cipher operation */
- static unsigned int test_skcipher_encdec(struct skcipher_def *sk,
- int enc)
- {
- int rc;
-
- if (enc)
- rc = crypto_wait_req(crypto_skcipher_encrypt(sk->req), &sk->wait);
- else
- rc = crypto_wait_req(crypto_skcipher_decrypt(sk->req), &sk->wait);
-
- if (rc)
- pr_info("skcipher encrypt returned with result %d\n", rc);
+This code encrypts some data with AES-256-XTS. For sake of example,
+all inputs are random bytes, the encryption is done in-place, and it's
+assumed the code is running in a context where it can sleep.
- return rc;
- }
+::
- /* Initialize and trigger cipher operation */
static int test_skcipher(void)
{
- struct skcipher_def sk;
- struct crypto_skcipher *skcipher = NULL;
- struct skcipher_request *req = NULL;
- char *scratchpad = NULL;
- char *ivdata = NULL;
- unsigned char key[32];
- int ret = -EFAULT;
-
- skcipher = crypto_alloc_skcipher("cbc-aes-aesni", 0, 0);
- if (IS_ERR(skcipher)) {
- pr_info("could not allocate skcipher handle\n");
- return PTR_ERR(skcipher);
- }
-
- req = skcipher_request_alloc(skcipher, GFP_KERNEL);
- if (!req) {
- pr_info("could not allocate skcipher request\n");
- ret = -ENOMEM;
- goto out;
- }
-
- skcipher_request_set_callback(req, CRYPTO_TFM_REQ_MAY_BACKLOG,
- crypto_req_done,
- &sk.wait);
-
- /* AES 256 with random key */
- get_random_bytes(&key, 32);
- if (crypto_skcipher_setkey(skcipher, key, 32)) {
- pr_info("key could not be set\n");
- ret = -EAGAIN;
- goto out;
- }
-
- /* IV will be random */
- ivdata = kmalloc(16, GFP_KERNEL);
- if (!ivdata) {
- pr_info("could not allocate ivdata\n");
- goto out;
- }
- get_random_bytes(ivdata, 16);
-
- /* Input data will be random */
- scratchpad = kmalloc(16, GFP_KERNEL);
- if (!scratchpad) {
- pr_info("could not allocate scratchpad\n");
- goto out;
- }
- get_random_bytes(scratchpad, 16);
-
- sk.tfm = skcipher;
- sk.req = req;
-
- /* We encrypt one block */
- sg_init_one(&sk.sg, scratchpad, 16);
- skcipher_request_set_crypt(req, &sk.sg, &sk.sg, 16, ivdata);
- crypto_init_wait(&sk.wait);
-
- /* encrypt data */
- ret = test_skcipher_encdec(&sk, 1);
- if (ret)
- goto out;
-
- pr_info("Encryption triggered successfully\n");
-
+ struct crypto_skcipher *tfm = NULL;
+ struct skcipher_request *req = NULL;
+ u8 *data = NULL;
+ const size_t datasize = 512; /* data size in bytes */
+ struct scatterlist sg;
+ DECLARE_CRYPTO_WAIT(wait);
+ u8 iv[16]; /* AES-256-XTS takes a 16-byte IV */
+ u8 key[64]; /* AES-256-XTS takes a 64-byte key */
+ int err;
+
+ /*
+ * Allocate a tfm (a transformation object) and set the key.
+ *
+ * In real-world use, a tfm and key are typically used for many
+ * encryption/decryption operations. But in this example, we'll just do a
+ * single encryption operation with it (which is not very efficient).
+ */
+
+ tfm = crypto_alloc_skcipher("xts(aes)", 0, 0);
+ if (IS_ERR(tfm)) {
+ pr_err("Error allocating xts(aes) handle: %ld\n", PTR_ERR(tfm));
+ return PTR_ERR(tfm);
+ }
+
+ get_random_bytes(key, sizeof(key));
+ err = crypto_skcipher_setkey(tfm, key, sizeof(key));
+ if (err) {
+ pr_err("Error setting key: %d\n", err);
+ goto out;
+ }
+
+ /* Allocate a request object */
+ req = skcipher_request_alloc(tfm, GFP_KERNEL);
+ if (!req) {
+ err = -ENOMEM;
+ goto out;
+ }
+
+ /* Prepare the input data */
+ data = kmalloc(datasize, GFP_KERNEL);
+ if (!data) {
+ err = -ENOMEM;
+ goto out;
+ }
+ get_random_bytes(data, datasize);
+
+ /* Initialize the IV */
+ get_random_bytes(iv, sizeof(iv));
+
+ /*
+ * Encrypt the data in-place.
+ *
+ * For simplicity, in this example we wait for the request to complete
+ * before proceeding, even if the underlying implementation is asynchronous.
+ *
+ * To decrypt instead of encrypt, just change crypto_skcipher_encrypt() to
+ * crypto_skcipher_decrypt().
+ */
+ sg_init_one(&sg, data, datasize);
+ skcipher_request_set_callback(req, CRYPTO_TFM_REQ_MAY_BACKLOG |
+ CRYPTO_TFM_REQ_MAY_SLEEP,
+ crypto_req_done, &wait);
+ skcipher_request_set_crypt(req, &sg, &sg, datasize, iv);
+ err = crypto_wait_req(crypto_skcipher_encrypt(req), &wait);
+ if (err) {
+ pr_err("Error encrypting data: %d\n", err);
+ goto out;
+ }
+
+ pr_debug("Encryption was successful\n");
out:
- if (skcipher)
- crypto_free_skcipher(skcipher);
- if (req)
+ crypto_free_skcipher(tfm);
skcipher_request_free(req);
- if (ivdata)
- kfree(ivdata);
- if (scratchpad)
- kfree(scratchpad);
- return ret;
+ kfree(data);
+ return err;
}
--
2.21.0
^ permalink raw reply related
* Re: [PATCH 13/22] docs: zh_CN: avoid duplicate citation references
From: Alex Shi @ 2019-06-02 15:01 UTC (permalink / raw)
To: Mauro Carvalho Chehab, Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet, Harry Wei
In-Reply-To: <9d3b9729663f75249b514dd3910309eb418d9e46.1559171394.git.mchehab+samsung@kernel.org>
On 2019/5/30 7:23 上午, Mauro Carvalho Chehab wrote:
> Documentation/process/management-style.rst:35: WARNING: duplicate label decisions, other instance in Documentation/translations/zh_CN/process/management-style.rst
> Documentation/process/programming-language.rst:37: WARNING: duplicate citation c-language, other instance in Documentation/translations/zh_CN/process/programming-language.rst
> Documentation/process/programming-language.rst:38: WARNING: duplicate citation gcc, other instance in Documentation/translations/zh_CN/process/programming-language.rst
> Documentation/process/programming-language.rst:39: WARNING: duplicate citation clang, other instance in Documentation/translations/zh_CN/process/programming-language.rst
> Documentation/process/programming-language.rst:40: WARNING: duplicate citation icc, other instance in Documentation/translations/zh_CN/process/programming-language.rst
> Documentation/process/programming-language.rst:41: WARNING: duplicate citation gcc-c-dialect-options, other instance in Documentation/translations/zh_CN/process/programming-language.rst
> Documentation/process/programming-language.rst:42: WARNING: duplicate citation gnu-extensions, other instance in Documentation/translations/zh_CN/process/programming-language.rst
> Documentation/process/programming-language.rst:43: WARNING: duplicate citation gcc-attribute-syntax, other instance in Documentation/translations/zh_CN/process/programming-language.rst
> Documentation/process/programming-language.rst:44: WARNING: duplicate citation n2049, other instance in Documentation/translations/zh_CN/process/programming-language.rst
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> ---
> .../zh_CN/process/management-style.rst | 4 +--
> .../zh_CN/process/programming-language.rst | 28 +++++++++----------
> 2 files changed, 16 insertions(+), 16 deletions(-)
>
> diff --git a/Documentation/translations/zh_CN/process/management-style.rst b/Documentation/translations/zh_CN/process/management-style.rst
> index a181fa56d19e..c6a5bb285797 100644
> --- a/Documentation/translations/zh_CN/process/management-style.rst
> +++ b/Documentation/translations/zh_CN/process/management-style.rst
> @@ -28,7 +28,7 @@ Linux内核管理风格
>
> 不管怎样，这里是：
>
> -.. _decisions:
> +.. _cn_decisions:
>
> 1）决策
> -------
> @@ -108,7 +108,7 @@ Linux内核管理风格
> 但是，为了做好作为内核管理者的准备，最好记住不要烧掉任何桥梁，不要轰炸任何
> 无辜的村民，也不要疏远太多的内核开发人员。事实证明，疏远人是相当容易的，而
> 亲近一个疏远的人是很难的。因此，“疏远”立即属于“不可逆”的范畴，并根据
> -:ref:`decisions` 成为绝不可以做的事情。
> +:ref:`cn_decisions` 成为绝不可以做的事情。
It's good to have.
>
> 这里只有几个简单的规则：
>
> diff --git a/Documentation/translations/zh_CN/process/programming-language.rst b/Documentation/translations/zh_CN/process/programming-language.rst
> index 51fd4ef48ea1..9de9a3108c4d 100644
> --- a/Documentation/translations/zh_CN/process/programming-language.rst
> +++ b/Documentation/translations/zh_CN/process/programming-language.rst
> @@ -8,21 +8,21 @@
> 程序设计语言
> ============
>
> -内核是用C语言 [c-language]_ 编写的。更准确地说，内核通常是用 ``gcc`` [gcc]_
> -在 ``-std=gnu89`` [gcc-c-dialect-options]_ 下编译的：ISO C90的 GNU 方言（
> +内核是用C语言 [cn_c-language]_ 编写的。更准确地说，内核通常是用 ``gcc`` [cn_gcc]_
this change isn't good. cn_gcc will show in docs, it looks wired and confusing for peoples. other changes have the same issue. Could you find other way to fix the warning? or I'd rather tolerant it.
Thanks
Alex
^ permalink raw reply
* Re: [PATCH 04/22] docs: zh_CN: get rid of basic_profiling.txt
From: Alex Shi @ 2019-06-02 14:36 UTC (permalink / raw)
To: Mauro Carvalho Chehab, Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet, Harry Wei
In-Reply-To: <81f5848d02cafb986d9145dbff17beb1e4427dea.1559171394.git.mchehab+samsung@kernel.org>
On 2019/5/30 7:23 上午, Mauro Carvalho Chehab wrote:
> Changeset 5700d1974818 ("docs: Get rid of the "basic profiling" guide")
> removed an old basic-profiling.txt file that was not updated over
> the last 11 years and won't reflect the post-perf era.
>
> It makes no sense to keep its translation, so get rid of it too.
>
> Fixes: 5700d1974818 ("docs: Get rid of the "basic profiling" guide")
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> ---
Acked-by: Alex Shi <alex.shi@linux.alibaba.com>
^ permalink raw reply
* Re: [PATCH v3 2/3] kernel/ucounts: expose count of inotify watches in use
From: Albert Vaca Cintora @ 2019-06-01 18:20 UTC (permalink / raw)
To: Andrew Morton
Cc: rdunlap, mingo, Jan Kara, ebiederm, Nicolas Saenz Julienne,
linux-kernel, corbet, linux-doc, Matthias Brugger
In-Reply-To: <20190531170046.ac2b52d8c4923fdeedf943cc@linux-foundation.org>
On Sat, Jun 1, 2019 at 2:00 AM Andrew Morton <akpm@linux-foundation.org> wrote:
>
> On Fri, 31 May 2019 21:50:15 +0200 Albert Vaca Cintora <albertvaka@gmail.com> wrote:
>
> > Adds a readonly 'current_inotify_watches' entry to the user sysctl table.
> > The handler for this entry is a custom function that ends up calling
> > proc_dointvec. Said sysctl table already contains 'max_inotify_watches'
> > and it gets mounted under /proc/sys/user/.
> >
> > Inotify watches are a finite resource, in a similar way to available file
> > descriptors. The motivation for this patch is to be able to set up
> > monitoring and alerting before an application starts failing because
> > it runs out of inotify watches.
> >
> > ...
> >
> > --- a/kernel/ucount.c
> > +++ b/kernel/ucount.c
> > @@ -118,6 +118,26 @@ static void put_ucounts(struct ucounts *ucounts)
> > kfree(ucounts);
> > }
> >
> > +#ifdef CONFIG_INOTIFY_USER
> > +int proc_read_inotify_watches(struct ctl_table *table, int write,
> > + void __user *buffer, size_t *lenp, loff_t *ppos)
> > +{
> > + struct ucounts *ucounts;
> > + struct ctl_table fake_table;
>
> hmm.
>
> > + int count = -1;
> > +
> > + ucounts = get_ucounts(current_user_ns(), current_euid());
> > + if (ucounts != NULL) {
> > + count = atomic_read(&ucounts->ucount[UCOUNT_INOTIFY_WATCHES]);
> > + put_ucounts(ucounts);
> > + }
> > +
> > + fake_table.data = &count;
> > + fake_table.maxlen = sizeof(count);
> > + return proc_dointvec(&fake_table, write, buffer, lenp, ppos);
>
> proc_dointvec
> ->do_proc_dointvec
> ->__do_proc_dointvec
> ->proc_first_pos_non_zero_ignore
> ->warn_sysctl_write
> ->pr_warn_once(..., table->procname)
>
> and I think ->procname is uninitialized.
>
> That's from a cursory check. Perhaps other uninitialized members of
> fake_table are accessed, dunno.
>
> we could do
>
> {
> struct ctl_table fake_table = {
> .data = &count,
> .maxlen = sizeof(count),
> };
>
> return proc_dointvec(&fake_table, write, buffer, lenp, ppos);
> }
>
> or whatever. That will cause the pr_warn_once to print "(null)" but
> that's OK I guess.
>
> Are there other places in the kernel which do this temp ctl_table
> trick? If so, what do they do? If not, what is special about this
> code?
>
>
I copied this 'fake_table' trick from proc_do_entropy in
drivers/char/random.c exactly as it is. It is also used in other
places with slight variations.
Note that, since we are creating a read-only proc file,
proc_first_pos_non_zero_ignore is not called from __do_proc_dointvec,
so the uninitialized ->procname is not accessed.
Albert
^ permalink raw reply
* Re: [PATCH RFC] Rough draft document on merging and rebasing
From: Theodore Ts'o @ 2019-06-01 15:42 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: Linus Torvalds, LKML, linux-doc
In-Reply-To: <20190530135317.3c8d0d7b@lwn.net>
On Thu, May 30, 2019 at 01:53:17PM -0600, Jonathan Corbet wrote:
> +Rebasing
> +========
> +
> +"Rebasing" is the process of changing the history of a series of commits
> +within a repository. At its simplest, a rebase could change the starting
> +point of a patch series from one point to another. Other uses include
> +fixing (or deleting) broken commits, adding tags to commits, or changing
> +the order in which commits are applied. Used properly, rebasing can yield
> +a cleaner and clearer development history; used improperly, it can obscure
> +that history and introduce bugs.
Rebasing is being used in two senses here. The first is where the
diffs don't change (much), but the starting point of the changes is
being changed. The second is where a broken commit is dropped, adding
a signed-off-by, etc.
Both have the property that they can used for good or ill, but the
details when this is an issue can change a bit. More below...
> +There are a few rules of thumb that can help developers to avoid the worst
> +perils of rebasing:
> +
> + - History that has been exposed to the world beyond your private system
> + should not be rebased. Others may have pulled a copy of your tree and
> + built on it; rebasing your tree will create pain for them. If work is
> + in need of rebasing, that is usually a sign that it is not yet ready to
> + be committed to a public repository.
That seems to be a bit too categorical. It's been recommended, and
some people do, push patches to a branch so the zero-day bot will pick
it up and test for potential problems. And broken commits *do* get
dropped from candidate stable kernel releases. And, of course,
there's linux-next, which is constantly getting rebased.
And there have been people who have pushed out RFC patche series onto
a git branch, and publicized it on LKML for the convenience of
reviewers. (Perhaps because there is a patch which is so big it
exceeds the LKML size restrictions.)
I think it's more about whether people know that a branch is
considered unstable from a historical perspective or not. No one
builds on top of linux-next because, well, that would be silly.
Finally, I'm bit concerned about anything which states absolutes,
because there are people who tend to be real stickler for the rules,
and if they see something stated in absolute terms, they fail to
understand that there are exceptions that are well understood, and in
use for years before the existence of the document which is trying to
codify best practices.
> + - Realize the rebasing a patch series changes the environment in which it
> + was developed and, likely, invalidates much of the testing that was
> + done. A rebased patch series should, as a general rule, be treated like
> + new code and retested from the beginning.
In this paragraph, "rebasing" is being used in the change the base
commit on top of which a series of changes were based upon. And it's
what most people think of when they see the word "rebase".
However "git rebase" is also used to rewrite git history when dropping
a bad commit, or fixing things so the branch is bisectable, etc. But
in the definitions above, the word "rebase" was defined to include
both "changing the base of a patch stack", and "rewriting git
history". I wonder if that helps more than it hinders understanding.
At least in my mind, "rebasing" is much more often the wrong thing,
where as "rewriting git history" for a leaf repository can be more
often justifable. And of course, if someone is working on a feature
for which the review and development cycle takes several kernel
releases, I'd claim that "rebasing" in that case always makes sense,
even if they *have* exposed their patch series via git for review /
commenting purposes.
Regards,
- Ted
^ permalink raw reply
* Re: [PATCH RFC 1/1] doc/rcu: Add some more listRCU patterns in the kernel
From: Joel Fernandes @ 2019-06-01 9:41 UTC (permalink / raw)
To: LKML, Neil Brown
Cc: rcu, Jonathan Corbet, Josh Triplett, kernel-team, Lai Jiangshan,
open list:DOCUMENTATION, Mathieu Desnoyers, Paul E. McKenney,
Steven Rostedt, Peter Zilstra
In-Reply-To: <20190601093926.28158-1-joel@joelfernandes.org>
Forgot to CC +Neil Brown , will do in the next posting, thanks!
On Sat, Jun 1, 2019 at 5:39 AM Joel Fernandes (Google)
<joel@joelfernandes.org> wrote:
>
> We keep the initially written audit examples and add to it, since the
> code that audit has is still relevant even though slightly different in
> the kernel.
>
> Cc: rcu@vger.kernel.org
> Signed-off-by: Joel Fernandes (Google) <joel@joelfernandes.org>
> ---
> Documentation/RCU/listRCU.txt | 154 +++++++++++++++++++++++++++++++---
> 1 file changed, 144 insertions(+), 10 deletions(-)
>
> diff --git a/Documentation/RCU/listRCU.txt b/Documentation/RCU/listRCU.txt
> index adb5a3782846..af5bf1bd689c 100644
> --- a/Documentation/RCU/listRCU.txt
> +++ b/Documentation/RCU/listRCU.txt
> @@ -7,8 +7,54 @@ is that all of the required memory barriers are included for you in
> the list macros. This document describes several applications of RCU,
> with the best fits first.
>
> -
> -Example 1: Read-Side Action Taken Outside of Lock, No In-Place Updates
> +Example 1: Read-mostly list: Deferred Destruction
> +
> +A widely used usecase for RCU lists in the kernel is lockless iteration over
> +all processes in the system. task_struct::tasks represents the list node that
> +links all the processes. The list can be traversed in parallel to any list
> +additions or removals.
> +
> +The traversal of the list is done using for_each_process() which is defined by
> +the 2 macros:
> +
> +#define next_task(p) \
> + list_entry_rcu((p)->tasks.next, struct task_struct, tasks)
> +
> +#define for_each_process(p) \
> + for (p = &init_task ; (p = next_task(p)) != &init_task ; )
> +
> +The code traversing the list of all processes typically looks like:
> +rcu_read_lock();
> +for_each_process(p) {
> + /* Do something with p */
> +}
> +rcu_read_unlock();
> +
> +Thes code (simplified) removing a process from the task lists is in
> +release_task():
> +
> +void release_task(struct task_struct *p)
> +{
> + write_lock(&tasklist_lock);
> + list_del_rcu(&p->tasks);
> + write_unlock(&tasklist_lock);
> + call_rcu(&p->rcu, delayed_put_task_struct);
> +}
> +
> +When a process exits, release_task() calls list_del_rcu(&p->tasks) to remove
> +the task from the list of all tasks, under tasklist_lock writer lock
> +protection. The tasklist_lock prevents concurrent list adds/removes from
> +corrupting the list. Readers using for_each_process() are not protected with
> +the tasklist_lock. To prevent readers from appearing to notice changes in the
> +list pointers, the task_struct object is freed only after one more more grace
> +periods elapse (with the help of call_rcu). This deferring of destruction
> +ensures that any readers traversing the list will see valid p->tasks.next
> +pointers and deletion/freeing can happen in parallel to traversal of the list.
> +This pattern is also called an "existence lock" sometimes, since RCU makes sure
> +the object exists in memory as long as readers exist, that are traversing.
> +
> +
> +Example 2: Read-Side Action Taken Outside of Lock, No In-Place Updates
>
> The best applications are cases where, if reader-writer locking were
> used, the read-side lock would be dropped before taking any action
> @@ -32,7 +78,7 @@ implementation of audit_filter_task() might be as follows:
> enum audit_state state;
>
> read_lock(&auditsc_lock);
> - /* Note: audit_netlink_sem held by caller. */
> + /* Note: audit_filter_mutex held by caller. */
> list_for_each_entry(e, &audit_tsklist, list) {
> if (audit_filter_rules(tsk, &e->rule, NULL, &state)) {
> read_unlock(&auditsc_lock);
> @@ -56,7 +102,7 @@ This means that RCU can be easily applied to the read side, as follows:
> enum audit_state state;
>
> rcu_read_lock();
> - /* Note: audit_netlink_sem held by caller. */
> + /* Note: audit_filter_mutex held by caller. */
> list_for_each_entry_rcu(e, &audit_tsklist, list) {
> if (audit_filter_rules(tsk, &e->rule, NULL, &state)) {
> rcu_read_unlock();
> @@ -139,7 +185,7 @@ Following are the RCU equivalents for these two functions:
>
> Normally, the write_lock() and write_unlock() would be replaced by
> a spin_lock() and a spin_unlock(), but in this case, all callers hold
> -audit_netlink_sem, so no additional locking is required. The auditsc_lock
> +audit_filter_mutex, so no additional locking is required. The auditsc_lock
> can therefore be eliminated, since use of RCU eliminates the need for
> writers to exclude readers. Normally, the write_lock() calls would
> be converted into spin_lock() calls.
> @@ -155,7 +201,7 @@ So, when readers can tolerate stale data and when entries are either added
> or deleted, without in-place modification, it is very easy to use RCU!
>
>
> -Example 2: Handling In-Place Updates
> +Example 3: Handling In-Place Updates
>
> The system-call auditing code does not update auditing rules in place.
> However, if it did, reader-writer-locked code to do so might look as
> @@ -171,7 +217,7 @@ otherwise, the added fields would need to be filled in):
> struct audit_newentry *ne;
>
> write_lock(&auditsc_lock);
> - /* Note: audit_netlink_sem held by caller. */
> + /* Note: audit_filter_mutex held by caller. */
> list_for_each_entry(e, list, list) {
> if (!audit_compare_rule(rule, &e->rule)) {
> e->rule.action = newaction;
> @@ -213,13 +259,23 @@ RCU ("read-copy update") its name. The RCU code is as follows:
> return -EFAULT; /* No matching rule */
> }
>
> -Again, this assumes that the caller holds audit_netlink_sem. Normally,
> +Again, this assumes that the caller holds audit_filter_mutex. Normally,
> the reader-writer lock would become a spinlock in this sort of code.
>
> +Another use of this pattern can be found in the openswitch driver's "connection
> +tracking table" code (ct_limit_set()). The table holds connection tracking
> +entries and has a limit on the maximum entries. There is one such table
> +per-zone and hence one "limit" per zone. The zones are mapped to their limits
> +through a hashtable using an RCU-managed hlist for the hash chains. When a new
> +limit is to be set, a new limit object is allocated and ct_limit_set() is
> +called to replace the old limit object with the new one using
> +list_replace_rcu(). The old limit object is then freed after a grace period
> +using kfree_rcu().
> +
>
> -Example 3: Eliminating Stale Data
> +Example 4: Eliminating Stale Data
>
> -The auditing examples above tolerate stale data, as do most algorithms
> +The auditing exampes above tolerates stale data, as do most algorithms
> that are tracking external state. Because there is a delay from the
> time the external state changes before Linux becomes aware of the change,
> additional RCU-induced staleness is normally not a problem.
> @@ -291,6 +347,84 @@ flag under the spinlock as follows:
> }
>
>
> +EXAMPLE 5: Skipping Stale Objects
> +
> +Stale data can also be eliminated for performance reasons since it is pointless
> +to process items in a list, if the object is being destroyed. One such example
> +can be found in the timerfd subsystem. When a CLOCK_REALTIME clock is
> +reprogrammed - for example due to setting of the system time, then all programmed
> +timerfds that depend on this clock get triggered and processes waiting on them
> +to expire are woken up in advance of their scheduled expiry. To facilitate
> +this, all such timers are added to a 'cancel_list' when they are setup in
> +timerfd_setup_cancel:
> +
> +static void timerfd_setup_cancel(struct timerfd_ctx *ctx, int flags)
> +{
> + spin_lock(&ctx->cancel_lock);
> + if ((ctx->clockid == CLOCK_REALTIME &&
> + (flags & TFD_TIMER_ABSTIME) && (flags & TFD_TIMER_CANCEL_ON_SET)) {
> + if (!ctx->might_cancel) {
> + ctx->might_cancel = true;
> + spin_lock(&cancel_lock);
> + list_add_rcu(&ctx->clist, &cancel_list);
> + spin_unlock(&cancel_lock);
> + }
> + }
> + spin_unlock(&ctx->cancel_lock);
> +}
> +
> +When a timerfd is freed (fd is closed), then the might_cancel flag of the
> +timerfd object is cleared, the object removed from the cancel_list and destroyed:
> +
> +int timerfd_release(struct inode *inode, struct file *file)
> +{
> + struct timerfd_ctx *ctx = file->private_data;
> +
> + spin_lock(&ctx->cancel_lock);
> + if (ctx->might_cancel) {
> + ctx->might_cancel = false;
> + spin_lock(&cancel_lock);
> + list_del_rcu(&ctx->clist);
> + spin_unlock(&cancel_lock);
> + }
> + spin_unlock(&ctx->cancel_lock);
> +
> + hrtimer_cancel(&ctx->t.tmr);
> + kfree_rcu(ctx, rcu);
> + return 0;
> +}
> +
> +If the CLOCK_REALTIME clock is set, for example by a time server, the hrtimer
> +framework calls timerfd_clock_was_set() which walks the cancel_list and wakes
> +up processes waiting on the timerfd. While iterating the cancel list, the
> +might_cancel flag is consulted to skip stale objects:
> +
> +void timerfd_clock_was_set(void)
> +{
> + struct timerfd_ctx *ctx;
> + unsigned long flags;
> +
> + rcu_read_lock();
> + list_for_each_entry_rcu(ctx, &cancel_list, clist) {
> + if (!ctx->might_cancel)
> + continue;
> + spin_lock_irqsave(&ctx->wqh.lock, flags);
> + if (ctx->moffs != ktime_mono_to_real(0)) {
> + ctx->moffs = KTIME_MAX;
> + ctx->ticks++;
> + wake_up_locked_poll(&ctx->wqh, EPOLLIN);
> + }
> + spin_unlock_irqrestore(&ctx->wqh.lock, flags);
> + }
> + rcu_read_unlock();
> +}
> +
> +The key point here is, because RCU-traversal of the cancel_list happens while
> +objects are being added and removed to the list, sometimes the traversal can
> +step on an object that has been removed from the list. In this example, it is
> +seen that it is better to skip such objects using a flag.
> +
> +
> Summary
>
> Read-mostly list-based data structures that can tolerate stale data are
> --
> 2.22.0.rc1.311.g5d7573a151-goog
>
^ permalink raw reply
* [PATCH RFC 1/1] doc/rcu: Add some more listRCU patterns in the kernel
From: Joel Fernandes (Google) @ 2019-06-01 9:39 UTC (permalink / raw)
To: linux-kernel
Cc: Joel Fernandes (Google), rcu, Jonathan Corbet, Josh Triplett,
kernel-team, Lai Jiangshan, linux-doc, Mathieu Desnoyers,
Paul E. McKenney, Steven Rostedt, peterz
We keep the initially written audit examples and add to it, since the
code that audit has is still relevant even though slightly different in
the kernel.
Cc: rcu@vger.kernel.org
Signed-off-by: Joel Fernandes (Google) <joel@joelfernandes.org>
---
Documentation/RCU/listRCU.txt | 154 +++++++++++++++++++++++++++++++---
1 file changed, 144 insertions(+), 10 deletions(-)
diff --git a/Documentation/RCU/listRCU.txt b/Documentation/RCU/listRCU.txt
index adb5a3782846..af5bf1bd689c 100644
--- a/Documentation/RCU/listRCU.txt
+++ b/Documentation/RCU/listRCU.txt
@@ -7,8 +7,54 @@ is that all of the required memory barriers are included for you in
the list macros. This document describes several applications of RCU,
with the best fits first.
-
-Example 1: Read-Side Action Taken Outside of Lock, No In-Place Updates
+Example 1: Read-mostly list: Deferred Destruction
+
+A widely used usecase for RCU lists in the kernel is lockless iteration over
+all processes in the system. task_struct::tasks represents the list node that
+links all the processes. The list can be traversed in parallel to any list
+additions or removals.
+
+The traversal of the list is done using for_each_process() which is defined by
+the 2 macros:
+
+#define next_task(p) \
+ list_entry_rcu((p)->tasks.next, struct task_struct, tasks)
+
+#define for_each_process(p) \
+ for (p = &init_task ; (p = next_task(p)) != &init_task ; )
+
+The code traversing the list of all processes typically looks like:
+rcu_read_lock();
+for_each_process(p) {
+ /* Do something with p */
+}
+rcu_read_unlock();
+
+Thes code (simplified) removing a process from the task lists is in
+release_task():
+
+void release_task(struct task_struct *p)
+{
+ write_lock(&tasklist_lock);
+ list_del_rcu(&p->tasks);
+ write_unlock(&tasklist_lock);
+ call_rcu(&p->rcu, delayed_put_task_struct);
+}
+
+When a process exits, release_task() calls list_del_rcu(&p->tasks) to remove
+the task from the list of all tasks, under tasklist_lock writer lock
+protection. The tasklist_lock prevents concurrent list adds/removes from
+corrupting the list. Readers using for_each_process() are not protected with
+the tasklist_lock. To prevent readers from appearing to notice changes in the
+list pointers, the task_struct object is freed only after one more more grace
+periods elapse (with the help of call_rcu). This deferring of destruction
+ensures that any readers traversing the list will see valid p->tasks.next
+pointers and deletion/freeing can happen in parallel to traversal of the list.
+This pattern is also called an "existence lock" sometimes, since RCU makes sure
+the object exists in memory as long as readers exist, that are traversing.
+
+
+Example 2: Read-Side Action Taken Outside of Lock, No In-Place Updates
The best applications are cases where, if reader-writer locking were
used, the read-side lock would be dropped before taking any action
@@ -32,7 +78,7 @@ implementation of audit_filter_task() might be as follows:
enum audit_state state;
read_lock(&auditsc_lock);
- /* Note: audit_netlink_sem held by caller. */
+ /* Note: audit_filter_mutex held by caller. */
list_for_each_entry(e, &audit_tsklist, list) {
if (audit_filter_rules(tsk, &e->rule, NULL, &state)) {
read_unlock(&auditsc_lock);
@@ -56,7 +102,7 @@ This means that RCU can be easily applied to the read side, as follows:
enum audit_state state;
rcu_read_lock();
- /* Note: audit_netlink_sem held by caller. */
+ /* Note: audit_filter_mutex held by caller. */
list_for_each_entry_rcu(e, &audit_tsklist, list) {
if (audit_filter_rules(tsk, &e->rule, NULL, &state)) {
rcu_read_unlock();
@@ -139,7 +185,7 @@ Following are the RCU equivalents for these two functions:
Normally, the write_lock() and write_unlock() would be replaced by
a spin_lock() and a spin_unlock(), but in this case, all callers hold
-audit_netlink_sem, so no additional locking is required. The auditsc_lock
+audit_filter_mutex, so no additional locking is required. The auditsc_lock
can therefore be eliminated, since use of RCU eliminates the need for
writers to exclude readers. Normally, the write_lock() calls would
be converted into spin_lock() calls.
@@ -155,7 +201,7 @@ So, when readers can tolerate stale data and when entries are either added
or deleted, without in-place modification, it is very easy to use RCU!
-Example 2: Handling In-Place Updates
+Example 3: Handling In-Place Updates
The system-call auditing code does not update auditing rules in place.
However, if it did, reader-writer-locked code to do so might look as
@@ -171,7 +217,7 @@ otherwise, the added fields would need to be filled in):
struct audit_newentry *ne;
write_lock(&auditsc_lock);
- /* Note: audit_netlink_sem held by caller. */
+ /* Note: audit_filter_mutex held by caller. */
list_for_each_entry(e, list, list) {
if (!audit_compare_rule(rule, &e->rule)) {
e->rule.action = newaction;
@@ -213,13 +259,23 @@ RCU ("read-copy update") its name. The RCU code is as follows:
return -EFAULT; /* No matching rule */
}
-Again, this assumes that the caller holds audit_netlink_sem. Normally,
+Again, this assumes that the caller holds audit_filter_mutex. Normally,
the reader-writer lock would become a spinlock in this sort of code.
+Another use of this pattern can be found in the openswitch driver's "connection
+tracking table" code (ct_limit_set()). The table holds connection tracking
+entries and has a limit on the maximum entries. There is one such table
+per-zone and hence one "limit" per zone. The zones are mapped to their limits
+through a hashtable using an RCU-managed hlist for the hash chains. When a new
+limit is to be set, a new limit object is allocated and ct_limit_set() is
+called to replace the old limit object with the new one using
+list_replace_rcu(). The old limit object is then freed after a grace period
+using kfree_rcu().
+
-Example 3: Eliminating Stale Data
+Example 4: Eliminating Stale Data
-The auditing examples above tolerate stale data, as do most algorithms
+The auditing exampes above tolerates stale data, as do most algorithms
that are tracking external state. Because there is a delay from the
time the external state changes before Linux becomes aware of the change,
additional RCU-induced staleness is normally not a problem.
@@ -291,6 +347,84 @@ flag under the spinlock as follows:
}
+EXAMPLE 5: Skipping Stale Objects
+
+Stale data can also be eliminated for performance reasons since it is pointless
+to process items in a list, if the object is being destroyed. One such example
+can be found in the timerfd subsystem. When a CLOCK_REALTIME clock is
+reprogrammed - for example due to setting of the system time, then all programmed
+timerfds that depend on this clock get triggered and processes waiting on them
+to expire are woken up in advance of their scheduled expiry. To facilitate
+this, all such timers are added to a 'cancel_list' when they are setup in
+timerfd_setup_cancel:
+
+static void timerfd_setup_cancel(struct timerfd_ctx *ctx, int flags)
+{
+ spin_lock(&ctx->cancel_lock);
+ if ((ctx->clockid == CLOCK_REALTIME &&
+ (flags & TFD_TIMER_ABSTIME) && (flags & TFD_TIMER_CANCEL_ON_SET)) {
+ if (!ctx->might_cancel) {
+ ctx->might_cancel = true;
+ spin_lock(&cancel_lock);
+ list_add_rcu(&ctx->clist, &cancel_list);
+ spin_unlock(&cancel_lock);
+ }
+ }
+ spin_unlock(&ctx->cancel_lock);
+}
+
+When a timerfd is freed (fd is closed), then the might_cancel flag of the
+timerfd object is cleared, the object removed from the cancel_list and destroyed:
+
+int timerfd_release(struct inode *inode, struct file *file)
+{
+ struct timerfd_ctx *ctx = file->private_data;
+
+ spin_lock(&ctx->cancel_lock);
+ if (ctx->might_cancel) {
+ ctx->might_cancel = false;
+ spin_lock(&cancel_lock);
+ list_del_rcu(&ctx->clist);
+ spin_unlock(&cancel_lock);
+ }
+ spin_unlock(&ctx->cancel_lock);
+
+ hrtimer_cancel(&ctx->t.tmr);
+ kfree_rcu(ctx, rcu);
+ return 0;
+}
+
+If the CLOCK_REALTIME clock is set, for example by a time server, the hrtimer
+framework calls timerfd_clock_was_set() which walks the cancel_list and wakes
+up processes waiting on the timerfd. While iterating the cancel list, the
+might_cancel flag is consulted to skip stale objects:
+
+void timerfd_clock_was_set(void)
+{
+ struct timerfd_ctx *ctx;
+ unsigned long flags;
+
+ rcu_read_lock();
+ list_for_each_entry_rcu(ctx, &cancel_list, clist) {
+ if (!ctx->might_cancel)
+ continue;
+ spin_lock_irqsave(&ctx->wqh.lock, flags);
+ if (ctx->moffs != ktime_mono_to_real(0)) {
+ ctx->moffs = KTIME_MAX;
+ ctx->ticks++;
+ wake_up_locked_poll(&ctx->wqh, EPOLLIN);
+ }
+ spin_unlock_irqrestore(&ctx->wqh.lock, flags);
+ }
+ rcu_read_unlock();
+}
+
+The key point here is, because RCU-traversal of the cancel_list happens while
+objects are being added and removed to the list, sometimes the traversal can
+step on an object that has been removed from the list. In this example, it is
+seen that it is better to skip such objects using a flag.
+
+
Summary
Read-mostly list-based data structures that can tolerate stale data are
--
2.22.0.rc1.311.g5d7573a151-goog
^ 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