From patchwork Tue Sep 12 07:34:02 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Linus Walleij X-Patchwork-Id: 112242 Delivered-To: patch@linaro.org Received: by 10.140.106.117 with SMTP id d108csp4837284qgf; Tue, 12 Sep 2017 00:34:10 -0700 (PDT) X-Received: by 10.101.85.70 with SMTP id t6mr13620142pgr.255.1505201650186; Tue, 12 Sep 2017 00:34:10 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1505201650; cv=none; d=google.com; s=arc-20160816; b=Qso5F+xOJNJEmvNSqdj4oIZp10Uu/X5RzFfSX/rvypCL7TgE/TdAyQKbTM0AQLN66/ Vmv1maPQo6yl20wtYubcr7jKWUndDKNJcloRm/PnU5B0NG5yY8Fp/n/IYkuxNNpRowH0 q8YjSN04BxoAGqAXo2yaXcqkgEeyvJlvj5G/l10RCsSOWsP7NfDwA7ymuoOVl+AIumX1 AD0MUHXhgZ41fNtx40yGNpd50nFGBByrhIQCFXucoLJwbwYZn098PX54iYpYQzUHcQBD WxEo84khKzjyYLoCLc/Wfanlps5vLHDnhS8mQ0EtBtmogp++9c0tnkCNFtbtMnFRft8c MMEA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:sender:message-id:date:subject:cc:to:from :dkim-signature:arc-authentication-results; bh=6DTwrHSrag3BYCkUTxW6wuqY4daWWb2NyGub2iDu29E=; b=NR5nZTW2iZ0Xho4+xeJJjhwf7akdVsOxWAEOgBJ/cnaxwV/WhZUPAyQIhw8saOMP+B wauM2ZA7Vv3H9S3Ccu8ZOsfuftcfADaUj3AxIkH/WXcIl98GinLsp7EIczSerlJ1wG6q SCOTtub1lwlwzBveZEbbzVkNbSpM/nhF3gS6CdgxV/MaR1NU6RHS0+9DCrXIwlVhuT8Q IjTRWl/wQ3okrcI7tilaA3eZ6KxvtST0d3jrIvOCp9Rcck78k46P1iHsAwlIFdx+0Tp0 O5xDZeV/VVh97K/7HrgbZ+49DqF8Fs7K0JnG0xFlHtuzTLNgaHjvZgyHRiWzqVEdJfoX VtAA== ARC-Authentication-Results: i=1; mx.google.com; dkim=neutral (body hash did not verify) header.i=@linaro.org header.s=google header.b=PqeCWc5f; spf=pass (google.com: best guess record for domain of linux-gpio-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-gpio-owner@vger.kernel.org; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id z15si7623338pfk.30.2017.09.12.00.34.09; Tue, 12 Sep 2017 00:34:10 -0700 (PDT) Received-SPF: pass (google.com: best guess record for domain of linux-gpio-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67; Authentication-Results: mx.google.com; dkim=neutral (body hash did not verify) header.i=@linaro.org header.s=google header.b=PqeCWc5f; spf=pass (google.com: best guess record for domain of linux-gpio-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-gpio-owner@vger.kernel.org; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1751052AbdILHeJ (ORCPT + 5 others); Tue, 12 Sep 2017 03:34:09 -0400 Received: from mail-lf0-f41.google.com ([209.85.215.41]:35332 "EHLO mail-lf0-f41.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1751015AbdILHeI (ORCPT ); Tue, 12 Sep 2017 03:34:08 -0400 Received: by mail-lf0-f41.google.com with SMTP id d17so24100283lfe.2 for ; Tue, 12 Sep 2017 00:34:08 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id; bh=7ToOlKPrA1MHzTp+QlHEON+e2txm36LwftiypR469zo=; b=PqeCWc5fXP7oKqj3GgPFQ7JXLTHzdbeTFYj4jh5qj6FRRBvy1QPMWlq2pip76RscOG qkBN1Gj1VipjTQ5AM2aICM9g8CBZ87mJg/ZO/O8qYBWGcVe6rFIO8loxr3hHeF77QwJA uprwrr7bnaR4iStzG3F0VO/JshXVbCDoIAcgw= 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; bh=7ToOlKPrA1MHzTp+QlHEON+e2txm36LwftiypR469zo=; b=UGg8uVuMhO2uhLTYGnAY9Gafkpck9GFE04GgDswf7QyKF4YI4fILZVVMlLHAWJC+xr GZ4/wEmsLbE1rKnW5MJ/SAnploAbvOgzmRV1K2nQDRKk3b1s3Jyxyk4Z+Hx/pVrqLA4v BjF0gve6fVcVzTxzI/uls0ZMJX7Q4BOCg22F8l3dRaWoCk7EXK6ZVranjEruKNfCfW3k 9HRxFriNLTjcHXDa9UhocVyz4AU1akYfMHNx5RwuXG81JJgrK26WsmoXc/agKpkWzG7y Yh4xKZLENfXw5x+juJ+t64Tz2sXn6t8AcuPPBNbXBiyhpm8CUe6Dk10XEUcXYIc9HeGG mGDg== X-Gm-Message-State: AHPjjUh5e81Lt5MMH6rpA1gCBxoG8cnmhC3NbwloZB8P9WpBKmCizGcW cMQOh9Jfg3/E0jHMxvJv2A== X-Google-Smtp-Source: AOwi7QC48JTizuCZSqyu6KDGhNthERbYwDmQmvlWqZeUmcnWHJL4rf3nZIQYUCPORe0M1/jot1T3tw== X-Received: by 10.46.77.141 with SMTP id c13mr5508025ljd.150.1505201646940; Tue, 12 Sep 2017 00:34:06 -0700 (PDT) Received: from genomnajs.ideon.se ([85.235.10.227]) by smtp.gmail.com with ESMTPSA id g132sm1918066lfe.13.2017.09.12.00.34.05 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Tue, 12 Sep 2017 00:34:05 -0700 (PDT) From: Linus Walleij To: linux-gpio@vger.kernel.org Cc: Linus Walleij , Florian Fainelli , Sergei Shtylyov , Andrew Lunn Subject: [PATCH] gpio: Clarify consumer stubs use-cases Date: Tue, 12 Sep 2017 09:34:02 +0200 Message-Id: <20170912073402.2893-1-linus.walleij@linaro.org> X-Mailer: git-send-email 2.13.5 Sender: linux-gpio-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-gpio@vger.kernel.org After discussion we add a few blurbs to clarify how the stubs in the consumer API are supposed to be used. Cc: Florian Fainelli Cc: Sergei Shtylyov Cc: Andrew Lunn Signed-off-by: Linus Walleij --- Documentation/gpio/consumer.txt | 22 +++++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) -- 2.13.5 -- To unsubscribe from this list: send the line "unsubscribe linux-gpio" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html diff --git a/Documentation/gpio/consumer.txt b/Documentation/gpio/consumer.txt index 912568baabb9..ddbfa775a78a 100644 --- a/Documentation/gpio/consumer.txt +++ b/Documentation/gpio/consumer.txt @@ -10,14 +10,30 @@ Guidelines for GPIOs consumers ============================== Drivers that can't work without standard GPIO calls should have Kconfig entries -that depend on GPIOLIB. The functions that allow a driver to obtain and use -GPIOs are available by including the following file: +that depend on GPIOLIB or select GPIOLIB. The functions that allow a driver to +obtain and use GPIOs are available by including the following file: #include +There are static inline stubs for all functions in the header file in the case +where GPIOLIB is disabled. When these stubs are called they will emit +warnings. These stubs are used for two use cases: + +- Simple compile coverage with e.g. COMPILE_TEST - it does not matter that + the current platform does not enable or select GPIOLIB because we are not + going to execute the system anyway. + +- Truly optional GPIOLIB support - where the driver does not really make use + of the GPIOs on certain compile-time configurations for certain systems, but + will use it under other compile-time configurations. In this case the + consumer must make sure not to call into these functions, or the user will + be met with console warnings that may be perceived as intimidating. + All the functions that work with the descriptor-based GPIO interface are prefixed with gpiod_. The gpio_ prefix is used for the legacy interface. No -other function in the kernel should use these prefixes. +other function in the kernel should use these prefixes. The use of the legacy +functions is strongly discouraged, new code should use +and descriptors exclusively. Obtaining and Disposing GPIOs