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 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 77389C433EF for ; Mon, 27 Jun 2022 17:17:46 +0000 (UTC) Received: from h2850616.stratoserver.net (localhost [IPv6:::1]) by phobos.denx.de (Postfix) with ESMTP id 33EE083EC5; Mon, 27 Jun 2022 19:17:35 +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="SccIQuwy"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id D2E4083EC5; Mon, 27 Jun 2022 19:17:31 +0200 (CEST) Received: from mail-qv1-xf2a.google.com (mail-qv1-xf2a.google.com [IPv6:2607:f8b0:4864:20::f2a]) (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 E1E7B84282 for ; Mon, 27 Jun 2022 19:17:28 +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-xf2a.google.com with SMTP id p31so15689293qvp.5 for ; Mon, 27 Jun 2022 10:17:28 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=konsulko.com; s=google; h=from:to:subject:date:message-id:in-reply-to:references:mime-version :content-transfer-encoding; bh=fuR7m83AL3vwUxFxVIYIMlj9Qpeg+eH7GGqa8YbF8Fc=; b=SccIQuwySpfSSTKGHOdzf+8bP8DFOVzwA8p+xG9XSrO8ziiENb6+HGqncQ1dzMVMr9 yVgnZ8kV/vb7WFcucffXlMHsaYfEHILDaooeW/Gvm7KWbkG+lVjSn5wabTAukghE4U5M jaCcrFXf68RhVSqWauy0Apo4YZ21sU+ZDk9Ks= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=fuR7m83AL3vwUxFxVIYIMlj9Qpeg+eH7GGqa8YbF8Fc=; b=wzlaK99tawmKJP/WvW4xKLxXKONjneCQ0O1hpjJUpikkckFX+MvLS7wRdjg4p5yQKu rJJ3E5lwVVvX2eeCqO36f9R/OQgWtH+VH9BYoUaeYwGuE9RQlKzM5UVtjBAyQrd/i/YC bgbJMVRlpEc57fWOyLr3CIuNpoIKGsnkKcv3PFa9qwPwAiDEbweb6OWbIHZpFX2E7Ax0 gLAsDgSl589HgwmgLIwNg589hcuszlUpwXIi6euIsz9g6PN/HsfSmDwtxKbwU5F1UX1M /vkgErofbbqH7d6TVGX5Q9+bamVV3B/f6R7drC9bdnpVA1x2t0RgXpl1wE3UvioBVW/Y wHIA== X-Gm-Message-State: AJIora8qBZAt9PutTMEnLN7xiwcj1oH/3JQdCYfEJOlAWCFozEmDz3/t k+874uZJOdFfvh51AMbiUIrf8jpC8jD+iw== X-Google-Smtp-Source: AGRyM1uXdUVIDkOeB8uMpYiq6XL7+hAnqVUTDPM7ZDdp9ZDOZgO8+w43n8/GXDoTmqSHoa96nOGbNQ== X-Received: by 2002:a05:622a:144:b0:305:ad2:44f with SMTP id v4-20020a05622a014400b003050ad2044fmr10139156qtw.494.1656350247270; Mon, 27 Jun 2022 10:17:27 -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 t12-20020a05620a450c00b006a746826feesm9524646qkp.120.2022.06.27.10.17.26 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 27 Jun 2022 10:17:26 -0700 (PDT) From: Tom Rini To: u-boot@lists.denx.de Subject: [PATCH 1/4] doc: Migrate CodingStyle wiki page to sphinx Date: Mon, 27 Jun 2022 13:17:19 -0400 Message-Id: <20220627171722.1153337-2-trini@konsulko.com> X-Mailer: git-send-email 2.25.1 In-Reply-To: <20220627171722.1153337-1-trini@konsulko.com> References: <20220627171722.1153337-1-trini@konsulko.com> 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 Move the current CodingStyle wiki page to doc/develop/codingstyle.rst. The changes here are for formatting or slight rewording so that it reads well when linking to other sphinx documents. Signed-off-by: Tom Rini --- doc/develop/codingstyle.rst | 211 ++++++++++++++++++++++++++++++++++++ doc/develop/index.rst | 8 ++ 2 files changed, 219 insertions(+) create mode 100644 doc/develop/codingstyle.rst diff --git a/doc/develop/codingstyle.rst b/doc/develop/codingstyle.rst new file mode 100644 index 000000000000..a41aed2764fb --- /dev/null +++ b/doc/develop/codingstyle.rst @@ -0,0 +1,211 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +U-Boot Coding Style +=================== + +The following Coding Style requirements shall be mandatory for all code contributed to +the U-Boot project. + +Exceptions are only allowed if code from other projects is integrated with no +or only minimal changes. + +The following rules apply: + +* All contributions to U-Boot should conform to the `Linux kernel + coding style `_ + and the `Linent script `_. + * The exception for net files to the `multi-line comment + `_ + applies only to Linux, not to U-Boot. Only large hunks which are copied + unchanged from Linux may retain that comment format. +* Use patman to send your patches (``tools/patman/patman -H`` for full + instructions). With a few tags in your commits this will check your patches + and take care of emailing them. +* If you don't use patman, make sure to run ``scripts/checkpatch.pl``. For + more information, read :doc:`checkpatch`. Note that this should be done + *before* posting on the mailing list! +* Source files originating from different projects (for example the MTD + subsystem or the hush shell code from the BusyBox project) may, after + careful consideration, be exempted from these rules. For such files, the + original coding style may be kept to ease subsequent migration to newer + versions of those sources. +* Please note that U-Boot is implemented in C (and to some small parts in + Assembler); no C++ is used, so please do not use C++ style comments (//) in + your code. + + * The sole exception here is for SPDX tags in some files (checkpatch.pl will warn you). + +* Please also stick to the following formatting rules: + + * Remove any trailing white space + * Use TAB characters for indentation and vertical alignment, not spaces + * Make sure NOT to use DOS ``\r\n`` line feeds + * Do not add more than 2 consecutive empty lines to source files + * Do not add trailing empty lines to source files + * Using the option ``git config --global color.diff auto`` will help to + visually see whitespace problems in ``diff`` output from ``git``. + * In Emacs one can use ``=M-x whitespace-global-mode=`` to get visual + feedback on the nasty details. ``=M-x whitespace-cleanup=`` does The Right + Thing (tm) + +Submissions of new code or patches that do not conform to these requirements +shall be rejected with a request to reformat the changes. + +U-Boot Code Documentation +------------------------- + +U-Boot adopted the kernel-doc annotation style, this is the only exception from +multi-line comment rule of Coding Style. While not mandatory, adding +documentation is strongly advised. The Linux kernel `kernel-doc `_ documentation applies with no changes. +applies with no changes. + +Use structures for I/O access +----------------------------- + +U-Boot typically uses a C structure to map out the registers in an I/O region, rather than offsets. The reasons for this are: + +* It dissociates the register location (offset) from the register type, which + means the developer has to make sure the type is right for each access, + whereas with the struct method, this is checked by the compiler; +* It avoids actually writing all offsets, which is (more) error- prone; +* It allows for better compile time sanity-checking of values we write to registers. + +Some reasons why you might not use C structures: + +* Where the registers appear at different offsets in different hardware + revisions supported by the same driver +* Where the driver only uses a small subset of registers and it is not worth + defining a struct to cover them all, with large empty regions +* Where the offset of a register might be hard to figure out when buried a long + way down a structure, possibly with embedded sub-structures +* This may need to change to the kernel model if we allow for more run-time + detection of what drivers are appropriate for what we're running on. + +Please use check_member() to verify that your structure is the expected size, or that particular members appear at the right offset. + +Include files +------------- + +You should follow this ordering in U-Boot. The common.h header (which is going away at some point) should always be first, followed by other headers in order, then headers with directories, then local files:: + + + + + + + + + + "local.h" + +Within that order, sort your includes. + +It is important to include common.h first since it provides basic features used by most files, e.g. CONFIG options. + +For files that need to be compiled for the host (e.g. tools), you need to use ``#ifndef USE_HOSTCC`` to avoid including common.h since it includes a lot of internal U-Boot things. See common/image.c for an example. + +If your file uses driver model, include in the C file. Do not include dm.h in a header file. Try to use forward declarations (e.g. ``struct udevice``) instead. + +Filenames +--------- + +For .c and .h files try to use underscore rather than hyphen unless you want the file to stand out (e.g. driver-model uclasses should be named xxx-uclass.h. Avoid upper case and keep the names fairly short. + +Function and struct comments +---------------------------- + +Non-trivial functions should have a comment which describes what they do. If it is an exported function, put the comment in the header file so the API is in one place. If it is a static function, put it in the C file. + +If the function returns errors, mention that and list the different errors that are returned. If it is merely passing errors back from a function it calls, then you can skip that. + +See `here `_ for style. + +Driver model +------------ + +When declaring a device, try to use ``struct udevice *dev``, i.e. ``dev`` as the name:: + + struct udevice *dev; + +Use ``ret`` as the return value:: + + struct udevice *dev; + int ret; + + ret = uclass_first_device_err(UCLASS_ACPI_PMC, &dev); + if (ret) + return log_msg_ret("pmc", dev); + +Consider using log_reg() or log_msg_ret() to return a value (see above) + +Add a ``p`` suffix on return arguments:: + + int dm_pci_find_class(uint find_class, int index, struct udevice **devp) + { + ... + *devp = dev; + + return 0; + } + +There are standard variable names that you should use in drivers: + +* ``struct xxx_priv`` and ``priv`` for dev_get_priv() +* ``struct xxx_plat`` and ``plat`` for dev_get_platdata() + +For example:: + + struct simple_bus_plat { + u32 base; + u32 size; + u32 target; + }; + + /* Davinci MMC board definitions */ + struct davinci_mmc_priv { + struct davinci_mmc_regs *reg_base; /* Register base address */ + uint input_clk; /* Input clock to MMC controller */ + struct gpio_desc cd_gpio; /* Card Detect GPIO */ + struct gpio_desc wp_gpio; /* Write Protect GPIO */ + }; + + struct rcar_gpio_priv *priv = dev_get_priv(dev); + + struct pl01x_serial_platdata *plat = dev_get_platdata(dev); + +Other +----- + +Some minor things: + +* Put a blank line before the last ``return`` in a function unless it is the only line:: + + struct udevice *pci_get_controller(struct udevice *dev) + { + while (device_is_on_pci_bus(dev)) + dev = dev->parent; + + return dev; + } + +Tests +----- + + +Please add tests when you add code. Please change or expand tests when you change code. + +Run the tests with:: + + make check + make qcheck (skips some tests) + +Python tests are in test/py/tests - see the docs in test/py for info. + +Try to write your tests in C if you can. For example, tests to check a command +will be much faster (10-100x or more) if they can directly call run_command() +and ut_check_console_line() instead of using Python to send commands over a +pipe to U-Boot. + +Tests run all supported CI systems (gitlab, travis, azure) using scripts in the +root of the U-Boot tree. + diff --git a/doc/develop/index.rst b/doc/develop/index.rst index fe3564a9fbf4..dde47994c71a 100644 --- a/doc/develop/index.rst +++ b/doc/develop/index.rst @@ -3,6 +3,14 @@ Develop U-Boot ============== +General +------- + +.. toctree:: + :maxdepth: 1 + + codingstyle + Implementation -------------- -- 2.25.1