From patchwork Mon Feb 12 05:15:44 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Joel Stanley X-Patchwork-Id: 127925 Delivered-To: patch@linaro.org Received: by 10.46.124.24 with SMTP id x24csp2878860ljc; Sun, 11 Feb 2018 21:17:12 -0800 (PST) X-Google-Smtp-Source: AH8x224BtddsnAvtC50k0WdpmFzDWCTteipdP5rxu3fF9hddsdwoRmSS86SjKO4ekbPF0svNrOaJ X-Received: by 10.101.80.69 with SMTP id k5mr8530120pgo.431.1518412632313; Sun, 11 Feb 2018 21:17:12 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1518412632; cv=none; d=google.com; s=arc-20160816; b=p5uLKamv9TzVRNFhT4gPnkNPx+FCib9AuUdUKIEEvxylc0m0AWMcEZCyL84zKNA0bq f/Mhp9/mOpTFDPVHuS811Zjgy81dd8+k3NN/qMGquHkvvo+RB7su8qlo+dKXJSU89KIv wQoX66+3q0xVzhqJ7Af2WHFRj9+mw3RrBXBN2qr+G6QQG2c7Ep5IP0/H7GVm7WcwAn0P 27bYI6RxO9a1yN6cYZIrq0j4BQ4svlJcBKUFv6rjzcELOg8XbCEntOdE+LQpD9HJjfRN mbcxkpJ3niT9juyHKFNt0hjWn4JlUj7F3rNbRt1L/ZfQgYanPNl1kqKop6xkNmvVtc3Z J9PQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:sender:references:in-reply-to:message-id:date :subject:cc:to:from:dkim-signature:arc-authentication-results; bh=rNzHqYsvJJiXVpH19xWBuCpdAEWoaA62sThTAClHcLk=; b=JM6avKEITzE+EufF3dvFoF9WwVwHkBYKi9aMI04C21kjhfe07HW6FSzZ76eIOvFzCT bjc0YaJEvF9HSb7t7uQqUax9SBpHEfQ4MmKgKrrzzbgVwpLqg72ZL3EW/S9Ho0BEvT2X fNHBLIGYHkSl+kToO4qR8ho44v5KwllDihiI8aK9RJYppi+0wmF18tiIzfm7ijaT3X4u Wkx2EDYvDS2GZYHjzmKX2qfvTfm6EOiTX0sF1XKuc+VBQZEhCPwVyxTSN0CMTnT31RVb v/PZmpAb6VuYqoyyo9F8AXFRzHRZHU2zQmAQg0YMRRp1hmVOw/BHt6uctUjDqeD7q7Ph 18+Q== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@gmail.com header.s=20161025 header.b=t8oX1eG8; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Return-Path: Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id q75si5779712pfq.220.2018.02.11.21.17.12; Sun, 11 Feb 2018 21:17:12 -0800 (PST) Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67; Authentication-Results: mx.google.com; dkim=fail header.i=@gmail.com header.s=20161025 header.b=t8oX1eG8; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S932559AbeBLFRD (ORCPT + 13 others); Mon, 12 Feb 2018 00:17:03 -0500 Received: from mail-pg0-f66.google.com ([74.125.83.66]:39735 "EHLO mail-pg0-f66.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S932467AbeBLFQ4 (ORCPT ); Mon, 12 Feb 2018 00:16:56 -0500 Received: by mail-pg0-f66.google.com with SMTP id w17so6817733pgv.6; Sun, 11 Feb 2018 21:16:56 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=sender:from:to:cc:subject:date:message-id:in-reply-to:references; bh=rNzHqYsvJJiXVpH19xWBuCpdAEWoaA62sThTAClHcLk=; b=t8oX1eG82SL8dNu8ePVbTuXvHxHAZBDlPuXY72vvPDd1hmCqMBzRHWI8EYU9CUlm1g Qu4LU8ve/cE3w0YL/oPVqgQUuKJE92tXIQv1tWPxL2eD0xyhup9vGh09gbcuuBpy3sWW if7SdrtpcqbGVUtkqdrW6/FMPBiLA2IjSVE5/4NJefsYnRgJYrcI2S3hPwDTA3JL16b3 csZdzg5HrJDx2W6zZGYkZzJ2dxBvqQrVSEyMtGpPKFDOtMi9Jua2WLWK9Iyuhf9qpEpL JBmI4/XsysvEUVYMy9tHan36jpV384Y97W4w70O/jhZP4gzmB9YbCVRqcLqdK01L7uc+ L/hg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:sender:from:to:cc:subject:date:message-id :in-reply-to:references; bh=rNzHqYsvJJiXVpH19xWBuCpdAEWoaA62sThTAClHcLk=; b=PChkOCc/wmLaZQ8yGCExYmk7ZYa5aXZ12VfqkQWf+YBrK9C3llHttvxklbsg399ScF MSae8GUrR/8mF0J5XlQFvAiOKzZtnGOfcMyuUThKSTzRS48IN5poAY+oGzDUduvZOlOL GDkQSD4Ar6HrNEz0qbl45fmLk6nD6Scjf2SE+/HhSihEp2ac2qZznmM5BvM/e18E/b3K +Kb4hWIX8CkbkWvZaYrJvScH8WQfFTC/g3FtJ7vXubv8vWpp415DY6fY/KVR2mk0RPwj M1B+sflZP3HV4QB68QgvJ1cxh2gK6uTHCiuQP4QYboknicmLIFPNFseKtKmBozbAC+v7 CvwQ== X-Gm-Message-State: APf1xPD5GsJl/xKTUU9jozJszHn+m5BX/yZf2dx/8oXl3kL2ET4BJKci w131UGcxkCPa+S2q7RBkpWo= X-Received: by 10.99.137.195 with SMTP id v186mr7816810pgd.90.1518412615535; Sun, 11 Feb 2018 21:16:55 -0800 (PST) Received: from aurora.jms.id.au ([203.0.153.9]) by smtp.gmail.com with ESMTPSA id u13sm23646448pfd.169.2018.02.11.21.16.50 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Sun, 11 Feb 2018 21:16:54 -0800 (PST) Received: by aurora.jms.id.au (sSMTP sendmail emulation); Mon, 12 Feb 2018 15:46:48 +1030 From: Joel Stanley To: Greg Kroah-Hartman , Rob Herring , Mark Rutland Cc: Jeremy Kerr , Christopher Bostic , Brad Bishop , Edward James , linux-kernel@vger.kernel.org, devicetree@vger.kernel.org Subject: [PATCH 05/10] dt-bindings: fsi: Add specification for FSI busses Date: Mon, 12 Feb 2018 15:45:44 +1030 Message-Id: <20180212051549.8575-6-joel@jms.id.au> X-Mailer: git-send-email 2.15.1 In-Reply-To: <20180212051549.8575-1-joel@jms.id.au> References: <20180212051549.8575-1-joel@jms.id.au> Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org From: Jeremy Kerr This change introduces a proposed layout for describing FSI busses in the device tree. While the bus is probe-able, we'd still like a method of describing subordinate (eg i2c) busses that are behind FSI devices. The FSI core will be responsible for matching probed slaves & engines to their device tree nodes, so the FSI device drivers' probe() functions will be passed a struct device with the appropriate of_node populated where a matching DT node is found. Signed-off-by: Jeremy Kerr Acked-by: Joel Stanley Acked-by: Brad Bishop Acked-by: Eddie James Acked-by: Rob Herring Signed-off-by: Joel Stanley --- Documentation/devicetree/bindings/fsi/fsi.txt | 144 ++++++++++++++++++++++++++ 1 file changed, 144 insertions(+) create mode 100644 Documentation/devicetree/bindings/fsi/fsi.txt -- 2.15.1 diff --git a/Documentation/devicetree/bindings/fsi/fsi.txt b/Documentation/devicetree/bindings/fsi/fsi.txt new file mode 100644 index 000000000000..4eaf488d4015 --- /dev/null +++ b/Documentation/devicetree/bindings/fsi/fsi.txt @@ -0,0 +1,144 @@ +FSI bus & engine generic device tree bindings +============================================= + +The FSI bus is probe-able, so the OS is able to enumerate FSI slaves, and +engines within those slaves. However, we have a facility to match devicetree +nodes to probed engines. This allows for fsi engines to expose non-probeable +busses, which are then exposed by the device tree. For example, an FSI engine +that is an I2C master - the I2C bus can be described by the device tree under +the engine's device tree node. + +FSI masters may require their own DT nodes (to describe the master HW itself); +that requirement is defined by the master's implementation, and is described by +the fsi-master-* binding specifications. + +Under the masters' nodes, we can describe the bus topology using nodes to +represent the FSI slaves and their slave engines. As a basic outline: + + fsi-master { + /* top-level of FSI bus topology, bound to an FSI master driver and + * exposes an FSI bus */ + + fsi-slave@ { + /* this node defines the FSI slave device, and is handled + * entirely with FSI core code */ + + fsi-slave-engine@ { + /* this node defines the engine endpoint & address range, which + * is bound to the relevant fsi device driver */ + ... + }; + + fsi-slave-engine@ { + ... + }; + + }; + }; + +Note that since the bus is probe-able, some (or all) of the topology may +not be described; this binding only provides an optional facility for +adding subordinate device tree nodes as children of FSI engines. + +FSI masters +----------- + +FSI master nodes declare themselves as such with the "fsi-master" compatible +value. It's likely that an implementation-specific compatible value will +be needed as well, for example: + + compatible = "fsi-master-gpio", "fsi-master"; + +Since the master nodes describe the top-level of the FSI topology, they also +need to declare the FSI-standard addressing scheme. This requires two cells for +addresses (link index and slave ID), and no size: + + #address-cells = <2>; + #size-cells = <0>; + +FSI slaves +---------- + +Slaves are identified by a (link-index, slave-id) pair, so require two cells +for an address identifier. Since these are not a range, no size cells are +required. For an example, a slave on link 1, with ID 2, could be represented +as: + + cfam@1,2 { + reg = <1 2>; + [...]; + } + +Each slave provides an address-space, under which the engines are accessible. +That address space has a maximum of 23 bits, so we use one cell to represent +addresses and sizes in the slave address space: + + #address-cells = <1>; + #size-cells = <1>; + + +FSI engines (devices) +--------------------- + +Engines are identified by their address under the slaves' address spaces. We +use a single cell for address and size. Engine nodes represent the endpoint +FSI device, and are passed to those FSI device drivers' ->probe() functions. + +For example, for a slave using a single 0x400-byte page starting at address +0xc00: + + engine@c00 { + reg = <0xc00 0x400>; + }; + + +Full example +------------ + +Here's an example that illustrates: + - an FSI master + - connected to an FSI slave + - that contains an engine that is an I2C master + - connected to an I2C EEPROM + +The FSI master may be connected to additional slaves, and slaves may have +additional engines, but they don't necessarily need to be describe in the +device tree if no extra platform information is required. + + /* The GPIO-based FSI master node, describing the top level of the + * FSI bus + */ + gpio-fsi { + compatible = "fsi-master-gpio", "fsi-master"; + #address-cells = <2>; + #size-cells = <0>; + + /* A FSI slave (aka. CFAM) at link 0, ID 0. */ + cfam@0,0 { + reg = <0 0>; + #address-cells = <1>; + #size-cells = <1>; + + /* FSI engine at 0xc00, using a single page. In this example, + * it's an I2C master controller, so subnodes describe the + * I2C bus. + */ + i2c-controller@c00 { + reg = <0xc00 0x400>; + + /* Engine-specific data. In this case, we're describing an + * I2C bus, so we're conforming to the generic I2C binding + */ + compatible = "some-vendor,fsi-i2c-controller"; + #address-cells = <1>; + #size-cells = <1>; + + /* I2C endpoint device: an Atmel EEPROM */ + eeprom@50 { + compatible = "atmel,24c256"; + reg = <0x50>; + pagesize = <64>; + }; + }; + }; + };