From patchwork Wed May 11 20:14:22 2011 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Grant Likely X-Patchwork-Id: 1463 Return-Path: Delivered-To: unknown Received: from imap.gmail.com (74.125.159.109) by localhost6.localdomain6 with IMAP4-SSL; 08 Jun 2011 14:52:09 -0000 Delivered-To: patches@linaro.org Received: by 10.224.61.3 with SMTP id r3cs79870qah; Wed, 11 May 2011 13:14:27 -0700 (PDT) Received: by 10.223.33.80 with SMTP id g16mr2139886fad.125.1305144866566; Wed, 11 May 2011 13:14:26 -0700 (PDT) Received: from mail-fx0-f50.google.com (mail-fx0-f50.google.com [209.85.161.50]) by mx.google.com with ESMTPS id h7si921659fas.200.2011.05.11.13.14.26 (version=TLSv1/SSLv3 cipher=OTHER); Wed, 11 May 2011 13:14:26 -0700 (PDT) Received-SPF: neutral (google.com: 209.85.161.50 is neither permitted nor denied by best guess record for domain of grant.likely@secretlab.ca) client-ip=209.85.161.50; Authentication-Results: mx.google.com; spf=neutral (google.com: 209.85.161.50 is neither permitted nor denied by best guess record for domain of grant.likely@secretlab.ca) smtp.mail=grant.likely@secretlab.ca Received: by mail-fx0-f50.google.com with SMTP id 16so811705fxm.37 for ; Wed, 11 May 2011 13:14:26 -0700 (PDT) Received: by 10.223.86.197 with SMTP id t5mr1233408fal.98.1305144866092; Wed, 11 May 2011 13:14:26 -0700 (PDT) Received: from angua (business-89-133-214-82.business.broadband.hu [89.133.214.82]) by mx.google.com with ESMTPS id d18sm205361fak.22.2011.05.11.13.14.23 (version=TLSv1/SSLv3 cipher=OTHER); Wed, 11 May 2011 13:14:24 -0700 (PDT) Sender: Grant Likely Received: from localhost6.localdomain6 (angua [IPv6:::1]) by angua (Postfix) with ESMTP id D1B2F3C0169; Wed, 11 May 2011 14:14:22 -0600 (MDT) Subject: [PATCH v6 5/5] dt: add documentation of ARM dt boot interface To: linaro-dev@lists.linaro.org, Thomas Gleixner , Russell King - ARM Linux , linux-kernel@vger.kernel.org, linux-arm-kernel@lists.infradead.org From: Grant Likely Date: Wed, 11 May 2011 22:14:22 +0200 Message-ID: <20110511201422.21615.86728.stgit@localhost6.localdomain6> In-Reply-To: <20110511201401.21615.38893.stgit@localhost6.localdomain6> References: <20110511201401.21615.38893.stgit@localhost6.localdomain6> User-Agent: StGit/0.15 MIME-Version: 1.0 v6: typo fixes v5: clarified that dtb should be aligned on a 64 bit boundary in RAM. v3: added details to Documentation/arm/Booting Acked-by: Tony Lindgren Signed-off-by: Grant Likely --- Documentation/arm/Booting | 33 ++++++++++++++-- Documentation/devicetree/booting-without-of.txt | 48 +++++++++++++++++++++-- 2 files changed, 73 insertions(+), 8 deletions(-) diff --git a/Documentation/arm/Booting b/Documentation/arm/Booting index 7685029..4e686a2 100644 --- a/Documentation/arm/Booting +++ b/Documentation/arm/Booting @@ -65,13 +65,19 @@ looks at the connected hardware is beyond the scope of this document. The boot loader must ultimately be able to provide a MACH_TYPE_xxx value to the kernel. (see linux/arch/arm/tools/mach-types). - -4. Setup the kernel tagged list -------------------------------- +4. Setup boot data +------------------ Existing boot loaders: OPTIONAL, HIGHLY RECOMMENDED New boot loaders: MANDATORY +The boot loader must provide either a tagged list or a dtb image for +passing configuration data to the kernel. The physical address of the +boot data is passed to the kernel in register r2. + +4a. Setup the kernel tagged list +-------------------------------- + The boot loader must create and initialise the kernel tagged list. A valid tagged list starts with ATAG_CORE and ends with ATAG_NONE. The ATAG_CORE tag may or may not be empty. An empty ATAG_CORE tag @@ -101,6 +107,24 @@ The tagged list must be placed in a region of memory where neither the kernel decompressor nor initrd 'bootp' program will overwrite it. The recommended placement is in the first 16KiB of RAM. +4b. Setup the device tree +------------------------- + +The boot loader must load a device tree image (dtb) into system ram +at a 64bit aligned address and initialize it with the boot data. The +dtb format is documented in Documentation/devicetree/booting-without-of.txt. +The kernel will look for the dtb magic value of 0xd00dfeed at the dtb +physical address to determine if a dtb has been passed instead of a +tagged list. + +The boot loader must pass at a minimum the size and location of the +system memory, and the root filesystem location. The dtb must be +placed in a region of memory where the kernel decompressor will not +overwrite it. The recommended placement is in the first 16KiB of RAM +with the caveat that it may not be located at physical address 0 since +the kernel interprets a value of 0 in r2 to mean neither a tagged list +nor a dtb were passed. + 5. Calling the kernel image --------------------------- @@ -125,7 +149,8 @@ In either case, the following conditions must be met: - CPU register settings r0 = 0, r1 = machine type number discovered in (3) above. - r2 = physical address of tagged list in system RAM. + r2 = physical address of tagged list in system RAM, or + physical address of device tree block (dtb) in system RAM - CPU mode All forms of interrupts must be disabled (IRQs and FIQs) diff --git a/Documentation/devicetree/booting-without-of.txt b/Documentation/devicetree/booting-without-of.txt index 50619a0..7c1329d 100644 --- a/Documentation/devicetree/booting-without-of.txt +++ b/Documentation/devicetree/booting-without-of.txt @@ -12,8 +12,9 @@ Table of Contents ================= I - Introduction - 1) Entry point for arch/powerpc - 2) Entry point for arch/x86 + 1) Entry point for arch/arm + 2) Entry point for arch/powerpc + 3) Entry point for arch/x86 II - The DT block format 1) Header @@ -148,7 +149,46 @@ upgrades without significantly impacting the kernel code or cluttering it with special cases. -1) Entry point for arch/powerpc +1) Entry point for arch/arm +--------------------------- + + There is one single entry point to the kernel, at the start + of the kernel image. That entry point supports two calling + conventions. A summary of the interface is described here. A full + description of the boot requirements is documented in + Documentation/arm/Booting + + a) ATAGS interface. Minimal information is passed from firmware + to the kernel with a tagged list of predefined parameters. + + r0 : 0 + + r1 : Machine type number + + r2 : Physical address of tagged list in system RAM + + b) Entry with a flattened device-tree block. Firmware loads the + physical address of the flattened device tree block (dtb) into r2, + r1 is not used, but it is considered good practise to use a valid + machine number as described in Documentation/arm/Booting. + + r0 : 0 + + r1 : Valid machine type number. When using a device tree, + a single machine type number will often be assigned to + represent a class or family of SoCs. + + r2 : physical pointer to the device-tree block + (defined in chapter II) in RAM. Device tree can be located + anywhere in system RAM, but it should be aligned on a 64 bit + boundary. + + The kernel will differentiate between ATAGS and device tree booting by + reading the memory pointed to by r2 and looking for either the flattened + device tree block magic value (0xd00dfeed) or the ATAG_CORE value at + offset 0x4 from r2 (0x54410001). + +2) Entry point for arch/powerpc ------------------------------- There is one single entry point to the kernel, at the start @@ -226,7 +266,7 @@ it with special cases. cannot support both configurations with Book E and configurations with classic Powerpc architectures. -2) Entry point for arch/x86 +3) Entry point for arch/x86 ------------------------------- There is one single 32bit entry point to the kernel at code32_start,