Commit 2d5517a5 authored by Daniele Ceraolo Spurio's avatar Daniele Ceraolo Spurio Committed by Rodrigo Vivi

drm/i915/pxp: add PXP documentation

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: default avatarDaniele Ceraolo Spurio <daniele.ceraolospurio@intel.com>
Cc: Daniel Vetter <daniel.vetter@intel.com>
Cc: Rodrigo Vivi <rodrigo.vivi@intel.com>
Reviewed-by: default avatarRodrigo Vivi <rodrigo.vivi@intel.com>
Signed-off-by: default avatarRodrigo Vivi <rodrigo.vivi@intel.com>
Link: https://patchwork.freedesktop.org/patch/msgid/20210924191452.1539378-17-alan.previn.teres.alexis@intel.com
parent 390cf1b2
......@@ -474,6 +474,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
================
......
......@@ -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);
......
......@@ -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)
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment