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