Documentation/driver-api/slimbus.rst

   1 ============================
   2 Linux kernel SLIMbus support
   3 ============================
   4
   5 Overview
   6 ========
   7
   8 What is SLIMbus?
   9 ----------------
  10 SLIMbus (Serial Low Power Interchip Media Bus) is a specification developed by
  11 MIPI (Mobile Industry Processor Interface) alliance. The bus uses master/slave
  12 configuration, and is a 2-wire multi-drop implementation (clock, and data).
  13
  14 Currently, SLIMbus is used to interface between application processors of SoCs
  15 (System-on-Chip) and peripheral components (typically codec). SLIMbus uses
  16 Time-Division-Multiplexing to accommodate multiple data channels, and
  17 a control channel.
  18
  19 The control channel is used for various control functions such as bus
  20 management, configuration and status updates. These messages can be unicast (e.g.
  21 reading/writing device specific values), or multicast (e.g. data channel
  22 reconfiguration sequence is a broadcast message announced to all devices)
  23
  24 A data channel is used for data-transfer between 2 SLIMbus devices. Data
  25 channel uses dedicated ports on the device.
  26
  27 Hardware description:
  28 ---------------------
  29 SLIMbus specification has different types of device classifications based on
  30 their capabilities.
  31 A manager device is responsible for enumeration, configuration, and dynamic
  32 channel allocation. Every bus has 1 active manager.
  33
  34 A generic device is a device providing application functionality (e.g. codec).
  35
  36 Framer device is responsible for clocking the bus, and transmitting frame-sync
  37 and framing information on the bus.
  38
  39 Each SLIMbus component has an interface device for monitoring physical layer.
  40
  41 Typically each SoC contains SLIMbus component having 1 manager, 1 framer device,
  42 1 generic device (for data channel support), and 1 interface device.
  43 External peripheral SLIMbus component usually has 1 generic device (for
  44 functionality/data channel support), and an associated interface device.
  45 The generic device's registers are mapped as 'value elements' so that they can
  46 be written/read using SLIMbus control channel exchanging control/status type of
  47 information.
  48 In case there are multiple framer devices on the same bus, manager device is
  49 responsible to select the active-framer for clocking the bus.
  50
  51 Per specification, SLIMbus uses "clock gears" to do power management based on
  52 current frequency and bandwidth requirements. There are 10 clock gears and each
  53 gear changes the SLIMbus frequency to be twice its previous gear.
  54
  55 Each device has a 6-byte enumeration-address and the manager assigns every
  56 device with a 1-byte logical address after the devices report presence on the
  57 bus.
  58
  59 Software description:
  60 ---------------------
  61 There are 2 types of SLIMbus drivers:
  62
  63 slim_controller represents a 'controller' for SLIMbus. This driver should
  64 implement duties needed by the SoC (manager device, associated
  65 interface device for monitoring the layers and reporting errors, default
  66 framer device).
  67
  68 slim_device represents the 'generic device/component' for SLIMbus, and a
  69 slim_driver should implement driver for that slim_device.
  70
  71 Device notifications to the driver:
  72 -----------------------------------
  73 Since SLIMbus devices have mechanisms for reporting their presence, the
  74 framework allows drivers to bind when corresponding devices report their
  75 presence on the bus.
  76 However, it is possible that the driver needs to be probed
  77 first so that it can enable corresponding SLIMbus device (e.g. power it up and/or
  78 take it out of reset). To support that behavior, the framework allows drivers
  79 to probe first as well  (e.g. using standard DeviceTree compatibility field).
  80 This creates the necessity for the driver to know when the device is functional
  81 (i.e. reported present). device_up callback is used for that reason when the
  82 device reports present and is assigned a logical address by the controller.
  83
  84 Similarly, SLIMbus devices 'report absent' when they go down. A 'device_down'
  85 callback notifies the driver when the device reports absent and its logical
  86 address assignment is invalidated by the controller.
  87
  88 Another notification "boot_device" is used to notify the slim_driver when
  89 controller resets the bus. This notification allows the driver to take necessary
  90 steps to boot the device so that it's functional after the bus has been reset.
  91
  92 Driver and Controller APIs:
  93 ---------------------------
  94 .. kernel-doc:: include/linux/slimbus.h
  95    :internal:
  96
  97 .. kernel-doc:: drivers/slimbus/slimbus.h
  98    :internal:
  99
 100 .. kernel-doc:: drivers/slimbus/core.c
 101    :export:
 102
 103 Clock-pause:
 104 ------------
 105 SLIMbus mandates that a reconfiguration sequence (known as clock-pause) be
 106 broadcast to all active devices on the bus before the bus can enter low-power
 107 mode. Controller uses this sequence when it decides to enter low-power mode so
 108 that corresponding clocks and/or power-rails can be turned off to save power.
 109 Clock-pause is exited by waking up framer device (if controller driver initiates
 110 exiting low power mode), or by toggling the data line (if a slave device wants
 111 to initiate it).
 112
 113 Clock-pause APIs:
 114 ~~~~~~~~~~~~~~~~~
 115 .. kernel-doc:: drivers/slimbus/sched.c
 116    :export:
 117
 118 Messaging:
 119 ----------
 120 The framework supports regmap and read/write apis to exchange control-information
 121 with a SLIMbus device. APIs can be synchronous or asynchronous.
 122 The header file <linux/slimbus.h> has more documentation about messaging APIs.
 123
 124 Messaging APIs:
 125 ~~~~~~~~~~~~~~~
 126 .. kernel-doc:: drivers/slimbus/messaging.c
 127    :export:
 128
 129 Streaming APIs:
 130 ~~~~~~~~~~~~~~~
 131 .. kernel-doc:: drivers/slimbus/stream.c
 132    :export: