From patchwork Mon May 26 09:12:53 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Sughosh Ganu X-Patchwork-Id: 892611 Delivered-To: patch@linaro.org Received: by 2002:a5d:6e53:0:b0:3a3:61c9:c5d4 with SMTP id j19csp1103959wrz; Mon, 26 May 2025 02:14:10 -0700 (PDT) X-Forwarded-Encrypted: i=2; AJvYcCUrGXb5YY3QHDOxJXLCLvXduXHL94GdHNfai+YB6C0lZOtNKAF/hbWnr5kNcN+S+TgeJwIcgQ==@linaro.org X-Google-Smtp-Source: AGHT+IGnIsRVd8lC+kBcR5ztRgDVDhUPH08xUVgPaKD80brnfLvk4bJJjYT2MaMsFb7fQbNh1KxN X-Received: by 2002:a17:906:7951:b0:ad4:e114:581a with SMTP id a640c23a62f3a-ad85b13018emr668221666b.35.1748250850262; Mon, 26 May 2025 02:14:10 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1748250850; cv=none; d=google.com; s=arc-20240605; b=doisBIPHPok0aOb+ibNQM/SZIXp5wu2sq3aCOtA/ZCaxfqya1w0jPlrMVkvq0kJsqd BCWJXOIZT59E9iv5XWibc7v1ru9gYNRk8Mp/DnFIXb4P4HuRuBJxCrG/yDjFEfnaJpxh h5Ht+KDhMneuG2xk81H9VEKIEuj5pMbO69h8NLbJn1bvG8OTBeujOyXbpnjoOElyKYP7 T5rf6HKqD2pUk0luBBoBDsN8yHm8z3S3kk3OXywNG3eKOa9xr0aG1LTGO+hlB2R7KVy8 LBwLrTlVUylBbzlG4IIk9AxXj0s91KJz6AUmDAKp1uov1F5hnwBeT7MCfVDh6QL0nSJ/ kKNA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20240605; h=sender:errors-to:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:content-transfer-encoding :mime-version:references:in-reply-to:message-id:date:subject:cc:to :from; bh=A+x1vbEpOw2rSX/UssQ9z+Bqlv8icOcb4PZBKfOc1bU=; fh=OQsgrM7lYcbKid/8QRKDrRnr3aZuZ+FGeYy6ua/5St0=; b=MjEmIeKRkI1uBNojJdPKvfD/vAglZFzxohkfueqvBDz6V9Q8KUdhLx2rcy/RKoOh1Q Gl24ypl2p/uk+jKypDFg1fPaeHcUDCOfp1oDiF3pL9GH7QDkG7d3pEbOomtxInKv9UBX xvZ1jjBrf3IIRhKTLQzdSORZsRQXI3jXcSLpnmu2auX2rKtx0nTsN+a7kE1+XfCqZ869 vMr2ZUB/BWf/4AU4iEvFkpgo1eODm0euRIOddsI6L37B5ETOw9N8Z1tPEY6piygITFvu r13jxSlv6lhmd5kQbgs0OtcG6wL5/F2Qe9E4efDTwfzhhdxzjcVETbhWC6M7lSh48RRZ nKwg==; dara=google.com ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: domain of u-boot-bounces@lists.denx.de designates 2a01:238:438b:c500:173d:9f52:ddab:ee01 as permitted sender) smtp.mailfrom=u-boot-bounces@lists.denx.de; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from phobos.denx.de (phobos.denx.de. [2a01:238:438b:c500:173d:9f52:ddab:ee01]) by mx.google.com with ESMTPS id a640c23a62f3a-ad87fb0baf8si36778566b.286.2025.05.26.02.14.09 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 26 May 2025 02:14:10 -0700 (PDT) Received-SPF: pass (google.com: domain of u-boot-bounces@lists.denx.de designates 2a01:238:438b:c500:173d:9f52:ddab:ee01 as permitted sender) client-ip=2a01:238:438b:c500:173d:9f52:ddab:ee01; Authentication-Results: mx.google.com; spf=pass (google.com: domain of u-boot-bounces@lists.denx.de designates 2a01:238:438b:c500:173d:9f52:ddab:ee01 as permitted sender) smtp.mailfrom=u-boot-bounces@lists.denx.de; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org Received: from h2850616.stratoserver.net (localhost [IPv6:::1]) by phobos.denx.de (Postfix) with ESMTP id CE9F282E25; Mon, 26 May 2025 11:13:38 +0200 (CEST) Authentication-Results: phobos.denx.de; dmarc=fail (p=none dis=none) header.from=linaro.org Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=u-boot-bounces@lists.denx.de Received: by phobos.denx.de (Postfix, from userid 109) id 8F02D82D4E; Mon, 26 May 2025 11:13:37 +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=-1.2 required=5.0 tests=BAYES_00, RCVD_IN_DNSWL_BLOCKED,RCVD_IN_VALIDITY_RPBL_BLOCKED, RCVD_IN_VALIDITY_SAFE_BLOCKED,SPF_HELO_NONE,SPF_SOFTFAIL autolearn=no autolearn_force=no version=3.4.2 Received: from foss.arm.com (foss.arm.com [217.140.110.172]) by phobos.denx.de (Postfix) with ESMTP id 488198365C for ; Mon, 26 May 2025 11:13:35 +0200 (CEST) Authentication-Results: phobos.denx.de; dmarc=fail (p=none dis=none) header.from=linaro.org Authentication-Results: phobos.denx.de; spf=fail smtp.mailfrom=sughosh.ganu@linaro.org Received: from usa-sjc-imap-foss1.foss.arm.com (unknown [10.121.207.14]) by usa-sjc-mx-foss1.foss.arm.com (Postfix) with ESMTP id 31F48153B; Mon, 26 May 2025 02:13:19 -0700 (PDT) Received: from a079122.blr.arm.com (a079122.arm.com [10.164.21.38]) by usa-sjc-imap-foss1.foss.arm.com (Postfix) with ESMTPSA id 910DB3F673; Mon, 26 May 2025 02:13:31 -0700 (PDT) From: Sughosh Ganu To: u-boot@lists.denx.de Cc: Ilias Apalodimas , Tom Rini , Casey Connolly , Neil Armstrong , Mark Kettenis , Weijie Gao , Heinrich Schuchardt , Simon Glass , Sughosh Ganu Subject: [PATCH v3 6/6] doc: add lmb documentation Date: Mon, 26 May 2025 14:42:53 +0530 Message-Id: <20250526091253.400802-7-sughosh.ganu@linaro.org> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20250526091253.400802-1-sughosh.ganu@linaro.org> References: <20250526091253.400802-1-sughosh.ganu@linaro.org> 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.8 at phobos.denx.de X-Virus-Status: Clean The LMB module has undergone significant changes in the recent past. Add a document which briefly describes what the LMB module does, and the changes that have been made to it's design since the 2025.01 release. Signed-off-by: Sughosh Ganu Acked-by: Ilias Apalodimas --- Changes since V2: * Reflect the changed name of the API (lmb_alloc_mem) doc/api/index.rst | 1 - doc/api/lmb.rst | 7 -- doc/develop/index.rst | 1 + doc/develop/lmb.rst | 166 ++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 167 insertions(+), 8 deletions(-) delete mode 100644 doc/api/lmb.rst create mode 100644 doc/develop/lmb.rst diff --git a/doc/api/index.rst b/doc/api/index.rst index 506843ed74a..cf9d21e4c1c 100644 --- a/doc/api/index.rst +++ b/doc/api/index.rst @@ -17,7 +17,6 @@ U-Boot API documentation interrupt led linker_lists - lmb logging nvmem part diff --git a/doc/api/lmb.rst b/doc/api/lmb.rst deleted file mode 100644 index 2095bfa1618..00000000000 --- a/doc/api/lmb.rst +++ /dev/null @@ -1,7 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0+ - -Logical memory blocks -===================== - -.. kernel-doc:: include/lmb.h - :internal: diff --git a/doc/develop/index.rst b/doc/develop/index.rst index 0c83ef109ab..3c044e67927 100644 --- a/doc/develop/index.rst +++ b/doc/develop/index.rst @@ -46,6 +46,7 @@ Implementation cedit event global_data + lmb logging makefiles menus diff --git a/doc/develop/lmb.rst b/doc/develop/lmb.rst new file mode 100644 index 00000000000..b9d0f09c2bb --- /dev/null +++ b/doc/develop/lmb.rst @@ -0,0 +1,166 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Logical Memory Blocks (LMB) +=========================== + +U-Boot has support for reserving chunks of memory which is primarily +used for loading images to the DRAM memory, before these are booted, +or written to non-volatile storage medium. This functionality is +provided through the Logical Memory Blocks (LMB) module. + +Introduction +------------ + +The LMB module manages allocation requests for memory region not +occupied by the U-Boot image. Allocation requests that are made +through malloc() and similar functions result in memory getting +allocated from the heap region, which is part of the U-Boot +image. Typically, the heap memory is a few MiB in size. Loading an +image like the linux kernel might require lot more memory than what +the heap can provide. Such allocations are usually handled through the +LMB module. + +The U-Boot image typically gets relocated to the top of the usable +DRAM memory region. A typical memory layout looks as follows:: + + + + + + | | + | | + | | + | | + | | + --- +--------------+ <--- U-Boot ram top + | | | + | | Text | + | +--------------+ + | | | + | | Data | + | +--------------+ + | | | + | | BSS | + U-Boot Image +--------------+ + | | | + | | Heap | + | | | + | +--------------+ + | | | + | | | + | | Stack | + | | | + | | | + --- +--------------+ + | | + | | + | | + | | + | | + | | + | | + | | + | | + | | + | | + | | + | | + | | + +--------------+ <--- ram start + + + +The region of memory below the U-Boot image is the one controlled by +the LMB module. + + +Types of LMB Allocations +------------------------ + +There are two classes of allocation requests that get made to the LMB +module. One type of allocation requests are requesting memory of a +particular number of bytes. This type of allocation is similar to that +done using the malloc type of function calls. The other type of +allocations, are requests made for a specific memory address. The +second type of allocations are usually made for loading images to a +particular memory address. + + +LMB design Pre 2025.01 +---------------------- + +The earlier versions of U-Boot (pre 2025.01 release) +had a local memory map based LMB implementation whereby it was +possible to declare the LMB map inside a function or a C file. This +design resulted in temporary, non-global LMB maps, which also allowed +for re-use of memory. This meant that it was possible to use a region +of memory to load some image, and subsequently the same region of +memory could be used for loading a different image. A typical example +of this usage would be loading an image to a memory address, followed +by writing that image to some non-volatile storage medium. Once this +is done, the same address can be used for loading a different image +and then writing it to it's non-volatile storage +destination. Typically, environment variables like `loadaddr`, +`kernel_addr_r`, `ramdisk_addr_r` are used for loading images to +memory regions. + + +Current LMB implementation +-------------------------- + +Changes were made in the 2025.01 release to make the LMB memory map +global and persistent. With this, the LMB memory map is the same +across all of U-Boot, and also persists as long as U-Boot is +active. Even with this change, there has been consistency as far as +re-use of memory is concerned to maintain backward compatibility. It +is allowed for re-requesting the same region of memory if the memory +region has a particular attribute (LMB_NONE). + +As part of the platform boot, DRAM memory available for use in U-Boot +gets added to the LMB memory map. Any allocation requests made +subsequently will be made from this memory added as part of the board +init. + + +Allocation API +-------------- + +Any request for non-heap memory can be made through the LMB allocation +API. + +.. code-block:: c + + int lmb_alloc_mem(enum lmb_mem_type type, u64 align, + phys_addr_t *addr, phys_size_t size, + u32 flags); + +Correspondingly, the allocated memory can be free'd + +.. code-block:: c + + long lmb_free(phys_addr_t base, phys_size_t size, u32 flags); + +For a detailed API description, please refer to the header file. + + +UEFI allocations with LMB as the backend +---------------------------------------- + +The UEFI specification describes boot-time API's for allocation of +memory. These API's use the same memory that is being used by the LMB +module. Pre 2025.01 release, there wasn't any synchronisation between +the EFI sub-system and the LMB module about the memory that was +getting allocated by each of these modules. This was the primary +reason for making the LMB memory map global and persistent. With this +change, the EFI memory allocation API's have also been changed to use +the LMB module as the backend for the allocation requests. Any other +sub-system which might wish to use the same memory region for it's use +can then use the LMB as the backend for the memory allocations and +it's associated book-keeping. + + +API documentation +----------------- + +.. kernel-doc:: include/lmb.h +