Orange Pi5 kernel

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