From patchwork Fri Jan 11 16:40:48 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Daniel Vetter X-Patchwork-Id: 10760295 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 7D77A13B4 for ; Fri, 11 Jan 2019 16:41:09 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 6A7432A0A4 for ; Fri, 11 Jan 2019 16:41:09 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 5EC6C2A0AE; Fri, 11 Jan 2019 16:41:09 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-5.2 required=2.0 tests=BAYES_00,MAILING_LIST_MULTI, RCVD_IN_DNSWL_MED autolearn=ham version=3.3.1 Received: from gabe.freedesktop.org (gabe.freedesktop.org [131.252.210.177]) (using TLSv1.2 with cipher DHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.wl.linuxfoundation.org (Postfix) with ESMTPS id C0DC82A0A4 for ; Fri, 11 Jan 2019 16:41:08 +0000 (UTC) Received: from gabe.freedesktop.org (localhost [127.0.0.1]) by gabe.freedesktop.org (Postfix) with ESMTP id 9CE646F85C; Fri, 11 Jan 2019 16:41:04 +0000 (UTC) X-Original-To: dri-devel@lists.freedesktop.org Delivered-To: dri-devel@lists.freedesktop.org Received: from mail-ed1-x543.google.com (mail-ed1-x543.google.com [IPv6:2a00:1450:4864:20::543]) by gabe.freedesktop.org (Postfix) with ESMTPS id B7AF86F85A for ; Fri, 11 Jan 2019 16:41:00 +0000 (UTC) Received: by mail-ed1-x543.google.com with SMTP id a20so13574809edc.8 for ; Fri, 11 Jan 2019 08:41:00 -0800 (PST) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=bT/9/Y9rokwJCdBjC2UfOgzazdQkFFDNBOPTTd95Ry4=; b=sN4rFJkAg6toEJXEQOzeFmoLhUUrZcFurp5zfePJIoz3NELnzP/6NfluO4Lq+C1rlH wOY5GAwNyTYe8sxaXfkpfNfB41C+atOYZ2stgzd+fMnjM+aJBj/rvkQE6cC1qho116cx KiaEp4c+sOItZ47eKtPyQl4R8FwyAYE5J7Ktwx/x5cXOlrScz5nls2CprwYmBS4s/UGf jd+NQ6XJw2BZRmlN1wDV5dPgMZQIE0+yrFjZ1Uzfw5d1GS3Oe3U6bmDwGwCSt5pztXuE Fwl3aGtxmSVVHfEJnXhRmJTgBCW1TU0XeFr618WXwg61F99sZBtCR6e3cYRc19bPpYfJ 6meA== X-Gm-Message-State: AJcUukdHBRoXh2N6dU0Nv/gCSmePG0jqO8aiXwgwLAD0Z0D3LpAIg1tZ KO2Beey4kAtt/pzyJnabkZw92cyFMi8= X-Google-Smtp-Source: ALg8bN4VegEJ2K0DycUL12boPcsS3JbV8BrAy9yvcUoO6L3T3xSLhGzlHptQQCBbVXkbEnYBttE+XQ== X-Received: by 2002:a50:ad0b:: with SMTP id y11mr13354838edc.113.1547224858980; Fri, 11 Jan 2019 08:40:58 -0800 (PST) Received: from phenom.ffwll.local ([2a02:168:569e:0:3106:d637:d723:e855]) by smtp.gmail.com with ESMTPSA id a27sm2944131eda.65.2019.01.11.08.40.57 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Fri, 11 Jan 2019 08:40:58 -0800 (PST) From: Daniel Vetter To: DRI Development Subject: [PATCH 5/5] drm/doc: Polish kerneldoc for drm_device.h Date: Fri, 11 Jan 2019 17:40:48 +0100 Message-Id: <20190111164048.29067-5-daniel.vetter@ffwll.ch> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190111164048.29067-1-daniel.vetter@ffwll.ch> References: <20190111164048.29067-1-daniel.vetter@ffwll.ch> MIME-Version: 1.0 X-BeenThere: dri-devel@lists.freedesktop.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: Direct Rendering Infrastructure - Development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Daniel Vetter , Sam Ravnborg , Daniel Vetter Errors-To: dri-devel-bounces@lists.freedesktop.org Sender: "dri-devel" X-Virus-Scanned: ClamAV using ClamSMTP - Move all the legacy gunk at the bottom, and exclude it from kerneldoc. - Documentation for the remaining bits. Cc: Sam Ravnborg Signed-off-by: Daniel Vetter Acked-by: Sam Ravnborg --- Documentation/gpu/drm-internals.rst | 3 + include/drm/drm_device.h | 150 ++++++++++++++++------------ 2 files changed, 88 insertions(+), 65 deletions(-) diff --git a/Documentation/gpu/drm-internals.rst b/Documentation/gpu/drm-internals.rst index 36c569444e12..2d2d8ad7e05f 100644 --- a/Documentation/gpu/drm-internals.rst +++ b/Documentation/gpu/drm-internals.rst @@ -81,6 +81,9 @@ Device Instance and Driver Handling .. kernel-doc:: drivers/gpu/drm/drm_drv.c :doc: driver instance overview +.. kernel-doc:: include/drm/drm_device.h + :internal: + .. kernel-doc:: include/drm/drm_drv.h :internal: diff --git a/include/drm/drm_device.h b/include/drm/drm_device.h index d7cedbac66a3..ab6d3a6396bb 100644 --- a/include/drm/drm_device.h +++ b/include/drm/drm_device.h @@ -69,7 +69,13 @@ struct drm_device { /** @driver: DRM driver managing the device */ struct drm_driver *driver; - /** @dev_private: DRM driver private data */ + /** + * @dev_private: + * + * DRM driver private data. Instead of using this pointer it is + * recommended that drivers use drm_dev_init() and embed struct + * &drm_device in their larger per-device structure. + */ void *dev_private; /** @primary: Primary node */ @@ -78,6 +84,11 @@ struct drm_device { /** @render: Render node */ struct drm_minor *render; + /** + * @registered: + * + * Internally used by drm_dev_register() and drm_connector_register(). + */ bool registered; /** @@ -134,16 +145,13 @@ struct drm_device { */ int open_count; - /** @buf_lock: Lock for &buf_use and a few other things. */ - spinlock_t buf_lock; - - /** @buf_use: Usage counter for buffers in use -- cannot alloc */ - int buf_use; - - /** @buf_alloc: Buffer allocation in progress */ - atomic_t buf_alloc; - + /** @filelist_mutex: Protects @filelist. */ struct mutex filelist_mutex; + /** + * @filelist: + * + * List of userspace clients, linked through &drm_file.lhead. + */ struct list_head filelist; /** @@ -168,46 +176,6 @@ struct drm_device { */ struct list_head clientlist; - /** @maplist: Memory management - linked list of regions */ - struct list_head maplist; - - /** @map_hash: Memory management - user token hash table for maps */ - struct drm_open_hash map_hash; - - /** - * @ctxlist: - * Context handle management - linked list of context handles - */ - struct list_head ctxlist; - - /** - * @ctxlist_mutex: - * - * Context handle management - mutex for &ctxlist - */ - struct mutex ctxlist_mutex; - - /** - * @ctx_idr: - * Context handle management - */ - struct idr ctx_idr; - - /** - * @vmalist: - * Context handle management - list of vmas (for debugging) - */ - struct list_head vmalist; - - /** @dma: Optional pointer for DMA support */ - struct drm_device_dma *dma; - - /** @context_flag: Context swapping flag */ - __volatile__ long context_flag; - - /** @last_context: Last current context */ - int last_context; - /** * @irq_enabled: * @@ -216,6 +184,10 @@ struct drm_device { * to true manually. */ bool irq_enabled; + + /** + * @irq: Use by the drm_irq_install() and drm_irq_unistall() helpers. + */ int irq; /** @@ -249,6 +221,10 @@ struct drm_device { * Protects vblank count and time updates during vblank enable/disable */ spinlock_t vblank_time_lock; + /** + * @vbl_lock: Top-level vblank references lock, wraps the low-level + * @vblank_time_lock. + */ spinlock_t vbl_lock; /** @@ -264,14 +240,19 @@ struct drm_device { * races and imprecision over longer time periods, hence exposing a * hardware vblank counter is always recommended. * - * If non-zeor, &drm_crtc_funcs.get_vblank_counter must be set. + * If non-zero, &drm_crtc_funcs.get_vblank_counter must be set. */ - - /** @max_vblank_count: Size of vblank counter register */ u32 max_vblank_count; /** @vblank_event_list: List of vblank events */ struct list_head vblank_event_list; + + /** + * @event_lock: + * + * Protects @vblank_event_list and event delivery in + * general. See drm_send_event() and drm_send_event_locked(). + */ spinlock_t event_lock; /** @agp: AGP data */ @@ -281,23 +262,12 @@ struct drm_device { struct pci_dev *pdev; #ifdef __alpha__ + /** @hose: PCI hose, only used on ALPHA platforms. */ struct pci_controller *hose; #endif - - /** @sg: Scatter gather memory */ - struct drm_sg_mem *sg; - /** @num_crtcs: Number of CRTCs on this device */ unsigned int num_crtcs; - struct { - int context; - struct drm_hw_lock *lock; - } sigdata; - - struct drm_local_map *agp_buffer_map; - unsigned int agp_buffer_token; - /** @mode_config: Current mode config */ struct drm_mode_config mode_config; @@ -327,6 +297,56 @@ struct drm_device { * Set by drm_fb_helper_init() and cleared by drm_fb_helper_fini(). */ struct drm_fb_helper *fb_helper; + + /* Everything below here is for legacy driver, never use! */ + /* private: */ + + /* Context handle management - linked list of context handles */ + struct list_head ctxlist; + + /* Context handle management - mutex for &ctxlist */ + struct mutex ctxlist_mutex; + + /* Context handle management */ + struct idr ctx_idr; + + /* Memory management - linked list of regions */ + struct list_head maplist; + + /* Memory management - user token hash table for maps */ + struct drm_open_hash map_hash; + + /* Context handle management - list of vmas (for debugging) */ + struct list_head vmalist; + + /* Optional pointer for DMA support */ + struct drm_device_dma *dma; + + /* Context swapping flag */ + __volatile__ long context_flag; + + /* Last current context */ + int last_context; + + /* Lock for &buf_use and a few other things. */ + spinlock_t buf_lock; + + /* Usage counter for buffers in use -- cannot alloc */ + int buf_use; + + /* Buffer allocation in progress */ + atomic_t buf_alloc; + + struct { + int context; + struct drm_hw_lock *lock; + } sigdata; + + struct drm_local_map *agp_buffer_map; + unsigned int agp_buffer_token; + + /* Scatter gather memory */ + struct drm_sg_mem *sg; }; #endif