4 BIF (Battery Interface) is a MIPI (Mobile Industry Processor Interface)
5 Alliance specification for a serial interface between a host device and a
6 battery pack. It provides a means to handle smart battery packs which can
7 communicate over BIF as well as low cost battery packs which provide no
8 serial communication interface.
10 The BIF bus supports 1 master and up to 256 slaves. It supports data rates
11 up to 250 kbps. The master is in charge of initiating all bus
12 communications. Slaves may only respond asynchronously when they need to
13 signal the master that they have an interrupt pending and when the bus is
14 configured for interrupt mode.
16 The BIF framework consists of a core into which BIF controller drivers
17 register. At runtime, consumers are notified of various events (e.g. battery
18 insertion and battery removal) via a notifier. Various framework functions are
19 available for consumers to read and write slave registers as well as to send
20 arbitrary BIF commands on the bus.
25 The BIF bus is a 1-wire wired-or interface. The bus signal is referred to as
26 the battery communication line (BCL). The BCL is pulled high by a resistor on
27 the host side and is driven low when the master or one of the slaves is
28 communicating. Additionally, there is a pull down resistor in the battery
29 pack which is used to identify whether or not the battery pack has BIF slaves.
30 Battery removal detection is achieved by comparing the analog voltage of the BCL
31 when idle to the host side reference voltage. If these voltages are within a
32 certain threshold, then a battery pack is not present.
34 Slaves are addressed on the BIF bus using an 8-bit device address (DEV_ADR).
35 Notably, it is possible for no slaves to have defined DEV_ADR. In this case,
36 slave addressing is achieved via the always present unique ID (UID). The UID
37 of a slave is 80 bits long and guaranteed to be globally unique. A UID search
38 algorithm can be followed in order determine the UID of all slaves on the bus.
40 BIF slaves come in two varieties: primary and secondary. A single primary
41 slave may be present on the battery pack and a single primary slave may be
42 present on the host. A battery pack primary slave has DEV_ADR=0x01. The
43 DEV_ADR of a host primary slave is set by the manufacturer. A given primary
44 slave contains a list of the UIDs of all secondary slaves in the same
45 subsystem. This provides a fast mechanism to determine the address of all
46 slaves without having to resort to the lengthy UID search algorithm.
48 Each slave has a 64 kB address space. Part of this address space consists of
49 generic DDB L1 and L2 data structures at known addresses. This allows for
50 runtime discovery of supported battery properties and functions of a given
54 +-------------------------------+ +---------------------------------+
55 | Host | | Smart Battery Pack |
57 | Vbat-<+>-------<+>----------------------------+ |
59 | +--------------+ | | +--------------+ | |
60 | | Master BIF<+>-+---------<+>--BCL--<+>------+-<+>BIF Primary | | |
61 | | | | | | | | Slave | | |
62 | +--------------+ | | | | +--------------+ | |
64 | + - - - - - - -+ | | | | + - - - - - - -+ | |
65 | | Primary BIF<+>-+ | | +-<+>BIF Secondary| | |
66 | | Slave | | | | | | Slave | | |
67 | +- - - - - - - + | | | | +-- - - - - - -+ | |
69 | + - - - - - - -+ | | | | + - - - - - - -+ | |
70 | |Secondary BIF<+>-+ | | +-<+>BIF Secondary| | |
71 | |Slave | | | | | | Slave | | |
72 | +- - - - - - - + | | | | +-- - - - - - -+ | |
74 | Vref \ Rpu | | Rid \ ---- |
75 | ___ / | | / Battery -- |
76 | | \ | | \ Cell ---- |
77 | +-------+ | | | -- |
79 | GND-<+>-------<+>------+---------------------+ |
81 +-------------------------------+ +---------------------------------+
83 An overview of BIF is available at:
84 http://mipi.org/specifications/battery-interface
89 A given BIF hardware interface driver registers as a BIF controller in the
90 BIF framework during its probe function. The controller specifies a set of
91 callback functions which are used by the BIF framework to initiate bus
92 transactions (e.g. register read, register write, wait for slave interrupt)
93 and to configure the bus. The framework exposes a small API to controllers
94 which is used to notify the framework about asynchronous events such as
95 battery pack insertion/removal and slave interrupts.
97 A given BIF consumer is linked to a BIF controller by specifying a property
98 in the consumer's device tree node which takes as its value the phandle of
99 the BIF controller's device tree node.
101 A consumer driver calls a get function during its probe function with its
102 device pointer in order to get a handle to the BIF controller if it has probed.
103 If it hasn't, then ERR_PTR(-EPROBE_DEFER) is returned. The controller handle
104 can be used directly by the consumer to issue raw bus transactions if needed.
105 The controller handle can then be used to query which slaves are currently
106 present on the bus, if any. Handles to these slaves may be used by a consumer
107 driver in high level framework APIs such as register read and register write
108 which are slave oriented. All BIF framework API functions are synchronous,
109 blocking, and can sleep.
111 Consumer drivers may also register a notifier function which is called when
112 certain bus activities occur such as battery pack insertion and removal.
113 Additionally, consumer drivers may register a notifier function which is called
114 when a specified slave interrupt fires.
116 The framework maintains several linked-lists. One list contains all controllers
117 that have been registered. A second list contains all slaves that have been
118 seen since the system booted as well as a flag to indicate if they are currently
119 present or not. This scheme is used to avoid issues with slave handles existing
120 after a slave is removed and also so that function and object values do not have
121 to be searched when a slave is reinserted in the system since slaves are
122 globally unique and these features are read-only. Two further lists are
123 maintained inside slave device structures which contain BIF functions and
124 objects found in the slave. API functions are provided so that consumers can
125 find functions supported by slaves.
131 One major goal of the BIF framework is to provide a uniform API for BIF
132 consumers to communicate with battery packs. This ensures that consumers are
133 unaffected by changes in the controller driver which actually interfaces with
134 the BCL at a hardware level.
136 Another goal of the framework is to ensure the BIF bus can be shared between
137 multiple consumers in a simple and functionally correct way. Locking is used
138 inside of the framework to provide mutual exclusion on the bus.
140 The framework also exposes features that almost all consumers will need, such
141 as BIF slave identification and BIF function enumeration within a given slave.
143 The framework allows consumers to issue very specific bus commands which may
144 not be used within high level APIs. This provides maximum flexibility so
145 that consumers can make use of manufacturer defined bus commands which cannot be
146 handled in a generic fashion.
149 The choice to not treat BIF like a traditional Linux bus was made because
150 there is nothing within BIF that naturally maps to a device on the bus for a
151 driver to manage. Slave devices would be a good candidate except that
152 consumers will not be managing slaves so much as functions exposed within
153 slaves. Bus matching could then instead be made at a BIF slave function
154 level. Unfortunately, the BIF specification allows for manufacturer specific
155 features to reside at any non-defined addresses. Additionally, consumers may
156 wish only to read and make policy decisions based on BIF non-volatile memory
157 (NVM) objects read out of memory. Thus, there are use-cases that require
158 consumers to utilize the bus without having a particular function to match to.
160 Another trade-off was the choice to use custom interrupt handling functions
161 instead of the Linux interrupt framework. This choice was made because there is
162 no obvious way to handle IRQ chip registration given the dynamic nature of BIF
163 slaves (i.e. slaves may come and go at runtime if battery packs are swapped).
166 BIF controller drivers register a set of callback functions with the BIF
167 framework which implement various BIF transaction primitives. These
168 callbacks ensure that tight timing constraints are met such as when receiving
169 a bus query response immediately after issuing a command. Such actions
170 cannot be carried out at the framework level as timing requirements are on
171 the order of 32 us when using the maximum data rate.
173 The BIF framework provides easy access to standard BIF features such as
174 slave, functions, and interrupts. The framework also ensures mutual exclusion
175 between different BIF consumers.
177 BIF consumer drivers make use of the API exposed by the framework in order
178 utilize functionality found on smart battery packs. One example of a
179 consumer driver is a temperature monitoring driver which reads the
180 temperature reported by the BIF temperature function on a BIF slave and
181 reports it to the Linux thermal framework.
186 The framework does not perform any special actions during system suspend and
187 resume. Controller drivers may choose to enter low power states during
188 suspend if they wish as long as it does not affect the logical state of the
194 Various linked lists are maintained inside of the framework which are
195 protected by mutexes. Mutex locks are also used during transactions at a bus
196 level in order to ensure mutual exclusion between consumers of the bus.
201 The BIF bus is inherently slow. Consumers should expect transactions to take
202 a long time to execute. Consumers are responsible for blocking suspend if
203 their transactions must be completed before the system enters suspend.
205 Interface - BIF Consumer API
206 ============================
208 BIF framework structs, enums, and functions used by BIF consumers are defined in
209 include/linux/bif/consumer.h
211 Detailed descriptions of the BIF framework functions can be found in:
212 drivers/bif/bif-core.c
214 Get/put handle for a BIF controller:
215 ------------------------------------
217 struct bif_ctrl *bif_ctrl_get(struct device *consumer_dev);
219 void bif_ctrl_put(struct bif_ctrl *ctrl);
221 int bif_ctrl_count(void);
223 struct bif_ctrl *bif_ctrl_get_by_id(unsigned int id);
225 The function bif_ctrl_get() is intended to be the primary way to get a consumer
226 BIF controller handle. It relies upon the consumer device specifying a
227 "qcom,bif-ctrl" property in its device tree node which points to the phandle of
228 the BIF controller it wishes to use.
230 A secondary mechanism is also provided for drivers without device tree support.
231 bif_ctrl_count() returns the number of BIF controllers currently registered.
232 bif_ctrl_get_by_id() returns a handle to the id'th controller enumerated in
235 Get/put handle for a BIF slave:
236 -------------------------------
238 int bif_slave_match_count(struct bif_ctrl *ctrl,
239 const struct bif_match_criteria *match_criteria);
241 struct bif_slave *bif_slave_match_get(struct bif_ctrl *ctrl,
242 unsigned int id, const struct bif_match_criteria *match_criteria);
244 void bif_slave_put(struct bif_slave *slave);
246 A consumer finds a slave attached to a given BIF controller by specifying a set
247 of matching criteria. The criteria can include such quantities as manufacturer
248 ID, product ID, function type or function version. It is possible that multiple
249 slaves will match the criteria. bif_slave_match_count() returns how many slaves
250 match the specified criteria. bif_slave_match_get() returns the id'th slave
251 which matches the criteria in an arbitrary, but fixed order (for a constant set
252 of slaves). Consumer drivers need to be able to handle the case of multiple
253 slaves matching the criteria.
255 Additionally, if a battery pack is inserted or removed, then the output of
256 bif_slave_match_count() and bif_slave_match_get() could change. A consumer
257 driver can register to receive notification of battery pack insertion and
258 removal using the bif_ctrl_notifier_register() function listed below.
260 Check if slave handle is still meaningful:
261 ------------------------------------------
263 int bif_slave_is_present(struct bif_slave *slave);
265 If a battery pack is removed, then the handles for its slaves will no longer be
266 meaningful. All transactions using a handle for a slave that isn't present will
267 fail. The function bif_slave_is_present() allows a consumer to determine if
268 a given slave is still physically present in the system.
270 Get access to the controller handle present in a slave handle:
271 --------------------------------------------------------------
273 struct bif_ctrl *bif_get_ctrl_handle(struct bif_slave *slave);
275 This function is useful if a consumer wishes to only store a slave handle but
276 also has need to call bus oriented BIF framework functions.
278 Get version and register offset of a BIF function if it is present in a slave:
279 ------------------------------------------------------------------------------
281 int bif_slave_find_function(struct bif_slave *slave, u8 function, u8 *version,
282 u16 *function_pointer);
284 This function is used by consumers who wish to support given BIF functions
285 (e.g. temperature measurement, authentication, etc.) found inside of slaves.
287 Receive notification upon battery insertion and removal:
288 --------------------------------------------------------
290 int bif_ctrl_notifier_register(struct bif_ctrl *ctrl,
291 struct notifier_block *nb);
293 int bif_ctrl_notifier_unregister(struct bif_ctrl *ctrl,
294 struct notifier_block *nb);
296 Read or write BIF slave registers:
297 ----------------------------------
299 int bif_slave_read(struct bif_slave *slave, u16 addr, u8 *buf, int len);
301 int bif_slave_write(struct bif_slave *slave, u16 addr, u8 *buf, int len);
304 BIF slave non-volatile memory manipulation:
305 -------------------------------------------
307 int bif_slave_nvm_raw_read(struct bif_slave *slave, u16 offset, u8 *buf,
310 int bif_slave_nvm_raw_write(struct bif_slave *slave, u16 offset, u8 *buf,
313 Raw NVM writing may be needed in order to intialize the NVM BIF object list.
314 However, its use can be dangerous as it can overwrite existing objects in the
315 list and make the list unparsable.
317 BIF object search in slave non-volatile memory:
318 -----------------------------------------------
319 int bif_object_match_count(struct bif_slave *slave,
320 const struct bif_obj_match_criteria *match_criteria);
322 struct bif_object *bif_object_match_get(struct bif_slave *slave,
323 unsigned int id, const struct bif_obj_match_criteria *match_criteria);
325 void bif_object_put(struct bif_object *object);
327 bif_object_match_count() and bif_object_match_get() can be used together in
328 order to retrieve the set of BIF objects within a slave which match certain
329 criteria. bif_object_put() is used to free the memory allocated by
330 bif_object_match_get().
332 BIF object manipulation in slave non-volatile memory:
333 -----------------------------------------------------
334 int bif_object_write(struct bif_slave *slave, u8 type, u8 version, u16
335 manufacturer_id, const u8 *data, int data_len);
337 int bif_object_overwrite(struct bif_slave *slave,
338 struct bif_object *object, u8 type, u8 version,
339 u16 manufacturer_id, const u8 *data, int data_len);
341 int bif_object_delete(struct bif_slave *slave, const struct bif_object *object);
343 bif_object_write() can be used to write a new BIF data object into the NVM of
344 a given slave. The new object is added to the end of the NVM object list.
345 bif_object_overwrite() can be used to overwrite an existing BIF data object
346 in the NVM of a slave. The new object data must be the same size as the
347 existing object data. bif_object_delete() can be used to delete a object from
348 the NVM object list and shift all of the objects after it in order to fill the
349 deleted object's space.
351 Get or set the BIF bus state or period:
352 ---------------------------------------
354 int bif_ctrl_get_bus_state(struct bif_ctrl *ctrl);
356 int bif_ctrl_set_bus_state(struct bif_ctrl *ctrl, enum bif_bus_state state);
358 int bif_ctrl_get_bus_period(struct bif_ctrl *ctrl);
360 int bif_ctrl_set_bus_period(struct bif_ctrl *ctrl, int period_ns);
362 Bus states include: active for communication, active waiting for interrupt,
363 standby, and power down. The MIPI-BIF specification defines the allowed range
364 of bus periods as 2000 ns to 153000 ns. Individual controllers may further
365 restrict the range of allowed periods. When bif_ctrl_set_bus_period() is called
366 the first supported period that greater than or equal to the specified period
369 Measure battery pack resistance:
370 --------------------------------
372 int bif_ctrl_measure_rid(struct bif_ctrl *ctrl);
374 This function returns an estimate of the battery pack resistance in ohms. If
375 no battery pack is connected, then the output of this function is undefined.
377 Utilize BIF slave tasks and interrupts:
378 ---------------------------------------
380 int bif_request_irq(struct bif_slave *slave, unsigned int task,
381 struct notifier_block *nb);
383 int bif_free_irq(struct bif_slave *slave, unsigned int task,
384 struct notifier_block *nb);
386 int bif_trigger_task(struct bif_slave *slave, unsigned int task);
388 int bif_task_is_busy(struct bif_slave *slave, unsigned int task);
390 int bif_enable_auto_task(struct bif_slave *slave, unsigned int task);
392 int bif_disable_auto_task(struct bif_slave *slave, unsigned int task);
394 A consumer can request a slave interrupt and specify a notifier to call when the
395 interrupt is triggered. Once the interrupt is requested the consumer will need
396 to call bif_trigger_task() in order to start the task associated with the
397 interrupt (both are identified by the same index). Polling for task completion
398 is also supported via the bif_task_is_busy() function. Auto task triggered can
399 be enabled and disabled for a given task using bif_enable_auto_task() and
400 bif_disable_auto_task() respectively.
402 Raw BIF bus transactions:
403 -------------------------
405 void bif_ctrl_bus_lock(struct bif_ctrl *ctrl);
407 void bif_ctrl_bus_unlock(struct bif_ctrl *ctrl);
409 int bif_ctrl_raw_transaction(struct bif_ctrl *ctrl, int transaction, u8 data);
411 int bif_ctrl_raw_transaction_read(struct bif_ctrl *ctrl, int transaction,
412 u8 data, int *response);
414 int bif_ctrl_raw_transaction_query(struct bif_ctrl *ctrl, int transaction,
415 u8 data, bool *query_response);
417 int bif_slave_is_selected(struct bif_slave *slave);
419 int bif_slave_select(struct bif_slave *slave);
421 The function bif_ctrl_bus_lock() locks the BIF bus for exclusive use by the
422 consumer. No other transactions will be allowed on the bus including those
423 that would arise from battery insertion/removal or slave interrupt reception.
424 This lock is primarily intended to be used along with the raw transaction
425 functions. These functions allow a consumer to issue any BIF transaction
426 including manufacturer specific bus commands not handled by the BIF framework.
428 While performing raw transactions, features normally performed transparently by
429 the core, such as device selection, are not available. The functions
430 bif_slave_select() and bif_slave_is_selected() can be used to fill in this gap
431 so that raw transactions are performed on the desired slave.
433 Notify the BIF core that a battery has been inserted or removed:
434 ----------------------------------------------------------------
436 int bif_ctrl_signal_battery_changed(struct bif_ctrl *ctrl);
438 This function should only be called on systems where the BIF controller driver
439 is architecturally unable to detect battery insertion and removal on its own.
441 Perform BIF object CRC using CRC-CCITT algorithm:
442 -------------------------------------------------
444 u16 bif_crc_ccitt(const u8 *buffer, int len);
446 Interface - BIF Controller API
447 ==============================
449 BIF framework structs and functions used by BIF controllers are defined in:
450 include/linux/bif/driver.h
452 Ops found in struct bif_ctrl_ops:
453 ---------------------------------
455 int (*bus_transaction) (struct bif_ctrl_dev *bdev, int transaction, u8 data);
457 int (*bus_transaction_query) (struct bif_ctrl_dev *bdev, int transaction,
458 u8 data, bool *query_response);
460 int (*bus_transaction_read) (struct bif_ctrl_dev *bdev, int transaction,
461 u8 data, int *response);
463 int (*read_slave_registers) (struct bif_ctrl_dev *bdev, u16 addr,
466 int (*write_slave_registers) (struct bif_ctrl_dev *bdev, u16 addr,
467 const u8 *data, int len);
469 int (*get_bus_period) (struct bif_ctrl_dev *bdev);
471 int (*set_bus_period) (struct bif_ctrl_dev *bdev, int period_ns);
473 int (*get_battery_presence) (struct bif_ctrl_dev *bdev);
475 int (*get_battery_rid) (struct bif_ctrl_dev *bdev);
477 int (*get_bus_state) (struct bif_ctrl_dev *bdev);
479 int (*set_bus_state) (struct bif_ctrl_dev *bdev, int state);
481 A BIF controller driver registers a set of call back functions which instantiate
482 these ops. The BIF framework then calls these functions based on internal and
485 The ops bus_transaction(), bus_transaction_query(), and bus_transaction_read()
486 carry out the controller hardware specific actions to perform BIF transactions
487 on the BIF bus. These transactions result in no slave response, a pulse in
488 response, or a word in response respectively. The ops read_slave_registers()
489 and write_slave_registers() internally must perform all transactions necessary
490 to read and write to BIF slave registers. These ops exist so that burst reads
491 and writes can take place since these activities have very tight timing
492 constraints that the BIF core cannot handle.
494 The ops get_bus_period() and set_bus_period() return the current bus clock base
495 period in nanoseconds and change the period to a new value respectively. The
496 ops get_bus_state() and set_bus_state() allow for monitoring and controlling the
497 bus state (i.e. active for communication, active waiting for interrupt, standby,
498 or power down). The op get_battery_presence() returns if any battery pack
499 (smart or low cost) is currently connected to the BCL. The op get_battery_rid()
500 returns a best estimate of the Rid battery pack pull down ID resistance in ohms
501 which can be used to determine if the battery pack is smart or low cost.
503 Register/unregister a BIF controller:
504 -------------------------------------
506 struct bif_ctrl_dev *bif_ctrl_register(struct bif_ctrl_desc *bif_desc,
507 struct device *dev, void *driver_data, struct device_node *of_node);
509 void bif_ctrl_unregister(struct bif_ctrl_dev *bdev);
511 Notify the BIF framework that a battery has been inserted or removed:
512 ---------------------------------------------------------------------
514 int bif_ctrl_notify_battery_changed(struct bif_ctrl_dev *bdev);
516 The BIF core will then call the get_battery_presence() op internally to
517 determine if the event is an insertion or removal.
519 Notify the BIF framework that a slave interrupt has been received:
520 ------------------------------------------------------------------
522 int bif_ctrl_notify_slave_irq(struct bif_ctrl_dev *bdev);
524 Upon receiving this call, the BIF core interrogates each slave to determine
525 which slaves have pending interrupts. It then iterates through all interrupts
526 on those slaves clearing all pending interrupts and notifying any consumers
527 waiting for the interrupts.
529 Get BIF controller private data:
530 --------------------------------
532 void *bdev_get_drvdata(struct bif_ctrl_dev *bdev);
537 CONFIG_BIF - Enables BIF framework support.
542 No user space interface is provided in the BIF framework. Therefore, user
543 space will not be able to directly use it.
548 It is conceivable that the BIF framework should take some action during
549 system suspend and resume. However, it is not clear exactly what should be
550 done given that the BCL would still need to be active in order to detect
551 battery removal while suspended.
553 sysfs nodes could be added which describe slaves as well as functions and
554 objects within the slaves. However these nodes would be read-only and would
555 really only be useful for descriptive as opposed to control purposes.
557 The exact time at which slave searching, function enumeration, and object
558 loading takes place could be optimized in order to improve performance to
559 some degree. It could also be made configurable at a controller level if
OSDN Git Service
