* [PATCH v3] amdgpu: Add initial kernel documentation for the amd_ip_block_type structure
@ 2020-09-21 15:54 Ryan Taylor
2020-09-22 15:20 ` Alex Deucher
0 siblings, 1 reply; 2+ messages in thread
From: Ryan Taylor @ 2020-09-21 15:54 UTC (permalink / raw)
To: amd-gfx; +Cc: Alex Deucher, Ryan Taylor
From: Ryan Taylor <Ryan.Taylor@amd.com>
Added IP block section to amdgpu.rst.
Added more documentation to amd_ip_funcs.
Created documentation for amd_ip_block_type.
v2: Provides a more detailed DOC section on IP blocks.
v3: Clarifies the IP block list. Adds info on IP block enumeration.
Signed-off-by: Ryan Taylor <ryan.taylor@amd.com>
Reviewed-by: Alex Deucher <alexander.deucher@amd.com>
---
Documentation/gpu/amdgpu.rst | 9 +++
drivers/gpu/drm/amd/include/amd_shared.h | 87 +++++++++++++++++-------
2 files changed, 71 insertions(+), 25 deletions(-)
diff --git a/Documentation/gpu/amdgpu.rst b/Documentation/gpu/amdgpu.rst
index 29ca5f5feb35..57047dcb8d19 100644
--- a/Documentation/gpu/amdgpu.rst
+++ b/Documentation/gpu/amdgpu.rst
@@ -70,6 +70,15 @@ Interrupt Handling
.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_irq.c
:internal:
+IP Blocks
+------------------
+
+.. kernel-doc:: drivers/gpu/drm/amd/include/amd_shared.h
+ :doc: IP Blocks
+
+.. kernel-doc:: drivers/gpu/drm/amd/include/amd_shared.h
+ :identifiers: amd_ip_block_type amd_ip_funcs
+
AMDGPU XGMI Support
===================
diff --git a/drivers/gpu/drm/amd/include/amd_shared.h b/drivers/gpu/drm/amd/include/amd_shared.h
index e98c84ef206f..6b8a40051f41 100644
--- a/drivers/gpu/drm/amd/include/amd_shared.h
+++ b/drivers/gpu/drm/amd/include/amd_shared.h
@@ -47,6 +47,40 @@ enum amd_apu_flags {
AMD_APU_IS_RENOIR = 0x00000008UL,
};
+/**
+* DOC: IP Blocks
+*
+* GPUs are composed of IP (intellectual property) blocks. These
+* IP blocks provide various functionalities: display, graphics,
+* video decode, etc. The IP blocks that comprise a particular GPU
+* are listed in the GPU's respective SoC file. amdgpu_device.c
+* acquires the list of IP blocks for the GPU in use on initialization.
+* It can then operate on this list to perform standard driver operations
+* such as: init, fini, suspend, resume, etc.
+*
+*
+* IP block implementations are named using the following convention:
+* <functionality>_v<version> (E.g.: gfx_v6_0).
+*/
+
+/**
+* enum amd_ip_block_type - Used to classify IP blocks by functionality.
+*
+* @AMD_IP_BLOCK_TYPE_COMMON: GPU Family
+* @AMD_IP_BLOCK_TYPE_GMC: Graphics Memory Controller
+* @AMD_IP_BLOCK_TYPE_IH: Interrupt Handler
+* @AMD_IP_BLOCK_TYPE_SMC: System Management Controller
+* @AMD_IP_BLOCK_TYPE_PSP: Platform Security Processor
+* @AMD_IP_BLOCK_TYPE_DCE: Display and Compositing Engine
+* @AMD_IP_BLOCK_TYPE_GFX: Graphics and Compute Engine
+* @AMD_IP_BLOCK_TYPE_SDMA: System DMA Engine
+* @AMD_IP_BLOCK_TYPE_UVD: Unified Video Decoder
+* @AMD_IP_BLOCK_TYPE_VCE: Video Compression Engine
+* @AMD_IP_BLOCK_TYPE_ACP: Audio Co-Processor
+* @AMD_IP_BLOCK_TYPE_VCN: Video Core/Codec Next
+* @AMD_IP_BLOCK_TYPE_MES: Micro-Engine Scheduler
+* @AMD_IP_BLOCK_TYPE_JPEG: JPEG Engine
+*/
enum amd_ip_block_type {
AMD_IP_BLOCK_TYPE_COMMON,
AMD_IP_BLOCK_TYPE_GMC,
@@ -165,56 +199,59 @@ enum DC_DEBUG_MASK {
};
enum amd_dpm_forced_level;
+
/**
* struct amd_ip_funcs - general hooks for managing amdgpu IP Blocks
+ * @name: Name of IP block
+ * @early_init: sets up early driver state (pre sw_init),
+ * does not configure hw - Optional
+ * @late_init: sets up late driver/hw state (post hw_init) - Optional
+ * @sw_init: sets up driver state, does not configure hw
+ * @sw_fini: tears down driver state, does not configure hw
+ * @hw_init: sets up the hw state
+ * @hw_fini: tears down the hw state
+ * @late_fini: final cleanup
+ * @suspend: handles IP specific hw/sw changes for suspend
+ * @resume: handles IP specific hw/sw changes for resume
+ * @is_idle: returns current IP block idle status
+ * @wait_for_idle: poll for idle
+ * @check_soft_reset: check soft reset the IP block
+ * @pre_soft_reset: pre soft reset the IP block
+ * @soft_reset: soft reset the IP block
+ * @post_soft_reset: post soft reset the IP block
+ * @set_clockgating_state: enable/disable cg for the IP block
+ * @set_powergating_state: enable/disable pg for the IP block
+ * @get_clockgating_state: get current clockgating status
+ * @enable_umd_pstate: enable UMD powerstate
+ *
+ * These hooks provide an interface for controlling the operational state
+ * of IP blocks. After acquiring a list of IP blocks for the GPU in use,
+ * the driver can make chip-wide state changes by walking this list and
+ * making calls to hooks from each IP block. This list is ordered to ensure
+ * that the driver initializes the IP blocks in a safe sequence.
*/
struct amd_ip_funcs {
- /** @name: Name of IP block */
char *name;
- /**
- * @early_init:
- *
- * sets up early driver state (pre sw_init),
- * does not configure hw - Optional
- */
int (*early_init)(void *handle);
- /** @late_init: sets up late driver/hw state (post hw_init) - Optional */
int (*late_init)(void *handle);
- /** @sw_init: sets up driver state, does not configure hw */
int (*sw_init)(void *handle);
- /** @sw_fini: tears down driver state, does not configure hw */
int (*sw_fini)(void *handle);
- /** @hw_init: sets up the hw state */
int (*hw_init)(void *handle);
- /** @hw_fini: tears down the hw state */
int (*hw_fini)(void *handle);
- /** @late_fini: final cleanup */
void (*late_fini)(void *handle);
- /** @suspend: handles IP specific hw/sw changes for suspend */
int (*suspend)(void *handle);
- /** @resume: handles IP specific hw/sw changes for resume */
int (*resume)(void *handle);
- /** @is_idle: returns current IP block idle status */
bool (*is_idle)(void *handle);
- /** @wait_for_idle: poll for idle */
int (*wait_for_idle)(void *handle);
- /** @check_soft_reset: check soft reset the IP block */
bool (*check_soft_reset)(void *handle);
- /** @pre_soft_reset: pre soft reset the IP block */
int (*pre_soft_reset)(void *handle);
- /** @soft_reset: soft reset the IP block */
int (*soft_reset)(void *handle);
- /** @post_soft_reset: post soft reset the IP block */
int (*post_soft_reset)(void *handle);
- /** @set_clockgating_state: enable/disable cg for the IP block */
int (*set_clockgating_state)(void *handle,
enum amd_clockgating_state state);
- /** @set_powergating_state: enable/disable pg for the IP block */
int (*set_powergating_state)(void *handle,
enum amd_powergating_state state);
- /** @get_clockgating_state: get current clockgating status */
void (*get_clockgating_state)(void *handle, u32 *flags);
- /** @enable_umd_pstate: enable UMD powerstate */
int (*enable_umd_pstate)(void *handle, enum amd_dpm_forced_level *level);
};
--
2.28.0
_______________________________________________
amd-gfx mailing list
amd-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/amd-gfx
^ permalink raw reply related [flat|nested] 2+ messages in thread
* Re: [PATCH v3] amdgpu: Add initial kernel documentation for the amd_ip_block_type structure
2020-09-21 15:54 [PATCH v3] amdgpu: Add initial kernel documentation for the amd_ip_block_type structure Ryan Taylor
@ 2020-09-22 15:20 ` Alex Deucher
0 siblings, 0 replies; 2+ messages in thread
From: Alex Deucher @ 2020-09-22 15:20 UTC (permalink / raw)
To: Ryan Taylor; +Cc: Alex Deucher, amd-gfx list
On Mon, Sep 21, 2020 at 11:55 AM Ryan Taylor <ryan.taylor@amd.com> wrote:
>
> From: Ryan Taylor <Ryan.Taylor@amd.com>
>
> Added IP block section to amdgpu.rst.
> Added more documentation to amd_ip_funcs.
> Created documentation for amd_ip_block_type.
>
> v2: Provides a more detailed DOC section on IP blocks.
> v3: Clarifies the IP block list. Adds info on IP block enumeration.
>
> Signed-off-by: Ryan Taylor <ryan.taylor@amd.com>
> Reviewed-by: Alex Deucher <alexander.deucher@amd.com>
Looks good. Feel free to commit it.
Thanks!
Alex
> ---
> Documentation/gpu/amdgpu.rst | 9 +++
> drivers/gpu/drm/amd/include/amd_shared.h | 87 +++++++++++++++++-------
> 2 files changed, 71 insertions(+), 25 deletions(-)
>
> diff --git a/Documentation/gpu/amdgpu.rst b/Documentation/gpu/amdgpu.rst
> index 29ca5f5feb35..57047dcb8d19 100644
> --- a/Documentation/gpu/amdgpu.rst
> +++ b/Documentation/gpu/amdgpu.rst
> @@ -70,6 +70,15 @@ Interrupt Handling
> .. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_irq.c
> :internal:
>
> +IP Blocks
> +------------------
> +
> +.. kernel-doc:: drivers/gpu/drm/amd/include/amd_shared.h
> + :doc: IP Blocks
> +
> +.. kernel-doc:: drivers/gpu/drm/amd/include/amd_shared.h
> + :identifiers: amd_ip_block_type amd_ip_funcs
> +
> AMDGPU XGMI Support
> ===================
>
> diff --git a/drivers/gpu/drm/amd/include/amd_shared.h b/drivers/gpu/drm/amd/include/amd_shared.h
> index e98c84ef206f..6b8a40051f41 100644
> --- a/drivers/gpu/drm/amd/include/amd_shared.h
> +++ b/drivers/gpu/drm/amd/include/amd_shared.h
> @@ -47,6 +47,40 @@ enum amd_apu_flags {
> AMD_APU_IS_RENOIR = 0x00000008UL,
> };
>
> +/**
> +* DOC: IP Blocks
> +*
> +* GPUs are composed of IP (intellectual property) blocks. These
> +* IP blocks provide various functionalities: display, graphics,
> +* video decode, etc. The IP blocks that comprise a particular GPU
> +* are listed in the GPU's respective SoC file. amdgpu_device.c
> +* acquires the list of IP blocks for the GPU in use on initialization.
> +* It can then operate on this list to perform standard driver operations
> +* such as: init, fini, suspend, resume, etc.
> +*
> +*
> +* IP block implementations are named using the following convention:
> +* <functionality>_v<version> (E.g.: gfx_v6_0).
> +*/
> +
> +/**
> +* enum amd_ip_block_type - Used to classify IP blocks by functionality.
> +*
> +* @AMD_IP_BLOCK_TYPE_COMMON: GPU Family
> +* @AMD_IP_BLOCK_TYPE_GMC: Graphics Memory Controller
> +* @AMD_IP_BLOCK_TYPE_IH: Interrupt Handler
> +* @AMD_IP_BLOCK_TYPE_SMC: System Management Controller
> +* @AMD_IP_BLOCK_TYPE_PSP: Platform Security Processor
> +* @AMD_IP_BLOCK_TYPE_DCE: Display and Compositing Engine
> +* @AMD_IP_BLOCK_TYPE_GFX: Graphics and Compute Engine
> +* @AMD_IP_BLOCK_TYPE_SDMA: System DMA Engine
> +* @AMD_IP_BLOCK_TYPE_UVD: Unified Video Decoder
> +* @AMD_IP_BLOCK_TYPE_VCE: Video Compression Engine
> +* @AMD_IP_BLOCK_TYPE_ACP: Audio Co-Processor
> +* @AMD_IP_BLOCK_TYPE_VCN: Video Core/Codec Next
> +* @AMD_IP_BLOCK_TYPE_MES: Micro-Engine Scheduler
> +* @AMD_IP_BLOCK_TYPE_JPEG: JPEG Engine
> +*/
> enum amd_ip_block_type {
> AMD_IP_BLOCK_TYPE_COMMON,
> AMD_IP_BLOCK_TYPE_GMC,
> @@ -165,56 +199,59 @@ enum DC_DEBUG_MASK {
> };
>
> enum amd_dpm_forced_level;
> +
> /**
> * struct amd_ip_funcs - general hooks for managing amdgpu IP Blocks
> + * @name: Name of IP block
> + * @early_init: sets up early driver state (pre sw_init),
> + * does not configure hw - Optional
> + * @late_init: sets up late driver/hw state (post hw_init) - Optional
> + * @sw_init: sets up driver state, does not configure hw
> + * @sw_fini: tears down driver state, does not configure hw
> + * @hw_init: sets up the hw state
> + * @hw_fini: tears down the hw state
> + * @late_fini: final cleanup
> + * @suspend: handles IP specific hw/sw changes for suspend
> + * @resume: handles IP specific hw/sw changes for resume
> + * @is_idle: returns current IP block idle status
> + * @wait_for_idle: poll for idle
> + * @check_soft_reset: check soft reset the IP block
> + * @pre_soft_reset: pre soft reset the IP block
> + * @soft_reset: soft reset the IP block
> + * @post_soft_reset: post soft reset the IP block
> + * @set_clockgating_state: enable/disable cg for the IP block
> + * @set_powergating_state: enable/disable pg for the IP block
> + * @get_clockgating_state: get current clockgating status
> + * @enable_umd_pstate: enable UMD powerstate
> + *
> + * These hooks provide an interface for controlling the operational state
> + * of IP blocks. After acquiring a list of IP blocks for the GPU in use,
> + * the driver can make chip-wide state changes by walking this list and
> + * making calls to hooks from each IP block. This list is ordered to ensure
> + * that the driver initializes the IP blocks in a safe sequence.
> */
> struct amd_ip_funcs {
> - /** @name: Name of IP block */
> char *name;
> - /**
> - * @early_init:
> - *
> - * sets up early driver state (pre sw_init),
> - * does not configure hw - Optional
> - */
> int (*early_init)(void *handle);
> - /** @late_init: sets up late driver/hw state (post hw_init) - Optional */
> int (*late_init)(void *handle);
> - /** @sw_init: sets up driver state, does not configure hw */
> int (*sw_init)(void *handle);
> - /** @sw_fini: tears down driver state, does not configure hw */
> int (*sw_fini)(void *handle);
> - /** @hw_init: sets up the hw state */
> int (*hw_init)(void *handle);
> - /** @hw_fini: tears down the hw state */
> int (*hw_fini)(void *handle);
> - /** @late_fini: final cleanup */
> void (*late_fini)(void *handle);
> - /** @suspend: handles IP specific hw/sw changes for suspend */
> int (*suspend)(void *handle);
> - /** @resume: handles IP specific hw/sw changes for resume */
> int (*resume)(void *handle);
> - /** @is_idle: returns current IP block idle status */
> bool (*is_idle)(void *handle);
> - /** @wait_for_idle: poll for idle */
> int (*wait_for_idle)(void *handle);
> - /** @check_soft_reset: check soft reset the IP block */
> bool (*check_soft_reset)(void *handle);
> - /** @pre_soft_reset: pre soft reset the IP block */
> int (*pre_soft_reset)(void *handle);
> - /** @soft_reset: soft reset the IP block */
> int (*soft_reset)(void *handle);
> - /** @post_soft_reset: post soft reset the IP block */
> int (*post_soft_reset)(void *handle);
> - /** @set_clockgating_state: enable/disable cg for the IP block */
> int (*set_clockgating_state)(void *handle,
> enum amd_clockgating_state state);
> - /** @set_powergating_state: enable/disable pg for the IP block */
> int (*set_powergating_state)(void *handle,
> enum amd_powergating_state state);
> - /** @get_clockgating_state: get current clockgating status */
> void (*get_clockgating_state)(void *handle, u32 *flags);
> - /** @enable_umd_pstate: enable UMD powerstate */
> int (*enable_umd_pstate)(void *handle, enum amd_dpm_forced_level *level);
> };
>
> --
> 2.28.0
>
> _______________________________________________
> amd-gfx mailing list
> amd-gfx@lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/amd-gfx
_______________________________________________
amd-gfx mailing list
amd-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/amd-gfx
^ permalink raw reply [flat|nested] 2+ messages in thread
end of thread, other threads:[~2020-09-22 15:20 UTC | newest]
Thread overview: 2+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-09-21 15:54 [PATCH v3] amdgpu: Add initial kernel documentation for the amd_ip_block_type structure Ryan Taylor
2020-09-22 15:20 ` Alex Deucher
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).