From patchwork Mon Jul 11 17:14:34 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tom Rini X-Patchwork-Id: 1655029 X-Patchwork-Delegate: xypron.glpk@gmx.de Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: bilbo.ozlabs.org; dkim=pass (1024-bit key; unprotected) header.d=konsulko.com header.i=@konsulko.com header.a=rsa-sha256 header.s=google header.b=XRiQya5i; dkim-atps=neutral Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=lists.denx.de (client-ip=85.214.62.61; helo=phobos.denx.de; envelope-from=u-boot-bounces@lists.denx.de; receiver=) Received: from phobos.denx.de (phobos.denx.de [85.214.62.61]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits)) (No client certificate requested) by bilbo.ozlabs.org (Postfix) with ESMTPS id 4LhVrH1cZcz9s07 for ; Tue, 12 Jul 2022 03:15:11 +1000 (AEST) Received: from h2850616.stratoserver.net (localhost [IPv6:::1]) by phobos.denx.de (Postfix) with ESMTP id F08298404A; Mon, 11 Jul 2022 19:14:53 +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="XRiQya5i"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id E17018404C; Mon, 11 Jul 2022 19:14:47 +0200 (CEST) X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on phobos.denx.de X-Spam-Level: X-Spam-Status: No, score=-2.1 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,SPF_HELO_NONE,SPF_PASS, T_SCC_BODY_TEXT_LINE autolearn=ham autolearn_force=no version=3.4.2 Received: from mail-qv1-xf34.google.com (mail-qv1-xf34.google.com [IPv6:2607:f8b0:4864:20::f34]) (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 26EDB84020 for ; Mon, 11 Jul 2022 19:14:44 +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-xf34.google.com with SMTP id kh20so818056qvb.5 for ; Mon, 11 Jul 2022 10:14:44 -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:in-reply-to:references :mime-version:content-transfer-encoding; bh=F0+Xb68ioBuLvsZGI3Q9wnfxmYl9IPoKM1tcVUCIEfI=; b=XRiQya5inr2Vri9ttaChPXsx4WTUqLWuqGY4C0dzeQzcgg4IZvk2UgeNWKQFjZQJya Zb+7PyS0ZrbZG3SKnteL4AHDWswQSNvuyXdGDJsZJvYqCcvbSWhhQ9GZRgcaTuBT/R88 c8Xk2cIwQHtF9M++WqBfK8TWW2XnS2YnaG/z8= 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:in-reply-to :references:mime-version:content-transfer-encoding; bh=F0+Xb68ioBuLvsZGI3Q9wnfxmYl9IPoKM1tcVUCIEfI=; b=S8t86KnI7taUkC6nGFqVJRpR1M73pmcyyYcmi6jSG5IBewSrZPGDl4+2nF2k6uXE7I t/vgSht/5SslcKavj3MRTA2iAwONWrKi1PNAN0CB4RgluMsa7XcA6Q79XZOUUUrjhRjT +4jq6wPSov1LSouiXjbBt6pnKNBHwRPVwDt6lHYv9D9vrsRFy/CPniDZqcmsyoGpyuXZ DMwan7+m7dfBlAmCZZoKxjhNUNYkK7UtX7cuGk0GZDgQbyp/aJbdi01w+X+du+xxQlhj XIr9mUU2vGPCsKrTPsQhzutceKF2EYm+OZSEcn1Y5v6wOMVfyMo1fThaGUEjvGVtSs2/ CSLg== X-Gm-Message-State: AJIora9b1URdSYXMAQNCwWL5q97/wd+Buv5tDJS0BlmpfEtnavNi80qK GVZVL4VNllTH6RU1TKorIn3rph4Yg04SNQ== X-Google-Smtp-Source: AGRyM1s2L9vvQfDy9InlsJ+MhJX6/Il9popd8vGazudDC7YtcfbSqPndfo9m6S6eYvhUDJrn3QgANw== X-Received: by 2002:a05:6214:3002:b0:470:7273:bee5 with SMTP id ke2-20020a056214300200b004707273bee5mr14086821qvb.98.1657559682485; Mon, 11 Jul 2022 10:14:42 -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 bp20-20020a05622a1b9400b0031ea95094dcsm5519536qtb.72.2022.07.11.10.14.41 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 11 Jul 2022 10:14:41 -0700 (PDT) From: Tom Rini To: u-boot@lists.denx.de Cc: Heinrich Schuchardt Subject: [PATCH 2/7] doc: Migrate DesignPrinciples wiki page to Sphinx Date: Mon, 11 Jul 2022 13:14:34 -0400 Message-Id: <20220711171439.1657280-2-trini@konsulko.com> X-Mailer: git-send-email 2.25.1 In-Reply-To: <20220711171439.1657280-1-trini@konsulko.com> References: <20220711171439.1657280-1-trini@konsulko.com> MIME-Version: 1.0 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 DesignPrinciples wiki page to doc/develop/designprinciples.rst. The changes here are for formatting or slight rewording so that it reads well when linking to other Sphinx documents. Cc: Heinrich Schuchardt Signed-off-by: Tom Rini --- Changes in v2: - Assorted wiki -> Sphinx style corrections and a few typo fixes, per Heinrich --- doc/develop/designprinciples.rst | 205 +++++++++++++++++++++++++++++++ doc/develop/index.rst | 1 + 2 files changed, 206 insertions(+) create mode 100644 doc/develop/designprinciples.rst diff --git a/doc/develop/designprinciples.rst b/doc/develop/designprinciples.rst new file mode 100644 index 000000000000..43aeb5dacf5f --- /dev/null +++ b/doc/develop/designprinciples.rst @@ -0,0 +1,205 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +U-Boot Design Principles +======================== + +The 10 Golden Rules of U-Boot design +------------------------------------ + +Keep it Small +^^^^^^^^^^^^^ + +U-Boot is a Boot Loader, i.e. its primary purpose in the shipping +system is to load some operating system. +That means that U-Boot is +necessary to perform a certain task, but it's nothing you want to +throw any significant resources at. Typically U-Boot is stored in +relatively small NOR flash memory, which is expensive +compared to the much larger NAND devices often used to store the +operating system and the application. + +At the moment, U-Boot supports boards with just 128 KiB ROM or with +256 KiB NOR flash. We should not easily ignore such configurations - +they may be the exception in among all the other supported boards, +but if a design uses such a resource-constrained hardware setup it is +usually because costs are critical, i. e. because the number of +manufactured boards might be tens or hundreds of thousands or even +millions... + +A usable and useful configuration of U-Boot, including a basic +interactive command interpreter, support for download over Ethernet +and the capability to program the flash shall fit in no more than 128 !KiB. + +Keep it Fast +^^^^^^^^^^^^ + +The end user is not interested in running U-Boot. In most embedded +systems he is not even aware that U-Boot exists. The user wants to +run some application code, and that as soon as possible after switching +on his device. + +It is therefore essential that U-Boot is as fast as possible, +especially that it loads and boots the operating system as fast as possible. + +To achieve this, the following design principles shall be followed: + +* Enable caches as soon and whenever possible + +* Initialize devices only when they are needed within U-Boot, i.e. don't + initialize the Ethernet interface(s) unless U-Boot performs a download over + Ethernet; don't initialize any IDE or USB devices unless U-Boot actually + tries to load files from these, etc. (and don't forget to shut down these + devices after using them - otherwise nasty things may happen when you try to + boot your OS). + +Also, building of U-Boot shall be as fast as possible. +This makes it easier to run a build for all supported configurations +or at least for all configurations of a specific architecture, +which is essential for quality assurance. +If building is cumbersome and slow, most people will omit +this important step. + +Keep it Simple +^^^^^^^^^^^^^^ + +U-Boot is a boot loader, but it is also a tool used for board +bring-up, for production testing, and for other activities + +Keep it Portable +^^^^^^^^^^^^^^^^ + +U-Boot is a boot loader, but it is also a tool used for board +bring-up, for production testing, and for other activities that are +very closely related to hardware development. So far, it has been +ported to several hundreds of different boards on about 30 different +processor families - please make sure that any code you add can be +used on as many different platforms as possible. + +Avoid assembly language whenever possible - only the reset code with +basic CPU initialization, maybe a static DRAM initialization and the C +stack setup should be in assembly. +All further initializations should be done in C using assembly/C +subroutines or inline macros. These functions represent some +kind of HAL functionality and should be defined consistently on all +architectures. E.g. Basic MMU and cache control, stack pointer manipulation. +Non-existing functions should expand into empty macros or error codes. + +Don't make assumptions over the environment where U-Boot is running. +It may be communicating with a human operator on directly attached +serial console, but it may be through a GSM modem as well, or driven +by some automatic test or control system. So don't output any fancy +control character sequences or similar. + +Keep it Configurable +^^^^^^^^^^^^^^^^^^^^ + +Section "Keep it Small" already explains about the size restrictions +for U-Boot on one side. On the other side, U-Boot is a powerful tool +with many, many extremely useful features. The maintainer or user of +each board will have to decide which features are important to him and +what shall be included with his specific board configuration to meet +his current requirements and restrictions. + +Please make sure that it is easy to add or remove features from a +board configuration, so everybody can make the best use of U-Boot on +his system. + +If a feature is not included, it should not have any residual code +bloating the build. + +Keep it Debuggable +^^^^^^^^^^^^^^^^^^ + +Of course debuggable code is a big benefit for all of us contributing +in one way or another to the development of the U-Boot project. But +as already mentioned in section "Keep it Portable" above, U-Boot is +not only a tool in itself, it is often also used for hardware +bring-up, so debugging U-Boot often means that we don't know if we are +tracking down a problem in the U-Boot software or in the hardware we +are running on. Code that is clean and easy to understand and to +debug is all the more important to many of us. + +* One important feature of U-Boot is to enable output to the (usually serial) + console as soon as possible in the boot process, even if this causes + tradeoffs in other areas like memory footprint. + +* All initialization steps shall print some "begin doing this" message before + they actually start, and some "done" message when they complete. For example, + RAM initialization and size detection may print a "RAM: " before they start, + and "256 MB\n" when done. The purpose of this is that you can always see + which initialization step was running if there should be any problem. This + is important not only during software development, but also for the service + people dealing with broken hardware in the field. + +* U-Boot should be debuggable with simple JTAG or BDM equipment. It shall use + a simple, single-threaded execution model. Avoid any magic, which could + prevent easy debugging even when only 1 or 2 hardware breakpoints are + available. + +Keep it Usable +^^^^^^^^^^^^^^ + +Please always keep in mind that there are at least three different +groups of users for U-Boot, with completely different expectations +and requirements: + +* The end user of an embedded device just wants to run some application; he + does not even want to know that U-Boot exists and only rarely interacts with + it (for example to perform a reset to factory default settings etc.) + +* System designers and engineers working on the development of the application + and/or the operating system want a powerful tool that can boot from any boot + device they can imagine, they want it fast and scriptable and whatever - in + short, they want as many features supported as possible. And some more. + +* The engineer who ports U-Boot to a new board and the board maintainer want + U-Boot to be as simple as possible so porting it to and maintaining it on + their hardware is easy for them. + +* Make it easy to test. Add debug code (but don't re-invent the wheel - use + existing macros like debug() or debugX()). + +Please always keep in mind that U-Boot tries to meet all these +different requirements. + +Keep it Maintainable +^^^^^^^^^^^^^^^^^^^^ + +* Avoid ``#ifdefs`` where possible + +* Use "weak" functions + +* Always follow the :doc:`codingstyle` requirements. + +Keep it Beautiful +^^^^^^^^^^^^^^^^^ + +* Keep the source code clean: strictly follow the :doc:`codingstyle`, + keep lists (target names in the Makefiles, board names, etc.) + alphabetically sorted, etc. + +* Keep U-Boot console output clean: output only really necessary information, + be terse but precise, keep output vertically aligned, do not use control + character sequences (e.g. backspaces or \\r to do "spinning wheel" activity + indicators), etc. + +Keep it Open +^^^^^^^^^^^^ + +Contribute your work back to the whole community. Submit your changes +and extensions as patches to the U-Boot mailing list. + +Lemmas from the golden rules +---------------------------- + +Generic Code is Good Code +^^^^^^^^^^^^^^^^^^^^^^^^^ + +New code shall be as generic as possible and added to the U-Boot +abstraction hierarchy as high as possible. As few code as possible shall be +added in board directories as people usually do not expect re-usable code +there. Thus peripheral drivers should be put below +"drivers" even if they start out supporting only one specific +configuration. Note that it is not a requirement for such a first +instance to be generic as genericity generally cannot be extrapolated +from a single data point. diff --git a/doc/develop/index.rst b/doc/develop/index.rst index dde47994c71a..c0f4f0ba413a 100644 --- a/doc/develop/index.rst +++ b/doc/develop/index.rst @@ -10,6 +10,7 @@ General :maxdepth: 1 codingstyle + designprinciples Implementation --------------