What is SLIMbus?¶

SLIMbus (Serial Low Power Interchip Media Bus) is a specification developed byMIPI (Mobile Industry Processor Interface) alliance. The bus uses master/slaveconfiguration, and is a 2-wire multi-drop implementation (clock, and data).

Currently, SLIMbus is used to interface between application processors of SoCs(System-on-Chip) and peripheral components (typically codec). SLIMbus usesTime-Division-Multiplexing to accommodate multiple data channels, anda control channel.

The control channel is used for various control functions such as busmanagement, configuration and status updates. These messages can be unicast (e.g.reading/writing device specific values), or multicast (e.g. data channelreconfiguration sequence is a broadcast message announced to all devices)

A data channel is used for data-transfer between 2 SLIMbus devices. Datachannel uses dedicated ports on the device.

Hardware description:¶

SLIMbus specification has different types of device classifications based ontheir capabilities.A manager device is responsible for enumeration, configuration, and dynamicchannel allocation. Every bus has 1 active manager.

A generic device is a device providing application functionality (e.g. codec).

Framer device is responsible for clocking the bus, and transmitting frame-syncand framing information on the bus.

Each SLIMbus component has an interface device for monitoring physical layer.

Typically each SoC contains SLIMbus component having 1 manager, 1 framer device,1 generic device (for data channel support), and 1 interface device.External peripheral SLIMbus component usually has 1 generic device (forfunctionality/data channel support), and an associated interface device.The generic device’s registers are mapped as ‘value elements’ so that they canbe written/read using SLIMbus control channel exchanging control/status type ofinformation.In case there are multiple framer devices on the same bus, manager device isresponsible to select the active-framer for clocking the bus.

Per specification, SLIMbus uses “clock gears” to do power management based oncurrent frequency and bandwidth requirements. There are 10 clock gears and eachgear changes the SLIMbus frequency to be twice its previous gear.

Each device has a 6-byte enumeration-address and the manager assigns everydevice with a 1-byte logical address after the devices report presence on thebus.

Software description:¶

There are 2 types of SLIMbus drivers:

slim_controller represents a ‘controller’ for SLIMbus. This driver shouldimplement duties needed by the SoC (manager device, associatedinterface device for monitoring the layers and reporting errors, defaultframer device).

slim_device represents the ‘generic device/component’ for SLIMbus, and aslim_driver should implement driver for that slim_device.

Device notifications to the driver:¶

Since SLIMbus devices have mechanisms for reporting their presence, theframework allows drivers to bind when corresponding devices report theirpresence on the bus.However, it is possible that the driver needs to be probedfirst so that it can enable corresponding SLIMbus device (e.g. power it up and/ortake it out of reset). To support that behavior, the framework allows driversto probe first as well (e.g. using standard DeviceTree compatibility field).This creates the necessity for the driver to know when the device is functional(i.e. reported present). device_up callback is used for that reason when thedevice reports present and is assigned a logical address by the controller.

Similarly, SLIMbus devices ‘report absent’ when they go down. A ‘device_down’callback notifies the driver when the device reports absent and its logicaladdress assignment is invalidated by the controller.

Another notification “boot_device” is used to notify the slim_driver whencontroller resets the bus. This notification allows the driver to take necessarysteps to boot the device so that it’s functional after the bus has been reset.

Driver and Controller APIs:¶

structslim_eaddr¶

Enumeration address for a SLIMbus device

Definition

struct slim_eaddr {  u8 instance;  u8 dev_index;  u16 prod_code;  u16 manf_id;};

Members

instance

Instance value

dev_index

Device index

prod_code

Product code

manf_id

Manufacturer Id for the device

enumslim_device_status¶

slim device status

Constants

SLIM_DEVICE_STATUS_DOWN

Slim device is absent or not reported yet.

SLIM_DEVICE_STATUS_UP

Slim device is announced on the bus.

SLIM_DEVICE_STATUS_RESERVED

Reserved for future use.

structslim_device¶

Slim device handle.

Definition

struct slim_device {  struct device           dev;  struct slim_eaddr       e_addr;  struct slim_controller  *ctrl;  enum slim_device_status status;  u8 laddr;  bool is_laddr_valid;  struct list_head        stream_list;  spinlock_t stream_list_lock;};

Members

dev

Driver model representation of the device.

e_addr

Enumeration address of this device.

ctrl

slim controller instance.

status

slim device status

laddr

1-byte Logical address of this device.

is_laddr_valid

indicates if the laddr is valid or not

stream_list

List of streams on this device

stream_list_lock

lock to protect the stream list

Description

This is the client/device handle returned when a SLIMbusdevice is registered with a controller.Pointer to this structure is used by client-driver as a handle.

structslim_driver¶

SLIMbus ‘generic device’ (slave) device driver (similar to ‘spi_device’ on SPI)

Definition

struct slim_driver {  int (*probe)(struct slim_device *sl);  void (*remove)(struct slim_device *sl);  void (*shutdown)(struct slim_device *sl);  int (*device_status)(struct slim_device *sl, enum slim_device_status s);  struct device_driver            driver;  const struct slim_device_id     *id_table;};

Members

probe

Binds this driver to a SLIMbus device.

remove

Unbinds this driver from the SLIMbus device.

shutdown

Standard shutdown callback used during powerdown/halt.

device_status

This callback is called when- The device reports present and gets a laddr assigned- The device reports absent, or the bus goes down.

driver

SLIMbus device drivers should initialize name and owner field ofthis structure

id_table

List of SLIMbus devices supported by this driver

structslim_val_inf¶

Slimbus value or information element

Definition

struct slim_val_inf {  u16 start_offset;  u8 num_bytes;  u8 *rbuf;  const u8                *wbuf;  struct completion      *comp;};

Members

start_offset

Specifies starting offset in information/value element map

num_bytes

upto 16. This ensures that the message will fit the slicesizeper SLIMbus spec

rbuf

buffer to read the values

wbuf

buffer to write

comp

completion for asynchronous operations, valid only if TID isrequired for transaction, like REQUEST operations.Rest of the transactions are synchronous anyway.

structslim_stream_config¶

SLIMbus stream configuration Configuring a stream is done at hw_params or prepare call from audio drivers where they have all the required information regarding rate, number of channels and so on. There is a 1:1 mapping of channel and ports.

Definition

struct slim_stream_config {  unsigned int rate;  unsigned int bps;  unsigned int ch_count;  unsigned int *chs;  unsigned long port_mask;  int direction;};

Members

rate

data rate

bps

bits per data sample

ch_count

number of channels

chs

pointer to list of channel numbers

port_mask

port mask of ports to use for this stream

direction

direction of the stream, SNDRV_PCM_STREAM_PLAYBACKor SNDRV_PCM_STREAM_CAPTURE.

module_slim_driver(__slim_driver)¶

Helper macro for registering a SLIMbus driver

Parameters

__slim_driver

slimbus_driver struct

Description

Helper macro for SLIMbus drivers which do not do anything special in moduleinit/exit. This eliminates a lot of boilerplate. Each module may onlyuse this macro once, and calling it replacesmodule_init() andmodule_exit()

structslim_framer¶

Represents SLIMbus framer. Every controller may have multiple framers. There is 1 active framer device responsible for clocking the bus. Manager is responsible for framer hand-over.

Definition

struct slim_framer {  struct device           dev;  struct slim_eaddr       e_addr;  int rootfreq;  int superfreq;};

Members

dev

Driver model representation of the device.

e_addr

Enumeration address of the framer.

rootfreq

Root Frequency at which the framer can run. This is maximumfrequency (‘clock gear 10’) at which the bus can operate.

superfreq

Superframes per root frequency. Every frame is 6144 bits.

structslim_msg_txn¶

Message to be sent by the controller. This structure has packet header, payload and buffer to be filled (if any)

Definition

struct slim_msg_txn {  u8 rl;  u8 mt;  u8 mc;  u8 dt;  u16 ec;  u8 tid;  u8 la;  struct slim_val_inf     *msg;  struct completion      *comp;};

Members

rl

Header field. remaining length.

mt

Header field. Message type.

mc

Header field. LSB is message code for type mt.

dt

Header field. Destination type.

ec

Element code. Used for elemental access APIs.

tid

Transaction ID. Used for messages expecting response.(relevant for message-codes involving read operation)

la

Logical address of the device this message is going to.(Not used when destination type is broadcast.)

msg

Elemental access message to be read/written

comp

completion if read/write is synchronous, used internallyfor tid based transactions.

enumslim_clk_state¶

Constants

SLIM_CLK_ACTIVE

SLIMbus clock is active

SLIM_CLK_ENTERING_PAUSE

SLIMbus clock pause sequence is being sent on thebus. If this succeeds, state changes to SLIM_CLK_PAUSED. If thetransition fails, state changes back to SLIM_CLK_ACTIVE

SLIM_CLK_PAUSED

SLIMbus controller clock has paused.

Description

maintaining current clock state.

structslim_sched¶

Definition

struct slim_sched {  enum slim_clk_state     clk_state;  struct completion       pause_comp;  struct mutex            m_reconf;};

Members

clk_state

Controller’s clock state from enum slim_clk_state

pause_comp

Signals completion of clock pause sequence. This is useful whenclient tries to call SLIMbus transaction when controller is enteringclock pause.

m_reconf

This mutex is held until current reconfiguration (data channelscheduling, message bandwidth reservation) is done. Message APIs canuse the bus concurrently when this mutex is held since elemental accessmessages can be sent on the bus when reconfiguration is in progress.

enumslim_port_direction¶

Constants

SLIM_PORT_SINK

SLIMbus port is a sink

SLIM_PORT_SOURCE

SLIMbus port is a source

enumslim_port_state¶

Constants

SLIM_PORT_DISCONNECTED

SLIMbus port is disconnectedentered from Unconfigure/configured state afterDISCONNECT_PORT or REMOVE_CHANNEL core command

SLIM_PORT_UNCONFIGURED

SLIMbus port is in unconfigured state.entered from disconnect state after CONNECT_SOURCE/SINK core command

SLIM_PORT_CONFIGURED

SLIMbus port is in configured state.entered from unconfigured state after DEFINE_CHANNEL, DEFINE_CONTENTand ACTIVATE_CHANNEL core commands. Ready for data transmission.

Description

according to SLIMbus Spec 2.0

enumslim_channel_state¶

Constants

SLIM_CH_STATE_DISCONNECTED

SLIMbus channel is disconnected

SLIM_CH_STATE_ALLOCATED

SLIMbus channel is allocated

SLIM_CH_STATE_ASSOCIATED

SLIMbus channel is associated with port

SLIM_CH_STATE_DEFINED

SLIMbus channel parameters are defined

SLIM_CH_STATE_CONTENT_DEFINED

SLIMbus channel content is defined

SLIM_CH_STATE_ACTIVE

SLIMbus channel is active and ready for data

SLIM_CH_STATE_REMOVED

SLIMbus channel is inactive and removed

enumslim_ch_data_fmt¶

Constants

SLIM_CH_DATA_FMT_NOT_DEFINED

Undefined

SLIM_CH_DATA_FMT_LPCM_AUDIO

LPCM audio

SLIM_CH_DATA_FMT_IEC61937_COMP_AUDIO

IEC61937 Compressed audio

SLIM_CH_DATA_FMT_PACKED_PDM_AUDIO

Packed PDM audio

Description

Table 60 of SLIMbus Spec 1.01.01

enumslim_ch_aux_bit_fmt¶

Constants

SLIM_CH_AUX_FMT_NOT_APPLICABLE

Undefined

SLIM_CH_AUX_FMT_ZCUV_TUNNEL_IEC60958

ZCUV for tunneling IEC60958

SLIM_CH_AUX_FMT_USER_DEFINED

User defined

Description

Table 63 of SLIMbus Spec 2.0

structslim_channel¶

SLIMbus channel, used for state machine

Definition

struct slim_channel {  int id;  int prrate;  int seg_dist;  enum slim_ch_data_fmt data_fmt;  enum slim_ch_aux_bit_fmt aux_fmt;  enum slim_channel_state state;};

Members

id

ID of channel

prrate

Presense rate of channel from Table 66 of SLIMbus 2.0 Specs

seg_dist

segment distribution code from Table 20 of SLIMbus 2.0 Specs

data_fmt

Data format of channel.

aux_fmt

Aux format for this channel.

state

channel state machine

structslim_port¶

SLIMbus port

Definition

struct slim_port {  int id;  enum slim_port_direction direction;  enum slim_port_state state;  struct slim_channel ch;};

Members

id

Port id

direction

Port direction, Source or Sink.

state

state machine of port.

ch

channel associated with this port.

enumslim_transport_protocol¶

Constants

SLIM_PROTO_ISO

Isochronous Protocol, no flow control as data rate matchchannel rate flow control embedded in the data.

SLIM_PROTO_PUSH

Pushed Protocol, includes flow control, Used to carrydata whose rate is equal to, or lower than the channel rate.

SLIM_PROTO_PULL

Pulled Protocol, similar usage as pushed protocolbut pull is a unicast.

SLIM_PROTO_LOCKED

Locked Protocol

SLIM_PROTO_ASYNC_SMPLX

Asynchronous Protocol-Simplex

SLIM_PROTO_ASYNC_HALF_DUP

Asynchronous Protocol-Half-duplex

SLIM_PROTO_EXT_SMPLX

Extended Asynchronous Protocol-Simplex

SLIM_PROTO_EXT_HALF_DUP

Extended Asynchronous Protocol-Half-duplex

Description

Table 47 of SLIMbus 2.0 specs.

structslim_stream_runtime¶

SLIMbus stream runtime instance

Definition

struct slim_stream_runtime {  const char *name;  struct slim_device *dev;  int direction;  enum slim_transport_protocol prot;  unsigned int rate;  unsigned int bps;  unsigned int ratem;  int num_ports;  struct slim_port *ports;  struct list_head node;};

Members

name

Name of the stream

dev

SLIM Device instance associated with this stream

direction

direction of stream

prot

Transport protocol used in this stream

rate

Data rate of samples *

bps

bits per sample

ratem

rate multipler which is super frame rate/data rate

num_ports

number of ports

ports

pointer to instance of ports

node

list head for stream associated with slim device.

structslim_controller¶

Controls every instance of SLIMbus (similar to ‘master’ on SPI)

Definition

struct slim_controller {  struct device           *dev;  unsigned int            id;  char name[SLIMBUS_NAME_SIZE];  int min_cg;  int max_cg;  int clkgear;  struct ida              laddr_ida;  struct slim_framer      *a_framer;  struct mutex            lock;  struct list_head        devices;  struct idr              tid_idr;  spinlock_t txn_lock;  struct slim_sched       sched;  int (*xfer_msg)(struct slim_controller *ctrl, struct slim_msg_txn *tx);  int (*set_laddr)(struct slim_controller *ctrl, struct slim_eaddr *ea, u8 laddr);  int (*get_laddr)(struct slim_controller *ctrl, struct slim_eaddr *ea, u8 *laddr);  int (*enable_stream)(struct slim_stream_runtime *rt);  int (*disable_stream)(struct slim_stream_runtime *rt);  int (*wakeup)(struct slim_controller *ctrl);};

Members

dev

Device interface to this driver

id

Board-specific number identifier for this controller/bus

name

Name for this controller

min_cg

Minimum clock gear supported by this controller (default value: 1)

max_cg

Maximum clock gear supported by this controller (default value: 10)

clkgear

Current clock gear in which this bus is running

laddr_ida

logical address id allocator

a_framer

Active framer which is clocking the bus managed by this controller

lock

Mutex protecting controller data structures

devices

Slim device list

tid_idr

tid id allocator

txn_lock

Lock to protect table of transactions

sched

scheduler structure used by the controller

xfer_msg

Transfer a message on this controller (this can be a broadcastcontrol/status message like data channel setup, or a unicast messagelike value element read/write.

set_laddr

Setup logical address at laddr for the slave with elementaladdress e_addr. Drivers implementing controller will be expected tosend unicast message to this device with its logical address.

get_laddr

It is possible that controller needs to set fixed logicaladdress table and get_laddr can be used in that case so that controllercan do this assignment. Use case is when the master is on the remoteprocessor side, who is resposible for allocating laddr.

enable_stream

This function pointer implements controller-specific procedureto enable a stream.

disable_stream

This function pointer implements controller-specific procedureto disable stream.

‘Manager device’ is responsible for device management, bandwidthallocation, channel setup, and port associations per channel.Device management means Logical address assignment/removal based onenumeration (report-present, report-absent) of a device.Bandwidth allocation is done dynamically by the manager based on activechannels on the bus, message-bandwidth requests made by SLIMbus devices.Based on current bandwidth usage, manager chooses a frequency to runthe bus at (in steps of ‘clock-gear’, 1 through 10, each clock gearrepresenting twice the frequency than the previous gear).Manager is also responsible for entering (and exiting) low-power-mode(known as ‘clock pause’).Manager can do handover of framer if there are multiple framers on thebus and a certain usecase warrants using certain framer to avoid keepingprevious framer being powered-on.

Controller here performs duties of the manager device, and ‘interfacedevice’. Interface device is responsible for monitoring the bus andreporting information such as loss-of-synchronization, dataslot-collision.

wakeup

This function pointer implements controller-specific procedureto wake it up from clock-pause. Framework will call this to bringthe controller out of clock pause.

intslim_unregister_controller(structslim_controller * ctrl)¶

Controller tear-down.

Parameters

structslim_controller*ctrl

Controller to tear-down.

voidslim_report_absent(structslim_device * sbdev)¶

Controller calls this function when a device reports absent, OR when the device cannot be communicated with

Parameters

structslim_device*sbdev

Device that cannot be reached, or sent report absent

structslim_device *slim_get_device(structslim_controller * ctrl, structslim_eaddr * e_addr)¶

get handle to a device.

Parameters

structslim_controller*ctrl

Controller on which this device will be added/queried

structslim_eaddr*e_addr

Enumeration address of the device to be queried

Return

pointer to a device if it has already reported. Creates a newdevice and returns pointer to it if the device has not yet enumerated.

structslim_device *of_slim_get_device(structslim_controller * ctrl, struct device_node * np)¶

get handle to a device using dt node.

Parameters

structslim_controller*ctrl

Controller on which this device will be added/queried

structdevice_node*np

node pointer to device

Return

pointer to a device if it has already reported. Creates a newdevice and returns pointer to it if the device has not yet enumerated.

intslim_device_report_present(structslim_controller * ctrl, structslim_eaddr * e_addr, u8 * laddr)¶

Report enumerated device.

Parameters

structslim_controller*ctrl

Controller with which device is enumerated.

structslim_eaddr*e_addr

Enumeration address of the device.

u8*laddr

Return logical address (if valid flag is false)

Description

Called by controller in response to REPORT_PRESENT. Framework will assigna logical address to this enumeration address.Function returns -EXFULL to indicate that all logical addresses are alreadytaken.

intslim_get_logical_addr(structslim_device * sbdev)¶

get/allocate logical address of a SLIMbus device.

Parameters

structslim_device*sbdev

client handle requesting the address.

Return

zero if a logical address is valid or a new logical addresshas been assigned. error code in case of error.

Clock-pause:¶

SLIMbus mandates that a reconfiguration sequence (known as clock-pause) bebroadcast to all active devices on the bus before the bus can enter low-powermode. Controller uses this sequence when it decides to enter low-power mode sothat corresponding clocks and/or power-rails can be turned off to save power.Clock-pause is exited by waking up framer device (if controller driver initiatesexiting low power mode), or by toggling the data line (if a slave device wantsto initiate it).

Messaging:¶

The framework supports regmap and read/write apis to exchange control-informationwith a SLIMbus device. APIs can be synchronous or asynchronous.The header file <linux/slimbus.h> has more documentation about messaging APIs.