drm/amdgpu: Add documentation to some parts of the AMDGPU ring and wb

 */

#define AMDGPU_MAX_WB 1024	/* Reserve at most 1024 WB slots for amdgpu-owned rings. */

/**

 * amdgpu_wb - This struct is used for small GPU memory allocation.

 *

 * This struct is used to allocate a small amount of GPU memory that can be

 * used to shadow certain states into the memory. This is especially useful for

 * providing easy CPU access to some states without requiring register access

 * (e.g., if some block is power gated, reading register may be problematic).

 *

 * Note: the term writeback was initially used because many of the amdgpu

 * components had some level of writeback memory, and this struct initially

 * described those components.

 */

struct amdgpu_wb {

	/**

	 * @wb_obj:

	 *

	 * Buffer Object used for the writeback memory.

	 */

	struct amdgpu_bo	*wb_obj;

	/**

	 * @wb:

	 *

	 * Pointer to the first writeback slot. In terms of CPU address

	 * this value can be accessed directly by using the offset as an index.

	 * For the GPU address, it is necessary to use gpu_addr and the offset.

	 */

	volatile uint32_t	*wb;

	/**

	 * @gpu_addr:

	 *

	 * Writeback base address in the GPU.

	 */

	uint64_t		gpu_addr;

	u32			num_wb;	/* Number of wb slots actually reserved for amdgpu. */

	/**

	 * @num_wb:

	 *

	 * Number of writeback slots reserved for amdgpu.

	 */

	u32			num_wb;

	/**

	 * @used:

	 *

	 * Track the writeback slot already used.

	 */

	unsigned long		used[DIV_ROUND_UP(AMDGPU_MAX_WB, BITS_PER_LONG)];

	/**

	 * @lock:

	 *

	 * Protects read and write of the used field array.

	 */

	spinlock_t		lock;

};

/* provided by hw blocks that expose a ring buffer for commands */

struct amdgpu_ring_funcs {

	/**

	 * @type:

	 *

	 * GFX, Compute, SDMA, UVD, VCE, VCN, VPE, KIQ, MES, UMSCH, and CPER

	 * use ring buffers. The type field just identifies which component the

	 * ring buffer is associated with.

	 */

	enum amdgpu_ring_type	type;

	uint32_t		align_mask;

	/**

	 * @nop:

	 *

	 * Every block in the amdgpu has no-op instructions (e.g., GFX 10

	 * uses PACKET3(PACKET3_NOP, 0x3FFF), VCN 5 uses VCN_ENC_CMD_NO_OP,

	 * etc). This field receives the specific no-op for the component

	 * that initializes the ring.

	 */

	u32			nop;

	bool			support_64bit_ptrs;

	bool			no_user_fence;

	bool (*is_guilty)(struct amdgpu_ring *ring);

};

/**

 * amdgpu_ring - Holds ring information

 */

struct amdgpu_ring {

	struct amdgpu_device		*adev;

	const struct amdgpu_ring_funcs	*funcs;

	unsigned		rptr_offs;

	u64			rptr_gpu_addr;

	volatile u32		*rptr_cpu_addr;

	/**

	 * @wptr:

	 *

	 * This is part of the Ring buffer implementation and represents the

	 * write pointer. The wptr determines where the host has written.

	 */

	u64			wptr;

	/**

	 * @wptr_old:

	 *

	 * Before update wptr with the new value, usually the old value is

	 * stored in the wptr_old.

	 */

	u64			wptr_old;

	unsigned		ring_size;

	/**

	 * @max_dw:

	 *

	 * Maximum number of DWords for ring allocation. This information is

	 * provided at the ring initialization time, and each IP block can

	 * specify a specific value. Check places that invoke

	 * amdgpu_ring_init() to see the maximum size per block.

	 */

	unsigned		max_dw;

	/**

	 * @count_dw:

	 *

	 * This value starts with the maximum amount of DWords supported by the

	 * ring. This value is updated based on the ring manipulation.

	 */

	int			count_dw;

	uint64_t		gpu_addr;

	/**

	 * @ptr_mask:

	 *

	 * Some IPs provide support for 64-bit pointers and others for 32-bit

	 * only; this behavior is component-specific and defined by the field

	 * support_64bit_ptr. If the IP block supports 64-bits, the mask

	 * 0xffffffffffffffff is set; otherwise, this value assumes buf_mask.

	 * Notice that this field is used to keep wptr under a valid range.

	 */

	uint64_t		ptr_mask;

	/**

	 * @buf_mask:

	 *

	 * Buffer mask is a value used to keep wptr count under its

	 * thresholding. Buffer mask initialized during the ring buffer

	 * initialization time, and it is defined as (ring_size / 4) -1.

	 */

	uint32_t		buf_mask;

	u32			idx;

	u32			xcc_id;

	bool			use_pollmem;

	unsigned		wptr_offs;

	u64			wptr_gpu_addr;

	/**

	 * @wptr_cpu_addr:

	 *

	 * This is the CPU address pointer in the writeback slot. This is used

	 * to commit changes to the GPU.

	 */

	volatile u32		*wptr_cpu_addr;

	unsigned		fence_offs;

	u64			fence_gpu_addr;