Received: by 2002:ac0:98c7:0:0:0:0:0 with SMTP id g7-v6csp235882imd; Fri, 26 Oct 2018 07:48:59 -0700 (PDT) X-Google-Smtp-Source: AJdET5c7lhckb4dRFaVX+JRF8tStMbcozy7/KHXB5dPOu/+hl9WIpcWlKd/Vvr2msUJnv9KYFOgp X-Received: by 2002:a17:902:6a8b:: with SMTP id n11-v6mr3751544plk.16.1540565339574; Fri, 26 Oct 2018 07:48:59 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1540565339; cv=none; d=google.com; s=arc-20160816; b=pbkZ3UCzouAJUW0aMT0fg9AqADIWW7CQsjQTgr6goIa+br6WyW2OahIHgKiQpO0jkQ KHQFCCyq/6BM+DUSs5h8tKFelsh68P7B3Zgwe8dKhZtKo+03TNJ8oqhWpZwJw50oaGhk nZBf7Vg3uxUtI1tRXr9iVLSa3VHWOGj9ozPN+BuTKp5uyerxqWi/4GzOHbLFodLuTACf zRRLa2dW3ypTq7Wm8WaZ8wGJvMrq2WBOS/hoPSxkYg/LZ8+AtnSR1PRN24ZZkT1LoVDf amB+SuOyydLuM7vBCNsQdKZNCYa9tgI/55URprQXNXz7wC1YvYjwB5AGPQ2+27TimWos KFQQ== 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; bh=XaR1kW2vxkYvlioM27OhZGhi1jYAuG9rFnEBk9kYYE8=; b=GQpn1sO+DgKRMKlXns5GCTyjZKz4AnYvv2cQ6uahpYoC7YnJaiYfjTd/QnES4nsgWZ 5tso3ZxJX2Bl+x0Dr84PK1tMEsJjzQUC2+D7en1dYtIh7N5jKP9lF5sgId7TUVJW7aUj 8L/jb4aRu4T7LHqBZ/l4WGq8kixsGsXVtLx/ZSS5Qy0kR/NhW9dPU+yYQinGx3gqy89l UtbitJ3tQ3icC+pzZ2hV1Yh3j6vidIE+LH8FuKGCO2C6Heu8mIfaU/3XO8GfmMGjNBCX y/C2lRNtA0LMfrtHi2p1qaQCW3kEMzqAiPRhnHGssAs9rxMDfY4JpAJxlhCsXs7SVLdl 93Xg== ARC-Authentication-Results: i=1; mx.google.com; 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 b5-v6si2616846ple.258.2018.10.26.07.48.44; Fri, 26 Oct 2018 07:48:59 -0700 (PDT) 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; 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 S1728000AbeJZXZH (ORCPT + 99 others); Fri, 26 Oct 2018 19:25:07 -0400 Received: from mail.bootlin.com ([62.4.15.54]:46204 "EHLO mail.bootlin.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726243AbeJZXVB (ORCPT ); Fri, 26 Oct 2018 19:21:01 -0400 Received: by mail.bootlin.com (Postfix, from userid 110) id 4EFC12097B; Fri, 26 Oct 2018 16:43:37 +0200 (CEST) X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on mail.bootlin.com X-Spam-Level: X-Spam-Status: No, score=-1.0 required=5.0 tests=ALL_TRUSTED,SHORTCIRCUIT, URIBL_BLOCKED shortcircuit=ham autolearn=disabled version=3.4.0 Received: from localhost.localdomain (aaubervilliers-681-1-12-210.w90-88.abo.wanadoo.fr [90.88.133.210]) by mail.bootlin.com (Postfix) with ESMTPSA id 7A60620794; Fri, 26 Oct 2018 16:43:36 +0200 (CEST) From: Boris Brezillon To: Wolfram Sang , linux-i2c@vger.kernel.org, Jonathan Corbet , linux-doc@vger.kernel.org, Greg Kroah-Hartman , Arnd Bergmann Cc: Przemyslaw Sroka , Arkadiusz Golec , Alan Douglas , Bartosz Folta , Damian Kos , Alicja Jurasik-Urbaniak , Cyprian Wronka , Suresh Punnoose , Rafal Ciepiela , Thomas Petazzoni , Nishanth Menon , Rob Herring , Pawel Moll , Mark Rutland , Ian Campbell , Kumar Gala , devicetree@vger.kernel.org, linux-kernel@vger.kernel.org, Vitor Soares , Geert Uytterhoeven , Linus Walleij , Xiang Lin , linux-gpio@vger.kernel.org, Sekhar Nori , Przemyslaw Gaj , Peter Rosin , Mike Shettel , Stephen Boyd , Boris Brezillon Subject: [PATCH v10 2/9] docs: driver-api: Add I3C documentation Date: Fri, 26 Oct 2018 16:43:26 +0200 Message-Id: <20181026144333.12276-3-boris.brezillon@bootlin.com> X-Mailer: git-send-email 2.17.1 In-Reply-To: <20181026144333.12276-1-boris.brezillon@bootlin.com> References: <20181026144333.12276-1-boris.brezillon@bootlin.com> Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Add the I3C documentation describing the protocol, the master driver API and the device driver API. Signed-off-by: Boris Brezillon Reviewed-by: Randy Dunlap Reviewed-by: Arnd Bergmann --- Changes in v10: - None Changes in v9: - Add Arnd's R-b Changes in v8: - None Changes in v7: - None Changes in v6: - Fix typos reported by Randy - Add Randy's R-b Changes in v5: - Remove useless conf.py file - Add SPDX headers Changes in v2: - Moved out of patch "i3c: Add core I3C infrastructure" - Add link to the I3C spec - Move rst files in Documentation/driver-api/i3c/ --- .../driver-api/i3c/device-driver-api.rst | 9 + Documentation/driver-api/i3c/index.rst | 11 + .../driver-api/i3c/master-driver-api.rst | 10 + Documentation/driver-api/i3c/protocol.rst | 203 ++++++++++++++++++ Documentation/driver-api/index.rst | 1 + 5 files changed, 234 insertions(+) create mode 100644 Documentation/driver-api/i3c/device-driver-api.rst create mode 100644 Documentation/driver-api/i3c/index.rst create mode 100644 Documentation/driver-api/i3c/master-driver-api.rst create mode 100644 Documentation/driver-api/i3c/protocol.rst diff --git a/Documentation/driver-api/i3c/device-driver-api.rst b/Documentation/driver-api/i3c/device-driver-api.rst new file mode 100644 index 000000000000..85bc3381cd3e --- /dev/null +++ b/Documentation/driver-api/i3c/device-driver-api.rst @@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: GPL-2.0 + +===================== +I3C device driver API +===================== + +.. kernel-doc:: include/linux/i3c/device.h + +.. kernel-doc:: drivers/i3c/device.c diff --git a/Documentation/driver-api/i3c/index.rst b/Documentation/driver-api/i3c/index.rst new file mode 100644 index 000000000000..783d6dad054b --- /dev/null +++ b/Documentation/driver-api/i3c/index.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============= +I3C subsystem +============= + +.. toctree:: + + protocol + device-driver-api + master-driver-api diff --git a/Documentation/driver-api/i3c/master-driver-api.rst b/Documentation/driver-api/i3c/master-driver-api.rst new file mode 100644 index 000000000000..bb19264aa239 --- /dev/null +++ b/Documentation/driver-api/i3c/master-driver-api.rst @@ -0,0 +1,10 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================================ +I3C master controller driver API +================================ + +.. kernel-doc:: drivers/i3c/master.c + +.. kernel-doc:: include/linux/i3c/master.h + diff --git a/Documentation/driver-api/i3c/protocol.rst b/Documentation/driver-api/i3c/protocol.rst new file mode 100644 index 000000000000..dae3b6d32c6b --- /dev/null +++ b/Documentation/driver-api/i3c/protocol.rst @@ -0,0 +1,203 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============ +I3C protocol +============ + +Disclaimer +========== + +This chapter will focus on aspects that matter to software developers. For +everything hardware related (like how things are transmitted on the bus, how +collisions are prevented, ...) please have a look at the I3C specification. + +This document is just a brief introduction to the I3C protocol and the concepts +it brings to the table. If you need more information, please refer to the MIPI +I3C specification (can be downloaded here +http://resources.mipi.org/mipi-i3c-v1-download). + +Introduction +============ + +The I3C (pronounced 'eye-three-see') is a MIPI standardized protocol designed +to overcome I2C limitations (limited speed, external signals needed for +interrupts, no automatic detection of the devices connected to the bus, ...) +while remaining power-efficient. + +I3C Bus +======= + +An I3C bus is made of several I3C devices and possibly some I2C devices as +well, but let's focus on I3C devices for now. + +An I3C device on the I3C bus can have one of the following roles: + +* Master: the device is driving the bus. It's the one in charge of initiating + transactions or deciding who is allowed to talk on the bus (slave generated + events are possible in I3C, see below). +* Slave: the device acts as a slave, and is not able to send frames to another + slave on the bus. The device can still send events to the master on + its own initiative if the master allowed it. + +I3C is a multi-master protocol, so there might be several masters on a bus, +though only one device can act as a master at a given time. In order to gain +bus ownership, a master has to follow a specific procedure. + +Each device on the I3C bus has to be assigned a dynamic address to be able to +communicate. Until this is done, the device should only respond to a limited +set of commands. If it has a static address (also called legacy I2C address), +the device can reply to I2C transfers. + +In addition to these per-device addresses, the protocol defines a broadcast +address in order to address all devices on the bus. + +Once a dynamic address has been assigned to a device, this address will be used +for any direct communication with the device. Note that even after being +assigned a dynamic address, the device should still process broadcast messages. + +I3C Device discovery +==================== + +The I3C protocol defines a mechanism to automatically discover devices present +on the bus, their capabilities and the functionalities they provide. In this +regard I3C is closer to a discoverable bus like USB than it is to I2C or SPI. + +The discovery mechanism is called DAA (Dynamic Address Assignment), because it +not only discovers devices but also assigns them a dynamic address. + +During DAA, each I3C device reports 3 important things: + +* BCR: Bus Characteristic Register. This 8-bit register describes the device bus + related capabilities +* DCR: Device Characteristic Register. This 8-bit register describes the + functionalities provided by the device +* Provisional ID: A 48-bit unique identifier. On a given bus there should be no + Provisional ID collision, otherwise the discovery mechanism may fail. + +I3C slave events +================ + +The I3C protocol allows slaves to generate events on their own, and thus allows +them to take temporary control of the bus. + +This mechanism is called IBI for In Band Interrupts, and as stated in the name, +it allows devices to generate interrupts without requiring an external signal. + +During DAA, each device on the bus has been assigned an address, and this +address will serve as a priority identifier to determine who wins if 2 different +devices are generating an interrupt at the same moment on the bus (the lower the +dynamic address the higher the priority). + +Masters are allowed to inhibit interrupts if they want to. This inhibition +request can be broadcast (applies to all devices) or sent to a specific +device. + +I3C Hot-Join +============ + +The Hot-Join mechanism is similar to USB hotplug. This mechanism allows +slaves to join the bus after it has been initialized by the master. + +This covers the following use cases: + +* the device is not powered when the bus is probed +* the device is hotplugged on the bus through an extension board + +This mechanism is relying on slave events to inform the master that a new +device joined the bus and is waiting for a dynamic address. + +The master is then free to address the request as it wishes: ignore it or +assign a dynamic address to the slave. + +I3C transfer types +================== + +If you omit SMBus (which is just a standardization on how to access registers +exposed by I2C devices), I2C has only one transfer type. + +I3C defines 3 different classes of transfer in addition to I2C transfers which +are here for backward compatibility with I2C devices. + +I3C CCC commands +---------------- + +CCC (Common Command Code) commands are meant to be used for anything that is +related to bus management and all features that are common to a set of devices. + +CCC commands contain an 8-bit CCC ID describing the command that is executed. +The MSB of this ID specifies whether this is a broadcast command (bit7 = 0) or a +unicast one (bit7 = 1). + +The command ID can be followed by a payload. Depending on the command, this +payload is either sent by the master sending the command (write CCC command), +or sent by the slave receiving the command (read CCC command). Of course, read +accesses only apply to unicast commands. +Note that, when sending a CCC command to a specific device, the device address +is passed in the first byte of the payload. + +The payload length is not explicitly passed on the bus, and should be extracted +from the CCC ID. + +Note that vendors can use a dedicated range of CCC IDs for their own commands +(0x61-0x7f and 0xe0-0xef). + +I3C Private SDR transfers +------------------------- + +Private SDR (Single Data Rate) transfers should be used for anything that is +device specific and does not require high transfer speed. + +It is the equivalent of I2C transfers but in the I3C world. Each transfer is +passed the device address (dynamic address assigned during DAA), a payload +and a direction. + +The only difference with I2C is that the transfer is much faster (typical clock +frequency is 12.5MHz). + +I3C HDR commands +---------------- + +HDR commands should be used for anything that is device specific and requires +high transfer speed. + +The first thing attached to an HDR command is the HDR mode. There are currently +3 different modes defined by the I3C specification (refer to the specification +for more details): + +* HDR-DDR: Double Data Rate mode +* HDR-TSP: Ternary Symbol Pure. Only usable on busses with no I2C devices +* HDR-TSL: Ternary Symbol Legacy. Usable on busses with I2C devices + +When sending an HDR command, the whole bus has to enter HDR mode, which is done +using a broadcast CCC command. +Once the bus has entered a specific HDR mode, the master sends the HDR command. +An HDR command is made of: + +* one 16-bits command word in big endian +* N 16-bits data words in big endian + +Those words may be wrapped with specific preambles/post-ambles which depend on +the chosen HDR mode and are detailed here (see the specification for more +details). + +The 16-bits command word is made of: + +* bit[15]: direction bit, read is 1, write is 0 +* bit[14:8]: command code. Identifies the command being executed, the amount of + data words and their meaning +* bit[7:1]: I3C address of the device this command is addressed to +* bit[0]: reserved/parity-bit + +Backward compatibility with I2C devices +======================================= + +The I3C protocol has been designed to be backward compatible with I2C devices. +This backward compatibility allows one to connect a mix of I2C and I3C devices +on the same bus, though, in order to be really efficient, I2C devices should +be equipped with 50 ns spike filters. + +I2C devices can't be discovered like I3C ones and have to be statically +declared. In order to let the master know what these devices are capable of +(both in terms of bus related limitations and functionalities), the software +has to provide some information, which is done through the LVR (Legacy I2C +Virtual Register). diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index 6d9f2f9fe20e..cc6a33f232ea 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -32,6 +32,7 @@ available subsections can be seen below. pci spi i2c + i3c/index hsi edac scsi -- 2.17.1