1 // SPDX-License-Identifier: GPL-2.0
2 /*
3  * Serial line interface for Bosh BNO055 IMU (via serdev).
4  * This file implements serial communication up to the register read/write
5  * level.
6  *
7  * Copyright (C) 2021-2022 Istituto Italiano di Tecnologia
8  * Electronic Design Laboratory
9  * Written by Andrea Merello <andrea.merello@iit.it>
10  *
11  * This driver is based on
12  *	Plantower PMS7003 particulate matter sensor driver
13  *	Which is
14  *	Copyright (c) Tomasz Duszynski <tduszyns@gmail.com>
15  */
16 
17 #include <linux/completion.h>
18 #include <linux/device.h>
19 #include <linux/errno.h>
20 #include <linux/jiffies.h>
21 #include <linux/kernel.h>
22 #include <linux/mod_devicetable.h>
23 #include <linux/module.h>
24 #include <linux/mutex.h>
25 #include <linux/regmap.h>
26 #include <linux/serdev.h>
27 
28 #include "bno055_ser_trace.h"
29 #include "bno055.h"
30 
31 /*
32  * Register writes cmd have the following format
33  * +------+------+-----+-----+----- ... ----+
34  * | 0xAA | 0xOO | REG | LEN | payload[LEN] |
35  * +------+------+-----+-----+----- ... ----+
36  *
37  * Register write responses have the following format
38  * +------+----------+
39  * | 0xEE | ERROCODE |
40  * +------+----------+
41  *
42  * .. except when writing the SYS_RST bit (i.e. triggering a system reset); in
43  * case the IMU accepts the command, then it resets without responding. We don't
44  * handle this (yet) here (so we inform the common bno055 code not to perform
45  * sw resets - bno055 on serial bus basically requires the hw reset pin).
46  *
47  * Register read have the following format
48  * +------+------+-----+-----+
49  * | 0xAA | 0xO1 | REG | LEN |
50  * +------+------+-----+-----+
51  *
52  * Successful register read response have the following format
53  * +------+-----+----- ... ----+
54  * | 0xBB | LEN | payload[LEN] |
55  * +------+-----+----- ... ----+
56  *
57  * Failed register read response have the following format
58  * +------+--------+
59  * | 0xEE | ERRCODE|  (ERRCODE always > 1)
60  * +------+--------+
61  *
62  * Error codes are
63  * 01: OK
64  * 02: read/write FAIL
65  * 04: invalid address
66  * 05: write on RO
67  * 06: wrong start byte
68  * 07: bus overrun
69  * 08: len too high
70  * 09: len too low
71  * 10: bus RX byte timeout (timeout is 30mS)
72  *
73  *
74  * **WORKAROUND ALERT**
75  *
76  * Serial communication seems very fragile: the BNO055 buffer seems to overflow
77  * very easy; BNO055 seems able to sink few bytes, then it needs a brief pause.
78  * On the other hand, it is also picky on timeout: if there is a pause > 30mS in
79  * between two bytes then the transaction fails (IMU internal RX FSM resets).
80  *
81  * BNO055 has been seen also failing to process commands in case we send them
82  * too close each other (or if it is somehow busy?)
83  *
84  * In particular I saw these scenarios:
85  * 1) If we send 2 bytes per time, then the IMU never(?) overflows.
86  * 2) If we send 4 bytes per time (i.e. the full header), then the IMU could
87  *    overflow, but it seem to sink all 4 bytes, then it returns error.
88  * 3) If we send more than 4 bytes, the IMU could overflow, and I saw it sending
89  *    error after 4 bytes are sent; we have troubles in synchronizing again,
90  *    because we are still sending data, and the IMU interprets it as the 1st
91  *    byte of a new command.
92  *
93  * While we must avoid case 3, we could send 4 bytes per time and eventually
94  * retry in case of failure; this seemed convenient for reads (which requires
95  * TXing exactly 4 bytes), however it has been seen that, depending by the IMU
96  * settings (e.g. LPF), failures became less or more frequent; in certain IMU
97  * configurations they are very rare, but in certain others we keeps failing
98  * even after like 30 retries.
99  *
100  * So, we just split TXes in [2-bytes + delay] steps, and still keep an eye on
101  * the IMU response; in case it overflows (which is now unlikely), we retry.
102  */
103 
104 /*
105  * Read operation overhead:
106  *  4 bytes req + 2byte resp hdr.
107  *  6 bytes = 60 bit (considering 1start + 1stop bits).
108  *  60/115200 = ~520uS + about 2500mS delay -> ~3mS
109  * In 3mS we could read back about 34 bytes that means 17 samples, this means
110  * that in case of scattered reads in which the gap is 17 samples or less it is
111  * still convenient to go for a burst.
112  * We have to take into account also IMU response time - IMU seems to be often
113  * reasonably quick to respond, but sometimes it seems to be in some "critical
114  * section" in which it delays handling of serial protocol. Because of this we
115  * round-up to 22, which is the max number of samples, always bursting indeed.
116  */
117 #define BNO055_SER_XFER_BURST_BREAK_THRESHOLD 22
118 
119 struct bno055_ser_priv {
120 	enum {
121 		CMD_NONE,
122 		CMD_READ,
123 		CMD_WRITE,
124 	} expect_response;
125 	int expected_data_len;
126 	u8 *response_buf;
127 
128 	/**
129 	 * enum cmd_status - represent the status of a command sent to the HW.
130 	 * @STATUS_CRIT: The command failed: the serial communication failed.
131 	 * @STATUS_OK:   The command executed successfully.
132 	 * @STATUS_FAIL: The command failed: HW responded with an error.
133 	 */
134 	enum {
135 		STATUS_CRIT = -1,
136 		STATUS_OK = 0,
137 		STATUS_FAIL = 1,
138 	} cmd_status;
139 
140 	/*
141 	 * Protects all the above fields, which are accessed in behalf of both
142 	 * the serdev RX callback and the regmap side
143 	 */
144 	struct mutex lock;
145 
146 	/* Only accessed in serdev RX callback context*/
147 	struct {
148 		enum {
149 			RX_IDLE,
150 			RX_START,
151 			RX_DATA,
152 		} state;
153 		int databuf_count;
154 		int expected_len;
155 		int type;
156 	} rx;
157 
158 	/* Never accessed in behalf of serdev RX callback context */
159 	bool cmd_stale;
160 
161 	struct completion cmd_complete;
162 	struct serdev_device *serdev;
163 };
164 
bno055_ser_send_chunk(struct bno055_ser_priv * priv,const u8 * data,int len)165 static int bno055_ser_send_chunk(struct bno055_ser_priv *priv, const u8 *data, int len)
166 {
167 	int ret;
168 
169 	trace_send_chunk(len, data);
170 	ret = serdev_device_write(priv->serdev, data, len, msecs_to_jiffies(25));
171 	if (ret < 0)
172 		return ret;
173 
174 	if (ret < len)
175 		return -EIO;
176 
177 	return 0;
178 }
179 
180 /*
181  * Send a read or write command.
182  * 'data' can be NULL (used in read case). 'len' parameter is always valid; in
183  * case 'data' is non-NULL then it must match 'data' size.
184  */
bno055_ser_do_send_cmd(struct bno055_ser_priv * priv,bool read,int addr,int len,const u8 * data)185 static int bno055_ser_do_send_cmd(struct bno055_ser_priv *priv,
186 				  bool read, int addr, int len, const u8 *data)
187 {
188 	u8 hdr[] = {0xAA, read, addr, len};
189 	int chunk_len;
190 	int ret;
191 
192 	ret = bno055_ser_send_chunk(priv, hdr, 2);
193 	if (ret)
194 		goto fail;
195 	usleep_range(2000, 3000);
196 	ret = bno055_ser_send_chunk(priv, hdr + 2, 2);
197 	if (ret)
198 		goto fail;
199 
200 	if (read)
201 		return 0;
202 
203 	while (len) {
204 		chunk_len = min(len, 2);
205 		usleep_range(2000, 3000);
206 		ret = bno055_ser_send_chunk(priv, data, chunk_len);
207 		if (ret)
208 			goto fail;
209 		data += chunk_len;
210 		len -= chunk_len;
211 	}
212 
213 	return 0;
214 fail:
215 	/* waiting more than 30mS should clear the BNO055 internal state */
216 	usleep_range(40000, 50000);
217 	return ret;
218 }
219 
bno055_ser_send_cmd(struct bno055_ser_priv * priv,bool read,int addr,int len,const u8 * data)220 static int bno055_ser_send_cmd(struct bno055_ser_priv *priv,
221 			       bool read, int addr, int len, const u8 *data)
222 {
223 	const int retry_max = 5;
224 	int retry = retry_max;
225 	int ret = 0;
226 
227 	/*
228 	 * In case previous command was interrupted we still need to wait it to
229 	 * complete before we can issue new commands
230 	 */
231 	if (priv->cmd_stale) {
232 		ret = wait_for_completion_interruptible_timeout(&priv->cmd_complete,
233 								msecs_to_jiffies(100));
234 		if (ret == -ERESTARTSYS)
235 			return -ERESTARTSYS;
236 
237 		priv->cmd_stale = false;
238 		/* if serial protocol broke, bail out */
239 		if (priv->cmd_status == STATUS_CRIT)
240 			return -EIO;
241 	}
242 
243 	/*
244 	 * Try to convince the IMU to cooperate.. as explained in the comments
245 	 * at the top of this file, the IMU could also refuse the command (i.e.
246 	 * it is not ready yet); retry in this case.
247 	 */
248 	do {
249 		mutex_lock(&priv->lock);
250 		priv->expect_response = read ? CMD_READ : CMD_WRITE;
251 		reinit_completion(&priv->cmd_complete);
252 		mutex_unlock(&priv->lock);
253 
254 		if (retry != retry_max)
255 			trace_cmd_retry(read, addr, retry_max - retry);
256 		ret = bno055_ser_do_send_cmd(priv, read, addr, len, data);
257 		if (ret)
258 			continue;
259 
260 		ret = wait_for_completion_interruptible_timeout(&priv->cmd_complete,
261 								msecs_to_jiffies(100));
262 		if (ret == -ERESTARTSYS) {
263 			priv->cmd_stale = true;
264 			return -ERESTARTSYS;
265 		}
266 
267 		if (!ret)
268 			return -ETIMEDOUT;
269 
270 		if (priv->cmd_status == STATUS_OK)
271 			return 0;
272 		if (priv->cmd_status == STATUS_CRIT)
273 			return -EIO;
274 
275 		/* loop in case priv->cmd_status == STATUS_FAIL */
276 	} while (--retry);
277 
278 	if (ret < 0)
279 		return ret;
280 	if (priv->cmd_status == STATUS_FAIL)
281 		return -EINVAL;
282 	return 0;
283 }
284 
bno055_ser_write_reg(void * context,const void * _data,size_t count)285 static int bno055_ser_write_reg(void *context, const void *_data, size_t count)
286 {
287 	const u8 *data = _data;
288 	struct bno055_ser_priv *priv = context;
289 
290 	if (count < 2) {
291 		dev_err(&priv->serdev->dev, "Invalid write count %zu", count);
292 		return -EINVAL;
293 	}
294 
295 	trace_write_reg(data[0], data[1]);
296 	return bno055_ser_send_cmd(priv, 0, data[0], count - 1, data + 1);
297 }
298 
bno055_ser_read_reg(void * context,const void * _reg,size_t reg_size,void * val,size_t val_size)299 static int bno055_ser_read_reg(void *context,
300 			       const void *_reg, size_t reg_size,
301 			       void *val, size_t val_size)
302 {
303 	int ret;
304 	int reg_addr;
305 	const u8 *reg = _reg;
306 	struct bno055_ser_priv *priv = context;
307 
308 	if (val_size > 128) {
309 		dev_err(&priv->serdev->dev, "Invalid read valsize %zu", val_size);
310 		return -EINVAL;
311 	}
312 
313 	reg_addr = *reg;
314 	trace_read_reg(reg_addr, val_size);
315 	mutex_lock(&priv->lock);
316 	priv->expected_data_len = val_size;
317 	priv->response_buf = val;
318 	mutex_unlock(&priv->lock);
319 
320 	ret = bno055_ser_send_cmd(priv, 1, reg_addr, val_size, NULL);
321 
322 	mutex_lock(&priv->lock);
323 	priv->response_buf = NULL;
324 	mutex_unlock(&priv->lock);
325 
326 	return ret;
327 }
328 
329 /*
330  * Handler for received data; this is called from the receiver callback whenever
331  * it got some packet from the serial bus. The status tells us whether the
332  * packet is valid (i.e. header ok && received payload len consistent wrt the
333  * header). It's now our responsibility to check whether this is what we
334  * expected, of whether we got some unexpected, yet valid, packet.
335  */
bno055_ser_handle_rx(struct bno055_ser_priv * priv,int status)336 static void bno055_ser_handle_rx(struct bno055_ser_priv *priv, int status)
337 {
338 	mutex_lock(&priv->lock);
339 	switch (priv->expect_response) {
340 	case CMD_NONE:
341 		dev_warn(&priv->serdev->dev, "received unexpected, yet valid, data from sensor");
342 		mutex_unlock(&priv->lock);
343 		return;
344 
345 	case CMD_READ:
346 		priv->cmd_status = status;
347 		if (status == STATUS_OK &&
348 		    priv->rx.databuf_count != priv->expected_data_len) {
349 			/*
350 			 * If we got here, then the lower layer serial protocol
351 			 * seems consistent with itself; if we got an unexpected
352 			 * amount of data then signal it as a non critical error
353 			 */
354 			priv->cmd_status = STATUS_FAIL;
355 			dev_warn(&priv->serdev->dev,
356 				 "received an unexpected amount of, yet valid, data from sensor");
357 		}
358 		break;
359 
360 	case CMD_WRITE:
361 		priv->cmd_status = status;
362 		break;
363 	}
364 
365 	priv->expect_response = CMD_NONE;
366 	mutex_unlock(&priv->lock);
367 	complete(&priv->cmd_complete);
368 }
369 
370 /*
371  * Serdev receiver FSM. This tracks the serial communication and parse the
372  * header. It pushes packets to bno055_ser_handle_rx(), eventually communicating
373  * failures (i.e. malformed packets).
374  * Ideally it doesn't know anything about upper layer (i.e. if this is the
375  * packet we were really expecting), but since we copies the payload into the
376  * receiver buffer (that is not valid when i.e. we don't expect data), we
377  * snoop a bit in the upper layer..
378  * Also, we assume to RX one pkt per time (i.e. the HW doesn't send anything
379  * unless we require to AND we don't queue more than one request per time).
380  */
bno055_ser_receive_buf(struct serdev_device * serdev,const unsigned char * buf,size_t size)381 static int bno055_ser_receive_buf(struct serdev_device *serdev,
382 				  const unsigned char *buf, size_t size)
383 {
384 	int status;
385 	struct bno055_ser_priv *priv = serdev_device_get_drvdata(serdev);
386 	int remaining = size;
387 
388 	if (size == 0)
389 		return 0;
390 
391 	trace_recv(size, buf);
392 	switch (priv->rx.state) {
393 	case RX_IDLE:
394 		/*
395 		 * New packet.
396 		 * Check for its 1st byte that identifies the pkt type.
397 		 */
398 		if (buf[0] != 0xEE && buf[0] != 0xBB) {
399 			dev_err(&priv->serdev->dev,
400 				"Invalid packet start %x", buf[0]);
401 			bno055_ser_handle_rx(priv, STATUS_CRIT);
402 			break;
403 		}
404 		priv->rx.type = buf[0];
405 		priv->rx.state = RX_START;
406 		remaining--;
407 		buf++;
408 		priv->rx.databuf_count = 0;
409 		fallthrough;
410 
411 	case RX_START:
412 		/*
413 		 * Packet RX in progress, we expect either 1-byte len or 1-byte
414 		 * status depending by the packet type.
415 		 */
416 		if (remaining == 0)
417 			break;
418 
419 		if (priv->rx.type == 0xEE) {
420 			if (remaining > 1) {
421 				dev_err(&priv->serdev->dev, "EE pkt. Extra data received");
422 				status = STATUS_CRIT;
423 			} else {
424 				status = (buf[0] == 1) ? STATUS_OK : STATUS_FAIL;
425 			}
426 			bno055_ser_handle_rx(priv, status);
427 			priv->rx.state = RX_IDLE;
428 			break;
429 
430 		} else {
431 			/*priv->rx.type == 0xBB */
432 			priv->rx.state = RX_DATA;
433 			priv->rx.expected_len = buf[0];
434 			remaining--;
435 			buf++;
436 		}
437 		fallthrough;
438 
439 	case RX_DATA:
440 		/* Header parsed; now receiving packet data payload */
441 		if (remaining == 0)
442 			break;
443 
444 		if (priv->rx.databuf_count + remaining > priv->rx.expected_len) {
445 			/*
446 			 * This is an inconsistency in serial protocol, we lost
447 			 * sync and we don't know how to handle further data
448 			 */
449 			dev_err(&priv->serdev->dev, "BB pkt. Extra data received");
450 			bno055_ser_handle_rx(priv, STATUS_CRIT);
451 			priv->rx.state = RX_IDLE;
452 			break;
453 		}
454 
455 		mutex_lock(&priv->lock);
456 		/*
457 		 * NULL e.g. when read cmd is stale or when no read cmd is
458 		 * actually pending.
459 		 */
460 		if (priv->response_buf &&
461 		    /*
462 		     * Snoop on the upper layer protocol stuff to make sure not
463 		     * to write to an invalid memory. Apart for this, let's the
464 		     * upper layer manage any inconsistency wrt expected data
465 		     * len (as long as the serial protocol is consistent wrt
466 		     * itself (i.e. response header is consistent with received
467 		     * response len.
468 		     */
469 		    (priv->rx.databuf_count + remaining <= priv->expected_data_len))
470 			memcpy(priv->response_buf + priv->rx.databuf_count,
471 			       buf, remaining);
472 		mutex_unlock(&priv->lock);
473 
474 		priv->rx.databuf_count += remaining;
475 
476 		/*
477 		 * Reached expected len advertised by the IMU for the current
478 		 * packet. Pass it to the upper layer (for us it is just valid).
479 		 */
480 		if (priv->rx.databuf_count == priv->rx.expected_len) {
481 			bno055_ser_handle_rx(priv, STATUS_OK);
482 			priv->rx.state = RX_IDLE;
483 		}
484 		break;
485 	}
486 
487 	return size;
488 }
489 
490 static const struct serdev_device_ops bno055_ser_serdev_ops = {
491 	.receive_buf = bno055_ser_receive_buf,
492 	.write_wakeup = serdev_device_write_wakeup,
493 };
494 
495 static struct regmap_bus bno055_ser_regmap_bus = {
496 	.write = bno055_ser_write_reg,
497 	.read = bno055_ser_read_reg,
498 };
499 
bno055_ser_probe(struct serdev_device * serdev)500 static int bno055_ser_probe(struct serdev_device *serdev)
501 {
502 	struct bno055_ser_priv *priv;
503 	struct regmap *regmap;
504 	int ret;
505 
506 	priv = devm_kzalloc(&serdev->dev, sizeof(*priv), GFP_KERNEL);
507 	if (!priv)
508 		return -ENOMEM;
509 
510 	serdev_device_set_drvdata(serdev, priv);
511 	priv->serdev = serdev;
512 	mutex_init(&priv->lock);
513 	init_completion(&priv->cmd_complete);
514 
515 	serdev_device_set_client_ops(serdev, &bno055_ser_serdev_ops);
516 	ret = devm_serdev_device_open(&serdev->dev, serdev);
517 	if (ret)
518 		return ret;
519 
520 	if (serdev_device_set_baudrate(serdev, 115200) != 115200) {
521 		dev_err(&serdev->dev, "Cannot set required baud rate");
522 		return -EIO;
523 	}
524 
525 	ret = serdev_device_set_parity(serdev, SERDEV_PARITY_NONE);
526 	if (ret) {
527 		dev_err(&serdev->dev, "Cannot set required parity setting");
528 		return ret;
529 	}
530 	serdev_device_set_flow_control(serdev, false);
531 
532 	regmap = devm_regmap_init(&serdev->dev, &bno055_ser_regmap_bus,
533 				  priv, &bno055_regmap_config);
534 	if (IS_ERR(regmap))
535 		return dev_err_probe(&serdev->dev, PTR_ERR(regmap),
536 				     "Unable to init register map");
537 
538 	return bno055_probe(&serdev->dev, regmap,
539 			    BNO055_SER_XFER_BURST_BREAK_THRESHOLD, false);
540 }
541 
542 static const struct of_device_id bno055_ser_of_match[] = {
543 	{ .compatible = "bosch,bno055" },
544 	{ }
545 };
546 MODULE_DEVICE_TABLE(of, bno055_ser_of_match);
547 
548 static struct serdev_device_driver bno055_ser_driver = {
549 	.driver = {
550 		.name = "bno055-ser",
551 		.of_match_table = bno055_ser_of_match,
552 	},
553 	.probe = bno055_ser_probe,
554 };
555 module_serdev_device_driver(bno055_ser_driver);
556 
557 MODULE_AUTHOR("Andrea Merello <andrea.merello@iit.it>");
558 MODULE_DESCRIPTION("Bosch BNO055 serdev interface");
559 MODULE_IMPORT_NS(IIO_BNO055);
560 MODULE_LICENSE("GPL");
561