Commit | Line | Data |
---|---|---|
202318d3 SD |
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: | |
281a7af8 | 93 | --------------------------- |
202318d3 SD |
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: | |
abb9c9b8 SK |
128 | |
129 | Streaming APIs: | |
130 | ~~~~~~~~~~~~~~~ | |
131 | .. kernel-doc:: drivers/slimbus/stream.c | |
132 | :export: |