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 phobos.denx.de (phobos.denx.de [85.214.62.61]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 286BAC04A68 for ; Thu, 28 Jul 2022 13:20:56 +0000 (UTC) Received: from h2850616.stratoserver.net (localhost [IPv6:::1]) by phobos.denx.de (Postfix) with ESMTP id 61B7D83FAF; Thu, 28 Jul 2022 15:20:54 +0200 (CEST) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=konsulko.com Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=u-boot-bounces@lists.denx.de Authentication-Results: phobos.denx.de; dkim=pass (1024-bit key; unprotected) header.d=konsulko.com header.i=@konsulko.com header.b="jXjqdFMx"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id CD45A84144; Thu, 28 Jul 2022 15:20:52 +0200 (CEST) Received: from mail-qv1-xf2b.google.com (mail-qv1-xf2b.google.com [IPv6:2607:f8b0:4864:20::f2b]) (using TLSv1.3 with cipher TLS_AES_128_GCM_SHA256 (128/128 bits)) (No client certificate requested) by phobos.denx.de (Postfix) with ESMTPS id C36FF83F36 for ; Thu, 28 Jul 2022 15:20:49 +0200 (CEST) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=konsulko.com Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=trini@konsulko.com Received: by mail-qv1-xf2b.google.com with SMTP id mh14so1391720qvb.1 for ; Thu, 28 Jul 2022 06:20:49 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=konsulko.com; s=google; h=from:to:cc:subject:date:message-id:mime-version :content-transfer-encoding; bh=+IP3fDsOcCHd501zTFLRkQAYcJ3a/5J6aOiuwznXo1c=; b=jXjqdFMxE/2nxiN60NoEBSkFb7C8eIq81WhlSvGFdncpDsmsCO2AQnkLLk+CWaPKsQ eEcn7yfBMpUM38AD5hqT/hn9Tytvx/gq+EXgH498CBS3eQgWJporahW6gr8EX+p85r5E xWSb8/wPrnMQyyLvV+jWmEtezi7ElYKDpI72U= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:date:message-id:mime-version :content-transfer-encoding; bh=+IP3fDsOcCHd501zTFLRkQAYcJ3a/5J6aOiuwznXo1c=; b=qtU9znaxPRdKme9Co+4BmnqrsnM58u6RBrHeQDSI7AN1x2uMouJdE6ly8pdqgOqqTc DM2v6hJbzkLfPnfjtz6SG1V2JbcuOu/38Pr80DSBOK9DigpBzAqvNIaO8i90l+TM7s36 3lGLd1K8AgxO3C8oM7UG9b6dpqe4lhvh8GczKdtXr+R59x3JjnhcnbotOQFLHgSaKf9u 2MwG0W0Bx/UBHRfe3Bhtys8s1mVjN5fdlkuQrlxevdhTenDGNKdydThZNDSGE3Dgwi9K 0nAUSbUWW2UW/qfTZhTXmUYvURd5v1p9fBYz37iV5oqChE+zMPR18JSH3VgkpALeUnHp +kFA== X-Gm-Message-State: AJIora8GhLCiqUSKwL5wRFcBh7okczYiA/T7XL5uXdVpfEIP3lJXSdsM vsBh0YGIScVInS4D0p43l+f5YSyDABk9yU4Z X-Google-Smtp-Source: AGRyM1tt+e5N9Orn+WPKLalfPdkBXDFnx+00Vxmjq5+52UPK7eBiHTQ64tYP+AKMS8ot2iV13DNDcg== X-Received: by 2002:a05:6214:2306:b0:473:f77a:85a7 with SMTP id gc6-20020a056214230600b00473f77a85a7mr23382588qvb.106.1659014448209; Thu, 28 Jul 2022 06:20:48 -0700 (PDT) Received: from bill-the-cat.lan (cpe-65-184-195-139.ec.res.rr.com. [65.184.195.139]) by smtp.gmail.com with ESMTPSA id u12-20020a05620a430c00b006af1f0af045sm481382qko.107.2022.07.28.06.20.47 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 28 Jul 2022 06:20:47 -0700 (PDT) From: Tom Rini To: u-boot@lists.denx.de Cc: =?UTF-8?q?Pali=20Roh=C3=A1r?= , Simon Glass , Heinrich Schuchardt Subject: [RFCv1] doc: develop: Describe using CONFIG vs CFG for values Date: Thu, 28 Jul 2022 09:20:46 -0400 Message-Id: <20220728132046.2000282-1-trini@konsulko.com> X-Mailer: git-send-email 2.25.1 MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-BeenThere: u-boot@lists.denx.de X-Mailman-Version: 2.1.39 Precedence: list List-Id: U-Boot discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: u-boot-bounces@lists.denx.de Sender: "U-Boot" X-Virus-Scanned: clamav-milter 0.103.6 at phobos.denx.de X-Virus-Status: Clean Document how and when to use CONFIG or CFG namespace for options. There are times where Kconfig is not a great fit for our needs, so we want to use the CFG namespace instead. Signed-off-by: Tom Rini --- RFCv1: - This is essentially my idea on how to better handle the problem of CONFIG values that just don't fit in Kconfig because it makes much more sense to define them statically for a given SoC or calculate them from other values, and so on. One example here would be to revert c7fad78ec0ee ("Convert CONFIG_SYS_BR0_PRELIM et al to Kconfig") and re-name these to CFG_SYS_.. instead. Another big example here would be a global search-and-replace of 's/CONFIG_HPS_/CFG_HPS_/g' as that's all tool-generated. Not all CONFIG_SYS_ options would get this as boolean choices are well handled in Kconfig, and that may not be clear enough in what I wrote here? --- doc/develop/build_configuration.rst | 36 +++++++++++++++++++++++++++++ doc/develop/index.rst | 1 + 2 files changed, 37 insertions(+) create mode 100644 doc/develop/build_configuration.rst diff --git a/doc/develop/build_configuration.rst b/doc/develop/build_configuration.rst new file mode 100644 index 000000000000..541ce528b36a --- /dev/null +++ b/doc/develop/build_configuration.rst @@ -0,0 +1,36 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Using CONFIG or CFG to configure the build +========================================== + +There are two namespaces used to control the build-time configuration of +U-Boot, ``CONFIG`` and ``CFG``. These are used when it is either not possible +or not practical to make a run-time determination about some functionality of +the hardware or a required software feature or similar. Each of these has their +own places where they are better suited than the other for use. + +The first of these, ``CONFIG``` is managed in the `Kconfig language +`_ that is +most commonly associated with the Linux kernel and the Kconfig files found +throughout our sources. Adding options to this namespace is the preferred way of +exposing new configuration options as there are a number of ways for both users +and system integrators to manage and change these options. Some common examples +here are to enable a specific command within U-Boot or even a whole subsystem +such as NAND flash or network connectivity. + +The second of these, ``CFG`` is implemented directly as C preprocessor values or +macros, depending on what they are in turn describing. The nature of U-Boot +means that while we have some functionality that is very reasonable to expose to +the end user to enable or disable we have other places where we need to describe +things such as register locations or values, memory map ranges and so on. When +practical, we should be getting these values from the :doc:`device tree +`. However, there are cases where this is either not +practical due to when we need the information and may not have a device tree yet +or due to legacy reasons code has not been rewritten. As this information tends +to be specific to a given SoC (or family of SoCs) or if board specific something +that is mandated by the physical design rather than truly user configurable, it +is acceptable to ``#define`` these values in the ``CFG`` namespace. It is +strongly encouraged to place these in the architecture header files, if they are +generic to a given SoC, or under the board directory if board specific. Placing +them under the board.h file in the *include/configs/* directory should be seen +as a last resort. diff --git a/doc/develop/index.rst b/doc/develop/index.rst index 73741ceb6a2f..c8ec7c210d35 100644 --- a/doc/develop/index.rst +++ b/doc/develop/index.rst @@ -9,6 +9,7 @@ General .. toctree:: :maxdepth: 1 + build_configuration codingstyle designprinciples process -- 2.25.1