From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from gabe.freedesktop.org (gabe.freedesktop.org [131.252.210.177]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 6007AC6FD18 for ; Fri, 31 Mar 2023 08:47:02 +0000 (UTC) Received: from gabe.freedesktop.org (localhost [127.0.0.1]) by gabe.freedesktop.org (Postfix) with ESMTP id 4040910F136; Fri, 31 Mar 2023 08:47:02 +0000 (UTC) Received: from mga18.intel.com (mga18.intel.com [134.134.136.126]) by gabe.freedesktop.org (Postfix) with ESMTPS id AC92510F14D for ; Fri, 31 Mar 2023 08:46:52 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1680252412; x=1711788412; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=GH++2KpBYaYrtpUz6v1QVyPXFUIoCR+1eFy0cnIXsqY=; b=bbFrLyrtcvdRbKnmXJRgBYZhXJdTA6wsBd+W8ebLwoBZ6ZrAHP2PqIYk wTOG5QqAsVsn0Kt8z5AluwqVhQR1jeLq7Z32oX9R78snUJdWIUATIZa2D R13URzO/e128MY/fQtZCJfwpgCtpmivzB+6kSKWr6+DyOcsgMkgb+8KJb dWlSNu/GwbMfnxlueDygqh2u/nUPqe/FqZJqQP6ENFCH+Yvqreg1DOweV c4wh2/eKVP3+S5rxQS7ipxrHrk2gRSfQUBdYTOnkFwSVW2K9SgmDg3mCf 15Gy+oxsazbcEJu6ibUKbTVn9Y31tHGJHhojh88durPrkeqedjEzztl10 A==; X-IronPort-AV: E=McAfee;i="6600,9927,10665"; a="325364348" X-IronPort-AV: E=Sophos;i="5.98,307,1673942400"; d="scan'208";a="325364348" Received: from orsmga007.jf.intel.com ([10.7.209.58]) by orsmga106.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 31 Mar 2023 01:46:51 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=McAfee;i="6600,9927,10665"; a="678544911" X-IronPort-AV: E=Sophos;i="5.98,307,1673942400"; d="scan'208";a="678544911" Received: from kuhnbrex-mobl1.ger.corp.intel.com (HELO mwauld-desk1.intel.com) ([10.252.28.81]) by orsmga007-auth.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 31 Mar 2023 01:46:48 -0700 From: Matthew Auld To: intel-xe@lists.freedesktop.org Date: Fri, 31 Mar 2023 09:46:25 +0100 Message-Id: <20230331084628.421814-3-matthew.auld@intel.com> X-Mailer: git-send-email 2.39.2 In-Reply-To: <20230331084628.421814-1-matthew.auld@intel.com> References: <20230331084628.421814-1-matthew.auld@intel.com> MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Subject: [Intel-xe] [PATCH v4 2/5] drm/xe/uapi: add some kernel-doc for region query X-BeenThere: intel-xe@lists.freedesktop.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Intel Xe graphics driver List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Filip Hazubski , Lucas De Marchi , Effie Yu , Carl Zhang Errors-To: intel-xe-bounces@lists.freedesktop.org Sender: "Intel-xe" Since we need to extend this, we should also take the time to add some basic kernel-doc here for the existing bits. Note that this is all still subject to change when upstreaming. Also convert XE_MEM_REGION_CLASS_* into an enum, so we can more easily create links to it from other parts of the uapi. Suggested-by: Gwan-gyeong Mun Signed-off-by: Matthew Auld Cc: Maarten Lankhorst Cc: Thomas Hellström Cc: Lucas De Marchi Cc: José Roberto de Souza Cc: Filip Hazubski Cc: Carl Zhang Cc: Effie Yu Reviewed-by: Gwan-gyeong Mun --- include/uapi/drm/xe_drm.h | 74 ++++++++++++++++++++++++++++++++++++--- 1 file changed, 70 insertions(+), 4 deletions(-) diff --git a/include/uapi/drm/xe_drm.h b/include/uapi/drm/xe_drm.h index b0b80aae3ee8..8cb3324221f2 100644 --- a/include/uapi/drm/xe_drm.h +++ b/include/uapi/drm/xe_drm.h @@ -154,21 +154,84 @@ struct drm_xe_engine_class_instance { __u16 gt_id; }; -#define XE_MEM_REGION_CLASS_SYSMEM 0 -#define XE_MEM_REGION_CLASS_VRAM 1 +/** + * enum drm_xe_memory_class - Supported memory classes. + */ +enum drm_xe_memory_class { + /** @XE_MEM_REGION_CLASS_SYSMEM: Represents system memory. */ + XE_MEM_REGION_CLASS_SYSMEM = 0, + /** + * @XE_MEM_REGION_CLASS_VRAM: On discrete platforms, this + * represents the memory that is local to the device, which we + * call VRAM. Not valid on integrated platforms. + */ + XE_MEM_REGION_CLASS_VRAM +}; + +/** + * struct drm_xe_query_mem_usage - The region info query enumerates all regions + * known to the driver by filling in an array of struct drm_xe_query_mem_region + * structures. + */ struct drm_xe_query_mem_usage { + /** + * @num_regions: Number of supported memory regions for this device. + * + * The @regions will contain @num_regions entries. + */ __u32 num_regions; + /** @pad: MBZ */ __u32 pad; - + /** + * struct drm_xe_query_mem_region - Describes some region as known to + * the driver. + */ struct drm_xe_query_mem_region { + /** + * @mem_class: The memory class describing this region. + * + * See enum drm_xe_memory_class for supported values. + */ __u16 mem_class; - __u16 instance; /* unique ID even among different classes */ + /** + * @instance: The instance for this region. + * + * The @mem_class and @instance taken together will always give + * a unique pair. + */ + __u16 instance; + /** @pad: MBZ */ __u32 pad; + /** + * @min_page_size: Min page-size in bytes for this region. + * + * When the kernel allocates memory for this region, the + * underlying pages will be at least @min_page_size in size. + * + * Important note: When userspace allocates a GTT address which + * can point to memory allocated from this region, it must also + * respect this minimum alignment. This is enforced by the + * kernel. + */ __u32 min_page_size; + /** + * @max_page_size: Max page-size in bytes for this region. + */ __u32 max_page_size; + /** + * @total_size: The usable size in bytes for this region. + */ __u64 total_size; + /** + * @used: Estimate of the memory used in bytes for this region. + * + * Requires CAP_PERFMON or CAP_SYS_ADMIN to get reliable + * accounting. Without this the value here will always equal + * the @total_size. + */ __u64 used; + /** @reserved: MBZ */ __u64 reserved[8]; } regions[]; }; @@ -760,6 +823,9 @@ struct drm_xe_vm_madvise { * Setting the preferred location will trigger a migrate of the VMA * backing store to new location if the backing store is already * allocated. + * + * For DRM_XE_VM_MADVISE_PREFERRED_MEM_CLASS usage, see enum + * drm_xe_memory_class. */ #define DRM_XE_VM_MADVISE_PREFERRED_MEM_CLASS 0 #define DRM_XE_VM_MADVISE_PREFERRED_GT 1 -- 2.39.2