From patchwork Thu Nov 26 00:03:57 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Rodrigo Vivi X-Patchwork-Id: 7703681 Return-Path: X-Original-To: patchwork-dri-devel@patchwork.kernel.org Delivered-To: patchwork-parsemail@patchwork1.web.kernel.org Received: from mail.kernel.org (mail.kernel.org [198.145.29.136]) by patchwork1.web.kernel.org (Postfix) with ESMTP id 26F699FCA2 for ; Thu, 26 Nov 2015 00:04:22 +0000 (UTC) Received: from mail.kernel.org (localhost [127.0.0.1]) by mail.kernel.org (Postfix) with ESMTP id 0AC52208E2 for ; Thu, 26 Nov 2015 00:04:21 +0000 (UTC) Received: from gabe.freedesktop.org (gabe.freedesktop.org [131.252.210.177]) by mail.kernel.org (Postfix) with ESMTP id F039A208CC for ; Thu, 26 Nov 2015 00:04:19 +0000 (UTC) Received: from gabe.freedesktop.org (localhost [127.0.0.1]) by gabe.freedesktop.org (Postfix) with ESMTP id 1F5F46E10C; Wed, 25 Nov 2015 16:04:14 -0800 (PST) X-Original-To: dri-devel@lists.freedesktop.org Delivered-To: dri-devel@lists.freedesktop.org Received: from mga09.intel.com (mga09.intel.com [134.134.136.24]) by gabe.freedesktop.org (Postfix) with ESMTP id 619F46E089; Wed, 25 Nov 2015 16:04:10 -0800 (PST) Received: from orsmga002.jf.intel.com ([10.7.209.21]) by orsmga102.jf.intel.com with ESMTP; 25 Nov 2015 16:04:09 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.20,344,1444719600"; d="scan'208";a="859509020" Received: from rdvivi-dublin.jf.intel.com ([10.7.196.164]) by orsmga002.jf.intel.com with ESMTP; 25 Nov 2015 16:04:09 -0800 From: Rodrigo Vivi To: intel-gfx@lists.freedesktop.org Subject: [PATCH 1/9] drm: Improve drm_dp_aux DocBook. Date: Wed, 25 Nov 2015 16:03:57 -0800 Message-Id: <1448496245-1495-2-git-send-email-rodrigo.vivi@intel.com> X-Mailer: git-send-email 2.4.3 In-Reply-To: <1448496245-1495-1-git-send-email-rodrigo.vivi@intel.com> References: <1448496245-1495-1-git-send-email-rodrigo.vivi@intel.com> Cc: Daniel Vetter , dri-devel@lists.freedesktop.org, Rodrigo Vivi X-BeenThere: dri-devel@lists.freedesktop.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: Direct Rendering Infrastructure - Development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Errors-To: dri-devel-bounces@lists.freedesktop.org Sender: "dri-devel" X-Spam-Status: No, score=-4.8 required=5.0 tests=BAYES_00, RCVD_IN_DNSWL_MED, RP_MATCHES_RCVD, UNPARSEABLE_RELAY autolearn=unavailable version=3.3.1 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on mail.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP This patch converts drm_dp_aux doc to new per-member comment layout that 4.4 supports as suggested by Daniel. But also: 1. to let the split text with sense this patch also introduce a brief general AUX channel definition. 2. Remove .name and .dev duplications from the original text. 3. Improve .transfer() error code handler making more clear what is going on with each error code generated or handled Cc: Daniel Vetter Signed-off-by: Rodrigo Vivi --- include/drm/drm_dp_helper.h | 64 +++++++++++++++++++++++++++++---------------- 1 file changed, 42 insertions(+), 22 deletions(-) diff --git a/include/drm/drm_dp_helper.h b/include/drm/drm_dp_helper.h index 1252108..ed7dbdc 100644 --- a/include/drm/drm_dp_helper.h +++ b/include/drm/drm_dp_helper.h @@ -703,26 +703,9 @@ struct drm_dp_aux_msg { /** * struct drm_dp_aux - DisplayPort AUX channel - * @name: user-visible name of this AUX channel and the I2C-over-AUX adapter - * @ddc: I2C adapter that can be used for I2C-over-AUX communication - * @dev: pointer to struct device that is the parent for this AUX channel - * @hw_mutex: internal mutex used for locking transfers - * @transfer: transfers a message representing a single AUX transaction * - * The .dev field should be set to a pointer to the device that implements - * the AUX channel. - * - * The .name field may be used to specify the name of the I2C adapter. If set to - * NULL, dev_name() of .dev will be used. - * - * Drivers provide a hardware-specific implementation of how transactions - * are executed via the .transfer() function. A pointer to a drm_dp_aux_msg - * structure describing the transaction is passed into this function. Upon - * success, the implementation should return the number of payload bytes - * that were transferred, or a negative error-code on failure. Helpers - * propagate errors from the .transfer() function, with the exception of - * the -EBUSY error, which causes a transaction to be retried. On a short, - * helpers will return -EPROTO to make it simpler to check for failure. + * AUX channel is a half duplex channel used to transfer messages between + * source an sink. Mainly used for write and read sink DPCD registers. * * An AUX channel can also be used to transport I2C messages to a sink. A * typical application of that is to access an EDID that's present in the @@ -734,15 +717,52 @@ struct drm_dp_aux_msg { * received, the adapter will drop down to the size given by the partial * response for this transaction only. * - * Note that the aux helper code assumes that the .transfer() function - * only modifies the reply field of the drm_dp_aux_msg structure. The - * retry logic and i2c helpers assume this is the case. */ struct drm_dp_aux { + /** + * @name: user-visible name of this AUX channel and the I2C-over-AUX + * adapter. If set to NULL, dev_name() of .dev will be used. + */ const char *name; + + /** + * @ddc: I2C adapter that can be used for I2C-over-AUX communication + */ struct i2c_adapter ddc; + + /** + * @dev: pointer to struct device that is the parent and implements + * this AUX channel + */ struct device *dev; + + /** + * @hw_mutex: internal mutex used for locking transfers + */ struct mutex hw_mutex; + + /** + * @transfer: transfers a message representing a single AUX transaction + * + * Drivers provide a hardware-specific implementation of how + * transactions are executed via this function. A pointer to a + * drm_dp_aux_msg structure describing the transaction is passed into + * this function. + * + * Returns: + * Upon success, the implementation should return the number of + * payload bytes that were transferred. + * Otherwise a negative error-code on failure. Helpers propagate errors + * from the .transfer() function, with the exception of: + * - -EPROTO: On a short, helpers will return -EPROTO to make it simpler + * to check for failure. + * - -EBUSY: When BUSY helpers will attempt retries before propagating + * this error. + * + * Note that the aux helper code assumes that the .transfer() function + * only modifies the reply field of the drm_dp_aux_msg structure. The + * retry logic and i2c helpers assume this is the case. + */ ssize_t (*transfer)(struct drm_dp_aux *aux, struct drm_dp_aux_msg *msg); unsigned i2c_nack_count, i2c_defer_count;