From patchwork Mon Jul 24 19:49:11 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Alan Tull X-Patchwork-Id: 9860183 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id B760460385 for ; Mon, 24 Jul 2017 19:49:24 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id AAC4C27861 for ; Mon, 24 Jul 2017 19:49:24 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 9FA6328592; Mon, 24 Jul 2017 19:49:24 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-6.9 required=2.0 tests=BAYES_00,RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 3E5A627861 for ; Mon, 24 Jul 2017 19:49:24 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1751858AbdGXTtX (ORCPT ); Mon, 24 Jul 2017 15:49:23 -0400 Received: from mail.kernel.org ([198.145.29.99]:33136 "EHLO mail.kernel.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1751548AbdGXTtU (ORCPT ); Mon, 24 Jul 2017 15:49:20 -0400 Received: from localhost.localdomain (user-0ccsrjt.cable.mindspring.com [24.206.110.125]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-SHA256 (128/128 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPSA id 10F2E22CA7; Mon, 24 Jul 2017 19:49:19 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 10F2E22CA7 Authentication-Results: mail.kernel.org; dmarc=none (p=none dis=none) header.from=kernel.org Authentication-Results: mail.kernel.org; spf=none smtp.mailfrom=atull@kernel.org From: Alan Tull To: Moritz Fischer Cc: Alan Tull , linux-kernel@vger.kernel.org, linux-fpga@vger.kernel.org Subject: [RFC 1/5] doc: fpga: add document for the fdt FPGA header Date: Mon, 24 Jul 2017 14:49:11 -0500 Message-Id: <1500925755-5727-2-git-send-email-atull@kernel.org> X-Mailer: git-send-email 2.7.4 In-Reply-To: <1500925755-5727-1-git-send-email-atull@kernel.org> References: <1500925755-5727-1-git-send-email-atull@kernel.org> Sender: linux-fpga-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-fpga@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Add a document for the open source fdt FPGA header. Signed-off-by: Alan Tull --- Documentation/fpga/fpga-header.txt | 103 +++++++++++++++++++++++++++++++++++++ 1 file changed, 103 insertions(+) create mode 100644 Documentation/fpga/fpga-header.txt diff --git a/Documentation/fpga/fpga-header.txt b/Documentation/fpga/fpga-header.txt new file mode 100644 index 0000000..0045f63 --- /dev/null +++ b/Documentation/fpga/fpga-header.txt @@ -0,0 +1,103 @@ +Open source FPGA image headers + +Alan Tull 2017 + +CONTENTS +- Introduction +- Format +- Example +- Using mkimage + +Introduction +============ + +Open source FPGA image headers have been added to allow FPGA image specific +information to be included with the image. The header format is a simplified +form of u-boot FIT images and can be expanded as real use cases are raised. +As all the FPGA kernel frameworks are intended to be vendor agnostic, so also +is the header. As libfdt's licensing is permissive, this header is also +intended to be useful for OS's other than Linux such that the FPGA image need +not be rebuilt for use under another OS. + +Format +====== + +The format of the header is a reduced FIT-like header, so it can be built +using mkimage. The header is a FDT followed by two optional binary data +sections: a Device Tree overlay and a raw FPGA image. When the image is +applied to a FPGA region, first the FPGA is programmed (if the raw image is +present) and then the DT overlay, if present, is applied. If the DT overlay +is eliminated, this header format may be used on systems running without +Device Tree. + +Example +======= + +/dts-v1/; + +/ { + description = "Program FPGA image and apply DT overlay"; + #address-cells = <1>; + + images { + fdt@1 { + description = "Flattened Device Tree blob"; + type = "flat_dt"; + data = /incbin/("/some/path/persona0.dtb"); + }; + fpga@1 { + description = "FPGA image"; + type = "fpga"; + data = /incbin/("/some/path/persona0.rbf"); + partial-fpga-config; + region-unfreeze-timeout-us = <4>; + region-freeze-timeout-us = <4>; + config-complete-timeout-us = <100>; + }; + }; +}; + +This format is compatible with FIT, but leaves out a few things that were not +needed. The compression property is left out (assuming none). The +'configurations' section is left out since there is only one possible +configuration presented here. If we see an actual use case for +configurations in the future, we could expand to support it seamlessly. + +Any FPGA image info must be included in the FPGA image section. FPGA image +info properties are defined in the fpga-region.txt Device Tree binding +document at ../devicetree/bindings/fpga/fpga-region.txt. + +The FPGA image section has to come last. + +Using mkimage +============= + +If the above example is named persona0.its, it can be compiled by using +mkimage as follows. The output file is persona0.fit. + + mkimage -f persona0.its persona0.fit + +Applying the image +================== + +A sysfs attribute 'firmware_name' is added for each FPGA region. + +To apply the image: + + echo persona.fit > /sys/class/fpga_region/region0/firmware_name + +To free up the region for reprogramming: + + echo > /sys/class/fpga_region/region0/firmware_name + +FPGA Region API Function +======================== + +An API for FPGA region has been added: + + int fpga_region_fdt_image_apply(struct fpga_region *region) + +This function will parse the header of a FPGA image and do the programming +and apply the DT overlay. The FPGA image is presented as a scatter gather +table, a contiguous buffer, or name of a firmware file in the region's FPGA +image info (region->info).