From b047463c852272ef9956ad3a4c706f78f8b06c17 Mon Sep 17 00:00:00 2001 From: Joonas Lahtinen Date: Fri, 30 Aug 2019 11:58:48 +0300 Subject: drm/i915: Remove link to missing "Batchbuffer Pools" documentation The referenced documentation section has been removed. Remove the link to avoid warning when building the documentation. Signed-off-by: Joonas Lahtinen Cc: Chris Wilson Cc: Matthew Auld Reviewed-by: Chris Wilson Signed-off-by: Chris Wilson Link: https://patchwork.freedesktop.org/patch/msgid/20190830085849.12519-1-joonas.lahtinen@linux.intel.com --- Documentation/gpu/i915.rst | 9 --------- 1 file changed, 9 deletions(-) (limited to 'Documentation/gpu') diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst index 3415255ad3dc..7d1f65612856 100644 --- a/Documentation/gpu/i915.rst +++ b/Documentation/gpu/i915.rst @@ -358,15 +358,6 @@ Batchbuffer Parsing .. kernel-doc:: drivers/gpu/drm/i915/i915_cmd_parser.c :internal: -Batchbuffer Pools ------------------ - -.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_batch_pool.c - :doc: batch pool - -.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_batch_pool.c - :internal: - User Batchbuffer Execution -------------------------- -- cgit v1.2.3 From 4072761b981c630acbc6195391e5a22bae114e39 Mon Sep 17 00:00:00 2001 From: Joonas Lahtinen Date: Fri, 30 Aug 2019 11:58:49 +0300 Subject: drm/i915: Indent GuC/WOPCM documentation sections Indent GuC/WOPCM documentation correctly to reside under "Memory Management and Command Submission" section to avoid it escaping to the upper level navigation. Signed-off-by: Joonas Lahtinen Cc: Michal Wajdeczko Cc: Daniele Ceraolo Spurio Cc: Chris Wilson Acked-by: Chris Wilson Signed-off-by: Chris Wilson Link: https://patchwork.freedesktop.org/patch/msgid/20190830085849.12519-2-joonas.lahtinen@linux.intel.com --- Documentation/gpu/i915.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) (limited to 'Documentation/gpu') diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst index 7d1f65612856..e249ea7b0ec7 100644 --- a/Documentation/gpu/i915.rst +++ b/Documentation/gpu/i915.rst @@ -407,31 +407,31 @@ Object Tiling IOCTLs :doc: buffer object tiling WOPCM -===== +----- WOPCM Layout ------------- +~~~~~~~~~~~~ .. kernel-doc:: drivers/gpu/drm/i915/intel_wopcm.c :doc: WOPCM Layout GuC -=== +--- Firmware Layout -------------------- +~~~~~~~~~~~~~~~ .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_uc_fw_abi.h :doc: Firmware Layout GuC-specific firmware loader ----------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc_fw.c :internal: GuC-based command submission ----------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc_submission.c :doc: GuC-based command submission @@ -440,7 +440,7 @@ GuC-based command submission :internal: GuC Address Space ------------------ +~~~~~~~~~~~~~~~~~ .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc.c :doc: GuC Address Space -- cgit v1.2.3 From 5dd85e72bc922379fec10969c9390a72aaa4746f Mon Sep 17 00:00:00 2001 From: Animesh Manna Date: Fri, 20 Sep 2019 17:29:30 +0530 Subject: drm/i915/dsb: Documentation for DSB. Added docbook info regarding Display State Buffer(DSB) which is added from gen12 onwards to batch submit display HW programming. v1: Initial version as RFC. Cc: Jani Nikula Cc: Rodrigo Vivi Cc: Shashank Sharma Reviewed-by: Shashank Sharma Signed-off-by: Animesh Manna Signed-off-by: Jani Nikula Link: https://patchwork.freedesktop.org/patch/msgid/20190920115930.27829-11-animesh.manna@intel.com --- Documentation/gpu/i915.rst | 9 +++++ drivers/gpu/drm/i915/display/intel_dsb.c | 68 ++++++++++++++++++++++++++++++++ 2 files changed, 77 insertions(+) (limited to 'Documentation/gpu') diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst index e249ea7b0ec7..465779670fd4 100644 --- a/Documentation/gpu/i915.rst +++ b/Documentation/gpu/i915.rst @@ -246,6 +246,15 @@ Display PLLs .. kernel-doc:: drivers/gpu/drm/i915/display/intel_dpll_mgr.h :internal: +Display State Buffer +-------------------- + +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dsb.c + :doc: DSB + +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dsb.c + :internal: + Memory Management and Command Submission ======================================== diff --git a/drivers/gpu/drm/i915/display/intel_dsb.c b/drivers/gpu/drm/i915/display/intel_dsb.c index f4c0b37683a5..0a0a1536ac96 100644 --- a/drivers/gpu/drm/i915/display/intel_dsb.c +++ b/drivers/gpu/drm/i915/display/intel_dsb.c @@ -9,6 +9,23 @@ #define DSB_BUF_SIZE (2 * PAGE_SIZE) +/** + * DOC: DSB + * + * A DSB (Display State Buffer) is a queue of MMIO instructions in the memory + * which can be offloaded to DSB HW in Display Controller. DSB HW is a DMA + * engine that can be programmed to download the DSB from memory. + * It allows driver to batch submit display HW programming. This helps to + * reduce loading time and CPU activity, thereby making the context switch + * faster. DSB Support added from Gen12 Intel graphics based platform. + * + * DSB's can access only the pipe, plane, and transcoder Data Island Packet + * registers. + * + * DSB HW can support only register writes (both indexed and direct MMIO + * writes). There are no registers reads possible with DSB HW engine. + */ + /* DSB opcodes. */ #define DSB_OPCODE_SHIFT 24 #define DSB_OPCODE_MMIO_WRITE 0x1 @@ -66,6 +83,17 @@ static inline bool intel_dsb_disable_engine(struct intel_dsb *dsb) return true; } +/** + * intel_dsb_get() - Allocate DSB context and return a DSB instance. + * @crtc: intel_crtc structure to get pipe info. + * + * This function provides handle of a DSB instance, for the further DSB + * operations. + * + * Returns: address of Intel_dsb instance requested for. + * Failure: Returns the same DSB instance, but without a command buffer. + */ + struct intel_dsb * intel_dsb_get(struct intel_crtc *crtc) { @@ -116,6 +144,14 @@ err: return dsb; } +/** + * intel_dsb_put() - To destroy DSB context. + * @dsb: intel_dsb structure. + * + * This function destroys the DSB context allocated by a dsb_get(), by + * unpinning and releasing the VMA object associated with it. + */ + void intel_dsb_put(struct intel_dsb *dsb) { struct intel_crtc *crtc = container_of(dsb, typeof(*crtc), dsb); @@ -138,6 +174,19 @@ void intel_dsb_put(struct intel_dsb *dsb) } } +/** + * intel_dsb_indexed_reg_write() -Write to the DSB context for auto + * increment register. + * @dsb: intel_dsb structure. + * @reg: register address. + * @val: value. + * + * This function is used for writing register-value pair in command + * buffer of DSB for auto-increment register. During command buffer overflow, + * a warning is thrown and rest all erroneous condition register programming + * is done through mmio write. + */ + void intel_dsb_indexed_reg_write(struct intel_dsb *dsb, i915_reg_t reg, u32 val) { @@ -202,6 +251,18 @@ void intel_dsb_indexed_reg_write(struct intel_dsb *dsb, i915_reg_t reg, buf[dsb->free_pos] = 0; } +/** + * intel_dsb_reg_write() -Write to the DSB context for normal + * register. + * @dsb: intel_dsb structure. + * @reg: register address. + * @val: value. + * + * This function is used for writing register-value pair in command + * buffer of DSB. During command buffer overflow, a warning is thrown + * and rest all erroneous condition register programming is done + * through mmio write. + */ void intel_dsb_reg_write(struct intel_dsb *dsb, i915_reg_t reg, u32 val) { struct intel_crtc *crtc = container_of(dsb, typeof(*crtc), dsb); @@ -225,6 +286,13 @@ void intel_dsb_reg_write(struct intel_dsb *dsb, i915_reg_t reg, u32 val) i915_mmio_reg_offset(reg); } +/** + * intel_dsb_commit() - Trigger workload execution of DSB. + * @dsb: intel_dsb structure. + * + * This function is used to do actual write to hardware using DSB. + * On errors, fall back to MMIO. Also this function help to reset the context. + */ void intel_dsb_commit(struct intel_dsb *dsb) { struct intel_crtc *crtc = container_of(dsb, typeof(*crtc), dsb); -- cgit v1.2.3 From 493065e24eb13cf1e974ef9fc0185d6266d16067 Mon Sep 17 00:00:00 2001 From: Daniele Ceraolo Spurio Date: Mon, 14 Oct 2019 11:36:00 -0700 Subject: drm/i915: Add microcontrollers documentation section To better organize the information, add a microcontrollers section and move/link the GuC, HuC and DMC documentation under it. Also add a small intro. Signed-off-by: Daniele Ceraolo Spurio Cc: Michal Wajdeczko Acked-by: Anna Karas Reviewed-by: Martin Peres Link: https://patchwork.freedesktop.org/patch/msgid/20191014183602.3643-1-daniele.ceraolospurio@intel.com --- Documentation/gpu/i915.rst | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) (limited to 'Documentation/gpu') diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst index 465779670fd4..f1bae7867045 100644 --- a/Documentation/gpu/i915.rst +++ b/Documentation/gpu/i915.rst @@ -415,6 +415,15 @@ Object Tiling IOCTLs .. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_tiling.c :doc: buffer object tiling +Microcontrollers +================ + +Starting from gen9, three microcontrollers are available on the HW: the +graphics microcontroller (GuC), the HEVC/H.265 microcontroller (HuC) and the +display microcontroller (DMC). The driver is responsible for loading the +firmwares on the microcontrollers; the GuC and HuC firmwares are transferred +to WOPCM using the DMA engine, while the DMC firmware is written through MMIO. + WOPCM ----- @@ -454,6 +463,15 @@ GuC Address Space .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc.c :doc: GuC Address Space +HuC +--- +.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_huc_fw.c + :doc: HuC Firmware + +DMC +--- +See `CSR firmware support for DMC`_ + Tracing ======= -- cgit v1.2.3 From 218151e997449717cbb70f304b7b8f9918ba6af4 Mon Sep 17 00:00:00 2001 From: Daniele Ceraolo Spurio Date: Mon, 14 Oct 2019 11:36:01 -0700 Subject: drm/i915/guc: improve documentation Add a short description of what we expect from GuC and some minor improvements to existing documentation. Also remove a comment about a difference between GuC and HuC that is not true anymore. v2: add that the GuC is not mandatory (Martin) v3: add extra newline for better text organization (Martin) Signed-off-by: Daniele Ceraolo Spurio Cc: Michal Wajdeczko Cc: Matthew Brost Cc: Martin Peres Acked-by: Anna Karas Reviewed-by: Martin Peres Link: https://patchwork.freedesktop.org/patch/msgid/20191014183602.3643-2-daniele.ceraolospurio@intel.com --- Documentation/gpu/i915.rst | 22 ++++++++++------ drivers/gpu/drm/i915/gt/uc/intel_guc.c | 31 +++++++++++++++++++++-- drivers/gpu/drm/i915/gt/uc/intel_guc_submission.c | 6 +++++ drivers/gpu/drm/i915/gt/uc/intel_uc_fw_abi.h | 3 --- 4 files changed, 49 insertions(+), 13 deletions(-) (limited to 'Documentation/gpu') diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst index f1bae7867045..357e9dfa7de1 100644 --- a/Documentation/gpu/i915.rst +++ b/Documentation/gpu/i915.rst @@ -436,12 +436,24 @@ WOPCM Layout GuC --- -Firmware Layout -~~~~~~~~~~~~~~~ +.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc.c + :doc: GuC + +GuC Firmware Layout +~~~~~~~~~~~~~~~~~~~ .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_uc_fw_abi.h :doc: Firmware Layout +GuC Memory Management +~~~~~~~~~~~~~~~~~~~~~ + +.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc.c + :doc: GuC Memory Management +.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc.c + :functions: intel_guc_allocate_vma + + GuC-specific firmware loader ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -457,12 +469,6 @@ GuC-based command submission .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc_submission.c :internal: -GuC Address Space -~~~~~~~~~~~~~~~~~ - -.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc.c - :doc: GuC Address Space - HuC --- .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_huc_fw.c diff --git a/drivers/gpu/drm/i915/gt/uc/intel_guc.c b/drivers/gpu/drm/i915/gt/uc/intel_guc.c index 249c747e9756..37f7bcbf7dac 100644 --- a/drivers/gpu/drm/i915/gt/uc/intel_guc.c +++ b/drivers/gpu/drm/i915/gt/uc/intel_guc.c @@ -9,6 +9,27 @@ #include "intel_guc_submission.h" #include "i915_drv.h" +/** + * DOC: GuC + * + * The GuC is a microcontroller inside the GT HW, introduced in gen9. The GuC is + * designed to offload some of the functionality usually performed by the host + * driver; currently the main operations it can take care of are: + * + * - Authentication of the HuC, which is required to fully enable HuC usage. + * - Low latency graphics context scheduling (a.k.a. GuC submission). + * - GT Power management. + * + * The enable_guc module parameter can be used to select which of those + * operations to enable within GuC. Note that not all the operations are + * supported on all gen9+ platforms. + * + * Enabling the GuC is not mandatory and therefore the firmware is only loaded + * if at least one of the operations is selected. However, not loading the GuC + * might result in the loss of some features that do require the GuC (currently + * just the HuC, but more are expected to land in the future). + */ + static void gen8_guc_raise_irq(struct intel_guc *guc) { struct intel_gt *gt = guc_to_gt(guc); @@ -548,9 +569,15 @@ int intel_guc_resume(struct intel_guc *guc) } /** - * DOC: GuC Address Space + * DOC: GuC Memory Management * - * The layout of GuC address space is shown below: + * GuC can't allocate any memory for its own usage, so all the allocations must + * be handled by the host driver. GuC accesses the memory via the GGTT, with the + * exception of the top and bottom parts of the 4GB address space, which are + * instead re-mapped by the GuC HW to memory location of the FW itself (WOPCM) + * or other parts of the HW. The driver must take care not to place objects that + * the GuC is going to access in these reserved ranges. The layout of the GuC + * address space is shown below: * * :: * diff --git a/drivers/gpu/drm/i915/gt/uc/intel_guc_submission.c b/drivers/gpu/drm/i915/gt/uc/intel_guc_submission.c index f325d3dd564f..849a44add424 100644 --- a/drivers/gpu/drm/i915/gt/uc/intel_guc_submission.c +++ b/drivers/gpu/drm/i915/gt/uc/intel_guc_submission.c @@ -29,6 +29,12 @@ enum { /** * DOC: GuC-based command submission * + * IMPORTANT NOTE: GuC submission is currently not supported in i915. The GuC + * firmware is moving to an updated submission interface and we plan to + * turn submission back on when that lands. The below documentation (and related + * code) matches the old submission model and will be updated as part of the + * upgrade to the new flow. + * * GuC client: * A intel_guc_client refers to a submission path through GuC. Currently, there * is only one client, which is charged with all submissions to the GuC. This diff --git a/drivers/gpu/drm/i915/gt/uc/intel_uc_fw_abi.h b/drivers/gpu/drm/i915/gt/uc/intel_uc_fw_abi.h index f8f6c91a0df6..029214cdedd5 100644 --- a/drivers/gpu/drm/i915/gt/uc/intel_uc_fw_abi.h +++ b/drivers/gpu/drm/i915/gt/uc/intel_uc_fw_abi.h @@ -39,9 +39,6 @@ * 3. Length info of each component can be found in header, in dwords. * 4. Modulus and exponent key are not required by driver. They may not appear * in fw. So driver will load a truncated firmware in this case. - * - * The only difference between GuC and HuC firmwares is how the version - * information is saved. */ struct uc_css_header { -- cgit v1.2.3 From 0b23e2a6ed5cb1196dae7d34c5910193d86244a9 Mon Sep 17 00:00:00 2001 From: Daniele Ceraolo Spurio Date: Mon, 14 Oct 2019 11:36:02 -0700 Subject: drm/i915/huc: improve documentation Better explain the usage of the microcontroller and what i915 is responsible of. While at it, fix the documentation for the auth function, which doesn't do any pinning anymore. v2: add a comment on HuC being optional and descrive how HuC accesses memory (Martin) v3: add extra newline for better text organization (Martin) Signed-off-by: Daniele Ceraolo Spurio Cc: Michal Wajdeczko Cc: Martin Peres Acked-by: Anna Karas Reviewed-by: Martin Peres Link: https://patchwork.freedesktop.org/patch/msgid/20191014183602.3643-3-daniele.ceraolospurio@intel.com --- Documentation/gpu/i915.rst | 16 ++++++++++++-- drivers/gpu/drm/i915/gt/uc/intel_huc.c | 35 +++++++++++++++++++++++++++---- drivers/gpu/drm/i915/gt/uc/intel_huc_fw.c | 15 ------------- 3 files changed, 45 insertions(+), 21 deletions(-) (limited to 'Documentation/gpu') diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst index 357e9dfa7de1..60bd6e6403da 100644 --- a/Documentation/gpu/i915.rst +++ b/Documentation/gpu/i915.rst @@ -471,8 +471,20 @@ GuC-based command submission HuC --- -.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_huc_fw.c - :doc: HuC Firmware +.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_huc.c + :doc: HuC +.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_huc.c + :functions: intel_huc_auth + +HuC Memory Management +~~~~~~~~~~~~~~~~~~~~~ + +.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_huc.c + :doc: HuC Memory Management + +HuC Firmware Layout +~~~~~~~~~~~~~~~~~~~ +The HuC FW layout is the same as the GuC one, see `GuC Firmware Layout`_ DMC --- diff --git a/drivers/gpu/drm/i915/gt/uc/intel_huc.c b/drivers/gpu/drm/i915/gt/uc/intel_huc.c index 33608a114d4e..8be515c8d0f0 100644 --- a/drivers/gpu/drm/i915/gt/uc/intel_huc.c +++ b/drivers/gpu/drm/i915/gt/uc/intel_huc.c @@ -9,6 +9,34 @@ #include "intel_huc.h" #include "i915_drv.h" +/** + * DOC: HuC + * + * The HuC is a dedicated microcontroller for usage in media HEVC (High + * Efficiency Video Coding) operations. Userspace can directly use the firmware + * capabilities by adding HuC specific commands to batch buffers. + * + * The kernel driver is only responsible for loading the HuC firmware and + * triggering its security authentication, which is performed by the GuC. For + * The GuC to correctly perform the authentication, the HuC binary must be + * loaded before the GuC one. Loading the HuC is optional; however, not using + * the HuC might negatively impact power usage and/or performance of media + * workloads, depending on the use-cases. + * + * See https://github.com/intel/media-driver for the latest details on HuC + * functionality. + */ + +/** + * DOC: HuC Memory Management + * + * Similarly to the GuC, the HuC can't do any memory allocations on its own, + * with the difference being that the allocations for HuC usage are handled by + * the userspace driver instead of the kernel one. The HuC accesses the memory + * via the PPGTT belonging to the context loaded on the VCS executing the + * HuC-specific commands. + */ + void intel_huc_init_early(struct intel_huc *huc) { struct drm_i915_private *i915 = huc_to_gt(huc)->i915; @@ -118,10 +146,9 @@ void intel_huc_fini(struct intel_huc *huc) * * Called after HuC and GuC firmware loading during intel_uc_init_hw(). * - * This function pins HuC firmware image object into GGTT. - * Then it invokes GuC action to authenticate passing the offset to RSA - * signature through intel_guc_auth_huc(). It then waits for 50ms for - * firmware verification ACK and unpins the object. + * This function invokes the GuC action to authenticate the HuC firmware, + * passing the offset of the RSA signature to intel_guc_auth_huc(). It then + * waits for up to 50ms for firmware verification ACK. */ int intel_huc_auth(struct intel_huc *huc) { diff --git a/drivers/gpu/drm/i915/gt/uc/intel_huc_fw.c b/drivers/gpu/drm/i915/gt/uc/intel_huc_fw.c index 74602487ed67..d654340d4d03 100644 --- a/drivers/gpu/drm/i915/gt/uc/intel_huc_fw.c +++ b/drivers/gpu/drm/i915/gt/uc/intel_huc_fw.c @@ -7,21 +7,6 @@ #include "intel_huc_fw.h" #include "i915_drv.h" -/** - * DOC: HuC Firmware - * - * Motivation: - * GEN9 introduces a new dedicated firmware for usage in media HEVC (High - * Efficiency Video Coding) operations. Userspace can use the firmware - * capabilities by adding HuC specific commands to batch buffers. - * - * Implementation: - * The same firmware loader is used as the GuC. However, the actual - * loading to HW is deferred until GEM initialization is done. - * - * Note that HuC firmware loading must be done before GuC loading. - */ - /** * intel_huc_fw_init_early() - initializes HuC firmware struct * @huc: intel_huc struct -- cgit v1.2.3