From patchwork Thu Oct 8 15:03:41 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: =?utf-8?q?Marc_Mar=C3=AD?= X-Patchwork-Id: 527755 Return-Path: X-Original-To: incoming-dt@patchwork.ozlabs.org Delivered-To: patchwork-incoming-dt@bilbo.ozlabs.org Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by ozlabs.org (Postfix) with ESMTP id 88330141112 for ; Fri, 9 Oct 2015 02:03:47 +1100 (AEDT) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1756652AbbJHPDq (ORCPT ); Thu, 8 Oct 2015 11:03:46 -0400 Received: from mx1.redhat.com ([209.132.183.28]:37885 "EHLO mx1.redhat.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1756384AbbJHPDp (ORCPT ); Thu, 8 Oct 2015 11:03:45 -0400 Received: from int-mx14.intmail.prod.int.phx2.redhat.com (int-mx14.intmail.prod.int.phx2.redhat.com [10.5.11.27]) by mx1.redhat.com (Postfix) with ESMTPS id 27B4D91E9D; Thu, 8 Oct 2015 15:03:45 +0000 (UTC) Received: from localhost (vpn1-7-216.ams2.redhat.com [10.36.7.216]) by int-mx14.intmail.prod.int.phx2.redhat.com (8.14.4/8.14.4) with ESMTP id t98F3hpg012463; Thu, 8 Oct 2015 11:03:44 -0400 From: =?UTF-8?q?Marc=20Mar=C3=AD?= To: linux-kernel@vger.kernel.org Cc: Drew , Stefan Hajnoczi , "Kevin O'Connor" , Gerd Hoffmann , Laszlo , Arnd Bergmann , Rob Herring , Mark Rutland , Alexander Graf , devicetree@vger.kernel.org, =?UTF-8?q?Marc=20Mar=C3=AD?= Subject: [PATCH v5] QEMU fw_cfg DMA interface documentation Date: Thu, 8 Oct 2015 17:03:41 +0200 Message-Id: <1444316621-21863-1-git-send-email-markmb@redhat.com> In-Reply-To: <1444316523-21711-1-git-send-email-markmb@redhat.com> References: <1444316523-21711-1-git-send-email-markmb@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.68 on 10.5.11.27 Sender: devicetree-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: devicetree@vger.kernel.org Add fw_cfg DMA interface specfication in the fw_cfg documentation. Signed-off-by: Marc Marí --- Documentation/devicetree/bindings/arm/fw-cfg.txt | 52 +++++++++++++++++++++++- 1 file changed, 51 insertions(+), 1 deletion(-) diff --git a/Documentation/devicetree/bindings/arm/fw-cfg.txt b/Documentation/devicetree/bindings/arm/fw-cfg.txt index 953fb64..0633aad 100644 --- a/Documentation/devicetree/bindings/arm/fw-cfg.txt +++ b/Documentation/devicetree/bindings/arm/fw-cfg.txt @@ -38,6 +38,9 @@ The presence of the registers can be verified by selecting the "signature" blob with key 0x0000, and reading four bytes from the data register. The returned signature is "QEMU". +If the DMA interface is available, then reading the DMA Address Register +returns 0x51454d5520434647 ("QEMU CFG" in big-endian format). + The outermost protocol (involving the write / read sequences of the control and data registers) is expected to be versioned, and/or described by feature bits. The interface revision / feature bitmap can be retrieved with key 0x0001. The @@ -45,6 +48,51 @@ blob to be read from the data register has size 4, and it is to be interpreted as a uint32_t value in little endian byte order. The current value (corresponding to the above outer protocol) is zero. +If bit 1 of the feature bitmap is set, the DMA interface is present. This +can be used through the 64-bit wide address register. + +The address register is in big-endian format. The value for the register is 0 +at startup and after an operation. A write to the lower half triggers an +operation. This means, that operations with 32-bit addresses can be triggered +with just one write, whereas operations with 64-bit addresses can be triggered +with one 64-bit write or two 32-bit writes, starting with the higher part. + +In this register, the physical address of a FWCfgDmaAccess structure in RAM +should be written. This is the format of the FWCfgDmaAccess structure: + +typedef struct FWCfgDmaAccess { + uint32_t control; + uint32_t length; + uint64_t address; +} FWCfgDmaAccess; + +The fields of the structure are in big endian mode, and the field at the lowest +address is the "control" field. + +The "control" field has the following bits: + - Bit 0: Error + - Bit 1: Read + - Bit 2: Skip + - Bit 3: Select. The upper 16 bits are the selected index. + +When an operation is triggered, if the "control" field has bit 3 set, the +upper 16 bits are interpreted as an index of a firmware configuration item. +This has the same effect as writing the selector register. + +If the "control" field has bit 1 set, a read operation will be performed. +"length" bytes for the current selector and offset will be copied into the +physical RAM address specified by the "address" field. + +If the "control" field has bit 2 set (and not bit 1), a skip operation will be +performed. The offset for the current selector will be advanced "length" bytes. + +To check the result, read the "control" field: + error bit set -> something went wrong. + all bits cleared -> transfer finished successfully. + otherwise -> transfer still in progress (doesn't happen + today due to implementation not being async, + but may in the future). + The guest kernel is not expected to use these registers (although it is certainly allowed to); the device tree bindings are documented here because this is where device tree bindings reside in general. @@ -56,6 +104,8 @@ Required properties: - reg: the MMIO region used by the device. * Bytes 0x0 to 0x7 cover the data register. * Bytes 0x8 to 0x9 cover the selector register. + * With DMA interface enabled: Bytes 0x10 to 0x17 cover the DMA address + register. * Further registers may be appended to the region in case of future interface revisions / feature bits. @@ -66,7 +116,7 @@ Example: #address-cells = <0x2>; fw-cfg@9020000 { + reg = <0x0 0x9020000 0x0 0x18>; compatible = "qemu,fw-cfg-mmio"; - reg = <0x0 0x9020000 0x0 0xa>; }; };