archive mirror
 help / color / mirror / Atom feed
From: Boris Brezillon <>
To: Wolfram Sang <>,, Jonathan Corbet <>,,
	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 <>,,,
	Vitor Soares <>,
	Geert Uytterhoeven <>,
	Linus Walleij <>,
	Xiang Lin <>,, Sekhar Nori <>,
	Przemyslaw Gaj <>, Peter Rosin <>,
	Mike Shettel <>,
	Stephen Boyd <>,
	Boris Brezillon <>
Subject: [PATCH v8 02/10] docs: driver-api: Add I3C documentation
Date: Wed,  3 Oct 2018 15:22:04 +0200	[thread overview]
Message-ID: <> (raw)
In-Reply-To: <>

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 <>
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 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/
 Documentation/driver-api/i3c/device-driver-api.rst |   9 +
 Documentation/driver-api/i3c/index.rst             |  11 ++
 Documentation/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
+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
+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
+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
+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.
+   i3c/index

  parent reply	other threads:[~2018-10-03 13:23 UTC|newest]

Thread overview: 23+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2018-10-03 13:22 [PATCH v8 00/10] Add the I3C subsystem Boris Brezillon
2018-10-03 13:22 ` [PATCH v8 01/10] i3c: Add core I3C infrastructure Boris Brezillon
2018-10-03 13:22 ` Boris Brezillon [this message]
2018-10-03 13:22 ` [PATCH v8 03/10] i3c: Add sysfs ABI spec Boris Brezillon
2018-10-03 13:22 ` [PATCH v8 04/10] dt-bindings: i3c: Document core bindings Boris Brezillon
2018-10-03 13:22 ` [PATCH v8 05/10] dt-bindings: i3c: Add macros to help fill I3C/I2C device's reg property Boris Brezillon
2018-10-03 18:37   ` Joe Perches
2018-10-03 18:45     ` Geert Uytterhoeven
2018-10-03 19:02       ` Joe Perches
2018-10-03 18:59     ` Boris Brezillon
2018-10-03 19:06       ` Boris Brezillon
2018-10-03 13:22 ` [PATCH v8 06/10] MAINTAINERS: Add myself as the I3C subsystem maintainer Boris Brezillon
2018-10-03 13:22 ` [PATCH v8 07/10] i3c: master: Add driver for Cadence IP Boris Brezillon
2018-10-08 10:06   ` Arnd Bergmann
2018-10-08 10:21     ` Boris Brezillon
2018-10-08 10:36       ` Arnd Bergmann
2018-10-08 12:05         ` Boris Brezillon
2018-10-03 13:22 ` [PATCH v8 08/10] dt-bindings: i3c: Document Cadence I3C master bindings Boris Brezillon
2018-10-03 13:22 ` [PATCH v8 09/10] gpio: Add a driver for Cadence I3C GPIO expander Boris Brezillon
2018-10-03 13:22 ` [PATCH v8 10/10] dt-bindings: gpio: Add bindings for Cadence I3C gpio expander Boris Brezillon
2018-10-04  8:35   ` Linus Walleij
2018-10-08 10:47 ` [PATCH v8 00/10] Add the I3C subsystem Arnd Bergmann
2018-10-17 13:18   ` Boris Brezillon

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).