From: Alan Previn <alan.previn.teres.alexis@intel.com>
To: intel-gfx@lists.freedesktop.org
Cc: Daniele Ceraolo Spurio <daniele.ceraolospurio@intel.com>,
Daniel Vetter <daniel.vetter@intel.com>,
Rodrigo Vivi <rodrigo.vivi@intel.com>
Subject: [Intel-gfx] [PATCH v13 16/17] drm/i915/pxp: add PXP documentation
Date: Fri, 24 Sep 2021 12:14:51 -0700 [thread overview]
Message-ID: <20210924191452.1539378-17-alan.previn.teres.alexis@intel.com> (raw)
In-Reply-To: <20210924191452.1539378-1-alan.previn.teres.alexis@intel.com>
From: Daniele Ceraolo Spurio <daniele.ceraolospurio@intel.com>
Now that all the pieces are in place we can add a description of how the
feature works. Also modify the comments in struct intel_pxp into
kerneldoc.
v2: improve doc (Rodrigo)
Signed-off-by: Daniele Ceraolo Spurio <daniele.ceraolospurio@intel.com>
Cc: Daniel Vetter <daniel.vetter@intel.com>
Cc: Rodrigo Vivi <rodrigo.vivi@intel.com>
Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>
---
Documentation/gpu/i915.rst | 8 ++++
drivers/gpu/drm/i915/pxp/intel_pxp.c | 28 +++++++++++++
drivers/gpu/drm/i915/pxp/intel_pxp_types.h | 47 ++++++++++++++++------
3 files changed, 71 insertions(+), 12 deletions(-)
diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
index 311e10400708..b7d801993bfa 100644
--- a/Documentation/gpu/i915.rst
+++ b/Documentation/gpu/i915.rst
@@ -471,6 +471,14 @@ Object Tiling IOCTLs
.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_tiling.c
:doc: buffer object tiling
+Protected Objects
+-----------------
+
+.. kernel-doc:: drivers/gpu/drm/i915/pxp/intel_pxp.c
+ :doc: PXP
+
+.. kernel-doc:: drivers/gpu/drm/i915/pxp/intel_pxp_types.h
+
Microcontrollers
================
diff --git a/drivers/gpu/drm/i915/pxp/intel_pxp.c b/drivers/gpu/drm/i915/pxp/intel_pxp.c
index b85b72f12726..e2314ad9546d 100644
--- a/drivers/gpu/drm/i915/pxp/intel_pxp.c
+++ b/drivers/gpu/drm/i915/pxp/intel_pxp.c
@@ -11,6 +11,34 @@
#include "gt/intel_context.h"
#include "i915_drv.h"
+/**
+ * DOC: PXP
+ *
+ * PXP (Protected Xe Path) is a feature available in Gen12 and newer platforms.
+ * It allows execution and flip to display of protected (i.e. encrypted)
+ * objects. The SW support is enabled via the CONFIG_DRM_I915_PXP kconfig.
+ *
+ * Objects can opt-in to PXP encryption at creation time via the
+ * I915_GEM_CREATE_EXT_PROTECTED_CONTENT create_ext flag. For objects to be
+ * correctly protected they must be used in conjunction with a context created
+ * with the I915_CONTEXT_PARAM_PROTECTED_CONTENT flag. See the documentation
+ * of those two uapi flags for details and restrictions.
+ *
+ * Protected objects are tied to a pxp session; currently we only support one
+ * session, which i915 manages and whose index is available in the uapi
+ * (I915_PROTECTED_CONTENT_DEFAULT_SESSION) for use in instructions targeting
+ * protected objects.
+ * The session is invalidated by the HW when certain events occur (e.g.
+ * suspend/resume). When this happens, all the objects that were used with the
+ * session are marked as invalid and all contexts marked as using protected
+ * content are banned. Any further attempt at using them in an execbuf call is
+ * rejected, while flips are converted to black frames.
+ *
+ * Some of the PXP setup operations are performed by the Management Engine,
+ * which is handled by the mei driver; communication between i915 and mei is
+ * performed via the mei_pxp component module.
+ */
+
struct intel_gt *pxp_to_gt(const struct intel_pxp *pxp)
{
return container_of(pxp, struct intel_gt, pxp);
diff --git a/drivers/gpu/drm/i915/pxp/intel_pxp_types.h b/drivers/gpu/drm/i915/pxp/intel_pxp_types.h
index ae24064bb57e..73ef7d1754e1 100644
--- a/drivers/gpu/drm/i915/pxp/intel_pxp_types.h
+++ b/drivers/gpu/drm/i915/pxp/intel_pxp_types.h
@@ -16,42 +16,65 @@
struct intel_context;
struct i915_pxp_component;
+/**
+ * struct intel_pxp - pxp state
+ */
struct intel_pxp {
+ /**
+ * @pxp_component: i915_pxp_component struct of the bound mei_pxp
+ * module. Only set and cleared inside component bind/unbind functions,
+ * which are protected by &tee_mutex.
+ */
struct i915_pxp_component *pxp_component;
+ /**
+ * @pxp_component_added: track if the pxp component has been added.
+ * Set and cleared in tee init and fini functions respectively.
+ */
bool pxp_component_added;
+ /** @ce: kernel-owned context used for PXP operations */
struct intel_context *ce;
- /*
+ /** @arb_mutex: protects arb session start */
+ struct mutex arb_mutex;
+ /**
+ * @arb_is_valid: tracks arb session status.
* After a teardown, the arb session can still be in play on the HW
* even if the keys are gone, so we can't rely on the HW state of the
* session to know if it's valid and need to track the status in SW.
*/
- struct mutex arb_mutex; /* protects arb session start */
bool arb_is_valid;
- /*
- * Keep track of which key instance we're on, so we can use it to
- * determine if an object was created using the current key or a
+ /**
+ * @key_instance: tracks which key instance we're on, so we can use it
+ * to determine if an object was created using the current key or a
* previous one.
*/
u32 key_instance;
- struct mutex tee_mutex; /* protects the tee channel binding */
+ /** @tee_mutex: protects the tee channel binding and messaging. */
+ struct mutex tee_mutex;
- /*
- * If the HW perceives an attack on the integrity of the encryption it
- * will invalidate the keys and expect SW to re-initialize the session.
- * We keep track of this state to make sure we only re-start the arb
- * session when required.
+ /**
+ * @hw_state_invalidated: if the HW perceives an attack on the integrity
+ * of the encryption it will invalidate the keys and expect SW to
+ * re-initialize the session. We keep track of this state to make sure
+ * we only re-start the arb session when required.
*/
bool hw_state_invalidated;
+ /** @irq_enabled: tracks the status of the kcr irqs */
bool irq_enabled;
+ /**
+ * @termination: tracks the status of a pending termination. Only
+ * re-initialized under gt->irq_lock and completed in &session_work.
+ */
struct completion termination;
+ /** @session_work: worker that manages session events. */
struct work_struct session_work;
- u32 session_events; /* protected with gt->irq_lock */
+ /** @session_events: pending session events, protected with gt->irq_lock. */
+ u32 session_events;
#define PXP_TERMINATION_REQUEST BIT(0)
#define PXP_TERMINATION_COMPLETE BIT(1)
#define PXP_INVAL_REQUIRED BIT(2)
--
2.25.1
next prev parent reply other threads:[~2021-09-24 19:15 UTC|newest]
Thread overview: 22+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-09-24 19:14 [Intel-gfx] [PATCH v13 00/17] drm/i915: Introduce Intel PXP Alan Previn
2021-09-24 19:14 ` [Intel-gfx] [PATCH v13 01/17] drm/i915/pxp: Define PXP component interface Alan Previn
2021-09-24 19:14 ` [Intel-gfx] [PATCH v13 02/17] mei: pxp: export pavp client to me client bus Alan Previn
2021-09-24 19:14 ` [Intel-gfx] [PATCH v13 03/17] drm/i915/pxp: define PXP device flag and kconfig Alan Previn
2021-09-24 19:14 ` [Intel-gfx] [PATCH v13 04/17] drm/i915/pxp: allocate a vcs context for pxp usage Alan Previn
2021-09-24 19:14 ` [Intel-gfx] [PATCH v13 05/17] drm/i915/pxp: Implement funcs to create the TEE channel Alan Previn
2021-09-24 19:14 ` [Intel-gfx] [PATCH v13 06/17] drm/i915/pxp: set KCR reg init Alan Previn
2021-09-24 19:14 ` [Intel-gfx] [PATCH v13 07/17] drm/i915/pxp: Create the arbitrary session after boot Alan Previn
2021-09-24 19:14 ` [Intel-gfx] [PATCH v13 08/17] drm/i915/pxp: Implement arb session teardown Alan Previn
2021-09-24 19:14 ` [Intel-gfx] [PATCH v13 09/17] drm/i915/pxp: Implement PXP irq handler Alan Previn
2021-09-24 19:14 ` [Intel-gfx] [PATCH v13 10/17] drm/i915/pxp: interfaces for using protected objects Alan Previn
2021-09-24 19:14 ` [Intel-gfx] [PATCH v13 11/17] drm/i915/pxp: start the arb session on demand Alan Previn
2021-09-24 19:14 ` [Intel-gfx] [PATCH v13 12/17] drm/i915/pxp: Enable PXP power management Alan Previn
2021-09-24 19:14 ` [Intel-gfx] [PATCH v13 13/17] drm/i915/pxp: Add plane decryption support Alan Previn
2021-09-24 19:14 ` [Intel-gfx] [PATCH v13 14/17] drm/i915/pxp: black pixels on pxp disabled Alan Previn
2021-09-24 19:14 ` [Intel-gfx] [PATCH v13 15/17] drm/i915/pxp: add pxp debugfs Alan Previn
2021-09-24 19:14 ` Alan Previn [this message]
2021-09-24 19:14 ` [Intel-gfx] [PATCH v13 17/17] drm/i915/pxp: enable PXP for integrated Gen12 Alan Previn
2021-09-24 22:05 ` [Intel-gfx] ✗ Fi.CI.CHECKPATCH: warning for drm/i915: Introduce Intel PXP (rev13) Patchwork
2021-09-24 22:06 ` [Intel-gfx] ✗ Fi.CI.SPARSE: " Patchwork
2021-09-24 22:34 ` [Intel-gfx] ✓ Fi.CI.BAT: success " Patchwork
2021-09-25 2:39 ` [Intel-gfx] ✓ Fi.CI.IGT: " Patchwork
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20210924191452.1539378-17-alan.previn.teres.alexis@intel.com \
--to=alan.previn.teres.alexis@intel.com \
--cc=daniel.vetter@intel.com \
--cc=daniele.ceraolospurio@intel.com \
--cc=intel-gfx@lists.freedesktop.org \
--cc=rodrigo.vivi@intel.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).